X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapio.pod;h=1c57f9a9a89b1f4354162550aac0c21a393bc97b;hb=4ff31b786b9f6148fc8ea695db081861576d06a2;hp=9da7f2d3d6e69da72f07ca8c377bff289a2dc13b;hpb=4b069b44f3c785593c10e7aca80c893a2f210b9d;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapio.pod b/pod/perlapio.pod index 9da7f2d..1c57f9a 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -160,12 +160,17 @@ so it is (currently) legal to use C in perl sources. =item B, B -These correspond to fread() and fwrite(). Note that arguments are -different, there is only one "count" and order has "file" -first. Returns a byte count if successful (which may be zero or positive), returns -negative value and sets C on error. Depending on -implementation C may be C if operation was interrupted -by a signal. +These correspond functionally to fread() and fwrite() but the +arguments and return values are different. The PerlIO_read() and +PerlIO_write() signatures have been modeled on the more sane low level +read() and write() functions instead: The "file" argument is passed +first, there is only one "count", and the return value can distinguish +between error and C. + +Returns a byte count if successful (which may be zero or +positive), returns negative value and sets C on error. +Depending on implementation C may be C if operation was +interrupted by a signal. =item B @@ -220,18 +225,19 @@ This corresponds to clearerr(), i.e., clears 'error' and (usually) This corresponds to fflush(). Sends any buffered write data to the underlying file. If called with C this may flush all open -streams (or core dump with some USE_STDIO implementattions). -Calling on a handle open for read only, or on which last operation was a read of some kind -may lead to undefined behaviour on some USE_STDIO implementations. -The USE_PERLIO (layers) implementation tries to behave better: it flushes all open streams -when passed C, and attempts to retain data on read streams either in the buffer -or by seeking the handle to the current logical position. +streams (or core dump with some USE_STDIO implementations). Calling +on a handle open for read only, or on which last operation was a read +of some kind may lead to undefined behaviour on some USE_STDIO +implementations. The USE_PERLIO (layers) implementation tries to +behave better: it flushes all open streams when passed C, and +attempts to retain data on read streams either in the buffer or by +seeking the handle to the current logical position. =item B This corresponds to fseek(). Sends buffered write data to the underlying file, or discards any buffered read data, then positions -the file desciptor as specified by B and B (sic). +the file descriptor as specified by B and B (sic). This is the correct thing to do when switching between read and write on the same handle (see issues with PerlIO_flush() above). Offset is of type C which is a perl Configure value which may not be same @@ -310,10 +316,11 @@ changes in this area. Used to get a PerlIO * from a FILE *. -The mode argument should be a string as would be passed to fopen/PerlIO_open. -If it is NULL then - for legacy support - the code will (depending upon -the platform and the implementation) either attempt to empirically determine the mode in -which I is open, or use "r+" to indicate a read/write stream. +The mode argument should be a string as would be passed to +fopen/PerlIO_open. If it is NULL then - for legacy support - the code +will (depending upon the platform and the implementation) either +attempt to empirically determine the mode in which I is open, or +use "r+" to indicate a read/write stream. Once called the FILE * should I be closed by calling C on the returned PerlIO *. @@ -321,19 +328,22 @@ C on the returned PerlIO *. The PerlIO is set to textmode. Use PerlIO_binmode if this is not the desired mode. +This is B the reverse of PerlIO_exportFILE(). + =item B Given a PerlIO * create a 'native' FILE * suitable for passing to code -expecting to be compiled and linked with ANSI C I. -The mode argument should be a string as would be passed to fopen/PerlIO_open. -If it is NULL then - for legacy support - the FILE * is opened -in same mode as the PerlIO *. - -The fact that such a FILE * has been 'exported' is recorded, (normally by -pushing a new :stdio "layer" onto the PerlIO *), which may affect future -PerlIO operations on the original PerlIO *. -You should not call C on the file unless you call -C to disassociate it from the PerlIO *. +expecting to be compiled and linked with ANSI C I. The mode +argument should be a string as would be passed to fopen/PerlIO_open. +If it is NULL then - for legacy support - the FILE * is opened in same +mode as the PerlIO *. + +The fact that such a FILE * has been 'exported' is recorded, (normally +by pushing a new :stdio "layer" onto the PerlIO *), which may affect +future PerlIO operations on the original PerlIO *. You should not +call C on the file unless you call C +to disassociate it from the PerlIO *. (Do not use PerlIO_importFILE() +for doing the disassociation.) Calling this function repeatedly will create a FILE * on each call (and will push an :stdio layer each time as well). @@ -344,6 +354,9 @@ Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is complete. It is removed from the list of 'exported' FILE *s, and the associated PerlIO * should revert to its original behaviour. +Use this to disassociate a file from a PerlIO * that was associated +using PerlIO_exportFILE(). + =item B Returns a native FILE * used by a stdio layer. If there is none, it @@ -372,8 +385,8 @@ traditional way if a handle does not support them. =item B Returns true if implementation has all the interfaces required to -allow perl's C to "bypass" normal IO mechanism. -This can vary from handle to handle. +allow perl's C to "bypass" normal IO mechanism. This can +vary from handle to handle. PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ PerlIO_canset_cnt(f) && \ @@ -447,8 +460,8 @@ happened to C (or whatever) last time IO was requested. The new interface to the USE_PERLIO implementation. The layers ":crlf" and ":raw" are only ones allowed for other implementations and those -are silently ignored. (As of perl5.8 ":raw" is deprecated.) -Use PerlIO_binmode() below for the portable case. +are silently ignored. (As of perl5.8 ":raw" is deprecated.) Use +PerlIO_binmode() below for the portable case. =item PerlIO_binmode(f,ptype,imode,layers) @@ -467,12 +480,13 @@ B is perl's character for the kind of IO: B is C or C. -B is a string of layers to apply, only ":crlf" makes sense in the non USE_PERLIO -case. (As of perl5.8 ":raw" is deprecated in favour of passing NULL.) +B is a string of layers to apply, only ":crlf" makes sense in +the non USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in favour +of passing NULL.) Portable cases are: - PerlIO_binmode(f,ptype,O_BINARY,Nullch); + PerlIO_binmode(f,ptype,O_BINARY,NULL); and PerlIO_binmode(f,ptype,O_TEXT,":crlf");