getpwent, getpwuid, getpwnam, putpwent, setpwent, or endpwent Subroutine

Purpose

Accesses the basic user information in the user database.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <pwd.h>

struct passwd *getpwent ( )

struct passwd *getpwuid ( UserID) uid_t UserID;

struct passwd *getpwnam ( Name) char *Name;

int putpwent ( Password, File) struct passwd *Password; FILE *File;

void setpwent ( )

void endpwent ( )

Description

Attention: All information generated by the getpwent, getpwnam, and getpwuid subroutines is stored in a static area. Subsequent calls to these subroutines overwrite this static area. To save the information in the static area, applications should copy it.

Attention: The getpwent subroutine is only supported by LOCAL and NIS load modules, not any other LAM authentication module.

These subroutines access the basic user attributes.

The setpwent subroutine opens the user database if it is not already open. Then, this subroutine sets the cursor to point to the first user entry in the database. The endpwent subroutine closes the user database.

The getpwent, getpwnam, and getpwuid subroutines return information about a user. These subroutines do the following:

Item	Description
getpwent	Returns the next user entry in the sequential search.
getpwnam	Returns the first user entry in the database whose name matches the Name parameter.
getpwuid	Returns the first user entry in the database whose ID matches the UserID parameter.

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

The passwd Structure

The getpwent, getpwnam, and getpwuid subroutines return a passwd structure. The passwd structure is defined in the pwd.h file and has the following fields:

Item	Description
`pw_name`	Contains the name of the user name.
`pw_passwd`	Contains the user's encrypted password. Note: If the password is not stored in the /etc/passwd file and the invoker does not have access to the shadow file that contains passwords, this field contains an undecryptable string, usually an `*` (asterisk).
`pw_uid`	Contains the user's ID.
`pw_gid`	Identifies the user's principal group ID.
`pw_gecos`	Contains general user information.
`pw_dir`	Identifies the user's home directory.
`pw_shell`	Identifies the user's login shell.

Note: If Network Information Services (NIS) is enabled on the system, these subroutines attempt to retrieve the information from the NIS authentication server before attempting to retrieve the information locally.

Parameters

Item	Description
File	Points to an open file whose format is similar to the /etc/passwd file format.
Name	Specifies the user name.
Password	Points to a password structure. This structure contains user attributes.
UserID	Specifies the user ID.

Security

Item	Description
Files Accessed:

Mode	File
rw	/etc/passwd (write access for the putpwent subroutine only)
r	/etc/security/passwd (if the password is desired)

Return Values

The getpwent, getpwnam, and getpwuid subroutines return a pointer to a valid password structure if successful. Otherwise, a null pointer is returned.

The getpwent subroutine will return a null pointer and an errno value of ENOATTR when it detects a corrupt entry. To get subsequent entries following the corrupt entry, call the getpwent subroutine again.

Error codes

If any of these subroutines fail, the following errors might be returned:

Item	Description
EACCES	Access permission is denied for the data request.
EINVAL	The parameter does not contain one of the defined attributes or null.
EIO	Failed to access remote user database.
ENOATTR	The specified attribute is not defined for the current user.
EPERM	Operation is not permitted.
ESRCH	The specified parameter does not exist.

Files

Item	Description
/etc/passwd	Contains user IDs and their passwords