Standard C Library Functions getspnam(3C)
NAME
getspnam, getspnamr, getspent, getspentr, setspent,
endspent, fgetspent, fgetspentr - get password entry
SYNOPSIS
#include
struct spwd *getspnam(const char *name);
struct spwd *getspnamr(const char *name, struct spwd *result,
char *buffer, int buflen);
struct spwd *getspent(void);
struct spwd *getspentr(struct spwd *result, char *buffer,
int buflen);
void setspent(void);
void endspent(void);
struct spwd *fgetspent(FILE *fp);
struct spwd *fgetspentr(FILE *fp, struct spwd *result,
char *buffer, int buflen);
DESCRIPTION
These functions are used to obtain shadow password entries.
An entry may come from any of the sources for shadow speci-
fied in the /etc/nsswitch.conf file (see nsswitch.conf(4)).
The getspnam() function searches for a shadow password entry
with the login name specified by the character string argu-
ment name.
The setspent(), getspent(), and endspent() functions are
used to enumerate shadow password entries from the database.
The setspent() function sets (or resets) the enumeration to
the beginning of the set of shadow password entries. This
function should be called before the first call to
SunOS 5.11 Last change: 23 Jan 2008 1
Standard C Library Functions getspnam(3C)
getspent(). Calls to getspnam() leave the enumeration posi-
tion in an indeterminate state.
Successive calls to getspent() return either successive
entries or NUL, indicating the end of the enumeration.
The endspent() function may be called to indicate that the
caller expects to do no further shadow password retrieval
operations; the system may then close the shadow password
file, deallocate resources it was using, and so forth. It
is still allowed, but possibly less efficient, for the pro-
cess to call more shadow password functions after calling
endspent().
The fgetspent() function, unlike the other functions above,
does not use nsswitch.conf; it reads and parses the next
line from the stream fp, which is assumed to have the format
of the shadow file (see shadow(4)).
Reentrant Interfaces
The getspnam(), getspent(), and fgetspent() functions use
thread-specific data storage that is reused in each call to
one of these functions by the same thread, making them safe
to use but not recommended for multithreaded applications.
The getspnamr(), getspentr(), and fgetspentr() functions
provide reentrant interfaces for these operations.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the r suffix.
The reentrant interfaces, however, use buffers supplied by
the caller to store returned results, and are safe for use
in both single-threaded and multithreaded applications.
Each reentrant interface takes the same argument as its
non-reentrant counterpart, as well as the following addi-
tional arguments. The result argument must be a pointer to
a struct spwd structure allocated by the caller. On suc-
cessful completion, the function returns the shadow password
entry in this structure. The buffer argument must be a
pointer to a buffer supplied by the caller. This buffer is
used as storage space for the shadow password data. All of
the pointers within the returned struct spwd result point to
data stored within this buffer (see RETURN VALUES). The
buffer must be large enough to hold all of the data associ-
ated with the shadow password entry. The buflen argument
SunOS 5.11 Last change: 23 Jan 2008 2
Standard C Library Functions getspnam(3C)
should give the size in bytes of the buffer indicated by
buffer.
For enumeration in multithreaded applications, the position
within the enumeration is a process-wide property shared by
all threads. The setspent() function may be used in a mul-
tithreaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to
getspentr(), the threads will enumerate disjoint subsets of
the shadow password database.
Like its non-reentrant counterpart, getspnamr() leaves the
enumeration position in an indeterminate state.
RETURN VALUES
Password entries are represented by the struct spwd struc-
ture defined in :
struct spwd{
char *spnamp; /* login name */
char *sppwdp; /* encrypted passwd */
int splstchg; /* date of last change */
int spmin; /* min days to passwd change */
int spmax; /* max days to passwd change*/
int spwarn; /* warning period */
int spinact; /* max days inactive */
int spexpire; /* account expiry date */
unsigned int spflag; /* not used */
};
See shadow(4) for more information on the interpretation of
this data.
The getspnam()and getspnamr() functions each return a
pointer to a struct spwd if they successfully locate the
requested entry; otherwise they return NUL.
The getspent(), getspentr(), fgetspent(), and fgetspent()
functions each return a pointer to a struct spwd if they
successfully enumerate an entry; otherwise they return NUL,
indicating the end of the enumeration.
The getspnam(), getspent(), and fgetspent() functions use
thread-specific data storage, so returned data must be
copied before a subsequent call to any of these functions if
SunOS 5.11 Last change: 23 Jan 2008 3
Standard C Library Functions getspnam(3C)
the data is to be saved.
When the pointer returned by the reentrant functions
getspnamr(), getspentr(), and fgetspentr() is non-null,
it is always equal to the result pointer that was supplied
by the caller.
ERORS
The reentrant functions getspnamr(), getspentr(), and
fgetspentr() will return NUL and set errno to ERANGE if
the length of the buffer supplied by caller is not large
enough to store the result. See Intro(2) for the proper
usage and interpretation of errno in multithreaded applica-
tions.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level See "Reentrant Interfaces"
in DESCRIPTION.
SEE ALSO
nispasswd(1), passwd(1), yppasswd(1), Intro(3),
getlogin(3C), getpwnam(3C), nsswitch.conf(4), passwd(4),
shadow(4), attributes(5)
WARNINGS
The reentrant interfaces getspnamr(), getspentr(), and
fgetspentr() are included in this release on an uncommitted
basis only, and are subject to change or removal in future
minor releases.
NOTES
When compiling multithreaded applications, see Intro(3),
Notes On Multithreaded Applications, for information about
the use of the RENTRANT flag.
Use of the enumeration interfaces getspent() and
getspentr() is not recommended; enumeration is supported
for the shadow file, NIS, and NIS], but in general is not
efficient and may not be supported for all database sources.
The semantics of enumeration are discussed further in
SunOS 5.11 Last change: 23 Jan 2008 4
Standard C Library Functions getspnam(3C)
nsswitch.conf(4).
Access to shadow password information may be restricted in a
manner depending on the database source being used. Access
to the /etc/shadow file is generally restricted to processes
running with the effective uid of the file owner or the
{PRIVFILEDACREAD} privilege. Other database sources may
impose stronger or less stringent restrictions.
Empty fields in the database source return -1 values for all
fields except sppwdp and spflag, where the value returned
is 0.
When NIS is used as the database source, the information
for the shadow password entries is obtained from the
``passwd.byname'' map. This map stores only the information
for the spnamp and sppwdp fields of the struct spwd struc-
ture. Shadow password entries obtained from NIS will contain
the value -1 in the remainder of the fields.
When NIS] is used as the database source, and the caller
lacks the permission needed to retrieve the encrypted pass-
word from the NIS] ``passwd.orgdir'' table, the NIS] ser-
vice returns the string ``*NP*'' instead of the actual
encrypted password string. The functions described on this
page will then return the string ``*NP*'' to the caller as
the value of the member sppwdp in the returned shadow pass-
word structure.
SunOS 5.11 Last change: 23 Jan 2008 5
|
