NAME

getpwent, getpwent_r, getpwuid, getpwuid_r, getpwnam, getpwnam_r, putpwent, setpwent, setpwent_r, endpwent, endpwent_r, fgetpwent, fgetpwent_r − Access user attribute information in the user database

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <stdio.h> #include <pwd.h> struct passwd ∗getpwent(void); int getpwent_r(
struct passwd ∗result,
char ∗buffer,
int len,
FILE ∗∗pw_fp); struct passwd ∗getpwuid(
uid_t uid);

int getpwuid_r(
uid_t uid,
struct passwd ∗result,
char ∗buffer,
int len);

struct passwd ∗getpwnam(
const char ∗name);

int getpwnam_r(
const char ∗name,
struct passwd ∗result,
char ∗buffer,
int len);

int putpwent(
struct passwd ∗passwd,
FILE ∗file);

int setpwent(void);

int setpwent_r(FILE ∗∗pw_fp);

void endpwent(void);

void endpwent_r(FILE ∗∗pw_fp);

struct passwd ∗fgetpwent (FILE ∗f); int fgetpwent_r(
FILE ∗f,
struct passwd ∗result,
char ∗buffer,
int len);

void setpwfile(
const char ∗filename);

PARAMETERS

uidSpecifies the ID of the user for which the attributes are to be read. 

nameSpecifies the name of the user for which the attributes are to be read. 

passwdSpecifies the password structure that contains the user attributes that are to be written. 

fileSpecifies a stream open for writing to a file. 

resultPoints to the passwd structure that will contain the entry returned by the getpwnam_r(), getpwuid_r(), getpwent_r(), or fgetpwent_r() functions. 

bufferA working buffer for the result parameter that is able to hold the largest password entry in /etc/passwd.  [Digital only] The minimum buffer size is 1024 bytes as defined for SIABUFSIZ in /usr/include/sia.h. 

lenSpecifies the length of the character array that buffer points to.  [Digital only] The minimum buffer size is 1024 bytes as defined for SIABUFSIZ in /usr/include/sia.h. 

fSpecifies a file that contains the next passwd structure.  (This is for the fgetpwent() and fgetpwent_r() functions.) 

pw_fpPoints to a file stream open for reading password entries. 

filenameSpecifies a new default password file rather than using the default /etc/passwd file. 

DESCRIPTION

The getpwent(), getpwuid(), getpwnam(), putpwent(), setpwent(), endpwent(), and fgetpwent() functions may be used to access the basic user attributes. 

The getpwent(), getpwnam(), and getpwuid() functions return information about the specified user.  The getpwent() function returns the next user entry in a sequential search.  The getpwnam() function returns the first user entry in the database with a pw_name field that matches the name parameter.  The getpwuid() function returns the first user entry in the database with a pw_uid field that matches the uid parameter. 

The putpwent() function writes a password entry into a file in the colon-separated format of the /etc/passwd file. 

The setpwent() function ensures that the next call to getpwent() returns the first entry. 

The endpwent() function closes the user database. 

The user structure, which is returned by the getpwent(), getpwnam(), and getpwuid() functions and which is written by the putpwent() function, is defined in the pwd.h file and has the following members:

pw_nameThe name of the user. 

pw_passwdThe encrypted password of the user.  If the password is not stored in the /etc/passwd file and the invoker does not have access to the shadow file that contains them, this field will contain an unencryptable string, usually an ! (exclamation point). 

pw_uidThe ID of the user. 

pw_gidThe group ID of the principle group of the user. 

pw_gecosThe personal information about the user. 

pw_dirThe home directory of the user. 

pw_shellThe initial program for the user. 

The getpwuid_r(), getpwnam_r(), setpwent_r(), getpwent_r(), endpwent_r(), and fgetpwent_r() functions are the reentrant versions of the getpwuid(), getpwnam(), setpwent(), getpwent(), endpwent(), and fgetpwent() functions, respectively. The getpwent_r(), setpwent_r(), and endpwent_r() functions use the pw_fp parameter to keep track of the calls to the getpwent_r() function, so that subsequent calls will return subsequent password entries from the /etc/passwd file.  The setpwent_r() function must be called with the address of a valid file pointer (which may be NULL).  Upon successful completion, the result is stored in result. 

The fgetpwent() and fgetpwent_r() functions get a password file entry from the file specified by the f parameter, rather than from the /etc/passwd file.  This file must have the format of the /etc/passwd file. 

The setpwfile() function sets the new default password file to be filename instead of /etc/passwd. 

The system searches using NIS if NIS is available and your /etc/passwd file has NIS type entries (that is, +:, +name, +@netgroup, and -@netgroup).  The fgetpw∗ routines do not use NIS.  The operating system provides the getpwent_local, getpwuid_local, and getpwnam_local routines to avoid NIS. The getpw∗_local routines are provided only on Digital systems and are not in the pwd.h header file. 

NOTES

All information generated by the getpwent(), fgetpwent(), getpwnam(), and getpwuid() functions is stored in a static area and will be overwritten on subsequent calls to these routines. 

Password file entries which are too long are ignored. 

Note that the pw_fp parameter must be initialized by the user to NULL before the setpwent_r() function is called for the first time. 

If the system is configured to access the basic user attributes database through NIS, the getpwent_r()  function may not produce correct results if called from multiple threads. 

AES Support Level:
Full use (getpwnam(), getpwuid()). 

RETURN VALUES

Upon successful completion, the getpwent(), getpwnam(), getpwuid(), and fgetpwent() functions return a pointer to a valid password structure.  Otherwise, NULL is returned. 

Upon successful completion, the getpwent_r(), getpwnam_r(), getpwuid_r(), and fgetpwent_r(), functions return a value of 0 (zero).  Otherwise, a value of -1 is returned, and errno is set to indicate the error. 

ERRORS

If any of the following conditions occurs, the getpwent_r(), fgetpwent_r(), getpwnam_r() and getpwuid_r() functions set errno to the corresponding value:

[EINVAL]Either the result or buffer parameter is invalid, or len is too small. 

In addition, if any of the following conditions occurs, the getpwnam_r(), getpwuid_r(), and getpwent_r() functions set errno to the corresponding value:

[ESRCH]The entry could not be found. 

RELATED INFORMATION

Functions: getgrent(3).