getutent()

Updated: April 19, 2023

Read the next entry from the user-information file

Synopsis:

#include <utmp.h>

struct utmp * getutent( void );

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The getutent() function reads in the next entry from a user-information 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 a utmp structure for 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 No

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.