1N/Aperlapio - perl's IO abstraction interface.
1N/A #define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */
1N/A PerlIO *PerlIO_stdin(void);
1N/A PerlIO *PerlIO_stdout(void);
1N/A PerlIO *PerlIO_stderr(void);
1N/A PerlIO *PerlIO_open(const char *path,const char *mode);
1N/A PerlIO *PerlIO_fdopen(int fd, const char *mode);
1N/A PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old); /* deprecated */
1N/A int PerlIO_close(PerlIO *f);
1N/A int PerlIO_stdoutf(const char *fmt,...)
1N/A int PerlIO_puts(PerlIO *f,const char *string);
1N/A int PerlIO_putc(PerlIO *f,int ch);
1N/A int PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
1N/A int PerlIO_printf(PerlIO *f, const char *fmt,...);
1N/A int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
1N/A int PerlIO_flush(PerlIO *f);
1N/A int PerlIO_eof(PerlIO *f);
1N/A int PerlIO_error(PerlIO *f);
1N/A void PerlIO_clearerr(PerlIO *f);
1N/A int PerlIO_getc(PerlIO *d);
1N/A int PerlIO_ungetc(PerlIO *f,int ch);
1N/A int PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
1N/A int PerlIO_fileno(PerlIO *f);
1N/A void PerlIO_setlinebuf(PerlIO *f);
1N/A Off_t PerlIO_tell(PerlIO *f);
1N/A int PerlIO_seek(PerlIO *f, Off_t offset, int whence);
1N/A void PerlIO_rewind(PerlIO *f);
1N/A int PerlIO_getpos(PerlIO *f, SV *save); /* prototype changed */
1N/A int PerlIO_setpos(PerlIO *f, SV *saved); /* prototype changed */
1N/A int PerlIO_fast_gets(PerlIO *f);
1N/A int PerlIO_has_cntptr(PerlIO *f);
1N/A int PerlIO_get_cnt(PerlIO *f);
1N/A char *PerlIO_get_ptr(PerlIO *f);
1N/A void PerlIO_set_ptrcnt(PerlIO *f, char *ptr, int count);
1N/A int PerlIO_canset_cnt(PerlIO *f); /* deprecated */
1N/A void PerlIO_set_cnt(PerlIO *f, int count); /* deprecated */
1N/A int PerlIO_has_base(PerlIO *f);
1N/A char *PerlIO_get_base(PerlIO *f);
1N/A int PerlIO_get_bufsiz(PerlIO *f);
1N/A PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
1N/A FILE *PerlIO_exportFILE(PerlIO *f, int flags);
1N/A FILE *PerlIO_findFILE(PerlIO *f);
1N/A void PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
1N/A int PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers);
1N/A int PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers);
1N/A void PerlIO_debug(const char *fmt,...)
1N/APerl's source code, and extensions that want maximum portability,
1N/Ashould use the above functions instead of those defined in ANSI C's
1N/AC<#define> them to the I/O mechanism selected at Configure time.
1N/AThe functions are modeled on those in I<
stdio.h>, but parameter order
1N/Ahas been "tidied up a little".
1N/AC<PerlIO *> takes the place of FILE *. Like FILE * it should be
1N/Atreated as opaque (it is probably safe to assume it is a pointer to
1N/AThere are currently three implementations:
1N/AAll above are #define'd to stdio functions or are trivial wrapper
1N/Afunctions which call stdio. In this case I<only> PerlIO * is a FILE *.
1N/AThis has been the default implementation since the abstraction was
1N/Aintroduced in perl5.003_02.
1N/AA "legacy" implementation in terms of the "sfio" library. Used for
1N/Asome specialist applications on Unix machines ("sfio" is not widely
1N/Aported away from Unix). Most of above are #define'd to the sfio
1N/Afunctions. PerlIO * is in this case Sfio_t *.
1N/AIntroduced just after perl5.7.0, this is a re-implementation of the
1N/Aabove abstraction which allows perl more control over how IO is done
1N/Aas it decouples IO from the way the operating system and C library
1N/Achoose to do things. For USE_PERLIO PerlIO * has an extra layer of
1N/Aindirection - it is a pointer-to-a-pointer. This allows the PerlIO *
1N/Ato remain with a known value while swapping the implementation around
1N/Aunderneath I<at run time>. In this case all the above are true (but
1N/Avery simple) functions which call the underlying implementation.
1N/AThis is the only implementation for which C<PerlIO_apply_layers()>
1N/Adoes anything "interesting".
1N/AThe USE_PERLIO implementation is described in L<perliol>.
1N/ABecause "
perlio.h" is a thin layer (for efficiency) the semantics of
1N/Athese functions are somewhat dependent on the underlying implementation.
1N/AWhere these variations are understood they are noted below.
1N/AUnless otherwise noted, functions return 0 on success, or a negative
1N/Avalue (usually C<EOF> which is usually -1) and set C<errno> on error.
1N/A=item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>
1N/AUse these rather than C<stdin>, C<stdout>, C<stderr>. They are written
1N/Ato look like "function calls" rather than variables because this makes
1N/Ait easier to I<make them> function calls if platform cannot export data
1N/Ato loaded modules, or if (say) different "threads" might have different
1N/A=item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>
1N/AThese correspond to fopen()/fdopen() and the arguments are the same.
1N/AReturn C<NULL> and set C<errno> if there is an error. There may be an
1N/Aimplementation limit on the number of open handles, which may be lower
1N/Athan the limit on the number of open files - C<errno> may not be set
1N/Awhen C<NULL> is returned if this limit is exceeded.
1N/A=item B<PerlIO_reopen(path,mode,f)>
1N/AWhile this currently exists in all three implementations perl itself
1N/Adoes not use it. I<As perl does not use it, it is not well tested.>
1N/APerl prefers to C<dup> the new low-level descriptor to the descriptor
1N/Aused by the existing PerlIO. This may become the behaviour of this
1N/Afunction in the future.
1N/A=item B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>
1N/AThese are fprintf()/vfprintf() equivalents.
1N/A=item B<PerlIO_stdoutf(fmt,...)>
1N/AThis is printf() equivalent. printf is #defined to this function,
1N/Aso it is (currently) legal to use C<printf(fmt,...)> in perl sources.
1N/A=item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)>
1N/AThese correspond functionally to fread() and fwrite() but the
1N/Aarguments and return values are different. The PerlIO_read() and
1N/APerlIO_write() signatures have been modeled on the more sane low level
1N/Aread() and write() functions instead: The "file" argument is passed
1N/Afirst, there is only one "count", and the return value can distinguish
1N/Abetween error and C<EOF>.
1N/AReturns a byte count if successful (which may be zero or
1N/Apositive), returns negative value and sets C<errno> on error.
1N/ADepending on implementation C<errno> may be C<EINTR> if operation was
1N/Ainterrupted by a signal.
1N/A=item B<PerlIO_close(f)>
1N/ADepending on implementation C<errno> may be C<EINTR> if operation was
1N/Ainterrupted by a signal.
1N/A=item B<PerlIO_puts(f,s)>, B<PerlIO_putc(f,c)>
1N/AThese correspond to fputs() and fputc().
1N/ANote that arguments have been revised to have "file" first.
1N/A=item B<PerlIO_ungetc(f,c)>
1N/AThis corresponds to ungetc(). Note that arguments have been revised
1N/Ato have "file" first. Arranges that next read operation will return
1N/Athe byte B<c>. Despite the implied "character" in the name only
1N/Avalues in the range 0..0xFF are defined. Returns the byte B<c> on
1N/Asuccess or -1 (C<EOF>) on error. The number of bytes that can be
1N/A"pushed back" may vary, only 1 character is certain, and then only if
1N/Ait is the last character that was read from the handle.
1N/A=item B<PerlIO_getc(f)>
1N/AThis corresponds to getc().
1N/ADespite the c in the name only byte range 0..0xFF is supported.
1N/AReturns the character read or -1 (C<EOF>) on error.
1N/A=item B<PerlIO_eof(f)>
1N/Awhether the handle is at end of file. For terminal devices this may
1N/Aor may not be "sticky" depending on the implementation. The flag is
1N/Acleared by PerlIO_seek(), or PerlIO_rewind().
1N/A=item B<PerlIO_error(f)>
1N/Awhether there has been an IO error on the handle.
1N/A=item B<PerlIO_fileno(f)>
1N/AThis corresponds to fileno(), note that on some platforms, the meaning
1N/Aof "fileno" may not match Unix. Returns -1 if the handle has no open
1N/Adescriptor associated with it.
1N/A=item B<PerlIO_clearerr(f)>
1N/AThis corresponds to clearerr(),
i.e., clears 'error' and (usually)
1N/A'eof' flags for the "stream". Does not return a value.
1N/A=item B<PerlIO_flush(f)>
1N/AThis corresponds to fflush(). Sends any buffered write data to the
1N/Aunderlying file. If called with C<NULL> this may flush all open
1N/Astreams (or core dump with some USE_STDIO implementattions). Calling
1N/Aon a handle open for read only, or on which last operation was a read
1N/Aof some kind may lead to undefined behaviour on some USE_STDIO
1N/Aimplementations. The USE_PERLIO (layers) implementation tries to
1N/Abehave better: it flushes all open streams when passed C<NULL>, and
1N/Aattempts to retain data on read streams either in the buffer or by
1N/Aseeking the handle to the current logical position.
1N/A=item B<PerlIO_seek(f,offset,whence)>
1N/AThis corresponds to fseek(). Sends buffered write data to the
1N/Aunderlying file, or discards any buffered read data, then positions
1N/Athe file desciptor as specified by B<offset> and B<whence> (sic).
1N/AThis is the correct thing to do when switching between read and write
1N/Aon the same handle (see issues with PerlIO_flush() above). Offset is
1N/Aof type C<Off_t> which is a perl Configure value which may not be same
1N/A=item B<PerlIO_tell(f)>
1N/AThis corresponds to ftell(). Returns the current file position, or
1N/A(Off_t) -1 on error. May just return value system "knows" without
1N/Amaking a system call or checking the underlying file descriptor (so
1N/Ause on shared file descriptors is not safe without a
1N/APerlIO_seek()). Return value is of type C<Off_t> which is a perl
1N/AConfigure value which may not be same as stdio's C<off_t>.
1N/A=item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>
1N/AThese correspond (loosely) to fgetpos() and fsetpos(). Rather than
1N/Astdio's Fpos_t they expect a "Perl Scalar Value" to be passed. What is
1N/Astored there should be considered opaque. The layout of the data may
1N/Avary from handle to handle. When not using stdio or if platform does
1N/Anot have the stdio calls then they are implemented in terms of
1N/APerlIO_tell() and PerlIO_seek().
1N/A=item B<PerlIO_rewind(f)>
1N/AThis corresponds to rewind(). It is usually defined as being
1N/A PerlIO_seek(f,(Off_t)0L, SEEK_SET);
1N/A=item B<PerlIO_tmpfile()>
1N/AThis corresponds to tmpfile(),
i.e., returns an anonymous PerlIO or
1N/ANULL on error. The system will attempt to automatically delete the
1N/Afile when closed. On Unix the file is usually C<unlink>-ed just after
1N/Ait is created so it does not matter how it gets closed. On other
1N/Asystems the file may only be deleted if closed via PerlIO_close()
1N/Aand/or the program exits via C<exit>. Depending on the implementation
1N/Athere may be "race conditions" which allow other processes access to
1N/Athe file, though in general it will be safer in this regard than
1N/A=item B<PerlIO_setlinebuf(f)>
1N/AThis corresponds to setlinebuf(). Does not return a value. What
1N/Aconstitutes a "line" is implementation dependent but usually means
1N/Athat writing "\n" flushes the buffer. What happens with things like
1N/A"this\nthat" is uncertain. (Perl core uses it I<only> when "dumping";
1N/Ait has nothing to do with $| auto-flush.)
1N/A=head2 Co-existence with stdio
1N/AThere is outline support for co-existence of PerlIO with stdio.
1N/AObviously if PerlIO is implemented in terms of stdio there is no
1N/Aproblem. However in other cases then mechanisms must exist to create a
1N/AFILE * which can be passed to library code which is going to use stdio
1N/AThe first step is to add this line:
1N/A #define PERLIO_NOT_STDIO 0
1N/AI<before> including any perl header files. (This will probably become
1N/Athe default at some point). That prevents "
perlio.h" from attempting
1N/Ato #define stdio functions onto PerlIO functions.
1N/AXS code is probably better using "typemap" if it expects FILE *
1N/Aarguments. The standard typemap will be adjusted to comprehend any
1N/Achanges in this area.
1N/A=item B<PerlIO_importFILE(f,mode)>
1N/AUsed to get a PerlIO * from a FILE *.
1N/AThe mode argument should be a string as would be passed to
1N/Awill (depending upon the platform and the implementation) either
1N/Aattempt to empirically determine the mode in which I<f> is open, or
1N/AOnce called the FILE * should I<ONLY> be closed by calling
1N/AC<PerlIO_close()> on the returned PerlIO *.
1N/AThe PerlIO is set to textmode. Use PerlIO_binmode if this is
1N/Anot the desired mode.
1N/AThis is B<not> the reverse of PerlIO_exportFILE().
1N/A=item B<PerlIO_exportFILE(f,mode)>
1N/AGiven a PerlIO * create a 'native' FILE * suitable for passing to code
1N/Aexpecting to be compiled and linked with ANSI C I<
stdio.h>. The mode
1N/AIf it is NULL then - for legacy support - the FILE * is opened in same
1N/Amode as the PerlIO *.
1N/AThe fact that such a FILE * has been 'exported' is recorded, (normally
1N/Aby pushing a new :stdio "layer" onto the PerlIO *), which may affect
1N/Afuture PerlIO operations on the original PerlIO *. You should not
1N/Acall C<fclose()> on the file unless you call C<PerlIO_releaseFILE()>
1N/Ato disassociate it from the PerlIO *. (Do not use PerlIO_importFILE()
1N/Afor doing the disassociation.)
1N/ACalling this function repeatedly will create a FILE * on each call
1N/A(and will push an :stdio layer each time as well).
1N/A=item B<PerlIO_releaseFILE(p,f)>
1N/ACalling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
1N/Acomplete. It is removed from the list of 'exported' FILE *s, and the
1N/Aassociated PerlIO * should revert to its original behaviour.
1N/AUse this to disassociate a file from a PerlIO * that was associated
1N/Ausing PerlIO_exportFILE().
1N/A=item B<PerlIO_findFILE(f)>
1N/AReturns a native FILE * used by a stdio layer. If there is none, it
1N/Awill create one with PerlIO_exportFILE. In either case the FILE *
1N/Ashould be considered as belonging to PerlIO subsystem and should
1N/Aonly be closed by calling C<PerlIO_close()>.
1N/A=head2 "Fast gets" Functions
1N/AIn addition to standard-like API defined so far above there is an
1N/A"implementation" interface which allows perl to get at internals of
1N/APerlIO. The following calls correspond to the various FILE_xxx macros
1N/Adetermined by Configure - or their equivalent in other
1N/Aimplementations. This section is really of interest to only those
1N/Aconcerned with detailed perl-core behaviour, implementing a PerlIO
1N/Amapping or writing code which can make use of the "read ahead" that
1N/Ahas been done by the IO system in the same way perl does. Note that
1N/Aany code that uses these interfaces must be prepared to do things the
1N/Atraditional way if a handle does not support them.
1N/A=item B<PerlIO_fast_gets(f)>
1N/AReturns true if implementation has all the interfaces required to
1N/Aallow perl's C<sv_gets> to "bypass" normal IO mechanism. This can
1N/Avary from handle to handle.
1N/A PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
1N/A PerlIO_canset_cnt(f) && \
1N/A `Can set pointer into buffer'
1N/A=item B<PerlIO_has_cntptr(f)>
1N/AImplementation can return pointer to current position in the "buffer"
1N/Aand a count of bytes available in the buffer. Do not use this - use
1N/A=item B<PerlIO_get_cnt(f)>
1N/AReturn count of readable bytes in the buffer. Zero or negative return
1N/Ameans no more bytes available.
1N/A=item B<PerlIO_get_ptr(f)>
1N/AReturn pointer to next readable byte in buffer, accessing via the
1N/Apointer (dereferencing) is only safe if PerlIO_get_cnt() has returned
1N/Aa positive value. Only positive offsets up to value returned by
1N/APerlIO_get_cnt() are allowed.
1N/A=item B<PerlIO_set_ptrcnt(f,p,c)>
1N/ASet pointer into buffer, and a count of bytes still in the
1N/Abuffer. Should be used only to set pointer to within range implied by
1N/Aprevious calls to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>. The two
1N/Avalues I<must> be consistent with each other (implementation may only
1N/Ause one or the other or may require both).
1N/A=item B<PerlIO_canset_cnt(f)>
1N/AImplementation can adjust its idea of number of bytes in the buffer.
1N/ADo not use this - use PerlIO_fast_gets.
1N/A=item B<PerlIO_set_cnt(f,c)>
1N/AObscure - set count of bytes in the buffer. Deprecated. Only usable
1N/Aif PerlIO_canset_cnt() returns true. Currently used in only
doio.c to
1N/Aforce count less than -1 to -1. Perhaps should be PerlIO_set_empty or
1N/Asimilar. This call may actually do nothing if "count" is deduced from
1N/Apointer and a "limit". Do not use this - use PerlIO_set_ptrcnt().
1N/A=item B<PerlIO_has_base(f)>
1N/AReturns true if implementation has a buffer, and can return pointer
1N/Ato whole buffer and its size. Used by perl for B<-T> / B<-B> tests.
1N/AOther uses would be very obscure...
1N/A=item B<PerlIO_get_base(f)>
1N/AReturn I<start> of buffer. Access only positive offsets in the buffer
1N/Aup to the value returned by PerlIO_get_bufsiz().
1N/A=item B<PerlIO_get_bufsiz(f)>
1N/AReturn the I<total number of bytes> in the buffer, this is neither the
1N/Anumber that can be read, nor the amount of memory allocated to the
1N/Abuffer. Rather it is what the operating system
and/or implementation
1N/Ahappened to C<read()> (or whatever) last time IO was requested.
1N/A=head2 Other Functions
1N/A=item PerlIO_apply_layers(f,mode,layers)
1N/AThe new interface to the USE_PERLIO implementation. The layers ":crlf"
1N/Aand ":raw" are only ones allowed for other implementations and those
1N/Aare silently ignored. (As of perl5.8 ":raw" is deprecated.) Use
1N/APerlIO_binmode() below for the portable case.
1N/A=item PerlIO_binmode(f,ptype,imode,layers)
1N/AThe hook used by perl's C<binmode> operator.
1N/AB<ptype> is perl's character for the kind of IO:
1N/AB<imode> is C<O_BINARY> or C<O_TEXT>.
1N/AB<layers> is a string of layers to apply, only ":crlf" makes sense in
1N/Athe non USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in favour
1N/A PerlIO_binmode(f,ptype,O_BINARY,Nullch);
1N/A PerlIO_binmode(f,ptype,O_TEXT,":crlf");
1N/AOn Unix these calls probably have no effect whatsoever. Elsewhere
1N/Athey alter "\n" to CR,LF translation and possibly cause a special text
1N/A"end of file" indicator to be written or honoured on read. The effect
1N/Aof making the call after doing any IO to the handle depends on the
1N/Aimplementation. (It may be ignored, affect any data which is already
1N/Abuffered as well, or only apply to subsequent data.)
1N/A=item PerlIO_debug(fmt,...)
1N/APerlIO_debug is a printf()-like function which can be used for
1N/Adebugging. No return value. Its main use is inside PerlIO where using
1N/Areal printf, warn() etc. would recursively call PerlIO and be a
1N/APerlIO_debug writes to the file named by $ENV{'PERLIO_DEBUG'} typical
1N/A Bourne shells (sh, ksh, bash, zsh, ash, ...):
1N/A ./perl somescript some args
1N/A If you have the "env" utility:
1N/A set PERLIO_DEBUG=CON
1N/A perl somescript some args
1N/AIf $ENV{'PERLIO_DEBUG'} is not set PerlIO_debug() is a no-op.