getpwent(3C)

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

   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

Return values

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

Diagnostics

ENOMEM

sufficient space for the entry cannot be allocated.

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

References

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.