Content-type: text/html Man page of getutxent

getutxent

Section: C Library Functions (3)
Index Return to Main Contents
 

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 matching that 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() functions 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 performs 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.  

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


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:30 GMT, October 02, 2010