getutent()

Read the next entry from the user-information file

Synopsis:

#include <utmp.h>

struct utmp * getutent( void );

Description:

The getutent(), getutid(), getutline(), and pututline() functions each return a pointer to a utmp structure with at least the following members:

char                 ut_user[8];    /* user login name */
char                 ut_id[4];      /* /sbin/inittab id */
                                   /* (usually line #) */
char                 ut_line[12];   /* device name (console, lnxx) */
short                ut_pid;        /* process id */
short                ut_type;       /* type of entry */
struct exit_status   ut_exit;       /* exit status of a process */
                                    /* marked as DEAD_PROCESS */
time_t               ut_time;       /* time entry was made */

The structure exit_status includes at least the following members:

short   e_termination;   /* termination status */
short   e_exit;          /* exit status */

The getutent() function reads in the next entry from a utmp-like file. If the file isn't already open, getutent() opens it. If the function reaches the end of the file, it fails.

Returns:

A pointer to the next entry, or NULL if the file couldn't be read or reached the end of file.

Files:

_PATH_UTMP: Specifies the user information file.

Classification:

Unix

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes

Caveats:

The most current entry is saved in a static structure. Copy it before making further accesses.

On each call to either getutid() or getutline(), the routine examines the static structure before performing more I/O. If the contents of the static structure match what it's searching for, the function looks no further. For this reason, to use getutline() to search for multiple occurrences, zero out the static area after each success, or getutline() will return the same structure over and over again.

There's one exception to the rule about emptying the structure before further reads are done: the implicit read done by pututline() (if it finds that it isn't already at the correct place in the file) doesn't hurt the contents of the static structure returned by the getutent(), getutid() or getutline() routines, if you just modified those contents and passed the pointer back to pututline().

These routines use buffered standard I/O for input, but pututline() uses an unbuffered nonstandard write to avoid race conditions between processes trying to modify the utmp and wtmp files.