Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 327 insertions, 0 deletions

diff --git a/upstream/archlinux/man1/perlclib.1perl b/upstream/archlinux/man1/perlclib.1perl
new file mode 100644
index 00000000..148ae4d7
--- /dev/null
+++ b/upstream/archlinux/man1/perlclib.1perl
@@ -0,0 +1,327 @@
+.\" -*- 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 "PERLCLIB 1perl"
+.TH PERLCLIB 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
+perlclib \- Internal replacements for standard C library functions
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+One thing Perl porters should note is that \fIperl\fR doesn't tend to use that
+much of the C standard library internally; you'll see very little use of, 
+for example, the \fIctype.h\fR functions in there. This is because Perl
+tends to reimplement or abstract standard library functions, so that we
+know exactly how they're going to operate.
+.PP
+This is a reference card for people who are familiar with the C library
+and who want to do things the Perl way; to tell them which functions
+they ought to use instead of the more normal C functions.
+.SS Conventions
+.IX Subsection "Conventions"
+In the following tables:
+.ie n .IP """t""" 3
+.el .IP \f(CWt\fR 3
+.IX Item "t"
+is a type.
+.ie n .IP """p""" 3
+.el .IP \f(CWp\fR 3
+.IX Item "p"
+is a pointer.
+.ie n .IP """n""" 3
+.el .IP \f(CWn\fR 3
+.IX Item "n"
+is a number.
+.ie n .IP """s""" 3
+.el .IP \f(CWs\fR 3
+.IX Item "s"
+is a string.
+.PP
+\&\f(CW\*(C`sv\*(C'\fR, \f(CW\*(C`av\*(C'\fR, \f(CW\*(C`hv\*(C'\fR, etc. represent variables of their respective types.
+.SS "File Operations"
+.IX Subsection "File Operations"
+Instead of the \fIstdio.h\fR functions, you should use the Perl abstraction
+layer. Instead of \f(CW\*(C`FILE*\*(C'\fR types, you need to be handling \f(CW\*(C`PerlIO*\*(C'\fR
+types.  Don't forget that with the new PerlIO layered I/O abstraction 
+\&\f(CW\*(C`FILE*\*(C'\fR types may not even be available. See also the \f(CW\*(C`perlapio\*(C'\fR
+documentation for more information about the following functions:
+.PP
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& stdin                       PerlIO_stdin()
+\& stdout                      PerlIO_stdout()
+\& stderr                      PerlIO_stderr()
+\&
+\& fopen(fn, mode)             PerlIO_open(fn, mode)
+\& freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Dep\-
+\&                               recated)
+\& fflush(stream)              PerlIO_flush(perlio)
+\& fclose(stream)              PerlIO_close(perlio)
+.Ve
+.SS "File Input and Output"
+.IX Subsection "File Input and Output"
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)
+\&
+\& [f]getc(stream)             PerlIO_getc(perlio)
+\& [f]putc(stream, n)          PerlIO_putc(perlio, n)
+\& ungetc(n, stream)           PerlIO_ungetc(perlio, n)
+.Ve
+.PP
+Note that the PerlIO equivalents of \f(CW\*(C`fread\*(C'\fR and \f(CW\*(C`fwrite\*(C'\fR are slightly
+different from their C library counterparts:
+.PP
+.Vb 2
+\& fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
+\& fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)
+\&
+\& fputs(s, stream)            PerlIO_puts(perlio, s)
+.Ve
+.PP
+There is no equivalent to \f(CW\*(C`fgets\*(C'\fR; one should use \f(CW\*(C`sv_gets\*(C'\fR instead:
+.PP
+.Vb 1
+\& fgets(s, n, stream)         sv_gets(sv, perlio, append)
+.Ve
+.SS "File Positioning"
+.IX Subsection "File Positioning"
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& feof(stream)                PerlIO_eof(perlio)
+\& fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
+\& rewind(stream)              PerlIO_rewind(perlio)
+\&
+\& fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
+\& fsetpos(stream, p)          PerlIO_setpos(perlio, sv)
+\&
+\& ferror(stream)              PerlIO_error(perlio)
+\& clearerr(stream)            PerlIO_clearerr(perlio)
+.Ve
+.SS "Memory Management and String Handling"
+.IX Subsection "Memory Management and String Handling"
+.Vb 1
+\& Instead Of:                    Use:
+\&
+\& t* p = malloc(n)               Newx(p, n, t)
+\& t* p = calloc(n, s)            Newxz(p, n, t)
+\& p = realloc(p, n)              Renew(p, n, t)
+\& memcpy(dst, src, n)            Copy(src, dst, n, t)
+\& memmove(dst, src, n)           Move(src, dst, n, t)
+\& memcpy(dst, src, sizeof(t))    StructCopy(src, dst, t)
+\& memset(dst, 0, n * sizeof(t))  Zero(dst, n, t)
+\& memzero(dst, 0)                Zero(dst, n, char)
+\& free(p)                        Safefree(p)
+\&
+\& strdup(p)                      savepv(p)
+\& strndup(p, n)                  savepvn(p, n) (Hey, strndup doesn\*(Aqt
+\&                                               exist!)
+\&
+\& strstr(big, little)            instr(big, little)
+\& strcmp(s1, s2)                 strLE(s1, s2) / strEQ(s1, s2)
+\&                                              / strGT(s1,s2)
+\& strncmp(s1, s2, n)             strnNE(s1, s2, n) / strnEQ(s1, s2, n)
+\&
+\& memcmp(p1, p2, n)              memNE(p1, p2, n)
+\& !memcmp(p1, p2, n)             memEQ(p1, p2, n)
+.Ve
+.PP
+Notice the different order of arguments to \f(CW\*(C`Copy\*(C'\fR and \f(CW\*(C`Move\*(C'\fR than used
+in \f(CW\*(C`memcpy\*(C'\fR and \f(CW\*(C`memmove\*(C'\fR.
+.PP
+Most of the time, though, you'll want to be dealing with SVs internally
+instead of raw \f(CW\*(C`char *\*(C'\fR strings:
+.PP
+.Vb 6
+\& strlen(s)                   sv_len(sv)
+\& strcpy(dt, src)             sv_setpv(sv, s)
+\& strncpy(dt, src, n)         sv_setpvn(sv, s, n)
+\& strcat(dt, src)             sv_catpv(sv, s)
+\& strncat(dt, src)            sv_catpvn(sv, s)
+\& sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)
+.Ve
+.PP
+Note also the existence of \f(CW\*(C`sv_catpvf\*(C'\fR and \f(CW\*(C`sv_vcatpvfn\*(C'\fR, combining
+concatenation with formatting.
+.PP
+Sometimes instead of zeroing the allocated heap by using \fBNewxz()\fR you
+should consider "poisoning" the data.  This means writing a bit
+pattern into it that should be illegal as pointers (and floating point
+numbers), and also hopefully surprising enough as integers, so that
+any code attempting to use the data without forethought will break
+sooner rather than later.  Poisoning can be done using the \fBPoison()\fR
+macros, which have similar arguments to \fBZero()\fR:
+.PP
+.Vb 4
+\& PoisonWith(dst, n, t, b)    scribble memory with byte b
+\& PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
+\& PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
+\& Poison(dst, n, t)           equal to PoisonFree(dst, n, t)
+.Ve
+.SS "Character Class Tests"
+.IX Subsection "Character Class Tests"
+There are several types of character class tests that Perl implements.
+The only ones described here are those that directly correspond to C
+library functions that operate on 8\-bit characters, but there are
+equivalents that operate on wide characters, and UTF\-8 encoded strings.
+All are more fully described in "Character classification" in perlapi and
+"Character case changing" in perlapi.
+.PP
+The C library routines listed in the table below return values based on
+the current locale.  Use the entries in the final column for that
+functionality.  The other two columns always assume a POSIX (or C)
+locale.  The entries in the ASCII column are only meaningful for ASCII
+inputs, returning FALSE for anything else.  Use these only when you
+\&\fBknow\fR that is what you want.  The entries in the Latin1 column assume
+that the non-ASCII 8\-bit characters are as Unicode defines, them, the
+same as ISO\-8859\-1, often called Latin 1.
+.PP
+.Vb 1
+\& Instead Of:  Use for ASCII:   Use for Latin1:      Use for locale:
+\&
+\& isalnum(c)  isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
+\& isalpha(c)  isALPHA(c)        isALPHA_L1(c)        isALPHA_LC(u )
+\& isascii(c)  isASCII(c)                             isASCII_LC(c)
+\& isblank(c)  isBLANK(c)        isBLANK_L1(c)        isBLANK_LC(c)
+\& iscntrl(c)  isCNTRL(c)        isCNTRL_L1(c)        isCNTRL_LC(c)
+\& isdigit(c)  isDIGIT(c)        isDIGIT_L1(c)        isDIGIT_LC(c)
+\& isgraph(c)  isGRAPH(c)        isGRAPH_L1(c)        isGRAPH_LC(c)
+\& islower(c)  isLOWER(c)        isLOWER_L1(c)        isLOWER_LC(c)
+\& isprint(c)  isPRINT(c)        isPRINT_L1(c)        isPRINT_LC(c)
+\& ispunct(c)  isPUNCT(c)        isPUNCT_L1(c)        isPUNCT_LC(c)
+\& isspace(c)  isSPACE(c)        isSPACE_L1(c)        isSPACE_LC(c)
+\& isupper(c)  isUPPER(c)        isUPPER_L1(c)        isUPPER_LC(c)
+\& isxdigit(c) isXDIGIT(c)       isXDIGIT_L1(c)       isXDIGIT_LC(c)
+\&
+\& tolower(c)  toLOWER(c)        toLOWER_L1(c)
+\& toupper(c)  toUPPER(c)
+.Ve
+.PP
+To emphasize that you are operating only on ASCII characters, you can
+append \f(CW\*(C`_A\*(C'\fR to each of the macros in the ASCII column: \f(CW\*(C`isALPHA_A\*(C'\fR,
+\&\f(CW\*(C`isDIGIT_A\*(C'\fR, and so on.
+.PP
+(There is no entry in the Latin1 column for \f(CW\*(C`isascii\*(C'\fR even though there
+is an \f(CW\*(C`isASCII_L1\*(C'\fR, which is identical to \f(CW\*(C`isASCII\*(C'\fR;  the
+latter name is clearer.  There is no entry in the Latin1 column for
+\&\f(CW\*(C`toupper\*(C'\fR because the result can be non\-Latin1.  You have to use
+\&\f(CW\*(C`toUPPER_uvchr\*(C'\fR, as described in "Character case changing" in perlapi.)
+.SS "\fIstdlib.h\fP functions"
+.IX Subsection "stdlib.h functions"
+.Vb 1
+\& Instead Of:                 Use:
+\&
+\& atof(s)                     Atof(s)
+\& atoi(s)                     grok_atoUV(s, &uv, &e)
+\& atol(s)                     grok_atoUV(s, &uv, &e)
+\& strtod(s, &p)               Strtod(s, &p)
+\& strtol(s, &p, n)            Strtol(s, &p, b)
+\& strtoul(s, &p, n)           Strtoul(s, &p, b)
+.Ve
+.PP
+Typical use is to do range checks on \f(CW\*(C`uv\*(C'\fR before casting:
+.PP
+.Vb 9
+\&  int i; UV uv;
+\&  char* end_ptr = input_end;
+\&  if (grok_atoUV(input, &uv, &end_ptr)
+\&      && uv <= INT_MAX)
+\&    i = (int)uv;
+\&    ... /* continue parsing from end_ptr */
+\&  } else {
+\&    ... /* parse error: not a decimal integer in range 0 .. MAX_IV */
+\&  }
+.Ve
+.PP
+Notice also the \f(CW\*(C`grok_bin\*(C'\fR, \f(CW\*(C`grok_hex\*(C'\fR, and \f(CW\*(C`grok_oct\*(C'\fR functions in
+\&\fInumeric.c\fR for converting strings representing numbers in the respective
+bases into \f(CW\*(C`NV\*(C'\fRs.  Note that \fBgrok_atoUV()\fR doesn't handle negative inputs,
+or leading whitespace (being purposefully strict).
+.PP
+Note that \fBstrtol()\fR and \fBstrtoul()\fR may be disguised as \fBStrtol()\fR, \fBStrtoul()\fR,
+\&\fBAtol()\fR, \fBAtoul()\fR.  Avoid those, too.
+.PP
+In theory \f(CW\*(C`Strtol\*(C'\fR and \f(CW\*(C`Strtoul\*(C'\fR may not be defined if the machine perl is
+built on doesn't actually have strtol and strtoul. But as those 2
+functions are part of the 1989 ANSI C spec we suspect you'll find them
+everywhere by now.
+.PP
+.Vb 3
+\& int rand()                  double Drand01()
+\& srand(n)                    { seedDrand01((Rand_seed_t)n);
+\&                               PL_srand_called = TRUE; }
+\&
+\& exit(n)                     my_exit(n)
+\& system(s)                   Don\*(Aqt. Look at pp_system or use my_popen.
+\&
+\& getenv(s)                   PerlEnv_getenv(s)
+\& setenv(s, val)              my_setenv(s, val)
+.Ve
+.SS "Miscellaneous functions"
+.IX Subsection "Miscellaneous functions"
+You should not even \fBwant\fR to use \fIsetjmp.h\fR functions, but if you
+think you do, use the \f(CW\*(C`JMPENV\*(C'\fR stack in \fIscope.h\fR instead.
+.PP
+For \f(CW\*(C`signal\*(C'\fR/\f(CW\*(C`sigaction\*(C'\fR, use \f(CW\*(C`rsignal(signo, handler)\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlapi, perlapio, perlguts