--- name: "endutxent" section: "3" platform: "macos" package: "Libc" version: "1752.120.2" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/endutxent" --- # endutxent(3) user accounting database functions ## NAME **endutxent**, **getutxent**, **getutxid**, **getutxline**, **pututxline**, **setutxent** – user accounting database functions ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** *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*); ## DESCRIPTION These functions provide access to the [utmpx(5)](/utmpx/5.md) 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)](/utmpx/5.md) 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 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 Time of a system boot. - DEAD\_PROCESS A session leader exited. - EMPTY No valid user accounting information. - INIT\_PROCESS A process spawned by [init(8)](/init/8.md). - LOGIN\_PROCESS The session leader of a logged-in user. - NEW\_TIME Time after system clock change. - OLD\_TIME Time before system clock change. - RUN\_LVL Run level. Provided for compatibility, not used. - USER\_PROCESS A user process. - SHUTDOWN\_TIME Time of system shutdown (extension to the standards). For each value of *ut\_type*, the other fields with meaningful values are as follows: - BOOT\_TIME *ut\_tv* - DEAD\_PROCESS *ut\_id*, *ut\_pid*, *ut\_tv* - EMPTY (no others) - INIT\_PROCESS *ut\_id*, *ut\_pid*, *ut\_tv* - LOGIN\_PROCESS *ut\_id*, *ut\_user* (implementation-defined name of the login process), *ut\_pid*, *ut\_tv* - NEW\_TIME *ut\_tv* - OLD\_TIME *ut\_tv* - RUN\_LVL (no used) - USER\_PROCESS *ut\_id*, *ut\_user* (login name of the user), *ut\_line*, *ut\_pid*, *ut\_host* (hostname of remote user) *ut\_tv* - SHUTDOWN\_TIME *ut\_tv* ### Other extensions to the standards The *ut\_type* value may also be OR-ed with the following masks: - UTMPX\_AUTOFILL\_MASK Depending on the main part of *ut\_type* value, other fields are automatically filled in (as specified in the meaningful fields table above). In particular, the *ut\_id* field will be set using the convention of the last four characters of the *ut\_line* field (itself filled in automatically from the tty name of the device connected to the standard input, output or error, whichever is available). Note that it is more efficient to fill in as many values as are already available beforehand, rather than have then automatically filled in. - UTMPX\_DEAD\_IF\_CORRESPONDING\_MASK When *ut\_type* value is 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)](/getlastlogx/3.md). ### Backward compatibility 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. ## RETURN VALUES **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. ## ERRORS No errors are defined for the **endutxent**(), **getutxent**(), **getutxid**(), **getutxline**(), and **setutxent**() functions. The **pututxline**() function may fail if: - \[EPERM\] The process does not have appropriate privileges. - \[EINVAL\] The 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. ## SEE ALSO endutxent\_wtmp(3), [getlastlogx(3)](/getlastlogx/3.md), [utmpx(5)](/utmpx/5.md) ## STANDARDS 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”).