Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

getutxent(3) [osf1 man page]

getutxent(3)						     Library Functions Manual						      getutxent(3)

NAME
endutxent, getutxent, getutxid, getutxline, pututxline, setutxent - Access user accounting database functions LIBRARY
Standard C Library (libc.so, libc.a) SYNOPSIS
#include <utmpx.h> void endutxent(void); struct utmpx *getutxent(void); struct utmpx *getutxid( const struct utmpx *id); struct utmpx *getutxline( const struct utmpx *line); struct utmpx *pututxline( const struct utmpx *utmpx); void setutxent(void); STANDARDS
Interfaces documented on this reference page conform to industry standards as follows: endutxent(), getutxent(), getutxid(), getutxline(), pututxline(), setutxent(): XPG4-UNIX Refer to the standards(5) reference page for more information about industry standards and associated tags. PARAMETERS
Specifies one of the BOOT_TIME, OLD_TIME, NEW_TIME, INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS entries. Matches a utmpx entry of the type LOGIN_PROCESS or USER_PROCESS such that the ut_line member matches line->ut_line. Points to a utmpx structure to be placed into the user accounting database. DESCRIPTION
These functions provide access to the user accounting database. The getutxent() function reads the next entry from the user accounting database. If the database is not already open, getutxent() opens it. If the end of the database is reached, getutxent fails. The getutxid() function searches forward from the current point in the database. If the ut_type value of the utmpx structure pointed to by the id parameter is BOOT_TIME, OLD_TIME, or NEW_TIME, the getutxid() function stops when an entry with a matching ut_type value is found. If the ut_type value is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS, the getutxid() 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 database is reached without a match, the getutxid() function fails. The getutxline() function searches forward from the current point in the database until it finds an entry of the type LOGIN_PROCESS or USER_PROCESS which also has a ut_line value that matches the value in the utmpx structure pointed to by the line parameter. If the end of the database is reached without a match, the getutxline() function fails. If the process has appropriate privileges, the pututxline() function writes out the structure into the user accounting database. The pututxline() function calls getutxid() to search for a record that satisfies the request. If this search succeeds, the entry is replaced. Otherwise, a new entry is made at the end of the user accounting database. The setutxent() function resets the input stream to the beginning of the database. This should be done before each search for a new entry if you want to examine the entire database. The endutxent() function closes the user accounting database. NOTES
The most current entry is saved in a thread-specific structure, which is overwritten by a subsequent call to getutxid() or getutxline() by the same thread. To make multiple accesses, you must copy or use the structure between each access. The getutxid() and getutxline() func- tions examine the thread-specific structure first. If the contents of this structure match what they are searching for, they do not read the database. Therefore, you must fill the thread-specific structure with zeros after each use if you want to use these subroutines to search for multiple occurrences. If the pututxline() function finds that it is not already at the correct place in the user accounting database, the implicit read it per- forms does not overwrite the contents of the thread-specific structure returned by the getutxent(), getutxid(), or getutxline() functions. This allows you to get an entry with one of these subroutines, modify the structure, and pass the pointer back to the pututxline() function for writing. These functions use buffered standard I/O for input, but the pututxline() function uses an unbuffered write to avoid race conditions between processes trying to modify the utmpx and wtmpx files. RETURN VALUES
Upon successful completion, the getutxent(), getutxid(), and getutxline() functions return pointers to a utmpx structure containing a copy of the requested entry in the user accounting database. Otherwise, a null pointer is returned. Upon successful completion, the pututxline() function returns a pointer to a utmpx structure containing a copy of the entry added to the user accounting database. Otherwise, a null pointer is returned. ERRORS
The pututxline() function may fail and set errno to the corresponding value if the following condition occurs: The process does not have the appropriate privileges. FILES
Accounting header file that defines the format for the login database file. The active login/logoff database files. RELATED INFORMATION
Standards: standards(5) delim off getutxent(3)
Man Page