getspwent(3X)

NAME

getspwent(), getspwent_r(), getspwuid(), getspwuid_r(), getspwaid(), getspwaid_r(), getspwnam(), getspwnam_r(), setspwent(), setspwent_r(), endspwent(), endspwent_r(), fgetspwent(), fgetspwent_r() − get secure password file entry , on trusted systems

SYNOPSIS

#include <pwd.h>

struct s_passwd *getspwent(void);

int getspwent_r(struct s_passwd *result, char *buffer, int buflen,

FILE **pwfp);

struct s_passwd *getspwuid(uid_t uid);

int getspwuid_r(uid_t uid, struct s_passwd *result,

char *buffer, int buflen);

struct s_passwd *getspwaid(aid_t aid);

int getspwaid_r(aid_t aid, struct s_passwd *result,

char *buffer, int buflen);

struct s_passwd *getspwnam(const char *name);

int getspwnam_r(char *name, struct s_passwd *result,

char *buffer, int buflen);

void setspwent(void);

void setspwent_r(FILE **pwfp);

void endspwent(void);

void endspwent_r(FILE **pwfp);

struct s_passwd *fgetspwent(FILE *stream);

int fgetspwent_r(FILE *f, struct s_passwd *result,

char *buffer, int buflen);

DESCRIPTION

These privileged routines provide access to the protected password database 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(3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, libsec.

Note that getspwent() routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the getprpwent() routines. See getprpwent(3).

getspwent(), getspwuid(), getspwaid(), and getspwnam() each returns a pointer to an object of s_passwd structure. The s_passwd structure is maintained for compatibility with existing software and consists of five fields 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.

To access other fields in the protected password database that are not included in the s_passwd structure, use getprpwent(). See getprpwent(3) for more information.

getspwent() When first called, getspwent() returns a pointer to each s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database.

getspwuid() Searches for an entry that matches the specified 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 for an entry that matches the specified name. Returns a pointer to the particular structure in which name is found.

setspwent() Resets the protected password database pointer to the beginning of the file to allow repeated searches.

endspwent() Should be called to close the protected password database file when processing is complete.

fgetspwent() Is no longer supported. It is provided for those applications that did not use /.secure/etc/passwd.

Reentrant Interfaces

getspwuid_r(), getspwaid_r(), getspwnam_r(), and fgetspwent_r() expect to be passed three extra parameters:

1. The address of a s_passwd structure where the result will be stored;

2. A buffer to store character strings (such as the password) to which fields in the s_passwd structure will point;

3. The length of the user-supplied buffer.

In addition to the above three parameters, getspwent_r() requires a pointer to a (FILE *) variable. setspwent_r() and endspwent_r() are to be used only in conjunction with getspwent_r() and take the same pointer to a (FILE *) variable as a parameter. setspwent_r() can be used to rewind or open the protected password database. endspwent_r() should be called when done to close the file.

The /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database.

fgetspwent_r() is no longer supported, but is included for those users that did not use the /.secure/etc/passwd file.

Note that the (FILE *) variable must be initialized to NULL before it is passed to getspwent_r() or setspwent_r() for the first time. Thereafter it should not be modified in any way.

A buffer length of 1024 is recommended.

RETURN VALUE

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

getspwent_r() returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned.

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 for getspwent(), getspwuid(), getspwaid(), getspwnam(), setspwent(), endspwent(), and fgetspwent() is contained in a static area, it must be copied to be saved.

getspwent(), getspwuid(), getspwaid(), getspwnam(), setspwent(), endspwent(), and fgetspwent() are unsafe in multi-thread applications. getspwent_r(), getspwuid_r(), getspwaid_r(), getspwnam_r(), setspwent_r(), endspwent_r(), and fgetspwent_r() are MT-Safe and should be used instead.

Network Information Service is not supported on trusted systems.

EXAMPLE

The following code excerpt counts the number of entries in the protected password database:

int count = 0;
struct s_passwd pwbuf;
char buffer[1024];
FILE *pwf = NULL;
setspwent_r(&pwf);
while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)
count++;
endspwent_r(&pwf);

AUTHOR

getspwent() was developed by HP.

FILES

/tcb/files/auth/*/* Protected Password database

Museum

Related Articles

getspwent(3X)

NAME

SYNOPSIS

DESCRIPTION

Reentrant Interfaces

RETURN VALUE

WARNINGS

EXAMPLE

AUTHOR

FILES

SEE ALSO