GNU Info
(libc.info)Manipulating the Database
Manipulating the User Accounting Database
-----------------------------------------
These functions and the corresponding data structures are declared in
the header file `utmp.h'.
- Data Type: struct exit_status
The `exit_status' data structure is used to hold information about
the exit status of processes marked as `DEAD_PROCESS' in the user
accounting database.
`short int e_termination'
The exit status of the process.
`short int e_exit'
The exit status of the process.
- Data Type: struct utmp
The `utmp' data structure is used to hold information about entries
in the user accounting database. On the GNU system it has the
following members:
`short int ut_type'
Specifies the type of login; one of `EMPTY', `RUN_LVL',
`BOOT_TIME', `OLD_TIME', `NEW_TIME', `INIT_PROCESS',
`LOGIN_PROCESS', `USER_PROCESS', `DEAD_PROCESS' or
`ACCOUNTING'.
`pid_t ut_pid'
The process ID number of the login process.
`char ut_line[]'
The device name of the tty (without `/dev/').
`char ut_id[]'
The inittab ID of the process.
`char ut_user[]'
The user's login name.
`char ut_host[]'
The name of the host from which the user logged in.
`struct exit_status ut_exit'
The exit status of a process marked as `DEAD_PROCESS'.
`long ut_session'
The Session ID, used for windowing.
`struct timeval ut_tv'
Time the entry was made. For entries of type `OLD_TIME' this
is the time when the system clock changed, and for entries of
type `NEW_TIME' this is the time the system clock was set to.
`int32_t ut_addr_v6[4]'
The Internet address of a remote host.
The `ut_type', `ut_pid', `ut_id', `ut_tv', and `ut_host' fields are
not available on all systems. Portable applications therefore should
be prepared for these situations. To help doing this the `utmp.h'
header provides macros `_HAVE_UT_TYPE', `_HAVE_UT_PID', `_HAVE_UT_ID',
`_HAVE_UT_TV', and `_HAVE_UT_HOST' if the respective field is
available. The programmer can handle the situations by using `#ifdef'
in the program code.
The following macros are defined for use as values for the `ut_type'
member of the `utmp' structure. The values are integer constants.
`EMPTY'
This macro is used to indicate that the entry contains no valid
user accounting information.
`RUN_LVL'
This macro is used to identify the systems runlevel.
`BOOT_TIME'
This macro is used to identify the time of system boot.
`OLD_TIME'
This macro is used to identify the time when the system clock
changed.
`NEW_TIME'
This macro is used to identify the time after the system changed.
`INIT_PROCESS'
This macro is used to identify a process spawned by the init
process.
`LOGIN_PROCESS'
This macro is used to identify the session leader of a logged in
user.
`USER_PROCESS'
This macro is used to identify a user process.
`DEAD_PROCESS'
This macro is used to identify a terminated process.
`ACCOUNTING'
???
The size of the `ut_line', `ut_id', `ut_user' and `ut_host' arrays
can be found using the `sizeof' operator.
Many older systems have, instead of an `ut_tv' member, an `ut_time'
member, usually of type `time_t', for representing the time associated
with the entry. Therefore, for backwards compatibility only, `utmp.h'
defines `ut_time' as an alias for `ut_tv.tv_sec'.
- Function: void setutent (void)
This function opens the user accounting database to begin scanning
it. You can then call `getutent', `getutid' or `getutline' to
read entries and `pututline' to write entries.
If the database is already open, it resets the input to the
beginning of the database.
- Function: struct utmp * getutent (void)
The `getutent' function reads the next entry from the user
accounting database. It returns a pointer to the entry, which is
statically allocated and may be overwritten by subsequent calls to
`getutent'. You must copy the contents of the structure if you
wish to save the information or you can use the `getutent_r'
function which stores the data in a user-provided buffer.
A null pointer is returned in case no further entry is available.
- Function: void endutent (void)
This function closes the user accounting database.
- Function: struct utmp * getutid (const struct utmp *ID)
This function searches forward from the current point in the
database for an entry that matches ID. If the `ut_type' member of
the ID structure is one of `RUN_LVL', `BOOT_TIME', `OLD_TIME' or
`NEW_TIME' the entries match if the `ut_type' members are
identical. If the `ut_type' member of the ID structure is
`INIT_PROCESS', `LOGIN_PROCESS', `USER_PROCESS' or `DEAD_PROCESS',
the entries match if the `ut_type' member of the entry read from
the database is one of these four, and the `ut_id' members match.
However if the `ut_id' member of either the ID structure or the
entry read from the database is empty it checks if the `ut_line'
members match instead. If a matching entry is found, `getutid'
returns a pointer to the entry, which is statically allocated, and
may be overwritten by a subsequent call to `getutent', `getutid'
or `getutline'. You must copy the contents of the structure if
you wish to save the information.
A null pointer is returned in case the end of the database is
reached without a match.
The `getutid' function may cache the last read entry. Therefore,
if you are using `getutid' to search for multiple occurrences, it
is necessary to zero out the static data after each call.
Otherwise `getutid' could just return a pointer to the same entry
over and over again.
- Function: struct utmp * getutline (const struct utmp *LINE)
This function searches forward from the current point in the
database until it finds an entry whose `ut_type' value is
`LOGIN_PROCESS' or `USER_PROCESS', and whose `ut_line' member
matches the `ut_line' member of the LINE structure. If it finds
such an entry, it returns a pointer to the entry which is
statically allocated, and may be overwritten by a subsequent call
to `getutent', `getutid' or `getutline'. You must copy the
contents of the structure if you wish to save the information.
A null pointer is returned in case the end of the database is
reached without a match.
The `getutline' function may cache the last read entry. Therefore
if you are using `getutline' to search for multiple occurrences, it
is necessary to zero out the static data after each call.
Otherwise `getutline' could just return a pointer to the same
entry over and over again.
- Function: struct utmp * pututline (const struct utmp *UTMP)
The `pututline' function inserts the entry `*UTMP' at the
appropriate place in the user accounting database. If it finds
that it is not already at the correct place in the database, it
uses `getutid' to search for the position to insert the entry,
however this will not modify the static structure returned by
`getutent', `getutid' and `getutline'. If this search fails, the
entry is appended to the database.
The `pututline' function returns a pointer to a copy of the entry
inserted in the user accounting database, or a null pointer if the
entry could not be added. The following `errno' error conditions
are defined for this function:
`EPERM'
The process does not have the appropriate privileges; you
cannot modify the user accounting database.
All the `get*' functions mentioned before store the information they
return in a static buffer. This can be a problem in multi-threaded
programs since the data returned for the request is overwritten by the
return value data in another thread. Therefore the GNU C Library
provides as extensions three more functions which return the data in a
user-provided buffer.
- Function: int getutent_r (struct utmp *BUFFER, struct utmp **RESULT)
The `getutent_r' is equivalent to the `getutent' function. It
returns the next entry from the database. But instead of storing
the information in a static buffer it stores it in the buffer
pointed to by the parameter BUFFER.
If the call was successful, the function returns `0' and the
pointer variable pointed to by the parameter RESULT contains a
pointer to the buffer which contains the result (this is most
probably the same value as BUFFER). If something went wrong
during the execution of `getutent_r' the function returns `-1'.
This function is a GNU extension.
- Function: int getutid_r (const struct utmp *ID, struct utmp *BUFFER,
struct utmp **RESULT)
This function retrieves just like `getutid' the next entry matching
the information stored in ID. But the result is stored in the
buffer pointed to by the parameter BUFFER.
If successful the function returns `0' and the pointer variable
pointed to by the parameter RESULT contains a pointer to the
buffer with the result (probably the same as RESULT. If not
successful the function return `-1'.
This function is a GNU extension.
- Function: int getutline_r (const struct utmp *LINE, struct utmp
*BUFFER, struct utmp **RESULT)
This function retrieves just like `getutline' the next entry
matching the information stored in LINE. But the result is stored
in the buffer pointed to by the parameter BUFFER.
If successful the function returns `0' and the pointer variable
pointed to by the parameter RESULT contains a pointer to the
buffer with the result (probably the same as RESULT. If not
successful the function return `-1'.
This function is a GNU extension.
In addition to the user accounting database, most systems keep a
number of similar databases. For example most systems keep a log file
with all previous logins (usually in `/etc/wtmp' or `/var/log/wtmp').
For specifying which database to examine, the following function
should be used.
- Function: int utmpname (const char *FILE)
The `utmpname' function changes the name of the database to be
examined to FILE, and closes any previously opened database. By
default `getutent', `getutid', `getutline' and `pututline' read
from and write to the user accounting database.
The following macros are defined for use as the FILE argument:
- Macro: char * _PATH_UTMP
This macro is used to specify the user accounting database.
- Macro: char * _PATH_WTMP
This macro is used to specify the user accounting log file.
The `utmpname' function returns a value of `0' if the new name was
successfully stored, and a value of `-1' to indicate an error.
Note that `utmpname' does not try to open the database, and that
therefore the return value does not say anything about whether the
database can be successfully opened.
Specially for maintaining log-like databases the GNU C Library
provides the following function:
- Function: void updwtmp (const char *WTMP_FILE, const struct utmp
*UTMP)
The `updwtmp' function appends the entry *UTMP to the database
specified by WTMP_FILE. For possible values for the WTMP_FILE
argument see the `utmpname' function.
*Portability Note:* Although many operating systems provide a subset
of these functions, they are not standardized. There are often subtle
differences in the return types, and there are considerable differences
between the various definitions of `struct utmp'. When programming for
the GNU system, it is probably best to stick with the functions
described in this section. If however, you want your program to be
portable, consider using the XPG functions described in Note: XPG
Functions, or take a look at the BSD compatible functions in Note:
Logging In and Out.
automatically generated by info2www version 1.2.2.9