| .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and |
| .\" Walter Harms (walter.harms@informatik.uni-oldenburg.de) |
| .\" |
| .\" Distributed under GPL |
| .\" |
| .TH GETSPNAM 3 2003-11-15 "Shadow" "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 *" fp ); |
| .sp |
| .BI "struct spwd *sgetspent(const char *" s ); |
| .sp |
| .BI "int putspent(struct spwd *" p ", FILE *" fp ); |
| .sp |
| .B int lckpwdf(void); |
| .sp |
| .B int ulckpwdf(void); |
| .sp |
| /* GNU extension */ |
| .br |
| .BR "#define _SVID_SOURCE" " /* or _BSD_SOURCE */ |
| .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 *" fp ", 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 ); |
| .sp |
| .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. |
| .LP |
| The functions described below resemble those for |
| the traditional password database |
| (e.g., see |
| .BR getpwnam (3) |
| and |
| .BR getpwent (3)). |
| .\" Jul 2005, mtk: 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 funtions. |
| .\" 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 user name |
| .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 |
| .RI * p |
| as a text line in the shadow password file format to the stream |
| .IR fp . |
| 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 |
| .RI * spbufp . |
| .LP |
| The functions |
| .BR getspent_r (), |
| .BR fgetspent_r (), |
| and |
| .BR sgetspent_r () |
| are similarly analogous to their non-reentrant 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 |
| .RS +0.25i |
| .nf |
| struct spwd { |
| char *sp_namp; /* Login name */ |
| char *sp_pwdp; /* Encrypted password */ |
| long sp_lstchg; /* Date of last change */ |
| long sp_min; /* Min #days between changes */ |
| long sp_max; /* Max #days between changes */ |
| long sp_warn; /* #days before pwd expires |
| to warn user to change it */ |
| long sp_inact; /* #days after pwd expires |
| until account is disabled */ |
| long sp_expire; /* #days since 1970-01-01 |
| until account is disabled */ |
| unsigned long sp_flag; /* Reserved */ |
| }; |
| .fi |
| .RE |
| .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 \fBint\fR as the return value return 0 for |
| success and \-1 for failure. |
| .LP |
| For the non-reentrant 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 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 _PATH_SHADOW to the pathname of the shadow |
| password file. |
| .SH "CONFORMING TO" |
| The shadow password database and its associated API are |
| not specified in POSIX.1-2001. |
| However, many other systems provide a similar API. |
| .SH "SEE ALSO" |
| .BR getgrnam (3), |
| .BR getpwnam (3), |
| .BR getpwnam_r (3), |
| .BR shadow (5) |