HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

g
getspwent(3X) getspwent(3X)
To access other fields in the protected password database that are not included in the s_passwd structure,
use
getprpwent() . See getprpwent(3) for more information.
getspwent() When first called, getspwent() returns a pointer to each s_passwd structure
obtained from the protected password database for each user in sequence. Subse-
quent calls can be used to search the entire database.
getspwuid() Searches for an entry that matches the specified uid. It then returns a pointer to the
particular structure in which uid is found.
getspwaid() Similarly searches for a numerical audit ID matching aid and returns a pointer to the
particular structure in which aid is found (see passwd(4) for details on this field).
getspwnam() Searches for an entry that matches the specified name. Returns a pointer to the par-
ticular structure in which name is found.
setspwent() Resets the protected password database pointer to the beginning of the file to allow
repeated searches.
endspwent() Should be called to close the protected password database file when processing is com-
plete.
fgetspwent() Is no longer supported. It is provided for those applications that did not use
/.secure/etc/passwd
.
Reentrant Interfaces
getspwuid_r(), getspwaid_r()
, getspwnam_r(), and fgetspwent_r()
expect to be passed
three extra parameters:
1. The address of an s_passwd structure where the result will be stored;
2. A buffer to store character strings (such as the password) to which fields in the s_passwd structure will
point;
3. The length of the user-supplied buffer. A buffer length of 1024 is recommended.
In addition to the above three parameters,
getspwent_r()
requires a pointer to a (FILE *) variable.
setspwent_r() and endspwent_r()
are to be used only in conjunction with getspwent_r() and
take the same pointer to a (
FILE *) variable as a parameter. setspwent_r()
can be used to rewind
or open the protected password database.
endspwent_r()
should be called when done to close the file.
Note that the (
FILE *) variable must be initialized to NULL before it is passed to
getspwent_r() or
setspwent_r() for the first time. Thereafter it should not be modified in any way.
fgetspwent_r() and setspwent_r()
are to be obsoleted at a future date.
APPLICATION USAGE
In a multithreaded application, these routines are safe to be called only from one dedicated thread. These
routines are not POSIX.1c async-cancel safe nor async-signal safe.
RETURN VALUE
getspwent() returns a NULL pointer if any of its routines encounters an end-of-file or error while
searching, or if the effective user ID of the calling process is not zero.
getspwent_r() returns a −1 if any of its routines encounters an end-of-file or error, or if the supplied
buffer has insufficient length. If the operation is successful, 0 is returned.
WARNINGS
The above routines use <stdio.h>, which causes them to increase the size of programs by more than
might otherwise be expected.
Since all information for getspwent() , getspwuid() , getspwaid() , getspwnam() ,
setspwent() , endspwent() , and fgetspwent() is contained in a static area, it must be copied to
be saved.
Network Information Service is not supported on trusted systems.
The routines described in this manpage are no longer supported. They are temporarily available for back-
ward compatibility and are to be obsoleted in a future release.
HP-UX 11i Version 1: September 2005 − 2 − Hewlett-Packard Company Section 3−−383