getut(S)

getut: endutent, getutent, getutid, getutline, pututline, setutent, utmpname -- access utmp file entry

Syntax

cc . . . -lc

#include <utmp.h>

void endutent ()

struct utmp *getutent ()

struct utmp *getutid (id)
struct utmp *id;

struct utmp *getutline (line)
struct utmp *line;

struct utmp *pututline (utmp)
struct utmp *utmp;

void setutent ()

void utmpname (file)
char *file;

Description

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

   struct  utmp {
           char   ut_user[8];         /* User login name */
           char   ut_id[4];           /* /etc/inittab id (usually line #) */
           char   ut_line[12];        /* device name (console, lnxx) */
           short  ut_pid;             /* process id */
           short  ut_type;            /* type of entry */
           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. */
           time_t ut_time;            /* time entry was made */
   };

The getutent routine reads in the next utmp structure entry from a utmp-like file. If the file is not already open, it opens it. If it cannot open a file or if it reaches the end of the file, it fails.

The getutid routine searches forward from the current point in the utmp file until it finds an entry with a ut_type matching the one in the argument id if the type specified is BOOT_TIME, NEW_TIME, OLD_TIME, or RUN_LVL. If the type specified in the argument id is DEAD_PROCESS,INIT_PROCESS, LOGIN_PROCESS, or USER_PROCESS then getutid returns a pointer to the first entry whose ut_type and ut_id matches those specified in id. If the end of file is reached without a match, it fails.

The getutline routine searches forward from the current point in the utmp file until it finds an entry of the type LOGIN_PROCESS or USER_PROCESS, which also has a ut_line string matching the ut_line string in the argument line. If the end of file is reached without a match, it fails.

The pututline routine writes out the supplied utmp structure specified by the argument utmp. into the utmp-like file. It uses getutid to search forward for the proper place to overwrite if it finds that it is not already at the proper place. It is expected that normally the user of pututline has searched for the proper entry using one of the other getut routines. If so, pututline does not search. If pututline does not find a matching slot for the new entry, it adds a new entry to the end of the file.

The setutent routine resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined.

The endutent routine closes the currently open file after processing.

The utmpname routine allows the user to change the name of the file examined, from /etc/utmp to any other file. It is most often expected that this other file is /etc/wtmp. If the file does not exist, this is not made apparent until the first attempt to reference the file. This is because utmpname does not open the new file. It just closes the old file if it is currently open and saves the new file name.

Return value

Upon successful completion, the getutent, getutid, getutline, and pututline routines return a pointer to a utmp structure. These routines return a NULL pointer upon failure. There are no errors or return values defined for the setutent, endutent, and utmpname routines.

Diagnostics

The getutent, getutid, getutline, and pututline routines will return the NULL pointer if the utmp-like file is of improper format, cannot be open, cannot be created, or if the user does not have the proper permissions to read or write to it. For the first three routines, a NULL pointer is also return if the appropriate entry cannot be found.

Notes

The most current entry is saved in a static structure. Multiple accesses require that it be copied before further accesses are made. Each call to either getutid or getutline routine examines the static structure before performing more I/O. If the contents of the static structure match what it is searching for, it looks no further. For this reason, to use getutline to search for multiple occurrences, it would be necessary to zero out the static after each success, or getutline would just return the same pointer over and over again.

There is one exception to the rule about removing the structure before further reads are done. The implicit read done by pututline (if it finds that it is not already at the correct place in the file) does not hurt the contents of the static structure returned by the getutent, getutid, or getutline routines, if the user has just modified those contents and passed the pointer back to pututline.

These routines use buffered standard I/O for input, but pututline uses an unbuffered non-standard write to avoid race conditions between processes trying to modify the utmp and wtmp files.

Files

/etc/utmp
/etc/wtmp

Standards conformance

endutent, getutent, getutid, getutline, pututline, setutent and utmpname are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.