Scanning the List of All Users

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.

Function: struct passwd * fgetpwent (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.

This stream must correspond to a file in the same format as the standard password database file. This function comes from System V.

Function: int fgetpwent_r (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.

This stream must correspond to a file in the same format as the standard password database file.

If the function returns null result points to the structure with the wanted data (normally this is in result_buf). If errors occurred the return value is non-null and result contains a null pointer.

The way to scan all the entries in the user database is with setpwent, getpwent, and endpwent.

Function: void setpwent (void)

This function initializes a stream which getpwent and getpwent_r use to read the user database.

Function: struct passwd * getpwent (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 in case no further entry is available.

Function: int getpwent_r (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. But in contrast to the getpwent function this function is reentrant since the result is placed in the user supplied structure pointed to by result_buf. Additional data, normally the strings pointed to by the elements of the result structure, are placed in the additional buffer or length buflen starting at buffer.

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 non-zero and result contains a null pointer.

Function: void endpwent (void)

This function closes the internal stream used by getpwent or getpwent_r.

Go to the first, previous, next, last section, table of contents.