[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

getutent, getutid, getutline, pututline, setutent, endutent, or utmpname Subroutine


Accesses utmp file entries.


Standard C Library (libc.a)


#include <utmp.h>

struct utmp *getutent ( )

struct utmp *getutid ( ID)
struct utmp *ID;

struct utmp *getutline ( Line)
struct utmp *Line;

void pututline ( Utmp)
struct utmp *Utmp;

void setutent ( )

void endutent ( )

void utmpname ( File)
char *File;


The getutent, getutid, and getutline subroutines return a pointer to a structure of the following type:

#define    ut_name   ut_user
struct utmp
    char ut_user[256];           /* User name */
    char ut_id[14];              /* /etc/inittab ID */
    char ut_line[64];            /* Device name (console, lnxx) */
    pid_t ut_pid;                /* Process ID */
    short ut_type;               /* Type of entry */
#if !defined(__64BIT__) && !defined(__ia64)
        int __time_t_space;      /* for 32vs64-bit time_t PPC */
        time_t ut_time;          /* time entry was made */
#if !defined(__64BIT__) && defined(__ia64)
        int __time_t_space;      /* for 32vs64-bit time_t IA64 */
        struct exit_status
            short e_termination; /* Process termination status */
            short e_exit;        /* Process exit status */
        ut_exit;                 /* The exit status of a process
                                 /* marked as DEAD_PROCESS. */
        char ut_host[256];       /* host name */
        int __dbl_word_pad;      /* for double word alignment */
        int __reservedA[2];
        int __reservedV[6];

The getutent subroutine reads the next entry from a utmp-like file. If the file is not open, this subroutine opens it. If the end of the file is reached, the getutent subroutine fails.

The pututline subroutine writes the supplied Utmp parameter structure into the utmp file. It is assumed that the user of the pututline subroutine has searched for the proper entry point using one of the getut subroutines. If not, the pututline subroutine calls getutid to search forward for the proper place. If so, pututline does not search. If the pututline subroutine does not find a matching slot for the entry, it adds a new entry to the end of the file.

The setutent subroutine resets the input stream to the beginning of the file. Issue a setuid call before each search for a new entry if you want to examine the entire file.

The endutent subroutine closes the file currently open.

The utmpname subroutine changes the name of a file to be examined from /etc/utmp to any other file. The name specified is usually /var/adm/wtmp. If the specified file does not exist, no indication is given. You are not aware of this fact until your first attempt to reference the file. The utmpname subroutine does not open the file. It closes the old file, if currently open, and saves the new file name.

The most current entry is saved in a static structure. To make multiple accesses, you must copy or use the structure between each access. The getutid and getutline subroutines examine the static structure first. If the contents of the static structure match what they are searching for, they do not read the utmp file. Therefore, you must fill the static structure with zeros after each use if you want to use these subroutines to search for multiple occurrences.

If the pututline subroutine finds that it is not already at the correct place in the file, the implicit read it performs does not overwrite the contents of the static structure returned by the getutent subroutine, the getuid subroutine, or the getutline subroutine. This allows you to get an entry with one of these subroutines, modify the structure, and pass the pointer back to the pututline subroutine for writing.

These subroutines use buffered standard I/O for input. However, the pututline subroutine uses an unbuffered nonstandard write to avoid race conditions between processes trying to modify the utmp and wtmp files.


ID If you specify a type of RUN_LVL, BOOT_TIME, OLD_TIME, or NEW_TIME in the ID parameter, the getutid subroutine searches forward from the current point in the utmp file until an entry with a ut_type matching ID->ut_type is found.

If you specify a type of INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS in the ID parameter, the getutid subroutine returns a pointer to the first entry whose type is one of these four and whose ut_id field matches Id->ut_id. If the end of the file is reached without a match, the getutid subroutine fails.
Line The getutline subroutine searches forward from the current point in the utmp file until it finds an entry of type LOGIN_PROCESS or USER_PROCESS that also has a ut_line string matching the Line->ut_line parameter string. If the end of file is reached without a match, the getutline subroutine fails.
Utmp Points to the utmp structure.
File Specifies the name of the file to be examined.

Return Values

These subroutines fail and return a null pointer if a read or write fails due to a permission conflict or because the end of the file is reached.


/etc/utmp Path to the utmp file, which contains a record of users logged into the system.
/var/adm/wtmp Path to the wtmp file, which contains accounting information about users logged in.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The ttyslot subroutine.

The failedlogin, utmp, or wtmp file.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]