getutent(3)getutent(3)Name
getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
access file entries
Syntax
#include <utmp.h>
struct utmp *getutent(void);
struct utmp *getutid(
struct utmp *ID);
struct utmp *getutline(
struct utmp *line);
struct utmp *pututline(
struct utmp *utmp_ptr);
void setutent(void);
void endutent(void);
void utmpname(
char *file);
Arguments
ID The ID argument specifies one of the utmp structure
entries.
line The line argument matches one of the utmp line entries when
accounting for something other than a process.
utmp_ptr The utmp_ptr argument points to a utmp structure to be
placed into the utmp file.
utmp_data The utmp_data argument is data for the utmp database.
Description
The routine reads the next entry from a file similar to the utmp file.
If the file is not already open, the routine opens it. If the file
does not exist, the routine tries to create a file. The routine fails
and returns a null pointer if the end of the file is reached, the file
creation fails, or the read or write file permissions are inappropri‐
ate.
The and routines read forward from the current point in the file until
they find an entry that matches the ID or the line argument, respec‐
tively.
The routine writes the supplied utmp_ptr parameter structure into the
utmp file. If you have not searched for the proper place in the file
using one of the either the or the routines, the routine calls the rou‐
tine to search forward for the proper place. However, it is expected
behavior that the user of the routine has searched for the proper entry
by using either the or the routine. If so, the routine does not
search. If the routine does not find a matching slot for the entry, it
adds a new entry to the end of the file. Note that the routine waits
for a short time before it decides that the current process holding the
lock is dead and proceeds to write to the file.
The routine resets the input stream to the beginning of the file. You
should do this before each search for a new entry if you want to exam‐
ine the entire file.
The routine closes the currently open file.
The routine changes the name of the file to be examined from to any
other filename. The name specified is usually (For example, for
accounting purposes, you can use the routine to change the name.) If
the specified file does not exist, no indication is given until the
file is referenced. The routine does not open the file, but closes the
old file (if it is currently open) and saves the new filename.
These functions use buffered standard I/O for input, but the routine
uses an unbuffered nonstandard write to avoid race conditions between
processes trying to modify the utmp and wtmp files.
Notes
Before accessing the utmp file for the first time, the ut_fd field of
the utmp_data structure must be set to a value of -1.
Return Values
Upon successful completion, the and routines return pointers to the
utmp structure. If a read or write fails due to the end of the file,
or due to a permission conflict, the and routines fail and return a
null pointer. The routine can also fail if the ID is invalid.
The routine returns void. If it is given a file argument that exceeds
the maximum path length, the routine returns and does not change the
file name.
Diagnostics
[EINVAL] Either the utmp, ID, line, or utmp_data argument is
invalid.
[ESRCH] The search failed.
Files
Accounting header file that defines the format for the login database
file.
The active login/logoff database files.
See Alsoopen(2), utmp(4), wtmp(4)getutent(3)