Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 171 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/SDBM_File.3perl b/upstream/debian-unstable/man3/SDBM_File.3perl
new file mode 100644
index 00000000..f8736bdf
--- /dev/null
+++ b/upstream/debian-unstable/man3/SDBM_File.3perl
@@ -0,0 +1,171 @@
+.\" -*- 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 "SDBM_File 3perl"
+.TH SDBM_File 3perl 2024-01-12 "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
+SDBM_File \- Tied access to sdbm files
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\& use Fcntl;   # For O_RDWR, O_CREAT, etc.
+\& use SDBM_File;
+\&
+\& tie(%h, \*(AqSDBM_File\*(Aq, \*(Aqfilename\*(Aq, O_RDWR|O_CREAT, 0666)
+\&   or die "Couldn\*(Aqt tie SDBM file \*(Aqfilename\*(Aq: $!; aborting";
+\&
+\& # Now read and change the hash
+\& $h{newkey} = newvalue;
+\& print $h{oldkey}; 
+\& ...
+\&
+\& untie %h;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\f(CW\*(C`SDBM_File\*(C'\fR establishes a connection between a Perl hash variable and
+a file in SDBM_File format.  You can manipulate the data in the file
+just as if it were in a Perl hash, but when your program exits, the
+data will remain in the file, to be used the next time your program
+runs.
+.SS Tie
+.IX Subsection "Tie"
+Use \f(CW\*(C`SDBM_File\*(C'\fR with the Perl built-in \f(CW\*(C`tie\*(C'\fR function to establish
+the connection between the variable and the file.
+.PP
+.Vb 1
+\&    tie %hash, \*(AqSDBM_File\*(Aq, $basename, $modeflags, $perms;
+\&
+\&    tie %hash, \*(AqSDBM_File\*(Aq, $dirfile,  $modeflags, $perms, $pagfilename;
+.Ve
+.PP
+\&\f(CW$basename\fR is the base filename for the database.  The database is two
+files with ".dir" and ".pag" extensions appended to \f(CW$basename\fR,
+.PP
+.Vb 2
+\&    $basename.dir     (or .sdbm_dir on VMS, per DIRFEXT constant)
+\&    $basename.pag
+.Ve
+.PP
+The two filenames can also be given separately in full as \f(CW$dirfile\fR
+and \f(CW$pagfilename\fR.  This suits for two files without ".dir" and ".pag"
+extensions, perhaps for example two files from File::Temp.
+.PP
+\&\f(CW$modeflags\fR can be the following constants from the \f(CW\*(C`Fcntl\*(C'\fR module (in
+the style of the \fBopen\fR\|(2) system call),
+.PP
+.Vb 3
+\&    O_RDONLY          read\-only access
+\&    O_WRONLY          write\-only access
+\&    O_RDWR            read and write access
+.Ve
+.PP
+If you want to create the file if it does not already exist then bitwise-OR
+(\f(CW\*(C`|\*(C'\fR) \f(CW\*(C`O_CREAT\*(C'\fR too.  If you omit \f(CW\*(C`O_CREAT\*(C'\fR and the database does not
+already exist then the \f(CW\*(C`tie\*(C'\fR call will fail.
+.PP
+.Vb 1
+\&    O_CREAT           create database if doesn\*(Aqt already exist
+.Ve
+.PP
+\&\f(CW$perms\fR is the file permissions bits to use if new database files are
+created.  This parameter is mandatory even when not creating a new database.
+The permissions will be reduced by the user's umask so the usual value here
+would be 0666, or if some very private data then 0600.  (See
+"umask" in perlfunc.)
+.SH EXPORTS
+.IX Header "EXPORTS"
+SDBM_File optionally exports the following constants:
+.IP \(bu 4
+\&\f(CW\*(C`PAGFEXT\*(C'\fR \- the extension used for the page file, usually \f(CW\*(C`.pag\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`DIRFEXT\*(C'\fR \- the extension used for the directory file, \f(CW\*(C`.dir\*(C'\fR
+everywhere but VMS, where it is \f(CW\*(C`.sdbm_dir\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`PAIRMAX\*(C'\fR \- the maximum size of a stored hash entry, including the
+length of both the key and value.
+.PP
+These constants can also be used with fully qualified names,
+eg. \f(CW\*(C`SDBM_File::PAGFEXT\*(C'\fR.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+On failure, the \f(CW\*(C`tie\*(C'\fR call returns an undefined value and probably
+sets \f(CW$!\fR to contain the reason the file could not be tied.
+.ie n .SS """sdbm store returned \-1, errno 22, key ""..."" at ..."""
+.el .SS "\f(CWsdbm store returned \-1, errno 22, key ""..."" at ...\fP"
+.IX Subsection "sdbm store returned -1, errno 22, key ""..."" at ..."
+This warning is emitted when you try to store a key or a value that
+is too long.  It means that the change was not recorded in the
+database.  See BUGS AND WARNINGS below.
+.SH "SECURITY WARNING"
+.IX Header "SECURITY WARNING"
+\&\fBDo not accept SDBM files from untrusted sources!\fR
+.PP
+The sdbm file format was designed for speed and convenience, not for
+portability or security.  A maliciously crafted file might cause perl to
+crash or even expose a security vulnerability.
+.SH "BUGS AND WARNINGS"
+.IX Header "BUGS AND WARNINGS"
+There are a number of limits on the size of the data that you can
+store in the SDBM file.  The most important is that the length of a
+key, plus the length of its associated value, may not exceed 1008
+bytes.
+.PP
+See "tie" in perlfunc, perldbmfilter, Fcntl