getspent(3G) getspent(3G)
NAME
getspent, getspnam, setspent, endspent, fgetspent, lckpwdf,
ulckpwdf - manipulate shadow password file entry
SYNOPSIS
cc [flag . . . ] file . . . -lgen [library] . . .
#include <shadow.h>
struct spwd *getspent (void);
struct spwd *getspnam (const char *name);
int lckpwdf (void);
int ulckpwdf (void);
void setspent (void);
void endspent (void);
struct spwd *fgetspent (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;
long sp_warn;
long sp_inact;
long sp_expire;
unsigned long sp_flag;
};
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, or sp_expire field with -1 or the sp_flag
field with 0 if the corresponding field in /etc/shadow is
empty. If an end-of-file is encountered on reading, these
functions return a NULL pointer. If a read error occurs,
Copyright 1994 Novell, Inc. Page 1
getspent(3G) getspent(3G)
these functions return a NULL pointer and errno is set to
indicate the error. If there is a format error in the file, a
NULL pointer is returned and errno is set to EINVAL.
/etc/security/ia/.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/security/ia/.pwd.lock
within 15 seconds. If unsuccessful, for example,
/etc/security/ia/.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/security/ia/.pwd.lock. If unsuccessful, for example,
/etc/security/ia/.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.
Files
/etc/shadow, /etc/passwd, /etc/security/ia/.pwd.lock
Return Values
getspent, getspnam, lckpwdf, ulckpwdf, and fgetspent return a
null pointer on EOF or error.
REFERENCES
getpwent(3C), putpwent(3C), putspent(3C)
Copyright 1994 Novell, Inc. Page 2
getspent(3G) getspent(3G)
NOTICES
This routine is for internal use only; compatibility is not
guaranteed.
All information is contained in a static area, so it must be
copied if it is to be saved.
Copyright 1994 Novell, Inc. Page 3