irix-657m-src/eoe/man/man3c/getspent.3c

'\"macro stdmacro
.if n .pH g3x.getspent @(#)getspent	41.2 of 5/26/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 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, \f4getspent_r\f1, \f4getspnam\f1, \f4getspnam_r\f1, \f4setspent\f1, \f4endspent\f1, \f4fgetspent\f1, \f4fgetspent_r\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 \(**getspent_r (struct spwd *spent, char *buffer, int bufsize);\f1
.PP
\f4struct spwd \(**fgetspent (FILE *);\f1
.PP
\f4struct spwd \(**fgetspent_r (FILE *, struct spwd *spent, char *buffer, int bufsize);\f1
.PP
\f4struct spwd \(**getspnam (const char \(**name);\f1
.PP
\f4struct spwd \(**getspnam_r (const char \(**name, struct spwd *spent, char *buffer, int bufsize);\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
.PP
\f4struct spwd \(**fgetspent_r (FILE \(**fp, struct spwd *spent, char *buffer, int bufsize);\f1
.SH DESCRIPTION
The 
\f4getspent\fP,
\f4getspnam\fP
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
\f4/etc/shadow\f1
file, or some other back-end database.
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
Many SVR4 derived programs use these routines exclusively to get password and
aging information.
These programs assume that all systems have a \f4/etc/shadow\fP file.
Historically, IRIX has not had a \f4/etc/shadow\fP file so in order
to permit these standard SVR4 programs to work properly, \f4getspnam\fP,
in the absence of a shadow file, will get as much information as possible
from \f4/etc/passwd\fP.
\f4getspent\fP does not have this compatibility feature, and will return
NULL if the system has no \f4/etc/shadow\fP file.
.PP
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.
.SH NOTE
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.
.SH FILES
.nf
\f4/etc/shadow
/etc/passwd
/etc/.pwd.lock
/etc/nsswitch.conf
/var/ns/cache/shadow.byname.m\f1
.fi
.SH "SEE ALSO"
\f4nsd\fP(1M),
\f4getpwent\fP(3C),
\f4putpwent\fP(3C),
\f4putspent\fP(3C).
.SH DIAGNOSTICS
\f4getspent\f1,
\f4getspnam\f1,
and
\f4fgetspent\f1
return
a null pointer on \f4EOF\f1 or error.
.PP
\f4lckpwdf\f1
and
\f4ulckpwdf\f1
return \-1 on error.
.Ee