getutxent(3) Library Functions Manual getutxent(3)
NAME
endutxent, getutxent, getutxid, getutxline, pututxline, setutxent - Access user accounting database functions
LIBRARY
Standard C Library (libc.so, libc.a)
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);
STANDARDS
Interfaces documented on this reference page conform to industry standards 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() function 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 satisfies the request. If this search succeeds, the entry is replaced.
Otherwise, a new entry is made at the end of the user accounting database.
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 correct 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 pututxline() 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 getutxline() 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.
RELATED INFORMATION
Standards: standards(5) delim off
getutxent(3)