GETUT(3,L) AIX Technical Reference GETUT(3,L)
-------------------------------------------------------------------------------
getut: getutent, getutid, getutline, pututline, setutent, endutent, utmpname
PURPOSE
Accesses utmp file entries.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <utmp.h>
struct utmp *getutent ( ) void pututline (utmp)
struct utmp *utmp;
struct utmp *getutid (id)
struct utmp *id; void setutent ( )
struct utmp *getutline (line) void endutent ( )
struct utmp *line;
void utmpname (file)
char *file;
DESCRIPTION
The getutent, getutid, and getutline subroutines each return a pointer to a
structure of the following type:
#define ut_name ut_user
struct utmp
{
char ut_user[8]; /* User login name */
char ut_id[6]; /* id from /etc/inittab */
char ut_line[12]; /* device name (console, ttyx) */
pid_t 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 */
Processed November 7, 1990 GETUT(3,L) 1
GETUT(3,L) AIX Technical Reference GETUT(3,L)
/* marked as DEAD_PROCESS. */
time_t ut_time; /* time entry was made */
char ut_host[16]; /* host name if remote login */
long ut_lsite; /* reserved */
char ut_datarep[4]; /* reserved */
};
The getutent subroutine reads the next entry from a utmp-like file. If the
file is not already open, this subroutine opens it. If the end of the file is
reached, getutent fails.
If you specify type 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 one of the types INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS or
DEAD_PROCESS in the id parameter, then 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.
The getutline subroutine searches forward from the current point in the utmp
file until it finds an entry of the type LOGIN_PROCESS or USER_PROCESS that
also has a ut_line string matching the line"->"ut_line parameter string. If
the end the of file is reached without a match, the getutline subroutine fails.
The pututline subroutine writes the supplied utmp structure into the utmp file.
If you have not searched for the proper place in the file using one of the
getut routines, then the pututline subroutine calls getutid to search forward
for the proper place. It is expected that normally the user of pututline
searched for the proper entry using one of the getut subroutines. 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.
You should do this before each search for a new entry if you want to examine
the entire file.
The endutent subroutine closes the currently open file.
The utmpname subroutine changes the name of the file to be examined from
/etc/utmp to any other file. The name specified is usually /usr/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 it is currently
open, and saves the new file name.
The most current entry is saved in a static structure. If you desire 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
Processed November 7, 1990 GETUT(3,L) 2
GETUT(3,L) AIX Technical Reference GETUT(3,L)
after each use if you want to use these subroutines to search for multiple
occurrences.
If pututline finds that it isn't already at the correct place in the file, then
the implicit read it performs does not overwrite the contents of the static
structure returned by the getutent, getuid, or getutline routine. This allows
you to get an entry with one of these subroutines, modify the structure, and
pass the pointer back to pututline for writing.
These subroutines use buffered standard I/O for input, but pututline uses an
unbuffered nonstandard write to avoid race conditions between processes trying
to modify the utmp and wtmp files.
RETURN VALUE
These subroutines fail and return a NULL pointer if a read or write fails due
to end-of-file or a permission conflict.
FILES
/etc/utmp
/usr/adm/wtmp
RELATED INFORMATION
In this book: "ttyslot" and "utmp, wtmp, .ilog."
Processed November 7, 1990 GETUT(3,L) 3