summaryrefslogtreecommitdiffstats
path: root/man3/getspnam.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/getspnam.3')
-rw-r--r--man3/getspnam.3344
1 files changed, 0 insertions, 344 deletions
diff --git a/man3/getspnam.3 b/man3/getspnam.3
deleted file mode 100644
index d3f9626..0000000
--- a/man3/getspnam.3
+++ /dev/null
@@ -1,344 +0,0 @@
-'\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)