X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/d360a069d6bdc55d9bfda16507abbff2168bf4f7..e0ea5e2d50a479e160d39f481e02abd7c0c9cf91:/pod/perlapio.pod diff --git a/pod/perlapio.pod b/pod/perlapio.pod index 68d794f..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 *. @@ -326,17 +333,17 @@ 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 *. -(Do not use PerlIO_importFILE() for doing the disassociation.) +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). @@ -378,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) && \ @@ -453,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) @@ -473,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");