getutent(3)
Name
getutent, getutid, getutline, pututline, setutent, endutent, utmpname − access utmp file entries
Syntax
#include <utmp.h>
struct utmp *getutent(void);
struct utmp *getutid(
struct utmp *ID);
struct utmp *getutline(
struct utmp *line);
struct utmp *pututline(
struct utmp *utmp_ptr);
void setutent(void);
void endutent(void);
void utmpname(
char *file);
Arguments
ID The ID argument specifies one of the utmp structure entries.
line The line argument matches one of the utmp line entries when accounting for something other than a process.
utmp_ptr The utmp_ptr argument points to a utmp structure to be placed into the utmp file.
utmp_data The utmp_data argument is data for the utmp database.
Description
The getutent routine reads the next entry from a file similar to the utmp file. If the file is not already open, the getutent routine opens it. If the file does not exist, the getutent routine tries to create a file. The getutent routine fails and returns a null pointer if the end of the file is reached, the file creation fails, or the read or write file permissions are inappropriate.
The getutid and getutline routines read forward from the current point in the utmp file until they find an entry that matches the ID or the line argument, respectively.
The pututline routine 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 either the getutid or the getutline routines, the pututline routine calls the getutid routine to search forward for the proper place. However, it is expected behavior that the user of the pututline routine has searched for the proper entry by using either the getutid or the getutline routine. If so, the pututline routine does not search. If the pututline routine does not find a matching slot for the entry, it adds a new entry to the end of the file. Note that the pututline routine waits for a short time before it decides that the current process holding the lock is dead and proceeds to write to the file.
The setutent routine 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 routine closes the currently open file.
The utmpname routine changes the name of the file to be examined from /etc/utmp to any other filename. The name specified is usually /usr/adm/wtmp. (For example, for accounting purposes, you can use the utmpname routine to change the name.) If the specified file does not exist, no indication is given until the file is referenced. The utmpname routine does not open the file, but closes the old file (if it is currently open) and saves the new filename.
These functions use buffered standard I/O for input, but the pututline routine uses an unbuffered nonstandard write to avoid race conditions between processes trying to modify the utmp and wtmp files.
Notes
Before accessing the utmp file for the first time, the ut_fd field of the utmp_data structure must be set to a value of -1.
Return Values
Upon successful completion, the getutent, getutid, and getutline routines return pointers to the utmp structure. If a read or write fails due to the end of the file, or due to a permission conflict, the getutent, getutid, getutline, and pututline routines fail and return a null pointer. The getutid routine can also fail if the ID is invalid.
The utmmpname routine returns void. If it is given a file argument that exceeds the maximum path length, the routine returns and does not change the file name.
Diagnostics
[EINVAL] Either the utmp, ID, line, or utmp_data argument is invalid.
[ESRCH] The search failed.
Files
/usr/include/utmp.h
Accounting header file that defines the format for the login database file.
/etc/utmp,/var/adm/wtmp
The active login/logoff database files.