HP-UX Reference (11i v1 00/12) - 3 Library Functions A-M (vol 6)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/!!!intro.3c
________________________________________________________________
___ ___
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 or
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 structpasswd pointed to by pwd and store a
pointer to that structure at the location pointed to by result. The structure shall contain an entry from
the user database with a matching uid or name. Storage referenced by the passwd structure pointed to
by pwd shall be allocated from the memory provided with the buffer parameter, which is 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.
A buffer length of 1024 is recommended.
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 password file,
/etc/passwd , users should use getprpwent () to access the protected password database. See get-
prpwent(3) and getspwent(3X).
putpwent() affects only /etc/passwd ; 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).
APPLICATION USAGE
getpwuid() and getpwnam() are not thread-safe. getpwent(), setpwent(), endpwent() ,
fgetpwent() , getpwuid_r() , and getpwnam_r() are thread-safe. These interfaces are not async-
cancel-safe. A cancellation point may occur when a thread is executing any of these interfaces.
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.
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.
The following fields have numerical limitationsas noted:
• The user ID is an integer value between -2 and UID_MAX inclusive.
• The group ID is an integer value between 0 and UID_MAX inclusive.
HP-UX Release 11i: December 2000 − 2 − Section 3−−341
___
___