getspent(3C)

NAME

getspnam(), getspnam_r(), getspent(), setspent(), endspent(), fgetspent() — access shadow password entries

SYNOPSIS

#include <shadow.h>

struct spwd *getspnam (const char *name);

struct spwd *getspnam_r (const char *name, struct spwd *result, char *buffer, size_t bufsiz);

struct spwd *getspent (void);

void setspent (void);

void endspent (void);

struct spwd *fgetspent (FILE *stream);

DESCRIPTION

The routines getspnam(), getspnam_r(), getspent() and fgetspent() return a pointer to a shadow password entry. Each shadow password entry is an spwd structure, declared in the <shadow.h> header file, with the following members:

char  *sp_namp;  /* the user's login name */
char  *sp_pwdp;  /* the encrypted password for the user */
long  sp_lstchg; /* # of days from 1/1/70 when passwd was last modified */
long  sp_min;    /* min # of days allowed between password changes */
long  sp_max;    /* max # of days allowed between password changes */
long  sp_warn;   /* # of days before password expires and warning issued*/
long  sp_inact;  /* # of days between account inactive and disabled */
long  sp_expire; /* # of days from 1/1/70 when account is locked */
unsigned long   sp_flag;/* currently unused */

The getspnam() routine returns a pointer to a structure containing an entry from the shadow password database with a matching name.

The getspnam_r() routine is similar to getspnam(), except that it does not work on systems which have been converted to trusted mode, and it has three extra parameters. getspnam_r() updates the spwd structure pointed to by result and returns a pointer to that structure. Storage referenced by the spwd structure pointed to by result is allocated from the memory provided with the buffer parameter, which is buflen in size. A buffer length of 2048 is recommended.

The initial call to getspent() returns a pointer to the first spwd structure. Subsequent calls return pointers to successive spwd structures. Repeated calls to getspent() can be used to search all entries in the password database. The getspnam() routine searches password entries from beginning to end, until a login name matching name is found, and returns a pointer to that entry.

The setspent() routine is used to reset access to the shadow password entries. After setspent() is called, the subsequent call to getspent() returns the first shadow password entry. This mechanism is used to allow repeated searches of the shadow password entries. The endspent() routine is used to indicate that processing of password entries is complete.

fgetspent(), unlike the other functions above, does not use /etc/nsswitch.conf, and does not access NIS. It returns a pointer to the next spwd structure in the standard I/O stream. The I/O stream should be open for reading and its contents should match the format of /etc/shadow.

Notes

Shadow password entries normally reside in /etc/shadow. However, there are two exceptions to this. On a standard system with no /etc/shadow file, the password and aging information is obtained from /etc/passwd and translated into an spwd structure. If the system has been converted to a trusted system, the password and aging information is obtained from the Protected Password Database (/tcb/files/auth/*/*) and translated into an spwd structure.

If the fields corresponding to sp_min, sp_max, sp_lstchg, sp_warn, sp_inact, sp_expire, or sp_flag are not specified in the entry, they default to -1. If the returned value of sp_min, sp_max, or sp_warn is -1, then the feature associated with that field is considered to be disabled.

The routines getspent(), getspnam() and getspnam_r() depend on the configuration of the /etc/nsswitch.conf file. See nsswitch.conf(4). Entries may reside in any repository specified in /etc/nsswitch.conf. These routines use the switch for the passwd database; for example, an entry in /etc/nsswitch.conf would contain "passwd: nis files"

Programs using these routines must be compiled with -lsec.

APPLICATION USAGE

In a multithreaded application on standard systems, getspnam, getspnam_r(), getspent(), setspent(), endspent() and fgetspent() are thread-safe, but not async-cancel-safe. A cancellation point may occur when a thread is executing any of these interfaces. On systems which have been converted to trusted mode, only fgetspent() is thread-safe.

RETURN VALUE

If an EOF or error is encountered while reading, getspnam(), getspnam_r(), getspent(), and fgetspent() return a NULL pointer. Otherwise, the return value points to a valid spwd structure. In the case of getspnam(), getspent(), and fgetspent(), the spwd structure resides in an internal area. In the case of getspnam_r(), the spwd structure resides in the spwd structure pointed to by the result argument.

WARNINGS

HP-UX 11i Version 3 is the last release to support trusted systems functionality.

FILES

/etc/passwd: system password file.
/etc/shadow: shadow password file.
/tcb/files/auth/*/*: protected password database, for trusted systems.

STANDARDS CONFORMANCE

getspent : SVID3