Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 422 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/PerlIO.3pm b/upstream/mageia-cauldron/man3pm/PerlIO.3pm
new file mode 100644
index 00000000..3a020697
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/PerlIO.3pm
@@ -0,0 +1,422 @@
+.\" -*- 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 "PerlIO 3pm"
+.TH PerlIO 3pm 2023-11-28 "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
+PerlIO \- On demand loader for PerlIO layers and root of PerlIO::* name space
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&  # support platform\-native and CRLF text files
+\&  open(my $fh, "<:crlf", "my.txt") or die "open failed: $!";
+\&
+\&  # append UTF\-8 encoded text
+\&  open(my $fh, ">>:encoding(UTF\-8)", "some.log")
+\&    or die "open failed: $!";
+\&
+\&  # portably open a binary file for reading
+\&  open(my $fh, "<", "his.jpg") or die "open failed: $!";
+\&  binmode($fh) or die "binmode failed: $!";
+\&
+\&  Shell:
+\&    PERLIO=:perlio perl ....
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+When an undefined layer 'foo' is encountered in an \f(CW\*(C`open\*(C'\fR or
+\&\f(CW\*(C`binmode\*(C'\fR layer specification then C code performs the equivalent of:
+.PP
+.Vb 1
+\&  use PerlIO \*(Aqfoo\*(Aq;
+.Ve
+.PP
+The Perl code in PerlIO.pm then attempts to locate a layer by doing
+.PP
+.Vb 1
+\&  require PerlIO::foo;
+.Ve
+.PP
+Otherwise the \f(CW\*(C`PerlIO\*(C'\fR package is a place holder for additional
+PerlIO related functions.
+.SS Layers
+.IX Subsection "Layers"
+Generally speaking, PerlIO layers (previously sometimes referred to as
+"disciplines") are an ordered stack applied to a filehandle (specified as
+a space\- or colon-separated list, conventionally written with a leading
+colon).  Each layer performs some operation on any input or output, except
+when bypassed such as with \f(CW\*(C`sysread\*(C'\fR or \f(CW\*(C`syswrite\*(C'\fR.  Read operations go
+through the stack in the order they are set (left to right), and write
+operations in the reverse order.
+.PP
+There are also layers which actually just set flags on lower layers, or
+layers that modify the current stack but don't persist on the stack
+themselves; these are referred to as pseudo-layers.
+.PP
+When opening a handle, it will be opened with any layers specified
+explicitly in the \fBopen()\fR call (or the platform defaults, if specified as
+a colon with no following layers).
+.PP
+If layers are not explicitly specified, the handle will be opened with the
+layers specified by the ${^OPEN} variable (usually
+set by using the open pragma for a lexical scope, or the \f(CW\*(C`\-C\*(C'\fR
+command-line switch or \f(CW\*(C`PERL_UNICODE\*(C'\fR environment variable for the main
+program scope).
+.PP
+If layers are not specified in the \fBopen()\fR call or \f(CW\*(C`${^OPEN}\*(C'\fR variable,
+the handle will be opened with the default layer stack configured for that
+architecture; see "Defaults and how to override them".
+.PP
+Some layers will automatically insert required lower level layers if not
+present; for example \f(CW\*(C`:perlio\*(C'\fR will insert \f(CW\*(C`:unix\*(C'\fR below itself for low
+level IO, and \f(CW\*(C`:encoding\*(C'\fR will insert the platform defaults for buffered
+IO.
+.PP
+The \f(CW\*(C`binmode\*(C'\fR function can be called on an opened handle to push
+additional layers onto the stack, which may also modify the existing
+layers.  \f(CW\*(C`binmode\*(C'\fR called with no layers will remove or unset any
+existing layers which transform the byte stream, making the handle
+suitable for binary data.
+.PP
+The following layers are currently defined:
+.IP :unix 4
+.IX Item ":unix"
+Lowest level layer which provides basic PerlIO operations in terms of
+UNIX/POSIX numeric file descriptor calls
+(\fBopen()\fR, \fBread()\fR, \fBwrite()\fR, \fBlseek()\fR, \fBclose()\fR).
+It is used even on non-Unix architectures, and most other layers operate on
+top of it.
+.IP :stdio 4
+.IX Item ":stdio"
+Layer which calls \f(CW\*(C`fread\*(C'\fR, \f(CW\*(C`fwrite\*(C'\fR and \f(CW\*(C`fseek\*(C'\fR/\f(CW\*(C`ftell\*(C'\fR etc.  Note
+that as this is "real" stdio it will ignore any layers beneath it and
+go straight to the operating system via the C library as usual.
+This layer implements both low level IO and buffering, but is rarely used
+on modern architectures.
+.IP :perlio 4
+.IX Item ":perlio"
+A from scratch implementation of buffering for PerlIO. Provides fast
+access to the buffer for \f(CW\*(C`sv_gets\*(C'\fR which implements Perl's readline/<>
+and in general attempts to minimize data copying.
+.Sp
+\&\f(CW\*(C`:perlio\*(C'\fR will insert a \f(CW\*(C`:unix\*(C'\fR layer below itself to do low level IO.
+.IP :crlf 4
+.IX Item ":crlf"
+A layer that implements DOS/Windows like CRLF line endings.  On read
+converts pairs of CR,LF to a single "\en" newline character.  On write
+converts each "\en" to a CR,LF pair.  Note that this layer will silently
+refuse to be pushed on top of itself.
+.Sp
+It currently does \fInot\fR mimic MS-DOS as far as treating of Control-Z
+as being an end-of-file marker.
+.Sp
+On DOS/Windows like architectures where this layer is part of the defaults,
+it also acts like the \f(CW\*(C`:perlio\*(C'\fR layer, and removing the CRLF translation
+(such as with \f(CW\*(C`:raw\*(C'\fR) will only unset the CRLF translation flag.  Since
+Perl 5.14, you can also apply another \f(CW\*(C`:crlf\*(C'\fR layer later, such as when
+the CRLF translation must occur after an encoding layer.  On other
+architectures, it is a mundane CRLF translation layer and can be added and
+removed normally.
+.Sp
+.Vb 3
+\&    # translate CRLF after encoding on Perl 5.14 or newer
+\&    binmode $fh, ":raw:encoding(UTF\-16LE):crlf"
+\&      or die "binmode failed: $!";
+.Ve
+.IP :utf8 4
+.IX Item ":utf8"
+Pseudo-layer that declares that the stream accepts Perl's \fIinternal\fR
+upgraded encoding of characters, which is approximately UTF\-8 on ASCII
+machines, but UTF-EBCDIC on EBCDIC machines.  This allows any character
+Perl can represent to be read from or written to the stream.
+.Sp
+This layer (which actually sets a flag on the preceding layer, and is
+implicitly set by any \f(CW\*(C`:encoding\*(C'\fR layer) does not translate or validate
+byte sequences.  It instead indicates that the byte stream will have been
+arranged by other layers to be provided in Perl's internal upgraded
+encoding, which Perl code (and correctly written XS code) will interpret
+as decoded Unicode characters.
+.Sp
+\&\fBCAUTION\fR: Do not use this layer to translate from UTF\-8 bytes, as
+invalid UTF\-8 or binary data will result in malformed Perl strings.  It is
+unlikely to produce invalid UTF\-8 when used for output, though it will
+instead produce UTF-EBCDIC on EBCDIC systems.  The \f(CW:encoding(UTF\-8)\fR
+layer (hyphen is significant) is preferred as it will ensure translation
+between valid UTF\-8 bytes and valid Unicode characters.
+.IP :bytes 4
+.IX Item ":bytes"
+This is the inverse of the \f(CW\*(C`:utf8\*(C'\fR pseudo-layer.  It turns off the flag
+on the layer below so that data read from it is considered to
+be Perl's internal downgraded encoding, thus interpreted as the native
+single-byte encoding of Latin\-1 or EBCDIC.  Likewise on output Perl will
+warn if a "wide" character (a codepoint not in the range 0..255) is
+written to a such a stream.
+.Sp
+This is very dangerous to push on a handle using an \f(CW\*(C`:encoding\*(C'\fR layer,
+as such a layer assumes to be working with Perl's internal upgraded
+encoding, so you will likely get a mangled result.  Instead use \f(CW\*(C`:raw\*(C'\fR or
+\&\f(CW\*(C`:pop\*(C'\fR to remove encoding layers.
+.IP :raw 4
+.IX Item ":raw"
+The \f(CW\*(C`:raw\*(C'\fR pseudo-layer is \fIdefined\fR as being identical to calling
+\&\f(CWbinmode($fh)\fR \- the stream is made suitable for passing binary data,
+i.e. each byte is passed as-is. The stream will still be buffered
+(but this was not always true before Perl 5.14).
+.Sp
+In Perl 5.6 and some books the \f(CW\*(C`:raw\*(C'\fR layer is documented as the inverse
+of the \f(CW\*(C`:crlf\*(C'\fR layer. That is no longer the case \- other layers which
+would alter the binary nature of the stream are also disabled.  If you
+want UNIX line endings on a platform that normally does CRLF translation,
+but still want UTF\-8 or encoding defaults, the appropriate thing to do is
+to add \f(CW\*(C`:perlio\*(C'\fR to the PERLIO environment variable, or open the handle
+explicitly with that layer, to replace the platform default of \f(CW\*(C`:crlf\*(C'\fR.
+.Sp
+The implementation of \f(CW\*(C`:raw\*(C'\fR is as a pseudo-layer which when "pushed"
+pops itself and then any layers which would modify the binary data stream.
+(Undoing \f(CW\*(C`:utf8\*(C'\fR and \f(CW\*(C`:crlf\*(C'\fR may be implemented by clearing flags
+rather than popping layers but that is an implementation detail.)
+.Sp
+As a consequence of the fact that \f(CW\*(C`:raw\*(C'\fR normally pops layers,
+it usually only makes sense to have it as the only or first element in
+a layer specification.  When used as the first element it provides
+a known base on which to build e.g.
+.Sp
+.Vb 2
+\&    open(my $fh,">:raw:encoding(UTF\-8)",...)
+\&      or die "open failed: $!";
+.Ve
+.Sp
+will construct a "binary" stream regardless of the platform defaults,
+but then enable UTF\-8 translation.
+.IP :pop 4
+.IX Item ":pop"
+A pseudo-layer that removes the top-most layer. Gives Perl code a
+way to manipulate the layer stack.  Note that \f(CW\*(C`:pop\*(C'\fR only works on
+real layers and will not undo the effects of pseudo-layers or flags
+like \f(CW\*(C`:utf8\*(C'\fR.  An example of a possible use might be:
+.Sp
+.Vb 7
+\&    open(my $fh,...) or die "open failed: $!";
+\&    ...
+\&    binmode($fh,":encoding(...)") or die "binmode failed: $!";
+\&    # next chunk is encoded
+\&    ...
+\&    binmode($fh,":pop") or die "binmode failed: $!";
+\&    # back to un\-encoded
+.Ve
+.Sp
+A more elegant (and safer) interface is needed.
+.SS "Custom Layers"
+.IX Subsection "Custom Layers"
+It is possible to write custom layers in addition to the above builtin
+ones, both in C/XS and Perl, as a module named \f(CW\*(C`PerlIO::<layer name>\*(C'\fR.
+Some custom layers come with the Perl distribution.
+.IP :encoding 4
+.IX Item ":encoding"
+Use \f(CW:encoding(ENCODING)\fR to transparently do character set and encoding
+transformations, for example from Shift-JIS to Unicode.  Note that an
+\&\f(CW\*(C`:encoding\*(C'\fR also enables \f(CW\*(C`:utf8\*(C'\fR.  See PerlIO::encoding for more
+information.
+.IP :mmap 4
+.IX Item ":mmap"
+A layer which implements "reading" of files by using \f(CWmmap()\fR to
+make a (whole) file appear in the process's address space, and then
+using that as PerlIO's "buffer". This \fImay\fR be faster in certain
+circumstances for large files, and may result in less physical memory
+use when multiple processes are reading the same file.
+.Sp
+Files which are not \f(CWmmap()\fR\-able revert to behaving like the \f(CW\*(C`:perlio\*(C'\fR
+layer. Writes also behave like the \f(CW\*(C`:perlio\*(C'\fR layer, as \f(CWmmap()\fR for write
+needs extra house-keeping (to extend the file) which negates any advantage.
+.Sp
+The \f(CW\*(C`:mmap\*(C'\fR layer will not exist if the platform does not support \f(CWmmap()\fR.
+See PerlIO::mmap for more information.
+.IP :via 4
+.IX Item ":via"
+\&\f(CW:via(MODULE)\fR allows a transformation to be applied by an arbitrary Perl
+module, for example compression / decompression, encryption / decryption.
+See PerlIO::via for more information.
+.IP :scalar 4
+.IX Item ":scalar"
+A layer implementing "in memory" files using scalar variables,
+automatically used in place of the platform defaults for IO when opening
+such a handle.  As such, the scalar is expected to act like a file, only
+containing or storing bytes.  See PerlIO::scalar for more information.
+.SS "Alternatives to raw"
+.IX Subsection "Alternatives to raw"
+To get a binary stream an alternate method is to use:
+.PP
+.Vb 2
+\&    open(my $fh,"<","whatever") or die "open failed: $!";
+\&    binmode($fh) or die "binmode failed: $!";
+.Ve
+.PP
+This has the advantage of being backward compatible with older versions
+of Perl that did not use PerlIO or where \f(CW\*(C`:raw\*(C'\fR was buggy (as it was
+before Perl 5.14).
+.PP
+To get an unbuffered stream specify an unbuffered layer (e.g. \f(CW\*(C`:unix\*(C'\fR)
+in the open call:
+.PP
+.Vb 1
+\&    open(my $fh,"<:unix",$path) or die "open failed: $!";
+.Ve
+.SS "Defaults and how to override them"
+.IX Subsection "Defaults and how to override them"
+If the platform is MS-DOS like and normally does CRLF to "\en"
+translation for text files then the default layers are:
+.PP
+.Vb 1
+\&  :unix:crlf
+.Ve
+.PP
+Otherwise if \f(CW\*(C`Configure\*(C'\fR found out how to do "fast" IO using the system's
+stdio (not common on modern architectures), then the default layers are:
+.PP
+.Vb 1
+\&  :stdio
+.Ve
+.PP
+Otherwise the default layers are
+.PP
+.Vb 1
+\&  :unix:perlio
+.Ve
+.PP
+Note that the "default stack" depends on the operating system and on the
+Perl version, and both the compile-time and runtime configurations of
+Perl.  The default can be overridden by setting the environment variable
+PERLIO to a space or colon separated list of layers, however this cannot
+be used to set layers that require loading modules like \f(CW\*(C`:encoding\*(C'\fR.
+.PP
+This can be used to see the effect of/bugs in the various layers e.g.
+.PP
+.Vb 3
+\&  cd .../perl/t
+\&  PERLIO=:stdio  ./perl harness
+\&  PERLIO=:perlio ./perl harness
+.Ve
+.PP
+For the various values of PERLIO see "PERLIO" in perlrun.
+.PP
+The following table summarizes the default layers on UNIX-like and
+DOS-like platforms and depending on the setting of \f(CW$ENV{PERLIO}\fR:
+.PP
+.Vb 5
+\& PERLIO     UNIX\-like                   DOS\-like
+\& \-\-\-\-\-\-     \-\-\-\-\-\-\-\-\-                   \-\-\-\-\-\-\-\-
+\& unset / "" :unix:perlio / :stdio [1]   :unix:crlf
+\& :stdio     :stdio                      :stdio
+\& :perlio    :unix:perlio                :unix:perlio
+\&
+\& # [1] ":stdio" if Configure found out how to do "fast stdio" (depends
+\& # on the stdio implementation) and in Perl 5.8, else ":unix:perlio"
+.Ve
+.SS "Querying the layers of filehandles"
+.IX Subsection "Querying the layers of filehandles"
+The following returns the \fBnames\fR of the PerlIO layers on a filehandle.
+.PP
+.Vb 1
+\&   my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH".
+.Ve
+.PP
+The layers are returned in the order an \fBopen()\fR or \fBbinmode()\fR call would
+use them, and without colons.
+.PP
+By default the layers from the input side of the filehandle are
+returned; to get the output side, use the optional \f(CW\*(C`output\*(C'\fR argument:
+.PP
+.Vb 1
+\&   my @layers = PerlIO::get_layers($fh, output => 1);
+.Ve
+.PP
+(Usually the layers are identical on either side of a filehandle but
+for example with sockets there may be differences.)
+.PP
+There is no \fBset_layers()\fR, nor does \fBget_layers()\fR return a tied array
+mirroring the stack, or anything fancy like that.  This is not
+accidental or unintentional.  The PerlIO layer stack is a bit more
+complicated than just a stack (see for example the behaviour of \f(CW\*(C`:raw\*(C'\fR).
+You are supposed to use \fBopen()\fR and \fBbinmode()\fR to manipulate the stack.
+.PP
+\&\fBImplementation details follow, please close your eyes.\fR
+.PP
+The arguments to layers are by default returned in parentheses after
+the name of the layer, and certain layers (like \f(CW\*(C`:utf8\*(C'\fR) are not real
+layers but instead flags on real layers; to get all of these returned
+separately, use the optional \f(CW\*(C`details\*(C'\fR argument:
+.PP
+.Vb 1
+\&   my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);
+.Ve
+.PP
+The result will be up to be three times the number of layers:
+the first element will be a name, the second element the arguments
+(unspecified arguments will be \f(CW\*(C`undef\*(C'\fR), the third element the flags,
+the fourth element a name again, and so forth.
+.PP
+\&\fBYou may open your eyes now.\fR
+.SH AUTHOR
+.IX Header "AUTHOR"
+Nick Ing-Simmons <nick@ing\-simmons.net>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+"binmode" in perlfunc, "open" in perlfunc, perlunicode, perliol,
+Encode