getspent(3C) getspent(3C)
getspent, getspent_r, getspnam, getspnam_r, setspent, endspent,
fgetspent, fgetspent_r, lckpwdf, ulckpwdf - manipulate shadow password
file entry
#include <shadow.h>
struct spwd *getspent (void);
struct spwd *getspent_r (struct spwd *spent, char *buffer, int bufsize);
struct spwd *fgetspent (FILE *);
struct spwd *fgetspent_r (FILE *, struct spwd *spent, char *buffer, int
bufsize);
struct spwd *getspnam (const char *name);
struct spwd *getspnam_r (const char *name, struct spwd *spent, char
*buffer, int bufsize);
int lckpwdf (void);
int ulckpwdf (void);
void setspent (void);
void endspent (void);
struct spwd *fgetspent (FILE *fp);
struct spwd *fgetspent_r (FILE *fp, struct spwd *spent, char *buffer, int
bufsize);
The getspent, getspnam and their reentrant counterpart 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, or some other backend
database. 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;
long sp_warn;
long sp_inact;
long sp_expire;
unsigned long sp_flag;
Page 1
getspent(3C) getspent(3C)
};
The getspent routine when first called returns a pointer to the first
spwd structure in the file; thereafter, it returns 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 sp_min, sp_max, sp_lstchg, sp_warn,
sp_inact, sp_expire, or sp_flag 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 and set errno to EINVAL.
/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.
lckpwdf attempts to lock the file /etc/.pwd.lock within 15 seconds. If
unsuccessful, e.g., /etc/.pwd.lock is already locked, it returns -1. If
successful, a return code other than -1 is returned.
ulckpwdf attempts to unlock the file /etc/.pwd.lock. If unsuccessful,
e.g., /etc/.pwd.lock is already unlocked, it returns -1. If successful,
it returns 0.
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.
The fgetspent routine returns a pointer to the next spwd structure in the
stream fp, which matches the format of /etc/shadow.
Many SVR4 derived programs use these routines exclusively to get password
and aging information. These programs assume that all systems have a
/etc/shadow file. Historically, IRIX has not had a /etc/shadow file so
in order to permit these standard SVR4 programs to work properly,
getspnam, in the absence of a shadow file, will get as much information
as possible from /etc/passwd. getspent does not have this compatibility
feature, and will return NULL if the system has no /etc/shadow file.
The routines getspent, fgetspent and getspnam return results in a
statically allocated memory location which is overwritten on each call.
Reentrant versions of each of these routines getspent_r, fgetspent_r and
getspnam_r which will parse the results into supplied memory. Each takes
three extra parameters, a pointer to a shadow password structure, a
pointer to a character buffer, and a length for the buffer.
Page 2
getspent(3C) getspent(3C)
The Mips ABI specifies nothing but local files so applications which wish
to use anything else must compile with libc prior to libnsl in the
library list.
When nsd is running changes to the local shadow file may not be noticed
by getspent() until the enumeration cache file has timed out.
/etc/shadow
/etc/passwd
/etc/.pwd.lock
/etc/nsswitch.conf
/var/ns/cache/shadow.byname.m
nsd(1M), getpwent(3C), putpwent(3C), putspent(3C).
getspent, getspnam, and fgetspent return a null pointer on EOF or error.
lckpwdf and ulckpwdf return -1 on error.
PPPPaaaaggggeeee 3333 [ Back ]
|