 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
getutent(3)
NAME
getutent, getutent_r, getutid, getutid_r, getutline, getutline_r,
pututline, pututline_r, setutent, setutent_r, endutent, endutent_r,
utmpname - Access utmp file entries
SYNOPSIS
#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 );
LIBRARY
Standard C Library (libc)
PARAMETERS
id 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.
line
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.
utmp_ptr
Points to a utmp structure to be placed into the utmp file.
file
Specifies the name of the file to be examined.
utmp
Points at the returned utmp structure.
utmp_data
Is the data for the utmp database.
DESCRIPTION
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.
NOTES
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.
RETURN VALUES
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.
ERRORS
The getutent_r(), getutid_r(), and getutline_r() functions set errno to the
corresponding value if any of the following conditions occurs:
[EINVAL]
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:
[ESRCH]
The search failed.
The pututline() and pututline_r() functions may fail and set errno to the
corresponding value if the following condition occurs:
[EPERM]
The process does not have the appropriate privileges.
FILES
/usr/include/utmp.h
Accounting header file that defines the format for the login database
file.
/var/adm/utmp, /var/adm/wtmp
The active login/logoff database files.
SEE ALSO
Commands: wtmpconvert(8)
Functions: flock(2), open(2)
Files: utmp(4), wtmp(4)
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|