Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 548 insertions, 0 deletions

diff --git a/upstream/archlinux/man1/perlapio.1perl b/upstream/archlinux/man1/perlapio.1perl
new file mode 100644
index 00000000..1750b8d6
--- /dev/null
+++ b/upstream/archlinux/man1/perlapio.1perl
@@ -0,0 +1,548 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLAPIO 1perl"
+.TH PERLAPIO 1perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perlapio \- perl's IO abstraction interface.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&  #define PERLIO_NOT_STDIO 0    /* For co\-existence with stdio only */
+\&  #include <perlio.h>           /* Usually via #include <perl.h> */
+\&
+\&  PerlIO *PerlIO_stdin(void);
+\&  PerlIO *PerlIO_stdout(void);
+\&  PerlIO *PerlIO_stderr(void);
+\&
+\&  PerlIO *PerlIO_open(const char *path,const char *mode);
+\&  PerlIO *PerlIO_fdopen(int fd, const char *mode);
+\&  PerlIO *PerlIO_reopen(const char *path, /* deprecated */
+\&          const char *mode, PerlIO *old);
+\&  int     PerlIO_close(PerlIO *f);
+\&
+\&  int     PerlIO_stdoutf(const char *fmt,...)
+\&  int     PerlIO_puts(PerlIO *f,const char *string);
+\&  int     PerlIO_putc(PerlIO *f,int ch);
+\&  SSize_t PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
+\&  int     PerlIO_printf(PerlIO *f, const char *fmt,...);
+\&  int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
+\&  int     PerlIO_flush(PerlIO *f);
+\&
+\&  int     PerlIO_fill(PerlIO *f);
+\&  int     PerlIO_eof(PerlIO *f);
+\&  int     PerlIO_error(PerlIO *f);
+\&  void    PerlIO_clearerr(PerlIO *f);
+\&
+\&  int     PerlIO_getc(PerlIO *d);
+\&  int     PerlIO_ungetc(PerlIO *f,int ch);
+\&  SSize_t PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
+\&  Size_t  PerlIO_unread(PerlIO *f,const void *vbuf, size_t count
+\&
+\&  int     PerlIO_fileno(PerlIO *f);
+\&
+\&  void    PerlIO_setlinebuf(PerlIO *f);
+\&
+\&  Off_t   PerlIO_tell(PerlIO *f);
+\&  int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
+\&  void    PerlIO_rewind(PerlIO *f);
+\&
+\&  int     PerlIO_getpos(PerlIO *f, SV *save);    /* prototype changed */
+\&  int     PerlIO_setpos(PerlIO *f, SV *saved);   /* prototype changed */
+\&
+\&  int     PerlIO_fast_gets(PerlIO *f);
+\&  int     PerlIO_has_cntptr(PerlIO *f);
+\&  SSize_t PerlIO_get_cnt(PerlIO *f);
+\&  char   *PerlIO_get_ptr(PerlIO *f);
+\&  void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t count);
+\&
+\&  int     PerlIO_canset_cnt(PerlIO *f);              /* deprecated */
+\&  void    PerlIO_set_cnt(PerlIO *f, int count);      /* deprecated */
+\&
+\&  int     PerlIO_has_base(PerlIO *f);
+\&  char   *PerlIO_get_base(PerlIO *f);
+\&  SSize_t PerlIO_get_bufsiz(PerlIO *f);
+\&
+\&  PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
+\&  FILE   *PerlIO_exportFILE(PerlIO *f, const char *mode);
+\&  FILE   *PerlIO_findFILE(PerlIO *f);
+\&  void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
+\&
+\&  int     PerlIO_apply_layers(pTHX_ PerlIO *f, const char *mode,
+\&                                                    const char *layers);
+\&  int     PerlIO_binmode(pTHX_ PerlIO *f, int ptype, int imode,
+\&                                                    const char *layers);
+\&  void    PerlIO_debug(const char *fmt,...);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl's source code, and extensions that want maximum portability,
+should use the above functions instead of those defined in ANSI C's
+\&\fIstdio.h\fR.  The perl headers (in particular "perlio.h") will
+\&\f(CW\*(C`#define\*(C'\fR them to the I/O mechanism selected at Configure time.
+.PP
+The functions are modeled on those in \fIstdio.h\fR, but parameter order
+has been "tidied up a little".
+.PP
+\&\f(CW\*(C`PerlIO *\*(C'\fR takes the place of FILE *. Like FILE * it should be
+treated as opaque (it is probably safe to assume it is a pointer to
+something).
+.PP
+There are currently two implementations:
+.IP "1. USE_STDIO" 4
+.IX Item "1. USE_STDIO"
+All above are #define'd to stdio functions or are trivial wrapper
+functions which call stdio. In this case \fIonly\fR PerlIO * is a FILE *.
+This has been the default implementation since the abstraction was
+introduced in perl5.003_02.
+.IP "2. USE_PERLIO" 4
+.IX Item "2. USE_PERLIO"
+Introduced just after perl5.7.0, this is a re-implementation of the
+above abstraction which allows perl more control over how IO is done
+as it decouples IO from the way the operating system and C library
+choose to do things. For USE_PERLIO PerlIO * has an extra layer of
+indirection \- it is a pointer-to-a-pointer.  This allows the PerlIO *
+to remain with a known value while swapping the implementation around
+underneath \fIat run time\fR. In this case all the above are true (but
+very simple) functions which call the underlying implementation.
+.Sp
+This is the only implementation for which \f(CWPerlIO_apply_layers()\fR
+does anything "interesting".
+.Sp
+The USE_PERLIO implementation is described in perliol.
+.PP
+Because "perlio.h" is a thin layer (for efficiency) the semantics of
+these functions are somewhat dependent on the underlying implementation.
+Where these variations are understood they are noted below.
+.PP
+Unless otherwise noted, functions return 0 on success, or a negative
+value (usually \f(CW\*(C`EOF\*(C'\fR which is usually \-1) and set \f(CW\*(C`errno\*(C'\fR on error.
+.IP "\fBPerlIO_stdin()\fR, \fBPerlIO_stdout()\fR, \fBPerlIO_stderr()\fR" 4
+.IX Item "PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()"
+Use these rather than \f(CW\*(C`stdin\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, \f(CW\*(C`stderr\*(C'\fR. They are written
+to look like "function calls" rather than variables because this makes
+it easier to \fImake them\fR function calls if platform cannot export data
+to loaded modules, or if (say) different "threads" might have different
+values.
+.IP "\fBPerlIO_open(path, mode)\fR, \fBPerlIO_fdopen(fd,mode)\fR" 4
+.IX Item "PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)"
+These correspond to \fBfopen()\fR/\fBfdopen()\fR and the arguments are the same.
+Return \f(CW\*(C`NULL\*(C'\fR and set \f(CW\*(C`errno\*(C'\fR if there is an error.  There may be an
+implementation limit on the number of open handles, which may be lower
+than the limit on the number of open files \- \f(CW\*(C`errno\*(C'\fR may not be set
+when \f(CW\*(C`NULL\*(C'\fR is returned if this limit is exceeded.
+.IP \fBPerlIO_reopen(path,mode,f)\fR 4
+.IX Item "PerlIO_reopen(path,mode,f)"
+While this currently exists in both implementations, perl itself
+does not use it. \fIAs perl does not use it, it is not well tested.\fR
+.Sp
+Perl prefers to \f(CW\*(C`dup\*(C'\fR the new low-level descriptor to the descriptor
+used by the existing PerlIO. This may become the behaviour of this
+function in the future.
+.IP "\fBPerlIO_printf(f,fmt,...)\fR, \fBPerlIO_vprintf(f,fmt,a)\fR" 4
+.IX Item "PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)"
+These are \fBfprintf()\fR/\fBvfprintf()\fR equivalents.
+.IP \fBPerlIO_stdoutf(fmt,...)\fR 4
+.IX Item "PerlIO_stdoutf(fmt,...)"
+This is \fBprintf()\fR equivalent. printf is #defined to this function,
+so it is (currently) legal to use \f(CW\*(C`printf(fmt,...)\*(C'\fR in perl sources.
+.IP "\fBPerlIO_read(f,buf,count)\fR, \fBPerlIO_write(f,buf,count)\fR" 4
+.IX Item "PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)"
+These correspond functionally to \fBfread()\fR and \fBfwrite()\fR but the
+arguments and return values are different.  The \fBPerlIO_read()\fR and
+\&\fBPerlIO_write()\fR signatures have been modeled on the more sane low level
+\&\fBread()\fR and \fBwrite()\fR functions instead: The "file" argument is passed
+first, there is only one "count", and the return value can distinguish
+between error and \f(CW\*(C`EOF\*(C'\fR.
+.Sp
+Returns a byte count if successful (which may be zero or
+positive), returns negative value and sets \f(CW\*(C`errno\*(C'\fR on error.
+Depending on implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was
+interrupted by a signal.
+.IP \fBPerlIO_fill(f)\fR 4
+.IX Item "PerlIO_fill(f)"
+Fills the buffer associated with \f(CW\*(C`f\*(C'\fR with data from the layer below.
+\&\f(CW\*(C`PerlIO_read\*(C'\fR calls this as part of its normal operation.  Returns 0
+upon success; \-1 on failure.
+.IP \fBPerlIO_close(f)\fR 4
+.IX Item "PerlIO_close(f)"
+Depending on implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was
+interrupted by a signal.
+.IP "\fBPerlIO_puts(f,s)\fR, \fBPerlIO_putc(f,c)\fR" 4
+.IX Item "PerlIO_puts(f,s), PerlIO_putc(f,c)"
+These correspond to \fBfputs()\fR and \fBfputc()\fR.
+Note that arguments have been revised to have "file" first.
+.IP \fBPerlIO_ungetc(f,c)\fR 4
+.IX Item "PerlIO_ungetc(f,c)"
+This corresponds to \fBungetc()\fR.  Note that arguments have been revised
+to have "file" first.  Arranges that next read operation will return
+the byte \fBc\fR.  Despite the implied "character" in the name only
+values in the range 0..0xFF are defined. Returns the byte \fBc\fR on
+success or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error.  The number of bytes that can be
+"pushed back" may vary, only 1 character is certain, and then only if
+it is the last character that was read from the handle.
+.IP \fBPerlIO_unread(f,buf,count)\fR 4
+.IX Item "PerlIO_unread(f,buf,count)"
+This allows one to unget more than a single byte.
+It effectively unshifts \f(CW\*(C`count\*(C'\fR bytes onto the beginning of the buffer 
+\&\f(CW\*(C`buf\*(C'\fR, so that the next read operation(s) will return them before
+anything else that was in the buffer.
+.Sp
+Returns the number of unread bytes.
+.IP \fBPerlIO_getc(f)\fR 4
+.IX Item "PerlIO_getc(f)"
+This corresponds to \fBgetc()\fR.
+Despite the c in the name only byte range 0..0xFF is supported.
+Returns the character read or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error.
+.IP \fBPerlIO_eof(f)\fR 4
+.IX Item "PerlIO_eof(f)"
+This corresponds to \fBfeof()\fR.  Returns a true/false indication of
+whether the handle is at end of file.  For terminal devices this may
+or may not be "sticky" depending on the implementation.  The flag is
+cleared by \fBPerlIO_seek()\fR, or \fBPerlIO_rewind()\fR.
+.IP \fBPerlIO_error(f)\fR 4
+.IX Item "PerlIO_error(f)"
+This corresponds to \fBferror()\fR.  Returns a true/false indication of
+whether there has been an IO error on the handle.
+.IP \fBPerlIO_fileno(f)\fR 4
+.IX Item "PerlIO_fileno(f)"
+This corresponds to \fBfileno()\fR, note that on some platforms, the meaning
+of "fileno" may not match Unix. Returns \-1 if the handle has no open
+descriptor associated with it.
+.IP \fBPerlIO_clearerr(f)\fR 4
+.IX Item "PerlIO_clearerr(f)"
+This corresponds to \fBclearerr()\fR, i.e., clears 'error' and (usually)
+\&'eof' flags for the "stream". Does not return a value.
+.IP \fBPerlIO_flush(f)\fR 4
+.IX Item "PerlIO_flush(f)"
+This corresponds to \fBfflush()\fR.  Sends any buffered write data to the
+underlying file.  If called with \f(CW\*(C`NULL\*(C'\fR this may flush all open
+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 \f(CW\*(C`NULL\*(C'\fR, and
+attempts to retain data on read streams either in the buffer or by
+seeking the handle to the current logical position.
+.IP \fBPerlIO_seek(f,offset,whence)\fR 4
+.IX Item "PerlIO_seek(f,offset,whence)"
+This corresponds to \fBfseek()\fR.  Sends buffered write data to the
+underlying file, or discards any buffered read data, then positions
+the file descriptor as specified by \fBoffset\fR and \fBwhence\fR (sic).
+This is the correct thing to do when switching between read and write
+on the same handle (see issues with \fBPerlIO_flush()\fR above).  Offset is
+of type \f(CW\*(C`Off_t\*(C'\fR which is a perl Configure value which may not be same
+as stdio's \f(CW\*(C`off_t\*(C'\fR.
+.IP \fBPerlIO_tell(f)\fR 4
+.IX Item "PerlIO_tell(f)"
+This corresponds to \fBftell()\fR.  Returns the current file position, or
+(Off_t) \-1 on error.  May just return value system "knows" without
+making a system call or checking the underlying file descriptor (so
+use on shared file descriptors is not safe without a
+\&\fBPerlIO_seek()\fR). Return value is of type \f(CW\*(C`Off_t\*(C'\fR which is a perl
+Configure value which may not be same as stdio's \f(CW\*(C`off_t\*(C'\fR.
+.IP "\fBPerlIO_getpos(f,p)\fR, \fBPerlIO_setpos(f,p)\fR" 4
+.IX Item "PerlIO_getpos(f,p), PerlIO_setpos(f,p)"
+These correspond (loosely) to \fBfgetpos()\fR and \fBfsetpos()\fR. Rather than
+stdio's Fpos_t they expect a "Perl Scalar Value" to be passed. What is
+stored there should be considered opaque. The layout of the data may
+vary from handle to handle.  When not using stdio or if platform does
+not have the stdio calls then they are implemented in terms of
+\&\fBPerlIO_tell()\fR and \fBPerlIO_seek()\fR.
+.IP \fBPerlIO_rewind(f)\fR 4
+.IX Item "PerlIO_rewind(f)"
+This corresponds to \fBrewind()\fR. It is usually defined as being
+.Sp
+.Vb 2
+\&    PerlIO_seek(f,(Off_t)0L, SEEK_SET);
+\&    PerlIO_clearerr(f);
+.Ve
+.IP \fBPerlIO_tmpfile()\fR 4
+.IX Item "PerlIO_tmpfile()"
+This corresponds to \fBtmpfile()\fR, i.e., returns an anonymous PerlIO or
+NULL on error.  The system will attempt to automatically delete the
+file when closed.  On Unix the file is usually \f(CW\*(C`unlink\*(C'\fR\-ed just after
+it is created so it does not matter how it gets closed. On other
+systems the file may only be deleted if closed via \fBPerlIO_close()\fR
+and/or the program exits via \f(CW\*(C`exit\*(C'\fR.  Depending on the implementation
+there may be "race conditions" which allow other processes access to
+the file, though in general it will be safer in this regard than
+ad. hoc. schemes.
+.IP \fBPerlIO_setlinebuf(f)\fR 4
+.IX Item "PerlIO_setlinebuf(f)"
+This corresponds to \fBsetlinebuf()\fR.  Does not return a value. What
+constitutes a "line" is implementation dependent but usually means
+that writing "\en" flushes the buffer.  What happens with things like
+"this\enthat" is uncertain.  (Perl core uses it \fIonly\fR when "dumping";
+it has nothing to do with $| auto-flush.)
+.SS "Co-existence with stdio"
+.IX Subsection "Co-existence with stdio"
+There is outline support for co-existence of PerlIO with stdio.
+Obviously if PerlIO is implemented in terms of stdio there is no
+problem. However in other cases then mechanisms must exist to create a
+FILE * which can be passed to library code which is going to use stdio
+calls.
+.PP
+The first step is to add this line:
+.PP
+.Vb 1
+\&   #define PERLIO_NOT_STDIO 0
+.Ve
+.PP
+\&\fIbefore\fR including any perl header files. (This will probably become
+the default at some point).  That prevents "perlio.h" from attempting
+to #define stdio functions onto PerlIO functions.
+.PP
+XS code is probably better using "typemap" if it expects FILE *
+arguments.  The standard typemap will be adjusted to comprehend any
+changes in this area.
+.IP \fBPerlIO_importFILE(f,mode)\fR 4
+.IX Item "PerlIO_importFILE(f,mode)"
+Used to get a PerlIO * from a FILE *.
+.Sp
+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 \fIf\fR is open, or
+use "r+" to indicate a read/write stream.
+.Sp
+Once called the FILE * should \fIONLY\fR be closed by calling
+\&\f(CWPerlIO_close()\fR on the returned PerlIO *.
+.Sp
+The PerlIO is set to textmode. Use PerlIO_binmode if this is
+not the desired mode.
+.Sp
+This is \fBnot\fR the reverse of \fBPerlIO_exportFILE()\fR.
+.IP \fBPerlIO_exportFILE(f,mode)\fR 4
+.IX Item "PerlIO_exportFILE(f,mode)"
+Given a PerlIO * create a 'native' FILE * suitable for passing to code
+expecting to be compiled and linked with ANSI C \fIstdio.h\fR.  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 *.
+.Sp
+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 \f(CWfclose()\fR on the file unless you call \f(CWPerlIO_releaseFILE()\fR
+to disassociate it from the PerlIO *.  (Do not use \fBPerlIO_importFILE()\fR
+for doing the disassociation.)
+.Sp
+Calling this function repeatedly will create a FILE * on each call
+(and will push an :stdio layer each time as well).
+.IP \fBPerlIO_releaseFILE(p,f)\fR 4
+.IX Item "PerlIO_releaseFILE(p,f)"
+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.
+.Sp
+Use this to disassociate a file from a PerlIO * that was associated
+using \fBPerlIO_exportFILE()\fR.
+.IP \fBPerlIO_findFILE(f)\fR 4
+.IX Item "PerlIO_findFILE(f)"
+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 as belonging to PerlIO subsystem and should
+only be closed by calling \f(CWPerlIO_close()\fR.
+.SS """Fast gets"" Functions"
+.IX Subsection """Fast gets"" Functions"
+In addition to standard-like API defined so far above there is an
+"implementation" interface which allows perl to get at internals of
+PerlIO.  The following calls correspond to the various FILE_xxx macros
+determined by Configure \- or their equivalent in other
+implementations. This section is really of interest to only those
+concerned with detailed perl-core behaviour, implementing a PerlIO
+mapping or writing code which can make use of the "read ahead" that
+has been done by the IO system in the same way perl does. Note that
+any code that uses these interfaces must be prepared to do things the
+traditional way if a handle does not support them.
+.IP \fBPerlIO_fast_gets(f)\fR 4
+.IX Item "PerlIO_fast_gets(f)"
+Returns true if implementation has all the interfaces required to
+allow perl's \f(CW\*(C`sv_gets\*(C'\fR to "bypass" normal IO mechanism.  This can
+vary from handle to handle.
+.Sp
+.Vb 3
+\&  PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \e
+\&                        PerlIO_canset_cnt(f) && \e
+\&                        \*(AqCan set pointer into buffer\*(Aq
+.Ve
+.IP \fBPerlIO_has_cntptr(f)\fR 4
+.IX Item "PerlIO_has_cntptr(f)"
+Implementation can return pointer to current position in the "buffer"
+and a count of bytes available in the buffer.  Do not use this \- use
+PerlIO_fast_gets.
+.IP \fBPerlIO_get_cnt(f)\fR 4
+.IX Item "PerlIO_get_cnt(f)"
+Return count of readable bytes in the buffer. Zero or negative return
+means no more bytes available.
+.IP \fBPerlIO_get_ptr(f)\fR 4
+.IX Item "PerlIO_get_ptr(f)"
+Return pointer to next readable byte in buffer, accessing via the
+pointer (dereferencing) is only safe if \fBPerlIO_get_cnt()\fR has returned
+a positive value.  Only positive offsets up to value returned by
+\&\fBPerlIO_get_cnt()\fR are allowed.
+.IP \fBPerlIO_set_ptrcnt(f,p,c)\fR 4
+.IX Item "PerlIO_set_ptrcnt(f,p,c)"
+Set pointer into buffer, and a count of bytes still in the
+buffer. Should be used only to set pointer to within range implied by
+previous calls to \f(CW\*(C`PerlIO_get_ptr\*(C'\fR and \f(CW\*(C`PerlIO_get_cnt\*(C'\fR. The two
+values \fImust\fR be consistent with each other (implementation may only
+use one or the other or may require both).
+.IP \fBPerlIO_canset_cnt(f)\fR 4
+.IX Item "PerlIO_canset_cnt(f)"
+Implementation can adjust its idea of number of bytes in the buffer.
+Do not use this \- use PerlIO_fast_gets.
+.IP \fBPerlIO_set_cnt(f,c)\fR 4
+.IX Item "PerlIO_set_cnt(f,c)"
+Obscure \- set count of bytes in the buffer. Deprecated.  Only usable
+if \fBPerlIO_canset_cnt()\fR returns true.  Currently used in only doio.c to
+force count less than \-1 to \-1.  Perhaps should be PerlIO_set_empty or
+similar.  This call may actually do nothing if "count" is deduced from
+pointer and a "limit".  Do not use this \- use \fBPerlIO_set_ptrcnt()\fR.
+.IP \fBPerlIO_has_base(f)\fR 4
+.IX Item "PerlIO_has_base(f)"
+Returns true if implementation has a buffer, and can return pointer
+to whole buffer and its size. Used by perl for \fB\-T\fR / \fB\-B\fR tests.
+Other uses would be very obscure...
+.IP \fBPerlIO_get_base(f)\fR 4
+.IX Item "PerlIO_get_base(f)"
+Return \fIstart\fR of buffer. Access only positive offsets in the buffer
+up to the value returned by \fBPerlIO_get_bufsiz()\fR.
+.IP \fBPerlIO_get_bufsiz(f)\fR 4
+.IX Item "PerlIO_get_bufsiz(f)"
+Return the \fItotal number of bytes\fR in the buffer, this is neither the
+number that can be read, nor the amount of memory allocated to the
+buffer. Rather it is what the operating system and/or implementation
+happened to \f(CWread()\fR (or whatever) last time IO was requested.
+.SS "Other Functions"
+.IX Subsection "Other Functions"
+.IP "PerlIO_apply_layers(aTHX_ f,mode,layers)" 4
+.IX Item "PerlIO_apply_layers(aTHX_ f,mode,layers)"
+The new interface to the USE_PERLIO implementation. The layers ":crlf"
+and ":raw" are the only ones allowed for other implementations and those
+are silently ignored. (As of perl5.8 ":raw" is deprecated.)  Use
+\&\fBPerlIO_binmode()\fR below for the portable case.
+.IP "PerlIO_binmode(aTHX_ f,ptype,imode,layers)" 4
+.IX Item "PerlIO_binmode(aTHX_ f,ptype,imode,layers)"
+The hook used by perl's \f(CW\*(C`binmode\*(C'\fR operator.
+\&\fBptype\fR is perl's character for the kind of IO:
+.RS 4
+.IP "'<' read" 8
+.IX Item "'<' read"
+.PD 0
+.IP "'>' write" 8
+.IX Item "'>' write"
+.IP "'+' read/write" 8
+.IX Item "'+' read/write"
+.RE
+.RS 4
+.PD
+.Sp
+\&\fBimode\fR is \f(CW\*(C`O_BINARY\*(C'\fR or \f(CW\*(C`O_TEXT\*(C'\fR.
+.Sp
+\&\fBlayers\fR 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.)
+.Sp
+Portable cases are:
+.Sp
+.Vb 3
+\&    PerlIO_binmode(aTHX_ f,ptype,O_BINARY,NULL);
+\&and
+\&    PerlIO_binmode(aTHX_ f,ptype,O_TEXT,":crlf");
+.Ve
+.Sp
+On Unix these calls probably have no effect whatsoever.  Elsewhere
+they alter "\en" to CR,LF translation and possibly cause a special text
+"end of file" indicator to be written or honoured on read. The effect
+of making the call after doing any IO to the handle depends on the
+implementation. (It may be ignored, affect any data which is already
+buffered as well, or only apply to subsequent data.)
+.RE
+.IP PerlIO_debug(fmt,...) 4
+.IX Item "PerlIO_debug(fmt,...)"
+PerlIO_debug is a \fBprintf()\fR\-like function which can be used for
+debugging.  No return value. Its main use is inside PerlIO where using
+real printf, \fBwarn()\fR etc. would recursively call PerlIO and be a
+problem.
+.Sp
+PerlIO_debug writes to the file named by \f(CW$ENV\fR{'PERLIO_DEBUG'} or defaults
+to stderr if the environment variable is not defined. Typical
+use might be
+.Sp
+.Vb 2
+\&  Bourne shells (sh, ksh, bash, zsh, ash, ...):
+\&   PERLIO_DEBUG=/tmp/perliodebug.log ./perl \-Di somescript some args
+\&
+\&  Csh/Tcsh:
+\&   setenv PERLIO_DEBUG /tmp/perliodebug.log
+\&   ./perl \-Di somescript some args
+\&
+\&  If you have the "env" utility:
+\&   env PERLIO_DEBUG=/tmp/perliodebug.log ./perl \-Di somescript args
+\&
+\&  Win32:
+\&   set PERLIO_DEBUG=perliodebug.log
+\&   perl \-Di somescript some args
+.Ve
+.Sp
+On a Perl built without \f(CW\*(C`\-DDEBUGGING\*(C'\fR, or when the \f(CW\*(C`\-Di\*(C'\fR command-line switch
+is not specified, or under taint, \fBPerlIO_debug()\fR is a no-op.