'\"macro stdmacro
.if n .pH g3x.getspent @(#)getspent	40.14 of 10/26/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getspent 3C "" "\&"
.if \nX=1 .ds x} getspent 3C ""
.if \nX=2 .ds x} getspent 3C "" "\&"
.if \nX=3 .ds x} getspent "" "" "\&"
.TH \*(x}
.SH NAME
\f4getspent\f1, \f4getspnam\f1\^, \f4setspent\f1, \f4endspent\f1, \f4fgetspent\f1, \f4lckpwdf\f1, \f4ulckpwdf\f1 \- manipulate shadow password file entry
.SH SYNOPSIS
\f4#include <shadow.h>\f1
.PP
\f4struct spwd \(**getspent (void);\f1
.PP
\f4struct spwd \(**getspnam (const char \(**name);\f1
.PP
\f4int lckpwdf (void);\f1
.PP
\f4int ulckpwdf (void);\f1
.PP
\f4void setspent (void);\f1
.PP
\f4void endspent (void);\f1
.PP
\f4struct spwd \(**fgetspent (FILE \(**fp);\f1
.SH DESCRIPTION
The 
\f4getspent\fP
and
\f4getspnam\fP
routines each return a pointer to an object with the
following structure
containing the broken-out
fields of a line in the
\f4/etc/shadow\f1
file.
Each line in the file
contains a ``shadow password''
structure, declared in the
\f4shadow.h\f1
header file:
.PP
.RS
.nf
.ft 4
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;
};
.ft 1
.fi
.RE
.PP
The 
\f4getspent\fP
routine when first called returns a pointer to the first
\f4spwd\f1 structure in the file;
thereafter, it returns a pointer to the next \f4spwd\f1 structure in the file;
so successive calls can
be used to search the entire file.
The 
\f4getspnam\fP
routine searches from the beginning of the
file until a login name matching
.I name\^
is found, and returns a pointer to the particular structure
in which it was found.
The 
\f4getspent\fP
and 
\f4getspnam\fP
routines populate the \f4sp_min\f1, \f4sp_max\f1, \f4sp_lstchg\f1,
\f4sp_warn\f1, \f4sp_inact\f1, \f4sp_expire\f1, or \f4sp_flag\f1
field with \-1 if the corresponding field in \f4/etc/shadow\f1 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 \f4errno\f1 to \f4EINVAL\fP.
.PP
\f4/etc/.pwd.lock\f1 is the lock file.  It is used to coordinate
modification access to the password files \f4/etc/passwd\f1
and \f4/etc/shadow\f1.  \f4lckpwdf\fP and \f4ulckpwdf\fP are
routines that are used to gain modification access to the password
files, through the lock file.  A process first uses \f4lckpwdf\fP
to lock the lock file, thereby gaining exclusive rights to modify
the \f4/etc/passwd\f1 or \f4/etc/shadow\f1 password file.  Upon completing
modifications, a process should release the lock on the lock file
via \f4ulckpwdf\fP.  This mechanism prevents simultaneous modification
of the password files.
.PP
\f4lckpwdf\fP attempts to lock the file \f4/etc/.pwd.lock\f1
within 15 seconds.
If unsuccessful, e.g., \f4/etc/.pwd.lock\f1
is already locked, it
returns \-1.  If successful,
a return code other
than \-1 is returned.
.PP
\f4ulckpwdf\fP attempts to unlock the file \f4/etc/.pwd.lock\f1.
If unsuccessful, e.g., \f4/etc/.pwd.lock\f1 is already unlocked,
it returns \-1.
If successful, it returns 0.
.PP
A call to the
\f4setspent\fP
routine has the effect of rewinding
the shadow password file
to allow
repeated searches.
The 
\f4endspent\fP
routine may be called to
close the shadow password file
when processing is complete.
.PP
The 
\f4fgetspent\fP
routine returns a pointer to the next \f4spwd\f1 structure in the stream
.IR fp ,
which matches the format of
\f4/etc/shadow\f1.
.PP
.SH FILES
.nf
\f4/etc/shadow
/etc/passwd
/etc/.pwd.lock\f1
.fi
.SH "SEE ALSO"
\f4getpwent\fP(3C),
\f4putpwent\fP(3C),
\f4putspent\fP(3C).
.SH DIAGNOSTICS
\f4getspent\f1,
\f4getspnam\f1,
\f4lckpwdf\f1,
\f4ulckpwdf\f1,
and
\f4fgetspent\f1
return
a null pointer on \f4EOF\f1 or error.
.SH NOTES
This routine is for internal use only; compatibility is not guaranteed.
.P
All information
is contained in a static area,
so it must be copied if it is
to be saved.
.\"	@(#)getspent.3x	6.3 of 7/20/87
.Ee

