getutxent(3)getutxent(3)NAME
endutxent, getutxent, getutxid, getutxline, pututxline, setutxent -
Access user accounting database functions
SYNOPSIS
#include <utmpx.h>
void endutxent(
void ); struct utmpx *getutxent(
void ); struct utmpx *getutxid(
const struct utmpx *id ); struct utmpx *getutxline(
const struct utmpx *line ); struct utmpx *pututxline(
const struct utmpx *utmpx ); void setutxent(
void );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
endutxent(), getutxent(), getutxid(), getutxline(), pututxline(),
setutxent(): XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies one of the BOOT_TIME, OLD_TIME, NEW_TIME, INIT_PROCESS,
LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS entries. Matches a utmpx
entry of the type LOGIN_PROCESS or USER_PROCESS such that the ut_line
member matches line->ut_line. Points to a utmpx structure to be placed
into the user accounting database.
DESCRIPTION
These functions provide access to the user accounting database.
The getutxent() function reads the next entry from the user accounting
database. If the database is not already open, getutxent() opens it. If
the end of the database is reached, getutxent fails.
The getutxid() function searches forward from the current point in the
database. If the ut_type value of the utmpx structure pointed to by the
id parameter is BOOT_TIME, OLD_TIME, or NEW_TIME, the getutxid() func‐
tion stops when an entry with a matching ut_type value is found.
If the ut_type value is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or
DEAD_PROCESS, the getutxid() function returns a pointer to the first
entry whose type is one of these four and whose ut_id field matches
id->ut_id. If the end of the database is reached without a match, the
getutxid() function fails.
The getutxline() function searches forward from the current point in
the database until it finds an entry of the type LOGIN_PROCESS or
USER_PROCESS which also has a ut_line value that matches the value in
the utmpx structure pointed to by the line parameter. If the end of
the database is reached without a match, the getutxline() function
fails.
If the process has appropriate privileges, the pututxline() function
writes out the structure into the user accounting database. The
pututxline() function calls getutxid() to search for a record that sat‐
isfies the request. If this search succeeds, the entry is replaced.
Otherwise, a new entry is made at the end of the user accounting data‐
base.
The setutxent() function resets the input stream to the beginning of
the database. This should be done before each search for a new entry if
you want to examine the entire database.
The endutxent() function closes the user accounting database.
NOTES
The most current entry is saved in a thread-specific structure, which
is overwritten by a subsequent call to getutxid() or getutxline() by
the same thread. To make multiple accesses, you must copy or use the
structure between each access. The getutxid() and getutxline() func‐
tions examine the thread-specific structure first. If the contents of
this structure match what they are searching for, they do not read the
database. Therefore, you must fill the thread-specific structure with
zeros after each use if you want to use these subroutines to search for
multiple occurrences.
If the pututxline() function finds that it is not already at the cor‐
rect place in the user accounting database, the implicit read it per‐
forms does not overwrite the contents of the thread-specific structure
returned by the getutxent(), getutxid(), or getutxline() functions.
This allows you to get an entry with one of these subroutines, modify
the structure, and pass the pointer back to the pututxline() function
for writing.
These functions use buffered standard I/O for input, but the pututx‐
line() function uses an unbuffered write to avoid race conditions
between processes trying to modify the utmpx and wtmpx files.
RETURN VALUES
Upon successful completion, the getutxent(), getutxid(), and getutx‐
line() functions return pointers to a utmpx structure containing a copy
of the requested entry in the user accounting database. Otherwise, a
null pointer is returned.
Upon successful completion, the pututxline() function returns a pointer
to a utmpx structure containing a copy of the entry added to the user
accounting database. Otherwise, a null pointer is returned.
ERRORS
The pututxline() function may fail and set errno to the corresponding
value if the following condition occurs: The process does not have the
appropriate privileges.
FILES
Accounting header file that defines the format for the login database
file. The active login/logoff database files.
SEE ALSO
Standards: standards(5)getutxent(3)
