Merging upstream version 6.8.

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

1 files changed, 344 insertions, 0 deletions

diff --git a/man/man3/getspnam.3 b/man/man3/getspnam.3
new file mode 100644
index 0000000..03fca91
--- /dev/null
+++ b/man/man3/getspnam.3
@@ -0,0 +1,344 @@
+'\" t
+.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and
+.\" Walter Harms (walter.harms@informatik.uni-oldenburg.de)
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.TH getspnam 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getspnam, getspnam_r, getspent, getspent_r, setspent, endspent,
+fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent,
+lckpwdf, ulckpwdf \- get shadow password file entry
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+/* General shadow password file API */
+.B #include <shadow.h>
+.P
+.BI "struct spwd *getspnam(const char *" name );
+.B struct spwd *getspent(void);
+.P
+.B void setspent(void);
+.B void endspent(void);
+.P
+.BI "struct spwd *fgetspent(FILE *" stream );
+.BI "struct spwd *sgetspent(const char *" s );
+.P
+.BI "int putspent(const struct spwd *" p ", FILE *" stream );
+.P
+.B int lckpwdf(void);
+.B int ulckpwdf(void);
+.P
+/* GNU extension */
+.B #include <shadow.h>
+.P
+.BI "int getspent_r(struct spwd *" spbuf ,
+.BI "               char " buf [. buflen "], size_t " buflen ", \
+struct spwd **" spbufp );
+.BI "int getspnam_r(const char *" name ", struct spwd *" spbuf ,
+.BI "               char " buf [. buflen "], size_t " buflen ", \
+struct spwd **" spbufp );
+.P
+.BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf ,
+.BI "               char " buf [. buflen "], size_t " buflen ", \
+struct spwd **" spbufp );
+.BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf ,
+.BI "               char " buf [. buflen "], size_t " buflen ", \
+struct spwd **" spbufp );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR getspent_r (),
+.BR getspnam_r (),
+.BR fgetspent_r (),
+.BR sgetspent_r ():
+.nf
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    glibc 2.19 and earlier:
+        _BSD_SOURCE || _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+Long ago it was considered safe to have encrypted passwords openly
+visible in the password file.
+When computers got faster and people
+got more security-conscious, this was no longer acceptable.
+Julianne Frances Haugh implemented the shadow password suite
+that keeps the encrypted passwords in
+the shadow password database
+(e.g., the local shadow password file
+.IR /etc/shadow ,
+NIS, and LDAP),
+readable only by root.
+.P
+The functions described below resemble those for
+the traditional password database
+(e.g., see
+.BR getpwnam (3)
+and
+.BR getpwent (3)).
+.\" FIXME . I've commented out the following for the
+.\" moment.  The relationship between PAM and nsswitch.conf needs
+.\" to be clearly documented in one place, which is pointed to by
+.\" the pages for the user, group, and shadow password functions.
+.\" (Jul 2005, mtk)
+.\"
+.\" This shadow password setup has been superseded by PAM
+.\" (pluggable authentication modules), and the file
+.\" .I /etc/nsswitch.conf
+.\" now describes the sources to be used.
+.P
+The
+.BR getspnam ()
+function returns a pointer to a structure containing
+the broken-out fields of the record in the shadow password database
+that matches the username
+.IR name .
+.P
+The
+.BR getspent ()
+function returns a pointer to the next entry in the shadow password
+database.
+The position in the input stream is initialized by
+.BR setspent ().
+When done reading, the program may call
+.BR endspent ()
+so that resources can be deallocated.
+.\" some systems require a call of setspent() before the first getspent()
+.\" glibc does not
+.P
+The
+.BR fgetspent ()
+function is similar to
+.BR getspent ()
+but uses the supplied stream instead of the one implicitly opened by
+.BR setspent ().
+.P
+The
+.BR sgetspent ()
+function parses the supplied string
+.I s
+into a struct
+.IR spwd .
+.P
+The
+.BR putspent ()
+function writes the contents of the supplied struct
+.I spwd
+.I *p
+as a text line in the shadow password file format to
+.IR stream .
+String entries with value NULL and numerical entries with value \-1
+are written as an empty string.
+.P
+The
+.BR lckpwdf ()
+function is intended to protect against multiple simultaneous accesses
+of the shadow password database.
+It tries to acquire a lock, and returns 0 on success,
+or \-1 on failure (lock not obtained within 15 seconds).
+The
+.BR ulckpwdf ()
+function releases the lock again.
+Note that there is no protection against direct access of the shadow
+password file.
+Only programs that use
+.BR lckpwdf ()
+will notice the lock.
+.P
+These were the functions that formed the original shadow API.
+They are widely available.
+.\" Also in libc5
+.\" SUN doesn't have sgetspent()
+.SS Reentrant versions
+Analogous to the reentrant functions for the password database, glibc
+also has reentrant functions for the shadow password database.
+The
+.BR getspnam_r ()
+function is like
+.BR getspnam ()
+but stores the retrieved shadow password structure in the space pointed to by
+.IR spbuf .
+This shadow password structure contains pointers to strings, and these strings
+are stored in the buffer
+.I buf
+of size
+.IR buflen .
+A pointer to the result (in case of success) or NULL (in case no entry
+was found or an error occurred) is stored in
+.IR *spbufp .
+.P
+The functions
+.BR getspent_r (),
+.BR fgetspent_r (),
+and
+.BR sgetspent_r ()
+are similarly analogous to their nonreentrant counterparts.
+.P
+Some non-glibc systems also have functions with these names,
+often with different prototypes.
+.\" SUN doesn't have sgetspent_r()
+.SS Structure
+The shadow password structure is defined in \fI<shadow.h>\fP as follows:
+.P
+.in +4n
+.EX
+struct spwd {
+    char *sp_namp;     /* Login name */
+    char *sp_pwdp;     /* Encrypted password */
+    long  sp_lstchg;   /* Date of last change
+                          (measured in days since
+                          1970\-01\-01 00:00:00 +0000 (UTC)) */
+    long  sp_min;      /* Min # of days between changes */
+    long  sp_max;      /* Max # of days between changes */
+    long  sp_warn;     /* # of days before password expires
+                          to warn user to change it */
+    long  sp_inact;    /* # of days after password expires
+                          until account is disabled */
+    long  sp_expire;   /* Date when account expires
+                          (measured in days since
+                          1970\-01\-01 00:00:00 +0000 (UTC)) */
+    unsigned long sp_flag;  /* Reserved */
+};
+.EE
+.in
+.SH RETURN VALUE
+The functions that return a pointer return NULL if no more entries
+are available or if an error occurs during processing.
+The functions which have \fIint\fP as the return value return 0 for
+success and \-1 for failure, with
+.I errno
+set to indicate the error.
+.P
+For the nonreentrant functions, the return value may point to static area,
+and may be overwritten by subsequent calls to these functions.
+.P
+The reentrant functions return zero on success.
+In case of error, an error number is returned.
+.SH ERRORS
+.TP
+.B EACCES
+The caller does not have permission to access the shadow password file.
+.TP
+.B ERANGE
+Supplied buffer is too small.
+.SH FILES
+.TP
+.I /etc/shadow
+local shadow password database file
+.TP
+.I /etc/.pwd.lock
+lock file
+.P
+The include file
+.I <paths.h>
+defines the constant
+.B _PATH_SHADOW
+to the pathname of the shadow password file.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lbx
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR getspnam ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:getspnam locale
+T}
+T{
+.na
+.nh
+.BR getspent ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:getspent
+race:spentbuf locale
+T}
+T{
+.na
+.nh
+.BR setspent (),
+.BR endspent (),
+.BR getspent_r ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:getspent locale
+T}
+T{
+.na
+.nh
+.BR fgetspent ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:fgetspent
+T}
+T{
+.na
+.nh
+.BR sgetspent ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:sgetspent
+T}
+T{
+.na
+.nh
+.BR putspent (),
+.BR getspnam_r (),
+.BR sgetspent_r ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Safe locale
+T}
+T{
+.na
+.nh
+.BR lckpwdf (),
+.BR ulckpwdf (),
+.BR fgetspent_r ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Safe
+T}
+.TE
+.P
+In the above table,
+.I getspent
+in
+.I race:getspent
+signifies that if any of the functions
+.BR setspent (),
+.BR getspent (),
+.BR getspent_r (),
+or
+.BR endspent ()
+are used in parallel in different threads of a program,
+then data races could occur.
+.SH VERSIONS
+Many other systems provide a similar API.
+.SH STANDARDS
+None.
+.SH SEE ALSO
+.BR getgrnam (3),
+.BR getpwnam (3),
+.BR getpwnam_r (3),
+.BR shadow (5)