OSF  —  Environment_Note_Added

NAME

getpwent, getpwuid, getpwnam, putpwent, setpwent, setpwfile, endpwent − Accesses the basic user information in the user database

SYNOPSIS

#include <pwd.h> struct passwd ∗getpwent ( void ) struct passwd ∗getpwuid (
uid_t uid );

int ∗getpwuid_r (
uid_t uid,
struct passwd ∗result,
char buffer,
int len ); int ∗getpwnam_r (
const char ∗name,
struct passwd ∗result,
char buffer,
int len ); struct passwd ∗getpwnam (
const char ∗name ); int putpwent (
struct passwd ∗passwd
FILE ∗file ); void setpwent ( void ) void endpwent ( void ) void setpwfile (
char ∗pathname )

PARAMETERS

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

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

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

fileSpecifies a stream open for writing to a file whose format is like that of the /etc/passwd file. 

resultPoints to passwd structure to contain the entry returned by the getpwnam_r() or getpwuid_r() functions. 

bufferPoints to a character array to contain the strings associated with the entry returned by the getpwnam_r() or getpwuid_r() functions. 

lenSpecifies the length of the character array that buffer points to. 

pathnameSpecifies the pathname of the file used for local passwd lookups. 

DESCRIPTION

The getpwent(), getpwuid(), getpwnam(), putpwent(), setpwent(), and endpwent() 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 the 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 insures 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. 

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() and getpwnam_r() functions are the reentrant versions of the getpwuid() and getpwnam() functions, respectively.  Upon successful completion, the result is stored in two parts.  The struct passwd (which includes only pointers) is stored in result, and the strings themselves are stored in buffer. 

The setpwfile subroutine sets the pathname of the passwd file and optional hashed database to be used for local passwd lookups.  If a passwd file has been left open by a call to setpwent or getpwent, setpwfile will close it first. 

LIBRARY

Standard C Library (libc.a)

NOTES

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

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

ERRORS

If the getpwnam_r() or getpwuid_r() function fails, errno may be set to one of the following values:

[EINVAL]Either the result or buffer parameter is empty. 

[ENOENT]The entry could not be found. 

RETURN VALUES

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

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

ENVIRONMENT NOTES

This section describes system features that are not generic to OSF/1 but that are provided in this OSF/1 implementation. 

Digital Extensions

The system searches either the local /etc/passwd file or the NIS distributed networks file for the requested information.  To determine which file or files to search, and in which order, the system uses the switches in the /etc/svc.conf file. 
 

RELATED INFORMATION

Functions: getgrent(3)