getpwent(3C)

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

Synopsis

   #include <sys/types.h>
   #include <pwd.h>
   #include <stdio.h>
   
   struct passwd getpwent (void);
   

   struct passwd getpwuid (uid_t uid);
   

   int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer,
              size_t bufsize, struct passwd **result);
   

   struct passwd getpwnam (const char name);
   

   int getpwnam_r(const char *nam, struct passwd *pwd, char *buffer,
              size_t bufsize, struct passwd **result);
   

   void setpwent (void);
   

   void endpwent (void);
   

   struct passwd fgetpwent (FILE f);

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;
   };

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.

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.

getpwuid_r updates the passwd structure pointed to by pwd and stores a pointer to that structure at the location pointed to by result. The structure will contain an entry from the user database with a matching uid. Storage referenced by the structure is allocated from the memory provided with the buffer parameter, which is bufsize characters in size. A NULL pointer is returned at the location pointed to by result on error or if the requested entry is not 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. If an end-of-file or an error is encountered on reading, these functions return a null pointer.

getpwnam_r updates the passwd structure pointed to by pwd and stores a pointer to that structure at the location pointed to by result. The structure will contain an entry from the user database with a matching name. Storage referenced by the structure is allocated from the memory provided with the buffer parameter, which is bufsize characters in size. A NULL pointer is returned at the location pointed to by result on error or if the requested entry is not found.

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.

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.

getpwuid_r and getpwnam_r return zero on success. Otherwise, an error number is returned to indicate the error.

Diagnostics

getpwuid_r and getpwnam_r return the following value if the corresponding condition is detected:

ERANGE: Insufficient storage was supplied via buffer and bufsize 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), getuid(2), limits(4), passwd(4), pwd(1), types(5)

Notices

For getpwent, getpwuid, getpwnam, setpwent, endpwent, and fgetpwent, all information is contained in a static area, so it must be copied if it is to be saved.

Passwd structures will be obtained from NIS, when the dynamic versions of these routines are used and NIS is installed and running. See passwd(4) for the formats of NIS entries.