GETUTXENT(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

🦋 GETUTXENT(3) — like, the whole `getutxent` family, bestie 💅

okay so this is the GETUTXENT(3) page from the Library Functions Manual, and it lives in the Standard C Library (libc, -lc). buckle up, we're talking user accounting databases and honestly? it's giving main character energy 🎀

✨ NAME ✨

endutxent, getutxent, getutxid, getutxline, getutxuser, pututxline, setutxdb, setutxent — the user accounting database functions 🫶

📚 LIBRARY 📚

Standard C Library (libc, -lc)

🧾 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 *
getutxuser(const char *user);

struct utmpx *
pututxline(const struct utmpx *utmpx);

int
setutxdb(int type, const char *file);

void
setutxent(void);

💖 DESCRIPTION 💖

so these functions operate on the user accounting database, which literally stores records of all kinds of system activities — user logins and logouts, sure, but also system startups and shutdowns and modifications to the system's clock ⏰✨

the system stores these records in three databases, each with its own whole personality:

/var/run/utx.active — log of currently active user login sessions. this file is similar to the traditional utmp file. it only contains process related entries, such as user login and logout records 👑
/var/log/utx.lastlogin — log of last user login entries per user. similar to the traditional lastlog file. only contains user login records for users who have at least logged in once 🥺
/var/log/utx.log — log of all entries, sorted by date of addition. similar to the traditional wtmp file. this one may contain any type of record described below 🔥

each entry in these databases is defined by the structure utmpx, found in the include file <utmpx.h>:

struct utmpx {
        short           ut_type;    /* Type of entry. */
        struct timeval  ut_tv;      /* Time entry was made. */
        char            ut_id[];    /* Record identifier. */
        pid_t           ut_pid;     /* Process ID. */
        char            ut_user[];  /* User login name. */
        char            ut_line[];  /* Device name. */
        char            ut_host[];  /* Remote hostname. */
};

🏷️ the `ut_type` field

the ut_type field indicates the type of the log entry, and it can have one of these values:

EMPTY — no valid user accounting information.
BOOT_TIME — identifies time of system boot.
SHUTDOWN_TIME — identifies time of system shutdown.
OLD_TIME — identifies time when system clock changed.
NEW_TIME — identifies time after system clock changed.
USER_PROCESS — identifies a process.
INIT_PROCESS — identifies a process spawned by the init process.
LOGIN_PROCESS — identifies the session leader of a logged-in user.
DEAD_PROCESS — identifies a session leader who has exited.

heads up bestie: entries of type INIT_PROCESS and LOGIN_PROCESS are not processed by this implementation 💀

🧚 the other fields, one by one

ut_tv — the time the event occurred. this field is used for all types of entries, except EMPTY.
ut_id — an identifier used to refer to the entry. it can be used to remove or replace a login entry by writing a new entry to the database containing the same value for ut_id. only applicable to entries of type USER_PROCESS, INIT_PROCESS, LOGIN_PROCESS and DEAD_PROCESS.
ut_pid — the process identifier of the session leader of the login session. only applicable to entries of type USER_PROCESS, INIT_PROCESS, LOGIN_PROCESS and DEAD_PROCESS.
ut_user — the user login name corresponding with the login session. only applicable to entries of type USER_PROCESS and INIT_PROCESS. for INIT_PROCESS entries this entry typically contains the name of the login process.
ut_line — the name of the TTY character device, without the leading /dev/ prefix, corresponding with the device used to facilitate the user login session. if no TTY character device is used, this field is left blank. only applicable to entries of type USER_PROCESS and LOGIN_PROCESS.
ut_host — the network hostname of the remote system, connecting to perform a user login. if the user login session is not performed across a network, this field is left blank. only applicable to entries of type USER_PROCESS.

this implementation guarantees all inapplicable fields are discarded ✨ and the ut_user, ut_line and ut_host fields of the structure returned by the library functions are also guaranteed to be null-terminated in this implementation. no cap 🙌

🔍 the reading functions

the getutxent() function can be used to read the next entry from the user accounting database.

the getutxid() function searches for the next entry in the database of which the behaviour is based on the ut_type field of id. if ut_type has a value of BOOT_TIME, SHUTDOWN_TIME, OLD_TIME or NEW_TIME, it will return the next entry whose ut_type has an equal value. if ut_type has a value of USER_PROCESS, INIT_PROCESS, LOGIN_PROCESS or DEAD_PROCESS, it will return the next entry whose ut_type has one of the previously mentioned values and whose ut_id is equal.

the getutxline() function searches for the next entry in the database whose ut_type has a value of USER_PROCESS or LOGIN_PROCESS and whose ut_line is equal to the same field in line.

the getutxuser() function searches for the next entry in the database whose ut_type has a value of USER_PROCESS and whose ut_user is equal to user.

🎀 opening and closing stuff

the previously mentioned functions will automatically try to open the user accounting database if not already done so. the setutxdb() and setutxent() functions allow the database to be opened manually, causing the offset within the user accounting database to be rewound ⏪ the endutxent() function closes the database.

the setutxent() database always opens the active sessions database. the setutxdb() function opens the database identified by type, whose value is either UTXDB_ACTIVE, UTXDB_LASTLOGIN or UTXDB_LOG. it will open a custom file with filename file instead of the system-default if file is not null.

care must be taken that when using a custom filename, type still has to match with the actual format, since each database may use its own file format ⚠️ like, do not mix and match, i'm begging

✍️ the writing function

the pututxline() function writes record utmpx to the system-default user accounting databases. the value of ut_type determines which databases are modified.

entries of type SHUTDOWN_TIME, OLD_TIME and NEW_TIME will only be written to /var/log/utx.log.
entries of type USER_PROCESS will also be written to /var/run/utx.active and /var/log/utx.lastlogin.
entries of type DEAD_PROCESS will only be written to /var/log/utx.log and /var/run/utx.active if a corresponding USER_PROCESS, INIT_PROCESS or LOGIN_PROCESS entry whose ut_id is equal has been found in the latter.

in addition, entries of type BOOT_TIME and SHUTDOWN_TIME will cause all existing entries in /var/run/utx.active to be discarded 🗑️💀

all entries whose type has not been mentioned previously are discarded by this implementation of pututxline(). this implementation also ignores the value of ut_tv.

🫶 RETURN VALUES 🫶

the getutxent(), getutxid(), getutxline(), and getutxuser() functions return a pointer to an utmpx structure that matches the mentioned constraints on success or NULL when reaching the end-of-file or when an error occurs.

the pututxline() function returns a pointer to an utmpx structure containing a copy of the structure written to disk upon success. it returns NULL when the provided utmpx is invalid, or ut_type has a value of DEAD_PROCESS and an entry with an identifier with a value equal to the field ut_id was not found; the global variable errno is set to indicate the error.

the setutxdb() function returns 0 if the user accounting database was opened successfully. otherwise, -1 is returned and the global variable errno is set to indicate the error.

💀 ERRORS 💀

in addition to the error conditions described in open(2), fdopen(3), fopen(3), fseek(3), the pututxline() function can generate the following errors:

[ESRCH] — the value of ut_type is DEAD_PROCESS, and the process entry could not be found.
[EINVAL] — the value of ut_type is not supported by this implementation.

in addition to the error conditions described in fopen(3), the setutxdb() function can generate the following errors:

[EINVAL] — the type argument contains a value not supported by this implementation.
[EFTYPE] — the file format is invalid.

🌈 SEE ALSO 🌈

last(1), write(1), getpid(2), gettimeofday(2), tty(4), ac(8), newsyslog(8), utx(8)

👑 STANDARDS 👑

the endutxent(), getutxent(), getutxid(), getutxline() and setutxent() functions are expected to conform to IEEE Std 1003.1-2008 (“POSIX.1”).

the pututxline() function deviates from the standard by writing its records to multiple database files, depending on its ut_type. this prevents the need for special utility functions to update the other databases, such as the updlastlogx() and updwtmpx() functions which are available in other implementations. it also tries to replace DEAD_PROCESS entries in the active sessions database when storing USER_PROCESS entries and no entry with the same value for ut_id has been found. the standard always requires a new entry to be allocated, which could cause an unbounded growth of the database 😭

the getutxuser() and setutxdb() functions, the ut_host field of the utmpx structure and SHUTDOWN_TIME are extensions ✨

⭐ HISTORY ⭐

these functions appeared in FreeBSD 9.0. they replaced the <utmp.h> interface.

🎀 AUTHORS 🎀

Ed Schouten <ed@FreeBSD.org>

and that's the whole page, bestie, you ate that 🍓 fr fr — this one's from Debian, dated October 27, 2011, and honestly it's iconic. go log some sessions responsibly 💜🦋

📦 where this page comes from

freebsd 14.5: base 14.5
freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms