hpux 10.20 - getpwent (3)
NAME
getpwent(), getpwent_r(), getpwuid(), getpwuid_r(), getpwnam(),
getpwnam_r(), setpwent(), setpwent_r(), endpwent(), endpwent_r(),
fgetpwent(), fgetpwent_r() - get password file entry
SYNOPSIS
#include <pwd.h>
struct passwd *getpwent(void);
int getpwent_r(struct passwd *result, char *buffer, int buflen,
FILE **pwfp);
struct passwd *getpwuid(uid_t uid);
int getpwuid_r(uid_t uid, struct passwd *result,
char *buffer, int buflen);
struct passwd *getpwnam(const char *name);
int getpwnam_r(char *name, struct passwd *result,
char *buffer, int buflen);
void setpwent(void);
void setpwent_r(FILE **pwfp);
void endpwent(void);
void endpwent_r(FILE **pwfp);
struct passwd *fgetpwent(FILE *stream);
int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);
DESCRIPTION
getpwent(), getpwuid(), and getpwnam() locate an entry in the
/etc/passwd file, and return a pointer to an object of passwd
structure.
The passwd structure is defined in <pwd.h> and includes the following
members:
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
uid_t pw_uid; /* user id */
gid_t pw_gid; /* group id */
char *pw_age; /* password aging */
char *pw_comment;/* unused */
char *pw_gecos; /* user fullname, office, extension, homephone*/
char *pw_dir; /* initial directory */
char *pw_shell; /* initial shell */
aid_t pw_audid; /* numerical audit id */
int pw_audflg; /* numerical audit flag */
The pw_comment field is unused; for more information on the other
fields, refer to passwd(4).
getpwent() When first called, getpwent() returns a pointer to
the first passwd structure in the file.
Thereafter, it returns a pointer to the next
passwd structure in the file. In this way,
successive calls can be used to search the entire
file. getpwent() opens the /etc/passwd file prior
to doing its work and leaves the file open
afterward;
setpwent() Has the effect of rewinding this file to allow
repeated searches;
endpwent() Can be called to close the file when processing is
complete.
getpwuid() Searches from the beginning of the file until a
numeric user ID matching uid is found, and returns
a pointer to the particular structure in which it
was found.
getpwnam() searches from the beginning of the file until a
login name matching name is found, and returns a
pointer to the particular structure in which it
was found.
fgetpwent() 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.
Reentrant Interfaces
getpwuid_r(), getpwnam_r() and fgetpwent_r() expect to be passed three
extra parameters:
1. The address of a passwd structure where the result will be stored;
2. A buffer to store character strings (such as the password) to which
fields in passwd structure will point;
3. The length of the user-supplied buffer.
In addition to the above three parameters, getpwent_r() requires a
pointer to a (FILE *) variable into which is stored the result of an
fopen() call on the /etc/passwd file. This is to allow threads to
independently scan through the /etc/passwd file. setpwent_r() and
endpwent_r() are to be used only in conjunction with getpwent_r() and
take the same pointer to a (FILE *) variable as a parameter.
setpwent_r() can be used to rewind or open the /etc/passwd file.
endpwent_r() must be called when done to close the file and release
memory associated with that instance of the opened file.
Note that the (FILE *) variable must be initialized to NULL before it
is passed to getpwent_r() or setpwent_r() for the first time.
Thereafter it should not be modified in any way.
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
getprpwent(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 databse entries. See getprpwent(3).
NETWORKING FEATURES
NFS
If an entry beginning with a plus sign (+) or a minus sign (-) is
found, these routines try to use the Network Information Service
network database for data. See passwd(4) for proper syntax and
operation.
Network Information Service (NIS) is not supported on trusted systems.
RETURN VALUE
getpwent(), getpwuid(), getpwnam(), and fgetpwent() return a NULL
pointer if an end-of-file or error is encountered on reading.
Otherwise, the return value points to an internal static area
containing a valid passwd structure.
getpwent_r(), getpwuid_r(), getpwnam_r(), and fgetpwent_r(), return a
-1 if the end-of-file or error is encountered, or if the supplied
buffer is of insufficient length. If the operation is successful, 0
is returned.
ERRORS
getpwent(), getpwuid(), 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 above routines use <stdio.h> and the Network Information Service
library, which causes them to increase the size of programs, not
otherwise using standard I/O and Network Information Service, more
than might be expected.
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.
getpwent(), getpwuid(), getpwnam(), setpwent(), endpwent(), and
fgetpwent() are unsafe in multi-thread applications. getpwent_r(),
getpwuid_r(), getpwnam_r(), setpwent_r(), endpwent_r(), and
fgetpwent_r() are MT-Safe and should be used instead.
The following fields have numerical limitations as 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.
Users of getpwnam_r() and getpwuid_r() should also note that the
prototypes of these functions will change in the next release for
conformance with the new POSIX Threads standard.
EXAMPLE
The following code excerpt counts the number of entries in the
/etc/passwd file:
int count = 0;
struct passwd pwbuf;
char buffer[1024];
FILE *pwf = NULL;
setpwent_r(&pwf);
while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)
count++;
endpwent_r(&pwf);
DEPENDENCIES
NFS
Files:
/var/yp/domainname/passwd.byname
/var/yp/domainname/passwd.byuid
See Also:
ypcat(1).
AUTHOR
getpwent(), getpwuid(), getpwnam(), setpwent(), endpwent(), and
fgetpwent() were developed by AT&T and HP.
FILES
/etc/passwd System Password file
SEE ALSO
ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3),
getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4),
limits(5).
STANDARDS CONFORMANCE
getpwent(): SVID2, SVID3, XPG2
endpwent(): SVID2, SVID3, XPG2
fgetpwent(): SVID2, SVID3, XPG2
getpwnam(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
getpwuid(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
setpwent(): SVID2, SVID3, XPG2