X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapio.pod;h=68d794f66a9cb25e82fd4e645eb0a0b565014ddd;hb=14aaa8fc27b8350048cdee657c0128eb979d0b2a;hp=a0e4ffaf105ed6aafa95b1c1e3a23707ff1e8293;hpb=22569500a4329ba00826e9a263a1e15c2b24247f;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapio.pod b/pod/perlapio.pod index a0e4ffa..68d794f 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -56,7 +56,7 @@ perlapio - perl's IO abstraction interface. char *PerlIO_get_base(PerlIO *f); int PerlIO_get_bufsiz(PerlIO *f); - PerlIO *PerlIO_importFILE(FILE *stdio, int flags); + PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode); FILE *PerlIO_exportFILE(PerlIO *f, int flags); FILE *PerlIO_findFILE(PerlIO *f); void PerlIO_releaseFILE(PerlIO *f,FILE *stdio); @@ -162,7 +162,7 @@ so it is (currently) legal to use C in perl sources. 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), returns +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. @@ -220,9 +220,12 @@ 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). Calling on a handle open for read only, or on -which last operation was a read of some kind may lead to undefined -behaviour. +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. =item B @@ -303,33 +306,37 @@ changes in this area. =over 4 -=item B +=item B Used to get a PerlIO * from a FILE *. -The flags argument was meant to be used for read vs write vs -read/write information. In hindsight it would have been better to make -it a char *mode as in fopen/freopen. Flags arecurrently ignored, and -code attempts to empirically determine the mode in which I is open. +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 *. +The PerlIO is set to textmode. Use PerlIO_binmode if this is +not the desired mode. -=item B +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 flags argument was meant to be used for read vs write vs -read/write information. In hindsight it would have been better to make -it a char *mode as in fopen/freopen. Flags are ignored and the -FILE * is opened in same mode as the PerlIO *. +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 the PerlIO *. +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). @@ -337,14 +344,17 @@ Calling this function repeatedly will create a FILE * on each call =item B Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is -complete. It is removed from list of 'exported' FILE *s, and -associated PerlIO * should revert to original behaviour. +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 will create one with PerlIO_exportFILE. In either case the FILE * -should be considered at belonging to PerlIO subsystem and should +should be considered as belonging to PerlIO subsystem and should only be closed by calling C. @@ -443,8 +453,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. 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) @@ -463,12 +473,12 @@ B is perl's character for the kind of IO: B is C or C. -B is a string of layers to apply, only ":raw" or :"crlf" make -sense in the non USE_PERLIO case. +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,":raw"); + PerlIO_binmode(f,ptype,O_BINARY,Nullch); and PerlIO_binmode(f,ptype,O_TEXT,":crlf");