Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
GETUTXENT(3)           FreeBSD Library Functions Manual           GETUTXENT(3)

NAME
     endutxent, getutxent, getutxid, getutxline, getutxuser, pututxline,
     setutxdb, setutxent - 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
     These functions operate on the user accounting database which stores
     records of various system activities, such as user login and logouts, but
     also system startups and shutdowns and modifications to the system's
     clock.  The system stores these records in three databases, each having a
     different purpose:

     /var/run/utx.active
             Log of currently active user login sessions.  This file is
             similar to the traditional utmp file.  This file only contains
             process related entries, such as user login and logout records.

     /var/log/utx.lastlogin
             Log of last user login entries per user.  This file is similar to
             the traditional lastlog file.  This 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.  This file is
             similar to the traditional wtmp file.  This file 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 indicates the type of the log entry, which can have one
     of the following 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.

     Entries of type INIT_PROCESS and LOGIN_PROCESS are not processed by this
     implementation.

     Other fields inside the structure are:

     ut_tv    The time the event occurred.  This field is used for all types
              of entries, except EMPTY.

     ut_id    An identifier that is used to refer to the entry.  This
              identifier 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.  This field is 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.  This field is 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.  This
              field is 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.  This field is 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.  This field is only
              applicable to entries of type USER_PROCESS.

     This implementation guarantees all inapplicable fields are discarded.
     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.

     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.

     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.

     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 BOOT_TIME, 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
     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), wtmpcvt(1), getpid(2), gettimeofday(2), tty(4), ac(8),
     newsyslog(8), utxrm(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>

FreeBSD 11.0-PRERELEASE        February 19, 2011       FreeBSD 11.0-PRERELEASE

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getutxent&sektion=3&manpath=FreeBSD+9.3-RELEASE>

home | help