getpwent(3C)


getpwent, getpwent_r, getpwuid, getpwuid_r, getpwnam, getpwnam_r, setpwent, endpwent, fgetpwent, fgetpwent_r -- manipulate password file

Synopsis

   #include <pwd.h>
   

struct passwd *getpwent (void);

int getpwent_r (struct passwd *pwd, char *buf, size_t len, struct passwd **ptr);

struct passwd *getpwuid (uid_t uid);

int getpwuid_r (uid_t uid, struct passwd *pwd, char *buf, size_t len, struct passwd **ptr);

struct passwd *getpwnam (const char *name);

int getpwnam_r (const char *name, struct passwd *pwd, char *buf, size_t len, struct passwd **ptr);

void setpwent (void);

void endpwent (void);

struct passwd *fgetpwent (FILE *f);

int fgetpwent_r (FILE *f, struct passwd *pwd, char *buf, size_t len, struct passwd **ptr);

Description

getpwent, getpwuid, and getpwnam each returns a pointer to an object with the following structure containing the broken-out fields of a line in the /etc/passwd file. Each line in the file contains a passwd structure, declared in the pwd.h header file:
   struct passwd {
   	char	*pw_name;
   	char	*pw_passwd;
   	uid_t	pw_uid;
   	gid_t	pw_gid;
   	char	*pw_age;
   	char	*pw_comment;
   	char	*pw_gecos;
   	char	*pw_dir;
   	char	*pw_shell;
   };

The corresponding reentrant routines getpwent_r, getpwuid_r, and getpwnam_r each return zero, set the pointer pointed-to by ptr to be the address of the structure pointed-to by pwd, and fill in the structure whose address was passed as pwd if there is either a next entry (for getpwent_r) or a matching entry (for getpwnam_r and getpwuid_r). Otherwise, they set the pointer pointed-to by ptr to be null and return zero if no entry was found, or a nonzero errno-code if some error occurred. The buf argument points to the start of an array of at least len bytes into which these routines may read the input line and thus store the strings pointed-to by the filled-in structure. If insufficient space is provided, they fail, returning ERANGE.

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. Thus successive calls can be used to search the entire file. The same is true for the getpwent_r routine except that the objects filled-in are provided by the caller. Note that getpwent_r shares the ``current location'' in the file with getpwent.

getpwuid searches from the beginning of the file until a numerical user ID matching uid is found and returns a pointer to the particular structure in which it was found. The same is true for the getpwuid_r routine except that the objects filled-in are provided by the caller.

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. The same is true for the getpwnam_r routine except that the objects filled-in are provided by the caller.

A call to setpwent has the effect of rewinding the password file to allow repeated searches. endpwent may be called to close the password file when processing is complete.

fgetpwent returns a pointer to the next passwd structure in the stream f, which matches the format of /etc/passwd. The same is true for the fgetpwent_r routine except that the objects filled-in are provided by the caller.

Files

/etc/passwd
/var/yp/domainame/passwd.byname
/var/yp/domainame/passwd.byuid

Return values

getpwent, getpwuid, getpwnam, and fgetpwent return a null pointer on EOF or error.

getpwent_r, getpwuid_r, getpwnam_r, and fgetpwent_r return zero on EOF or a nonzero errno-code on error.

Diagnostics

getpwent, getpwuid, getpwnam, fgetpwent, setpwent, and endpwent return the following values if the corresponding conditions are detected:

ENOMEM
sufficient space for the entry cannot be allocated.
getpwent_r, getpwuid_r, getpwnam_r, and fgetpwent_r return the following value if the corresponding condition is detected:

ERANGE
Insufficient storage was supplied in the len bytes of buf to contain the data to be referenced by the resulting passwd structure.

Standards Compliance

The Single UNIX Specification, Version 2; The Open Group.

References

getgrent(3C), getlogin(3C), nsdispatch(3C), putpwent(3C), getuid(2), limits(4), passwd(4), pwd(1), types(5)

Notices

Except for fgetpwent and fgetpwent_r, these routines use NSS (Name Service Switch) to decide how to process the requested operations. See nsdispatch(3C).

For fgetpwent, getpwent, getpwuid, getpwnam, setpwent, and endpwent, all information is contained in a thread-specific buffers so that calls from separate threads will not interfere. Subsequent calls from the same thread will reuse these buffers, so information must be copied if it is to be saved. Moreover, getpwent and getpwent_r share the thread-specific current location in the password file.

Depending on whether NIS is installed and enabled, when the dynamic versions of these routines are used, and the NSS routing is so configured, the passwd structures may be obtained from NIS. See passwd(4) for the formats of NIS entries.


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004