Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 170 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/User::pwent.3perl b/upstream/archlinux/man3/User::pwent.3perl
new file mode 100644
index 00000000..39e0b76d
--- /dev/null
+++ b/upstream/archlinux/man3/User::pwent.3perl
@@ -0,0 +1,170 @@
+.\" -*- 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 "User::pwent 3perl"
+.TH User::pwent 3perl 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
+User::pwent \- by\-name interface to Perl's built\-in getpw*() functions
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 5
+\& use User::pwent;
+\& my $pw = getpwnam(\*(Aqdaemon\*(Aq)       || die "No daemon user";
+\& if ( $pw\->uid == 1 && $pw\->dir =~ m#^/(bin|tmp)?\ez#s ) {
+\&     print "gid 1 on root dir";
+\& }
+\&
+\& my $real_shell = $pw\->shell || \*(Aq/bin/sh\*(Aq;
+\&
+\& for (my ($fullname, $office, $workphone, $homephone) =
+\&        split /\es*,\es*/, $pw\->gecos)
+\& {
+\&    s/&/ucfirst(lc($pw\->name))/ge;
+\& }
+\&
+\& use User::pwent qw(:FIELDS);
+\& getpwnam(\*(Aqdaemon\*(Aq)             || die "No daemon user";
+\& if ( $pw_uid == 1 && $pw_dir =~ m#^/(bin|tmp)?\ez#s ) {
+\&     print "gid 1 on root dir";
+\& }
+\&
+\& my $pw = getpw($whoever);
+\&
+\& use User::pwent qw/:DEFAULT pw_has/;
+\& if (pw_has(qw[gecos expire quota])) { .... }
+\& if (pw_has("name uid gid passwd"))  { .... }
+\& print "Your struct pwd has: ", scalar pw_has(), "\en";
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This module's default exports override the core \fBgetpwent()\fR, \fBgetpwuid()\fR,
+and \fBgetpwnam()\fR functions, replacing them with versions that return
+\&\f(CW\*(C`User::pwent\*(C'\fR objects.  This object has methods that return the
+similarly named structure field name from the C's passwd structure
+from \fIpwd.h\fR, stripped of their leading "pw_" parts, namely \f(CW\*(C`name\*(C'\fR,
+\&\f(CW\*(C`passwd\*(C'\fR, \f(CW\*(C`uid\*(C'\fR, \f(CW\*(C`gid\*(C'\fR, \f(CW\*(C`change\*(C'\fR, \f(CW\*(C`age\*(C'\fR, \f(CW\*(C`quota\*(C'\fR, \f(CW\*(C`comment\*(C'\fR,
+\&\f(CW\*(C`class\*(C'\fR, \f(CW\*(C`gecos\*(C'\fR, \f(CW\*(C`dir\*(C'\fR, \f(CW\*(C`shell\*(C'\fR, and \f(CW\*(C`expire\*(C'\fR.  The \f(CW\*(C`passwd\*(C'\fR,
+\&\f(CW\*(C`gecos\*(C'\fR, and \f(CW\*(C`shell\*(C'\fR fields are tainted when running in taint mode.
+.PP
+You may also import all the structure fields directly into your
+namespace as regular variables using the :FIELDS import tag.  (Note
+that this still overrides your core functions.)  Access these fields
+as variables named with a preceding \f(CW\*(C`pw_\*(C'\fR in front their method
+names.  Thus, \f(CW\*(C`$passwd_obj\->shell\*(C'\fR corresponds to \f(CW$pw_shell\fR
+if you import the fields.
+.PP
+The \fBgetpw()\fR function is a simple front-end that forwards
+a numeric argument to \fBgetpwuid()\fR and the rest to \fBgetpwnam()\fR.
+.PP
+To access this functionality without the core overrides, pass the
+\&\f(CW\*(C`use\*(C'\fR an empty import list, and then access function functions
+with their full qualified names.  The built-ins are always still
+available via the \f(CW\*(C`CORE::\*(C'\fR pseudo-package.
+.SS "System Specifics"
+.IX Subsection "System Specifics"
+Perl believes that no machine ever has more than one of \f(CW\*(C`change\*(C'\fR,
+\&\f(CW\*(C`age\*(C'\fR, or \f(CW\*(C`quota\*(C'\fR implemented, nor more than one of either
+\&\f(CW\*(C`comment\*(C'\fR or \f(CW\*(C`class\*(C'\fR.  Some machines do not support \f(CW\*(C`expire\*(C'\fR,
+\&\f(CW\*(C`gecos\*(C'\fR, or allegedly, \f(CW\*(C`passwd\*(C'\fR.  You may call these methods
+no matter what machine you're on, but they return \f(CW\*(C`undef\*(C'\fR if
+unimplemented.
+.PP
+You may ask whether one of these was implemented on the system Perl
+was built on by asking the importable \f(CW\*(C`pw_has\*(C'\fR function about them.
+This function returns true if all parameters are supported fields
+on the build platform, false if one or more were not, and raises
+an exception if you asked about a field that Perl never knows how
+to provide.  Parameters may be in a space-separated string, or as
+separate arguments.  If you pass no parameters, the function returns
+the list of \f(CW\*(C`struct pwd\*(C'\fR fields supported by your build platform's
+C library, as a list in list context, or a space-separated string
+in scalar context.  Note that just because your C library had
+a field doesn't necessarily mean that it's fully implemented on
+that system.
+.PP
+Interpretation of the \f(CW\*(C`gecos\*(C'\fR field varies between systems, but
+traditionally holds 4 comma-separated fields containing the user's
+full name, office location, work phone number, and home phone number.
+An \f(CW\*(C`&\*(C'\fR in the gecos field should be replaced by the user's properly
+capitalized login \f(CW\*(C`name\*(C'\fR.  The \f(CW\*(C`shell\*(C'\fR field, if blank, must be
+assumed to be \fI/bin/sh\fR.  Perl does not do this for you.  The
+\&\f(CW\*(C`passwd\*(C'\fR is one-way hashed garble, not clear text, and may not be
+unhashed save by brute-force guessing.  Secure systems use more a
+more secure hashing than DES.  On systems supporting shadow password
+systems, Perl automatically returns the shadow password entry when
+called by a suitably empowered user, even if your underlying
+vendor-provided C library was too short-sighted to realize it should
+do this.
+.PP
+See \fBpasswd\fR\|(5) and \fBgetpwent\fR\|(3) for details.
+.SH NOTE
+.IX Header "NOTE"
+While this class is currently implemented using the Class::Struct
+module to build a struct-like class, you shouldn't rely upon this.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tom Christiansen
+.SH HISTORY
+.IX Header "HISTORY"
+.IP "March 18th, 2000" 4
+.IX Item "March 18th, 2000"
+Reworked internals to support better interface to dodgey fields
+than normal Perl function provides.  Added \fBpw_has()\fR field.  Improved
+documentation.