getspwent(3X)

NAME

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

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);

Obsolescent Interfaces

The following re-entrant interfaces are to be obsoleted:

getspwent_r(), getspwuid_r(), getspwaid_r(), getspwnam_r(), setspwent_r(), endspwent_r(), fgetspwent_r().

#include <pwd.h> 

int getspwent_r(struct s_passwd *result, char *buffer, int buflen, 
     FILE **pwfp); 

int getspwuid_r(uid_t uid, struct s_passwd *result, 
     char *buffer, int buflen); 

int getspwaid_r(aid_t aid, struct s_passwd *result, 
     char *buffer, int buflen); 

int getspwnam_r(char *name, struct s_passwd *result, 
     char *buffer, int buflen); 

void setspwent_r(FILE **pwfp); 

void endspwent_r(FILE **pwfp); 

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 no longer supported. They are temporarily available 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 passwd(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 an 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. A buffer length of 1024 is recommended.

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.

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.

fgetspwent_r() and setspwent_r() are to be obsoleted at a future date.

APPLICATION USAGE

In a multithreaded application, these routines are safe to be called only from one dedicated thread. These routines are not POSIX.1c async-cancel safe nor async-signal safe.

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.

Network Information Service is not supported on trusted systems.

The routines described in this manpage are no longer supported. They are temporarily available for backward compatibility and are to be obsoleted.

Obsolescent Interfaces

The following interfaces are to be obsoleted: getspwent_r(), getspwuid_r(), getspwaid_r(), getspwnam_r(), setspwent_r(), endspwent_r(), and fgetspwent_r().

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

EXAMPLES

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

int count = 0; 
struct s_passwd *pwbuf; 

setspwent(); 
while (pwbuf=getspwent()) 
    count++; 
endspwent(); 

AUTHOR

getspwent() was developed by HP.

FILES

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

getspwent(3X)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Obsolescent Interfaces

DESCRIPTION

Reentrant Interfaces

APPLICATION USAGE

RETURN VALUE

WARNINGS

Obsolescent Interfaces

EXAMPLES

AUTHOR

FILES

SEE ALSO