getutxent(2)                                               getutxent(2)

  endutxent()

  NAME

    endutxent(), getutxent(), getutxid(), getutxline(), pututxline(),
    setutxent() - user accounting database (utmpx) functions

  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 *utmpx)
    struct utmpx *setutxent (void)

  DESCRIPTION

    These functions provide access to the user accounting database, usually
    stored in the file /var/adm/utmpx. These functions are not reentrant.

    The getutxent(2) function reads the next entry. If the utmpx file isn't
    open, the function opens it. If the function reaches the end of the utmpx
    file, it fails.

    The getutxid(2) function searches forward in the database from the current
    point for a matching entry. The id is a utmpx structure; the match depends
    upon the value of the ut_type value in the structure.
    *     If the value is BOOT_TIME, OLD_TIME, or NEW_TIME, the search stops
          at the next entry with a matching value.
    *     If the value is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or
          DEAD_PROCESS, the search stops at the next entry with one of those
          types and whose ut_id member matches the ut_id member in id.

    The getutxid(2) function fails if it reaches the end of the database
    without a match.

    The getutxline(2) function searches forward in the database from the
    current point for an entry with a value of ut_line that matches the value
    in line, and that has a ut_type of LOGIN_PROCESS or USER_PROCESS. The
    function fails if it reaches the end of the database without finding a
    match.

    The pututxline(2) function writes out the information in the structure
    utmpx to the database. The process must have the appropriate privileges to
    do this. It searches the database for a matching entry (using
    getutxid(2)); if it finds a match, the existing information is replaced
    with the information in utmpx. If it doesn't find a match, the new
    information is added at the end of the file.

    The setutxent(2) function resets input to the beginning of the database.

    The endutxent(2) function closes the database.

    The functions getutxid(2) and getutxline(2) may cache the data. When using
    getutxline(2) to search for multiple occurrences, zero out the static data
    after each success, or getutxline(2) will repeatedly return a pointer to
    the same utmpx structure. (The implicit read done by pututxline(2) doesn't
    modify the static structure.)

    The utmpx structure is described in the file . It consists of at
    least these members:
    char               ut_user[]     user login name

    char               ut_id[]       initialization process identifier

    char               ut_line[]     device name

    pid_t              ut_pid        process ID

    short int          ut_type       type of entry -- see list

    struct timeval     ut_tv         time entry was made.

    The ut_type member is used for matches, as described above. It can have
    the following values:
    EMPTY             No valid information

    BOOT_TIME         Time of system boot (not stored)

    OLD_TIME          Time when system clock changed (not stored)

    NEW_TIME          Time after system clock changed (not stored)

    USER_PROCESS      Identifies a process

    INIT_PROCESS      Process was spawned by the init process

    LOGIN_PROCESS     Session leader of the logged-in user

    DEAD_PROCESS      Session leader has exited

    The values BOOT_TIME, OLD_TIME, NEW_TIME, and INIT_PROCESS do not show up
    in INTERIX systems.

  RETURN VALUE

    Upon completing successfully, the functions getutxent(2), getutxid(2), and
    getutxline(2) return a pointer to a utmpx structure which contains a copy
    of the requested entry. The structure is in a static area which may be
    overwritten by subsequent calls. On failure, they return a null pointer.

    Upon completing successfully, the function pututxline(2) returns a pointer
    to a utmpx structure containing the user information entered in the user
    database. On failure, it returns a null pointer.

    The endutxent(2) and setutxent(2) functions return no value.

  ERRORS

    The pututxline(2) function may fail for this reason:

    [EPERM]
        The process does not have privileges to write to /var/adm/utmpx.

  NOTES

    This set of APIs is new to INTERIX with release 2.1. Programs written to
    use these APIs will not run on INTERIX 2.0 systems.

  SEE ALSO

    who(1)

  USAGE NOTES

    None of these functions are thread safe.

    None of these functions are async-signal safe.