This section describes how to search and scan the database of registered users. The database itself is kept in the file /etc/passwd on most systems, but on some systems a special network server gives access to it.
The functions and data structures for accessing the system user database are declared in the header file pwd.h. function>struct passwd/function> The passwd data structure is used to hold information about entries in the system user data base. It has at least the following members:
The user's login name.
The encrypted password string.
The user ID number.
The user's default group ID number.
A string typically containing the user's real name, and possibly other information such as a phone number.
The user's home directory, or initial working directory. This might be a null pointer, in which case the interpretation is system-dependent.
The user's default shell, or the initial program run when the user logs in. This might be a null pointer, indicating that the system default should be used.
You can search the system user database for information about a specific user using getpwuid or getpwnam. These functions are declared in pwd.h.
struct passwd * function>getpwuid/function> (uid_t uid) This function returns a pointer to a statically-allocated structure containing information about the user whose user ID is uid. This structure may be overwritten on subsequent calls to getpwuid.
A null pointer value indicates there is no user in the data base with user ID uid.
int function>getpwuid_r/function> (uid_t uid, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result) This function is similar to getpwuid in that it returns information about the user whose user ID is uid. However, it fills the user supplied structure pointed to by result_buf with the information instead of using a static buffer. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.
If a user with ID uid is found, the pointer returned in result points to the record which contains the wanted data (i.e., result contains the value result_buf). If no user is found or if an error occurred, the pointer returned in result is a null pointer. The function returns zero or an error code. If the buffer buffer is too small to contain all the needed information, the error code ERANGE is returned and errno is set to ERANGE.
struct passwd * function>getpwnam/function> (const char *name) This function returns a pointer to a statically-allocated structure containing information about the user whose user name is name. This structure may be overwritten on subsequent calls to getpwnam.
A null pointer return indicates there is no user named name.
int function>getpwnam_r/function> (const char *name, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result) This function is similar to getpwnam in that is returns information about the user whose user name is name. However, like getpwuid_r, it fills the user supplied buffers in result_buf and buffer with the information instead of using a static buffer.
The return values are the same as for getpwuid_r.
This section explains how a program can read the list of all users in the system, one user at a time. The functions described here are declared in pwd.h.
You can use the fgetpwent function to read user entries from a particular file.
struct passwd * function>fgetpwent/function> (FILE *stream) This function reads the next user entry from stream and returns a pointer to the entry. The structure is statically allocated and is rewritten on subsequent calls to fgetpwent. You must copy the contents of the structure if you wish to save the information.
The stream must correspond to a file in the same format as the standard password database file.
int function>fgetpwent_r/function> (FILE *stream, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result) This function is similar to fgetpwent in that it reads the next user entry from stream. But the result is returned in the structure pointed to by result_buf. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.
The stream must correspond to a file in the same format as the standard password database file.
If the function returns zero result points to the structure with the wanted data (normally this is in result_buf). If errors occurred the return value is nonzero and result contains a null pointer.
The way to scan all the entries in the user database is with setpwent, getpwent, and endpwent.
void function>setpwent/function> (void) This function initializes a stream which getpwent and getpwent_r use to read the user database.
struct passwd * function>getpwent/function> (void) The getpwent function reads the next entry from the stream initialized by setpwent. It returns a pointer to the entry. The structure is statically allocated and is rewritten on subsequent calls to getpwent. You must copy the contents of the structure if you wish to save the information.
A null pointer is returned when no more entries are available.
int function>getpwent_r/function> (struct passwd *result_buf, char *buffer, int buflen, struct passwd **result) This function is similar to getpwent in that it returns the next entry from the stream initialized by setpwent. Like fgetpwent_r, it uses the user-supplied buffers in result_buf and buffer to return the information requested.
The return values are the same as for fgetpwent_r.
void function>endpwent/function> (void) This function closes the internal stream used by getpwent or getpwent_r.
int function>putpwent/function> (const struct passwd *p, FILE *stream) This function writes the user entry *p to the stream stream, in the format used for the standard user database file. The return value is zero on success and nonzero on failure.
This function exists for compatibility with SVID. We recommend that you avoid using it, because it makes sense only on the assumption that the struct passwd structure has no members except the standard ones; on a system which merges the traditional Unix data base with other extended information about users, adding an entry using this function would inevitably leave out much of the important information.
The function putpwent is declared in pwd.h.