HP-UX Reference (11i v3 07/02) - 3 Library Functions A-M (vol 6)

g
getpwent(3C) getpwent(3C)
getpwnam() Searches from the beginning of the password database until a login name matching
name is found, and returns a pointer to the particular structure in which it was found.
fgetpwent() Unlike the other functions above, does not use
nsswitch.conf, nor access NIS It
returns a pointer to the next
passwd structure in the standard I/O stream stream,
which should be open for reading, and its contents should match the format of
/etc/passwd .
Obsolescent Interfaces
getpwent_r() , setpwent_r() , endpwent_r() , fgetpwent_r()
get password file entry.
Reentrant Interfaces
getpwuid_r() , and getpwnam_r() both update the struct passwd
pointed to by pwd and store
a pointer to that structure at the location pointed to by
result. The structure must contain an entry
from the user database with a matching
uid
or name. Storage referenced by the passwd structure
pointed to by
pwd is allocated from the memory provided with the
buffer parameter, which is defined as
buflen in size. The maximum size needed for this buffer can be determined with the
_SC_GETPW_R_SIZE_MAX sysconf()
parameter. A NULL pointer is returned at the location
pointed to by
result on error or if the requested entry is not found.
Notes
When the repository is set to files in the /etc/nsswitch.conf
file, then the getpwent(),
getpwuid() , getpwuid_r() , getpwnam() , and getpwnam_r() calls return the passwd struc-
ture exactly as it appears in the /etc/passwd file. In shadowed standard mode, the calls normally
return "x" (instead of the encrypted password and aging information) in the pw_passwd field. The same
applies for calls to
fgetpwent() when the argument stream is set to /etc/passwd .
SECURITY FEATURES
If the system has been converted to a trusted system, the password, audit ID, and audit flag are not
returned. The password will be the default * that is in /etc/passwd and the audit ID and audit flag
will be set to −1. On trusted systems, if it is not necessary to obtain information from the regular pass-
word file, /etc/passwd , users should use getprpwent() to access the protected password database.
See getprpwent(3) and getspwent(3X).
putpwent() affects only /etc/passwd , and the audit ID and audit flag in the password structure are
ignored. putprpwnam() must be used to modify the protected password database entries. See get-
prpwent(3).
See WARNINGS about trusted system support.
RETURN VALUE
getpwent() , getpwuid() , getpwnam() , and fgetpwent() return a NULL pointer if an end-of-
file or error is encountered on reading. fgetpwent() returns a NULL pointer on encountering an
invalid entry. An invalid entry is one which does not follow the /etc/passwd structure. Otherwise, the
return value points to an internal static area containing a valid passwd structure.
getpwuid_r() and getpwnam_r() return zero upon success. Otherwise, an error number is
returned to indicate the error.
ERRORS
getpwent() , getpwuid() , getpwnam() , and fgetpwent() fail if any of the following are true:
[EIO] An I/O error has occurred.
[EMFILE] OPEN_MAX descriptors are currently open in the calling process.
[ENFILE] The maximum allowable number of files is currently open in the system.
The getpwnam_r() and getpwuid_r() functions will fail if:
[ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to be refer-
enced by the resulting passwd structure
WARNINGS
The value returned by getpwent() , getpwuid() , getpwnam() , and fgetpwent() points to a
single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be
saved.
HP-UX 11i Version 3: February 2007 − 2 − Hewlett-Packard Company 557