getutent, getutent_r, getutid, getutid_r, getutline,
getutline_r, pututline, pututline_r, setutent, setutent_r,
endutent, endutent_r, utmpname - Access utmp file entries
#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 );
The following functions are supported in order to maintain
backward compatibility with previous versions of the operating
system.
int getutent_r(
struct utmp **utmp,
struct utmp_data *utmp_data ); int getutid_r(
struct utmp *id,
struct utmp **utmp,
struct utmp_data *utmp_data ); int getutline_r(
struct utmp *line,
struct utmp **utmp,
struct utmp_data *utmp_data ); int pututline_r(
struct utmp *utmp_ptr,
struct utmp_data *utmp_data ); void setutent_r(
struct utmp_data *utmp_data ); void endutent_r(
struct utmp_data *utmp_data );
Standard C Library (libc)
Specifies one of the RUN_LVL, BOOT_TIME, OLD_TIME,
NEW_TIME, INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or
DEAD_PROCESS entries.
If id is one of the RUN_LVL, BOOT_TIME, OLD_TIME,
or NEW_TIME entries, 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 the INIT_PROCESS, LOGIN_PROCESS,
USER_PROCESS, or DEAD_PROCESS entries, 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. Matches 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. Points to a utmp structure to be placed
into the utmp file. Specifies the name of the file
to be examined. Points at the returned utmp structure.
Is the data for the utmp database.
The getutent(), getutid(), and getutline() functions
return a pointer to a utmp structure.
The getutent() function reads the next entry from a file
similar to the utmp file. If the file is not already open,
the getutent() function opens it. If the file does not
exist, getutent() tries to create a file. The getutent()
function fails and returns a null pointer if one or more
of the following occur: The end of the file is reached.
The file creation fails. The read or write file permissions
are inappropriate.
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. Note that the pututline()
function 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() 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(), getutid(), 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 and uses the flock system
call.
The getutent_r(), getutid_r(), getutline_r(), pututline_r(),
setutline_r(), and endutline_r() functions are
the reentrant versions of the getutent(), getutid(),
getutline(), pututline(), setutline(), and endutline()
functions. They are supported in order to maintain backward
compatibility with previous versions of the operating
system.
Upon successful completion, the getutent_r(), getutid_r(),
and getutline_r() functions provide a pointer to the utmp
structure in utmp. Otherwise, they return a value of -1.
The utmp.h header file defines the utmp_data structure.
The utmpname() function does not close any file streams
when used for reentrant applications.
The utmpname() function is a function that returns void.
If it is given a file parameter that exceeds the maximum
path length, the function simply returns and does not
change the filename.
Note that 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.
When compiling, calls to the getutent(), getutid(), getutline(),
pututline(), getutent_r(), getutid_r(), getutline_r(),
pututline_r(), endutent_r(), and setutent_r()
functions are internally renamed by prepending _E to the
function name. When debugging a module that includes these
functions, use _Egetutent to refer to the getutent() call.
Upon successful completion, the getutent(), getutid(), and
getutline() functions 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() functions fail and
return a null pointer.
The getutent_r(), getutxent_r(), and pututline_r() functions
return 0 (zero) on success.
The getutid() function may also fail if the ID is invalid,
as does the getutid_r() function.
The getutent_r(), getutid_r(), and getutline_r() functions
set errno to the corresponding value if any of the following
conditions occurs: Either the utmp, ID, line, or
utmp_data parameter is invalid.
The getutid_r() and getutline_r() functions set errno to
the corresponding value if the following condition occurs:
The search failed.
The pututline() and pututline_r() functions may fail and
set errno to the corresponding value if the following condition
occurs: The process does not have the appropriate
privileges.
Accounting header file that defines the format for the
login database file. The active login/logoff database
files.
Commands: wtmpconvert(8)
Functions: flock(2), open(2)
Files: utmp(4), wtmp(4)
getutent(3)
[ Back ] |
