ENDUTXENT(3) | Library Functions Manual | ENDUTXENT(3) |
endutxent
,
getutxent
, getutxid
,
getutxline
, pututxline
,
setutxent
— user accounting
database functions
Standard C Library (libc, -lc)
#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 *utx);
void
setutxent
(void);
These functions provide access to the utmpx(5) user accounting database.
getutxent
()
reads the next entry from the database; if the database was not yet open, it
also opens it.
setutxent
()
resets the database, so that the next getutxent
()
call will get the first entry.
endutxent
()
closes the database.
getutxid
()
returns the next entry of the type specified in its argument's
ut_type field, or NULL
if none
is found.
getutxline
()
returns the next LOGIN_PROCESS
or
USER_PROCESS
entry which has the same name as
specified in the ut_line field, or
NULL
if no match is found.
pututxline
()
adds the argument utmpx(5) entry line to
the accounting database, replacing a previous entry for the same user if it
exists. Only the superuser may write to the accounting database.
The utmpx
structure has the following
definition:
struct utmpx { char ut_user[_UTX_USERSIZE]; /* login name */ char ut_id[_UTX_IDSIZE]; /* id */ char ut_line[_UTX_LINESIZE]; /* tty name */ pid_t ut_pid; /* process id creating the entry */ short ut_type; /* type of this entry */ struct timeval ut_tv; /* time entry was created */ char ut_host[_UTX_HOSTSIZE]; /* host name */ __uint32_t ut_pad[16]; /* reserved for future use */ };
Valid entries for ut_type are:
BOOT_TIME
DEAD_PROCESS
EMPTY
INIT_PROCESS
LOGIN_PROCESS
NEW_TIME
OLD_TIME
RUN_LVL
USER_PROCESS
SHUTDOWN_TIME
For each value of ut_type, the other fields with meaningful values are as follows:
BOOT_TIME
DEAD_PROCESS
EMPTY
INIT_PROCESS
LOGIN_PROCESS
NEW_TIME
OLD_TIME
RUN_LVL
USER_PROCESS
SHUTDOWN_TIME
The ut_type value may also be OR-ed with the following masks:
UTMPX_AUTOFILL_MASK
UTMPX_DEAD_IF_CORRESPONDING_MASK
DEAD_PROCESS,
a call to
pututxline
()
will succeed only if a corresponding entry already exists with a
ut_type value of
USER_PROCESS
.Note that the above mask values do not show up in any file format, or in any subsequent reads of the data.
To support wtmpx and
lastlogx equivalent capability,
pututxline
()
automatically writes to the appropriate files. Additional APIs to read these
files is available in
endutxent_wtmp(3) and
getlastlogx(3).
Successful calls to pututxline
() will
automatically write equivalent entries into the
utmp, wtmp and
lastlog files. Programs that read these old files
should work as expected. However, directly writing to these files does not
make corresponding entries in utmpx and the
wtmpx and lastlogx
equivalent files, so such write-access is deprecated.
getutxent
() returns the next entry, or
NULL
on failure (end of database or problems reading
from the database). getutxid
() and
getutxline
() return the matching structure on
success, or NULL
if no match was found.
pututxline
() returns the structure that
was successfully written, or NULL
is returned and
the global variable errno is set to indicate the
error.
No errors are defined for the endutxent
(),
getutxent
(), getutxid
(),
getutxline
(), and
setutxent
() functions.
The pututxline
() function may fail if:
EPERM
]EINVAL
]UTMPX_DEAD_IF_CORRESPONDING_MASK
flags was
specified along with DEAD_PROCESS
, but no
corresponding entry with USER_PROCESS
was
found.Other errors may be returned if
UTMPX_AUTOFILL_MASK
was specified, and a field could
not be auto-filled.
The endutxent
(),
getutxent
(), getutxid
(),
getutxline
(), pututxline
(),
setutxent
() all conform to IEEE Std
1003.1-2001 (“POSIX.1”) (XSI extension), and previously
to X/Open Portability Guide Issue 4,
Version 2 (“XPG4.2”). The fields
ut_user, ut_id,
ut_line, ut_pid,
ut_type, and ut_tv conform to
IEEE Std 1003.1-2001 (“POSIX.1”) (XSI
extension), and previously to X/Open Portability Guide
Issue 4, Version 2 (“XPG4.2”).
June 29, 2006 | macOS 14.6 |