endutxent, getutxent, getutxid, getutxline, pututxline, setutxent - manage utmpx entries

Syntax

#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); 

Description

These functions allow access to the user accounting file /var/adm/utmpx.

getutxent(), getutxid() and getutxline() return a pointer to a utmpx structure containing the following fields:

char     ut_user[32];  /* Login name of the user */
char     ut_id[4];     /* /sbin/inittab ID (normally line no.) */
char     ut_line[32];  /* Device name (console, lnxx) */
pid_t    ut_pid;       /* Process ID */
short    ut_type;      /* Type of entry */
struct     exit_status {
    short     e_termination;  /* End status */
    short     e_exit;         /* Exit status */
} ut_exit;   /* Exit status of a process marked as DEAD_PROCESS */
struct timeval ut_tv;  /* Time entry made */
long     ut_session;   /* session ID, used for windowing  */
short    ut_syslen;    /* Significant length of ut_host */
char     ut_host[257]; /* Host name if given */

getutxent() reads the next entry from a utmpx-similar file. If the file is not yet open, it will be opened. If the end of the file is reached, the operation fails.

getutxid() searches forward from the current position in the utmpx file until an entry is found whose ut_type matches the id->ut_type if the specified type is RUN_LVL, BOOT_TIME,OLD_TIME or NEW_TIME. If the type specified in id is INIT_PROCESS, LOGIN_PROCESS,USER_PROCESS or DEAD_PROCESS, then getutxid() returns a pointer to the first entry whose type matches one of these four types and whose ut_id component matches the value of the transferred id->ut_id. If the end of the file is reached before a matching entry is found, the operation fails.

In all entries that are found with getutxid(), the ut_type component identifies the type of the entry. Depending on the value of ut_type, each entry contains further data that is significant for the processing:

Value of ut_type	Other components
EMPTY	No further data
BOOT_TIME	ut_tv
OLD_TIME	ut_tv
NEW_TIME	ut_tv
USER_PROCESS	ut_id, ut_user (login name), ut_line, ut_pid, ut_tv
INIT_PROCESS	ut_id, ut_pid, ut_tv
LOGIN_PROCESS	ut_id, ut_user (implementation-specific name of the login process), ut_pid, ut_tv
DEAD_PROCESS	ut_id, ut_pid, ut_tv

getutxline() searches forwards from the current position in the utmpx file until an entry with the type LOGIN_PROCESS or USER_PROCESS is found, whose ut_line string matches line->ut_line. If the end of the file is reached before a matching entry is found, the operation fails.

pututxline() writes the specified utmpx structure to the utmpx file. getutxid() is used to search for the correct position in the file if this is not given. It is expected that the user of

pututxline() has searched for the corresponding entry with one of the

getutx() functions. If this is the case, pututxline() does not perform a search. If pututxline() does not find an appropriate position for the new entry, the entry is added to the end of the file. A pointer to the utmpx structure is returned. To be able to use pututxline(), the process must have the appropriate privileges.

setutxent() sets the position of the input stream to the beginning of the file. This should be done before the whole file is searched for a new entry.

endutxent() closes the opened file.

endutxent(), getutxent(), getutxid(), getutxline(), pututxline() andsetutxent() are not thread-safe.

Return val.

getutxent(), getutxid() and getutxline():

Pointer to a utmpx structure

if successful. The returned structure contains a copy of the desired entry in
the user accounting file.

Null pointer

at EOF or if an error occurs.

pututxline():

Pointer to a utmpx structure

if successful. The returned structure contains a copy of the entry that was
written to the user accounting file.

Errors

pututxline() will fail if:

EPERM      the process does not have sufficiently high privileges.

Notes

The return value points to a static area that will be overwritten by a subsequent call of
getutxid() or getutxline().

The latest entry is stored in a static structure. Before the file is accessed again, this entry
must be copied. When getutxid() or getutxline() are called, the routines check the
static structure before further I/O operations are performed. If the contents of the static
structure match the pattern being sought, the search is discontinued. If several identical
entries are to be sought with getutxline(), the static structure must be deleted after
every successful search operation; otherwise getutxline() will keep returning the same
structure.

The implicit reading via pututxline() (if the correct position in the file has not yet been
reached) does not change the contents of the static structure that is returned by
getutxent(), getutxid() or getutxline(), as pututxline() saves the contents of
the structure before reading.

The size of the arrays in the structure can be determined via the sizeof operator.

See also

utmpx.h.