diff options
Diffstat (limited to 'man/man3/getspnam.3')
| -rw-r--r-- | man/man3/getspnam.3 | 344 |
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) |