| .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and |
| .\" Walter Harms (walter.harms@informatik.uni-oldenburg.de) |
| .\" |
| .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
| .\" Distributed under GPL |
| .\" %%%LICENSE_END |
| .\" |
| .TH GETSPNAM 3 2016-03-15 "GNU" "Linux Programmer's Manual" |
| .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 SYNOPSIS |
| .nf |
| /* General shadow password file API */ |
| .br |
| .B #include <shadow.h> |
| .sp |
| .BI "struct spwd *getspnam(const char *" name ); |
| .sp |
| .B struct spwd *getspent(void); |
| .sp |
| .B void setspent(void); |
| .sp |
| .B void endspent(void); |
| .sp |
| .BI "struct spwd *fgetspent(FILE *" stream ); |
| .sp |
| .BI "struct spwd *sgetspent(const char *" s ); |
| .sp |
| .BI "int putspent(const struct spwd *" p ", FILE *" stream ); |
| .sp |
| .B int lckpwdf(void); |
| .sp |
| .B int ulckpwdf(void); |
| .sp |
| /* GNU extension */ |
| .br |
| .B #include <shadow.h> |
| .sp |
| .BI "int getspent_r(struct spwd *" spbuf , |
| .br |
| .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
| .sp |
| .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , |
| .br |
| .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
| .sp |
| .BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf , |
| .br |
| .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
| .sp |
| .BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf , |
| .br |
| .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
| .fi |
| .sp |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .sp |
| .ad l |
| .BR getspent_r (), |
| .BR getspnam_r (), |
| .BR fgetspent_r (), |
| .BR sgetspent_r (): |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _BSD_SOURCE || _SVID_SOURCE |
| .ad b |
| .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. |
| .LP |
| 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. |
| .LP |
| 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 . |
| .LP |
| 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 |
| .LP |
| The |
| .BR fgetspent () |
| function is similar to |
| .BR getspent () |
| but uses the supplied stream instead of the one implicitly opened by |
| .BR setspent (). |
| .LP |
| The |
| .BR sgetspent () |
| function parses the supplied string |
| .I s |
| into a struct |
| .IR spwd . |
| .LP |
| 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. |
| .LP |
| 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. |
| .LP |
| 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 . |
| .LP |
| The functions |
| .BR getspent_r (), |
| .BR fgetspent_r (), |
| and |
| .BR sgetspent_r () |
| are similarly analogous to their nonreentrant counterparts. |
| .LP |
| 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: |
| .sp |
| .in +4n |
| .nf |
| 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 */ |
| }; |
| .fi |
| .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 cause of the error. |
| .LP |
| For the nonreentrant functions, the return value may point to static area, |
| and may be overwritten by subsequent calls to these functions. |
| .LP |
| 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 |
| .LP |
| 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; |
| lbw13 lb lbw30 |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR getspnam () |
| T} Thread safety T{ |
| MT-Unsafe race:getspnam locale |
| T} |
| T{ |
| .BR getspent () |
| T} Thread safety T{ |
| MT-Unsafe race:getspent |
| .br |
| race:spentbuf locale |
| T} |
| T{ |
| .BR setspent (), |
| .br |
| .BR endspent (), |
| .br |
| .BR getspent_r () |
| T} Thread safety T{ |
| MT-Unsafe race:getspent locale |
| T} |
| T{ |
| .BR fgetspent () |
| T} Thread safety MT-Unsafe race:fgetspent |
| T{ |
| .BR sgetspent () |
| T} Thread safety MT-Unsafe race:sgetspent |
| T{ |
| .BR putspent (), |
| .br |
| .BR getspnam_r (), |
| .br |
| .BR sgetspent_r () |
| T} Thread safety MT-Safe locale |
| T{ |
| .BR lckpwdf (), |
| .br |
| .BR ulckpwdf (), |
| .br |
| .BR fgetspent_r () |
| T} Thread safety MT-Safe |
| .TE |
| |
| In the above table, |
| .I getspent |
| in |
| .I race:getspent |
| signifies that if any of the functions |
| .BR setspent (3), |
| .BR getspent (3), |
| .BR getspent_r (3), |
| or |
| .BR endspent (3) |
| are used in parallel in different threads of a program, |
| then data races could occur. |
| .SH CONFORMING TO |
| The shadow password database and its associated API are |
| not specified in POSIX.1. |
| However, many other systems provide a similar API. |
| .SH SEE ALSO |
| .BR getgrnam (3), |
| .BR getpwnam (3), |
| .BR getpwnam_r (3), |
| .BR shadow (5) |