Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 579 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Opcode.3pm b/upstream/mageia-cauldron/man3pm/Opcode.3pm
new file mode 100644
index 00000000..2648ed93
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Opcode.3pm
@@ -0,0 +1,579 @@
+.\" -*- 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 "Opcode 3pm"
+.TH Opcode 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
+Opcode \- Disable named opcodes when compiling perl code
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  use Opcode;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl code is always compiled into an internal format before execution.
+.PP
+Evaluating perl code (e.g. via "eval" or "do 'file'") causes
+the code to be compiled into an internal format and then,
+provided there was no error in the compilation, executed.
+The internal format is based on many distinct \fIopcodes\fR.
+.PP
+By default no opmask is in effect and any code can be compiled.
+.PP
+The Opcode module allow you to define an \fIoperator mask\fR to be in
+effect when perl \fInext\fR compiles any code.  Attempting to compile code
+which contains a masked opcode will cause the compilation to fail
+with an error. The code will not be executed.
+.SH NOTE
+.IX Header "NOTE"
+The Opcode module is not usually used directly. See the ops pragma and
+Safe modules for more typical uses.
+.SH WARNING
+.IX Header "WARNING"
+The Opcode module does not implement an effective sandbox for
+evaluating untrusted code with the perl interpreter.
+.PP
+Bugs in the perl interpreter that could be abused to bypass
+Opcode restrictions are not treated as vulnerabilities. See
+perlsecpolicy for additional information.
+.PP
+The authors make \fBno warranty\fR, implied or otherwise, about the
+suitability of this software for safety or security purposes.
+.PP
+The authors shall not in any case be liable for special, incidental,
+consequential, indirect or other similar damages arising from the use
+of this software.
+.PP
+Your mileage will vary. If in any doubt \fBdo not use it\fR.
+.SH "Operator Names and Operator Lists"
+.IX Header "Operator Names and Operator Lists"
+The canonical list of operator names is the contents of the array
+PL_op_name defined and initialised in file \fIopcode.h\fR of the Perl
+source distribution (and installed into the perl library).
+.PP
+Each operator has both a terse name (its opname) and a more verbose or
+recognisable descriptive name. The opdesc function can be used to
+return a list of descriptions for a list of operators.
+.PP
+Many of the functions and methods listed below take a list of
+operators as parameters. Most operator lists can be made up of several
+types of element. Each element can be one of
+.IP "an operator name (opname)" 8
+.IX Item "an operator name (opname)"
+Operator names are typically small lowercase words like enterloop,
+leaveloop, last, next, redo etc. Sometimes they are rather cryptic
+like gv2cv, i_ncmp and ftsvtx.
+.IP "an operator tag name (optag)" 8
+.IX Item "an operator tag name (optag)"
+Operator tags can be used to refer to groups (or sets) of operators.
+Tag names always begin with a colon. The Opcode module defines several
+optags and the user can define others using the define_optag function.
+.IP "a negated opname or optag" 8
+.IX Item "a negated opname or optag"
+An opname or optag can be prefixed with an exclamation mark, e.g., !mkdir.
+Negating an opname or optag means remove the corresponding ops from the
+accumulated set of ops at that point.
+.IP "an operator set (opset)" 8
+.IX Item "an operator set (opset)"
+An \fIopset\fR as a binary string of approximately 44 bytes which holds a
+set or zero or more operators.
+.Sp
+The opset and opset_to_ops functions can be used to convert from
+a list of operators to an opset and \fIvice versa\fR.
+.Sp
+Wherever a list of operators can be given you can use one or more opsets.
+See also Manipulating Opsets below.
+.SH "Opcode Functions"
+.IX Header "Opcode Functions"
+The Opcode package contains functions for manipulating operator names
+tags and sets. All are available for export by the package.
+.IP opcodes 8
+.IX Item "opcodes"
+In a scalar context opcodes returns the number of opcodes in this
+version of perl (around 350 for perl\-5.7.0).
+.Sp
+In a list context it returns a list of all the operator names.
+(Not yet implemented, use \f(CW@names\fR = opset_to_ops(full_opset).)
+.IP "opset (OP, ...)" 8
+.IX Item "opset (OP, ...)"
+Returns an opset containing the listed operators.
+.IP "opset_to_ops (OPSET)" 8
+.IX Item "opset_to_ops (OPSET)"
+Returns a list of operator names corresponding to those operators in
+the set.
+.IP "opset_to_hex (OPSET)" 8
+.IX Item "opset_to_hex (OPSET)"
+Returns a string representation of an opset. Can be handy for debugging.
+.IP full_opset 8
+.IX Item "full_opset"
+Returns an opset which includes all operators.
+.IP empty_opset 8
+.IX Item "empty_opset"
+Returns an opset which contains no operators.
+.IP "invert_opset (OPSET)" 8
+.IX Item "invert_opset (OPSET)"
+Returns an opset which is the inverse set of the one supplied.
+.IP "verify_opset (OPSET, ...)" 8
+.IX Item "verify_opset (OPSET, ...)"
+Returns true if the supplied opset looks like a valid opset (is the
+right length etc) otherwise it returns false. If an optional second
+parameter is true then verify_opset will croak on an invalid opset
+instead of returning false.
+.Sp
+Most of the other Opcode functions call verify_opset automatically
+and will croak if given an invalid opset.
+.IP "define_optag (OPTAG, OPSET)" 8
+.IX Item "define_optag (OPTAG, OPSET)"
+Define OPTAG as a symbolic name for OPSET. Optag names always start
+with a colon \f(CW\*(C`:\*(C'\fR.
+.Sp
+The optag name used must not be defined already (define_optag will
+croak if it is already defined). Optag names are global to the perl
+process and optag definitions cannot be altered or deleted once
+defined.
+.Sp
+It is strongly recommended that applications using Opcode should use a
+leading capital letter on their tag names since lowercase names are
+reserved for use by the Opcode module. If using Opcode within a module
+you should prefix your tags names with the name of your module to
+ensure uniqueness and thus avoid clashes with other modules.
+.IP "opmask_add (OPSET)" 8
+.IX Item "opmask_add (OPSET)"
+Adds the supplied opset to the current opmask. Note that there is
+currently \fIno\fR mechanism for unmasking ops once they have been masked.
+This is intentional.
+.IP opmask 8
+.IX Item "opmask"
+Returns an opset corresponding to the current opmask.
+.IP "opdesc (OP, ...)" 8
+.IX Item "opdesc (OP, ...)"
+This takes a list of operator names and returns the corresponding list
+of operator descriptions.
+.IP "opdump (PAT)" 8
+.IX Item "opdump (PAT)"
+Dumps to STDOUT a two column list of op names and op descriptions.
+If an optional pattern is given then only lines which match the
+(case insensitive) pattern will be output.
+.Sp
+It's designed to be used as a handy command line utility:
+.Sp
+.Vb 2
+\&        perl \-MOpcode=opdump \-e opdump
+\&        perl \-MOpcode=opdump \-e \*(Aqopdump Eval\*(Aq
+.Ve
+.SH "Manipulating Opsets"
+.IX Header "Manipulating Opsets"
+Opsets may be manipulated using the perl bit vector operators & (and), | (or),
+^ (xor) and ~ (negate/invert).
+.PP
+However you should never rely on the numerical position of any opcode
+within the opset. In other words both sides of a bit vector operator
+should be opsets returned from Opcode functions.
+.PP
+Also, since the number of opcodes in your current version of perl might
+not be an exact multiple of eight, there may be unused bits in the last
+byte of an upset. This should not cause any problems (Opcode functions
+ignore those extra bits) but it does mean that using the ~ operator
+will typically not produce the same 'physical' opset 'string' as the
+invert_opset function.
+.SH "TO DO (maybe)"
+.IX Header "TO DO (maybe)"
+.Vb 3
+\&    $bool = opset_eq($opset1, $opset2)  true if opsets are logically
+\&                                        equivalent
+\&    $yes = opset_can($opset, @ops)      true if $opset has all @ops set
+\&
+\&    @diff = opset_diff($opset1, $opset2) => (\*(Aqfoo\*(Aq, \*(Aq!bar\*(Aq, ...)
+.Ve
+.SH "Predefined Opcode Tags"
+.IX Header "Predefined Opcode Tags"
+.IP :base_core 5
+.IX Item ":base_core"
+.Vb 1
+\&    null stub scalar pushmark wantarray const defined undef
+\&
+\&    rv2sv sassign padsv_store
+\&
+\&    rv2av aassign aelem aelemfast aelemfast_lex aslice kvaslice
+\&    av2arylen aelemfastlex_store
+\&
+\&    rv2hv helem hslice kvhslice each values keys exists delete
+\&    aeach akeys avalues multideref argelem argdefelem argcheck
+\&
+\&    preinc i_preinc predec i_predec postinc i_postinc
+\&    postdec i_postdec int hex oct abs pow multiply i_multiply
+\&    divide i_divide modulo i_modulo add i_add subtract i_subtract
+\&
+\&    left_shift right_shift bit_and bit_xor bit_or nbit_and
+\&    nbit_xor nbit_or sbit_and sbit_xor sbit_or negate i_negate not
+\&    complement ncomplement scomplement
+\&
+\&    lt i_lt gt i_gt le i_le ge i_ge eq i_eq ne i_ne ncmp i_ncmp
+\&    slt sgt sle sge seq sne scmp
+\&    isa
+\&
+\&    substr vec stringify study pos length index rindex ord chr
+\&
+\&    ucfirst lcfirst uc lc fc quotemeta trans transr chop schop
+\&    chomp schomp
+\&
+\&    match split qr
+\&
+\&    list lslice splice push pop shift unshift reverse
+\&
+\&    cond_expr flip flop andassign orassign dorassign and or dor xor
+\&    helemexistsor
+\&
+\&    warn die lineseq nextstate scope enter leave
+\&
+\&    rv2cv anoncode prototype coreargs avhvswitch anonconst
+\&    emptyavhv
+\&
+\&    entersub leavesub leavesublv return method method_named
+\&    method_super method_redir method_redir_super
+\&     \-\- XXX loops via recursion?
+\&
+\&    cmpchain_and cmpchain_dup
+\&
+\&    is_bool
+\&    is_weak weaken unweaken
+\&
+\&    leaveeval \-\- needed for Safe to operate, is safe
+\&                 without entereval
+\&
+\&    methstart initfield
+.Ve
+.IP :base_mem 5
+.IX Item ":base_mem"
+These memory related ops are not included in :base_core because they
+can easily be used to implement a resource attack (e.g., consume all
+available memory).
+.Sp
+.Vb 1
+\&    concat multiconcat repeat join range
+\&
+\&    anonlist anonhash
+.Ve
+.Sp
+Note that despite the existence of this optag a memory resource attack
+may still be possible using only :base_core ops.
+.Sp
+Disabling these ops is a \fIvery\fR heavy handed way to attempt to prevent
+a memory resource attack. It's probable that a specific memory limit
+mechanism will be added to perl in the near future.
+.IP :base_loop 5
+.IX Item ":base_loop"
+These loop ops are not included in :base_core because they can easily be
+used to implement a resource attack (e.g., consume all available CPU time).
+.Sp
+.Vb 6
+\&    grepstart grepwhile
+\&    mapstart mapwhile
+\&    enteriter iter
+\&    enterloop leaveloop unstack
+\&    last next redo
+\&    goto
+.Ve
+.IP :base_io 5
+.IX Item ":base_io"
+These ops enable \fIfilehandle\fR (rather than filename) based input and
+output. These are safe on the assumption that only pre-existing
+filehandles are available for use.  Usually, to create new filehandles
+other ops such as open would need to be enabled, if you don't take into
+account the magical open of ARGV.
+.Sp
+.Vb 1
+\&    readline rcatline getc read
+\&
+\&    formline enterwrite leavewrite
+\&
+\&    print say sysread syswrite send recv
+\&
+\&    eof tell seek sysseek
+\&
+\&    readdir telldir seekdir rewinddir
+.Ve
+.IP :base_orig 5
+.IX Item ":base_orig"
+These are a hotchpotch of opcodes still waiting to be considered
+.Sp
+.Vb 1
+\&    gvsv gv gelem
+\&
+\&    padsv padav padhv padcv padany padrange introcv clonecv
+\&
+\&    once
+\&
+\&    rv2gv refgen srefgen ref refassign lvref lvrefslice lvavref
+\&    blessed refaddr reftype
+\&
+\&    bless \-\- could be used to change ownership of objects
+\&             (reblessing)
+\&
+\&     regcmaybe regcreset regcomp subst substcont
+\&
+\&    sprintf prtf \-\- can core dump
+\&
+\&    crypt
+\&
+\&    tie untie
+\&
+\&    dbmopen dbmclose
+\&    sselect select
+\&    pipe_op sockpair
+\&
+\&    getppid getpgrp setpgrp getpriority setpriority
+\&    localtime gmtime
+\&
+\&    entertry leavetry \-\- can be used to \*(Aqhide\*(Aq fatal errors
+\&    entertrycatch poptry catch leavetrycatch \-\- similar
+\&
+\&    entergiven leavegiven
+\&    enterwhen leavewhen
+\&    break continue
+\&    smartmatch
+\&
+\&    pushdefer
+\&
+\&    custom \-\- where should this go
+\&
+\&    ceil floor
+\&
+\&    is_tainted
+.Ve
+.IP :base_math 5
+.IX Item ":base_math"
+These ops are not included in :base_core because of the risk of them being
+used to generate floating point exceptions (which would have to be caught
+using a \f(CW$SIG\fR{FPE} handler).
+.Sp
+.Vb 1
+\&    atan2 sin cos exp log sqrt
+.Ve
+.Sp
+These ops are not included in :base_core because they have an effect
+beyond the scope of the compartment.
+.Sp
+.Vb 1
+\&    rand srand
+.Ve
+.IP :base_thread 5
+.IX Item ":base_thread"
+These ops are related to multi-threading.
+.Sp
+.Vb 1
+\&    lock
+.Ve
+.IP :default 5
+.IX Item ":default"
+A handy tag name for a \fIreasonable\fR default set of ops.  (The current ops
+allowed are unstable while development continues. It will change.)
+.Sp
+.Vb 1
+\&    :base_core :base_mem :base_loop :base_orig :base_thread
+.Ve
+.Sp
+This list used to contain :base_io prior to Opcode 1.07.
+.Sp
+If safety matters to you (and why else would you be using the Opcode module?)
+then you should not rely on the definition of this, or indeed any other, optag!
+.IP :filesys_read 5
+.IX Item ":filesys_read"
+.Vb 1
+\&    stat lstat readlink
+\&
+\&    ftatime ftblk ftchr ftctime ftdir fteexec fteowned
+\&    fteread ftewrite ftfile ftis ftlink ftmtime ftpipe
+\&    ftrexec ftrowned ftrread ftsgid ftsize ftsock ftsuid
+\&    fttty ftzero ftrwrite ftsvtx
+\&
+\&    fttext ftbinary
+\&
+\&    fileno
+.Ve
+.IP :sys_db 5
+.IX Item ":sys_db"
+.Vb 4
+\&    ghbyname ghbyaddr ghostent shostent ehostent      \-\- hosts
+\&    gnbyname gnbyaddr gnetent snetent enetent         \-\- networks
+\&    gpbyname gpbynumber gprotoent sprotoent eprotoent \-\- protocols
+\&    gsbyname gsbyport gservent sservent eservent      \-\- services
+\&
+\&    gpwnam gpwuid gpwent spwent epwent getlogin       \-\- users
+\&    ggrnam ggrgid ggrent sgrent egrent                \-\- groups
+.Ve
+.IP :browse 5
+.IX Item ":browse"
+A handy tag name for a \fIreasonable\fR default set of ops beyond the
+:default optag.  Like :default (and indeed all the other optags) its
+current definition is unstable while development continues. It will change.
+.Sp
+The :browse tag represents the next step beyond :default. It is a
+superset of the :default ops and adds :filesys_read the :sys_db.
+The intent being that scripts can access more (possibly sensitive)
+information about your system but not be able to change it.
+.Sp
+.Vb 1
+\&    :default :filesys_read :sys_db
+.Ve
+.IP :filesys_open 5
+.IX Item ":filesys_open"
+.Vb 2
+\&    sysopen open close
+\&    umask binmode
+\&
+\&    open_dir closedir \-\- other dir ops are in :base_io
+.Ve
+.IP :filesys_write 5
+.IX Item ":filesys_write"
+.Vb 1
+\&    link unlink rename symlink truncate
+\&
+\&    mkdir rmdir
+\&
+\&    utime chmod chown
+\&
+\&    fcntl \-\- not strictly filesys related, but possibly as
+\&             dangerous?
+.Ve
+.IP :subprocess 5
+.IX Item ":subprocess"
+.Vb 1
+\&    backtick system
+\&
+\&    fork
+\&
+\&    wait waitpid
+\&
+\&    glob \-\- access to Cshell via <\`rm *\`>
+.Ve
+.IP :ownprocess 5
+.IX Item ":ownprocess"
+.Vb 1
+\&    exec exit kill
+\&
+\&    time tms \-\- could be used for timing attacks (paranoid?)
+.Ve
+.IP :others 5
+.IX Item ":others"
+This tag holds groups of assorted specialist opcodes that don't warrant
+having optags defined for them.
+.Sp
+SystemV Interprocess Communications:
+.Sp
+.Vb 1
+\&    msgctl msgget msgrcv msgsnd
+\&
+\&    semctl semget semop
+\&
+\&    shmctl shmget shmread shmwrite
+.Ve
+.IP :load 5
+.IX Item ":load"
+This tag holds opcodes related to loading modules and getting information
+about calling environment and args.
+.Sp
+.Vb 2
+\&    require dofile 
+\&    caller runcv
+.Ve
+.IP :still_to_be_decided 5
+.IX Item ":still_to_be_decided"
+.Vb 2
+\&    chdir
+\&    flock ioctl
+\&
+\&    socket getpeername ssockopt
+\&    bind connect listen accept shutdown gsockopt getsockname
+\&
+\&    sleep alarm \-\- changes global timer state and signal handling
+\&    sort \-\- assorted problems including core dumps
+\&    tied \-\- can be used to access object implementing a tie
+\&    pack unpack \-\- can be used to create/use memory pointers
+\&
+\&    hintseval \-\- constant op holding eval hints
+\&
+\&    entereval \-\- can be used to hide code from initial compile
+\&
+\&    reset
+\&
+\&    dbstate \-\- perl \-d version of nextstate(ment) opcode
+.Ve
+.IP :dangerous 5
+.IX Item ":dangerous"
+This tag is simply a bucket for opcodes that are unlikely to be used via
+a tag name but need to be tagged for completeness and documentation.
+.Sp
+.Vb 1
+\&    syscall dump chroot
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+ops \-\- perl pragma interface to Opcode module.
+.PP
+Safe \-\- Opcode and namespace limited execution compartments
+.SH AUTHORS
+.IX Header "AUTHORS"
+Originally designed and implemented by Malcolm Beattie,
+mbeattie@sable.ox.ac.uk as part of Safe version 1.
+.PP
+Split out from Safe module version 1, named opcode tags and other
+changes added by Tim Bunce.