getut(S) 6 January 1993 getut(S) Name getut: endutent, getutent, getutid, getutline, pututline, setutent, utmp- name - 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 uttype matching the one in the argu- ment id if the type specified is BOOTTIME, NEWTIME, OLDTIME, or RUNLVL. If the type specified in the argument id is DEADPROCESS,INITPROCESS, LOGINPROCESS, or USERPROCESS then getutid returns a pointer to the first entry whose uttype and utid 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 LOGINPROCESS or USERPROCESS, which also has a utline string matching the utline string in the argu- ment 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 exam- ined, 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 putut- line 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 getut- line 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 See also ttyslot(S), utmp(F) Standards conformance endutent, getutent, getutid, getutline, pututline, setutent and utmpname conform with: AT&T SVID Issue 2.