X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapio.pod;h=10b8dc554e0e97abcaa5e9555b2eb368b16eb262;hb=0c2f6559512b2211f892f1a6ae8db4739c5369b4;hp=981ee2048bc8cafac7141d331ba5fef57f35e6da;hpb=f504ae08d9ea711c106835665711262bdaa326c7;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapio.pod b/pod/perlapio.pod index 981ee20..10b8dc5 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); @@ -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), 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,9 +225,13 @@ 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,14 +312,15 @@ 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 are currently 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 *. @@ -318,20 +328,22 @@ 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 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). @@ -342,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 @@ -370,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) && \ @@ -445,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. 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) @@ -465,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 ":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");