OSF

NAME

getutent, getutid, getutline, pututline, setutent, endutent, utmpname − Accesses utmp file entries

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <utmp.h> struct utmp ∗getutent ( void ); struct utmp ∗getutid (
struct utmp ∗ID ); struct utmp ∗getutline (
struct utmp ∗line ); void pututline (
struct utmp ∗utmp_ptr ); void setutent ( void ); void endutent ( void ); void utmpname (
char ∗file );

PARAMETERS

IDSpecifies one of RUN_LVL, BOOT_TIME, OLD_TIME, NEW_TIME, INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS.  If ID is one of RUN_LVL, BOOT_TIME, OLD_TIME, or NEW_TIME, the getutid() function searches forward from the current point in the utmp file until an entry with a ut_type matching ID->ut_type is found.  If ID is one of INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS, the getutid() function 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() function fails. 

lineMatches a utmp entry of the type LOGIN_PROCESS or USER_PROCESS such that the ut_line matches line->ut_line.  The getutline() function searches from the current point in the utmp file until it finds a matching line.  If the end the of file is reached without a match, the getutline() function fails. 

utmp_ptrPoints to a utmp structure. 

fileSpecifies the name of the file to be examined. 

DESCRIPTION

The getutent(), getutid(), and getutline() functions return a pointer to a utmp structure. 

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

The pututline() function writes the supplied utmp_ptr parameter structure into the utmp file. If you have not searched for the proper place in the file using one of the getut- routines, the pututline() function calls getutid() to search forward for the proper place. It is expected that the user of pututline() searched for the proper entry using one of the getut- functions. If so, pututline() does not search. If the pututline() function does not find a matching slot for the entry, it adds a new entry to the end of the file. 

The setutent() function 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() function closes the currently open file. 

The utmpname() function changes the name of the file to be examined from /var/adm/utmp to any other filename. The name specified is usually /var/adm/wtmp. If the specified file does not exist, no indication is given until the file is referenced. The utmpname() function does not open the file, but closes the old file (if it is currently open) and saves the new filename. 

The most current entry is saved in a static structure, making the utmpname() function non-reentrant.  To make multiple accesses, you must copy or use the structure between each access. The getutid() and getutline() functions 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() function 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(), getuid(), or getutline() functions. This allows you to get an entry with one of these subroutines, modify the structure, and pass the pointer back to the pututline() function for writing. 

These functions use buffered standard I/O for input, but the pututline() function uses an unbuffered nonstandard write to avoid race conditions between processes trying to modify the utmp and wtmp files. 

RETURN VALUES

These functions fail and return a null pointer if a read or write fails due to the end of the file, or due to a permission conflict. 

FILES

/etc/utmp
/usr/adm/wtmp

RELATED INFORMATION

Functions: ttyslot(3)