diff options
Diffstat (limited to 'man3/getspnam.3')
| -rw-r--r-- | man3/getspnam.3 | 344 |
1 files changed, 0 insertions, 344 deletions
diff --git a/man3/getspnam.3 b/man3/getspnam.3 deleted file mode 100644 index c97f2fa2d..000000000 --- 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 (date) "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) |