getspwent(3C)

NAME

getspwent(), getspwuid(), getspwaid(), getspwnam(), setspwent(), endspwent(), fgetspwent() − get secure password file entry

SYNOPSIS

#include <pwd.h>

struct s_passwd *getspwent(void);

struct s_passwd *getspwuid(uid_t uid);

struct s_passwd *getspwaid(aid_t aid);

struct s_passwd *getspwnam(const char *name);

void setspwent(void);

void endspwent(void);

struct s_passwd *fgetspwent(FILE *stream);

DESCRIPTION

These privileged routines provide access to the secure password file in a manner similar to the way getpwent(3C) routines handle the regular password file, (/etc/passwd).

These routines are particularly useful in situations where it is not necessary to get information from the regular password file. getspwent(3C) routines run significantly faster than getpwent(3C) routines because they avoid unnecessary scanning of the password file and use of Network Information Service.

getspwent(), getspwuid(), getspwaid(), and getspwnam() each return a pointer to an object. The s_passwd structure is written in the /.secure/etc/passwd file, and consists of five fields per line, as follows:

struct s_passwd {
    char *pw_name;    /* login name */
    char *pw_passwd; /* encrypted password */
    char *pw_age;     /* password age */
    int   pw_audid;    /* audit ID   */
    int   pw_audflg;   /* audit flag 1=on, 0=off */
};

Since the s_passwd structure is declared in the <pwd.h> header file, it is unnecessary to redeclare it.

getspwent() When first called, getspwent() returns a pointer to each s_passwd structure in /.secure/etc/passwd in sequence. Subsequent calls can be used to search the entire file.

getspwuid() Searches each entry from the beginning of the file until it finds a numerical user ID matching uid. It then returns a pointer to the particular structure in which uid is found. getspwaid() Similarly searches for a numerical audit ID matching aid and returns a pointer to the particular structure in which aid is found (see spasswd(4) for details on this field).

getspwnam() Searches from the beginning of the file until a login name matching name is found. Returns a pointer to the particular structure in which name is found.

setspwent() Resets the file pointer to the beginning of the /.secure/etc/passwd file to allow repeated searches.

endspwent Can be called to close the secure password file when processing is complete.

fgetspwent Returns a pointer to the next s_passwd structure in the stream stream, which matches the format of /.secure/etc/passwd.

RETURN VALUE

getspwent() returns a NULL pointer if any of these routines encounter an end-of-file or error while searching, or if the effective user ID of the calling process is not zero.

WARNINGS

The above routines use <stdio.h>, which causes them to increase the size of programs by more than might otherwise be expected.

Since all information is contained in a static area, it must be copied to be saved.

AUTHOR

getspwent() was developed by HP.

FILES

/.secure/etc/passwd

Museum

Related Articles