GETSPENT(3X) GETSPENT(3X)
NAME
getspent, getspnam, setspent, endspent, fgetspent, lckpwdf,
ulckpwdf - get shadow password file entry
SYNOPSIS
#include <shadow.h>
struct spwd *getspent ( )
struct spwd *getspnam (name)
char *name;
int lckpwdf ( )
int ulckpwdf ( )
void setspent ( )
void endspent ( )
struct spwd *fgetspent (fp)
FILE *fp;
DESCRIPTION
The getspent and getspnam routines each return a pointer to
an object with the following structure containing the
broken-out fields of a line in the /etc/shadow file. Each
line in the file contains a "shadow password" structure,
declared in the < shadow.h> header file:
struct spwd{
char *sp_namp;
char *sp_pwdp;
long sp_lstchg;
long sp_min;
long sp_max;
};
The getspent routine when first called returns a pointer to
the first spwd structure in the file; thereafter, it returns
Page 1 May 1989
GETSPENT(3X) GETSPENT(3X)
a pointer to the next spwd structure in the file so
successive calls can be used to search the entire file. The
getspnam routine searches from the beginning of the file
until a login name matching name is found, and returns a
pointer to the particular structure in which it was found.
The getspent and getspnam routines populate the spmin,
spmax, or splstchg field with -1 if the corresponding
field in /etc/shadow is empty. If an end-of-file or an error
is encountered on reading, or there is a format error in the
file, these functions return a NULL pointer.
/etc/.pwd.lock is the lock file. It is used to coordinate
modification access to the password files /etc/passwd and
/etc/shadow. lckpwdf() and ulckpwdf() are routines that are
used to gain modification access to the password files,
through the lock file. A process first uses lckpwdf() to
lock the lock file thereby gaining exclusive rights to
modify the /etc/passwd or /etc/shadow password file. Upon
completing modifications, a process should release the lock
on the lock file via ulckpwdf(). This mechanism prevents
simultaneous modification of the password files.
The lckpwdf() routine attempts to lock the file
/etc/.pwd.lock. If file /etc/.pwd.lock is already locked,
lckpwdf() tries for 15 seconds to lock the file. If
lckpwdf() is unsuccessful, then lckpwdf() returns a -1. If
lckpwdf() succeeds to lock the file /etc/.pwd.lock within 15
seconds, then a return code other than -1 is returned.
The ulckpwdf() routine attempts to unlock the file
/etc/.pwd.lock. If successful, ulckpwdf() returns a 0. If
the unlocking failed, as in the case that file
/etc/.pwd.lock was not locked initially, then ulckpwdf()
returns a -1.
A call to the setspent routine has the effect of rewinding
the shadow password file to allow repeated searches. The
endspent routine may be called to close the shadow password
file when processing is complete.
Page 2 May 1989
GETSPENT(3X) GETSPENT(3X)
The fgetspent routine returns a pointer to the next spwd
structure in the stream fp, which matches the format of
/etc/shadow.
FILES
/etc/shadow, /etc/passwd, /etc/.pwd.lock
SEE ALSO
putspent(3X)
DIAGNOSTICS
A NULL pointer is returned on EOF or error.
WARNING
If a program not otherwise using standard I/O uses this
routine, the size of the program will increase more than
might be expected.
This routine is for internal use only, compatibility is not
guaranteed.
CAVEAT
All information is contained in a static area, so it must be
copied if it is to be saved.
Page 3 May 1989