Next: XPG Functions, Up: User Accounting Database
These functions and the corresponding data structures are declared in the header file utmp.h.
The
exit_statusdata structure is used to hold information about the exit status of processes marked asDEAD_PROCESSin the user accounting database.
short int e_termination- The exit status of the process.
short int e_exit- The exit status of the process.
The
utmpdata 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_PROCESSorACCOUNTING.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_TIMEthis is the time when the system clock changed, and for entries of typeNEW_TIMEthis 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.
EMPTYRUN_LVLBOOT_TIMEOLD_TIMENEW_TIMEINIT_PROCESSLOGIN_PROCESSUSER_PROCESSDEAD_PROCESSACCOUNTINGThe 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.
This function opens the user accounting database to begin scanning it. You can then call
getutent,getutidorgetutlineto read entries andpututlineto write entries.If the database is already open, it resets the input to the beginning of the database.
The
getutentfunction 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 togetutent. You must copy the contents of the structure if you wish to save the information or you can use thegetutent_rfunction which stores the data in a user-provided buffer.A null pointer is returned in case no further entry is available.
This function searches forward from the current point in the database for an entry that matches id. If the
ut_typemember of the id structure is one ofRUN_LVL,BOOT_TIME,OLD_TIMEorNEW_TIMEthe entries match if theut_typemembers are identical. If theut_typemember of the id structure isINIT_PROCESS,LOGIN_PROCESS,USER_PROCESSorDEAD_PROCESS, the entries match if theut_typemember of the entry read from the database is one of these four, and theut_idmembers match. However if theut_idmember of either the id structure or the entry read from the database is empty it checks if theut_linemembers match instead. If a matching entry is found,getutidreturns a pointer to the entry, which is statically allocated, and may be overwritten by a subsequent call togetutent,getutidorgetutline. 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
getutidfunction may cache the last read entry. Therefore, if you are usinggetutidto search for multiple occurrences, it is necessary to zero out the static data after each call. Otherwisegetutidcould just return a pointer to the same entry over and over again.
This function searches forward from the current point in the database until it finds an entry whose
ut_typevalue isLOGIN_PROCESSorUSER_PROCESS, and whoseut_linemember matches theut_linemember 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 togetutent,getutidorgetutline. 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
getutlinefunction may cache the last read entry. Therefore if you are usinggetutlineto search for multiple occurrences, it is necessary to zero out the static data after each call. Otherwisegetutlinecould just return a pointer to the same entry over and over again.
The
pututlinefunction 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 usesgetutidto search for the position to insert the entry, however this will not modify the static structure returned bygetutent,getutidandgetutline. If this search fails, the entry is appended to the database.The
pututlinefunction 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 followingerrnoerror 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.
The
getutent_ris equivalent to thegetutentfunction. 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
0and 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 ofgetutent_rthe function returns-1.This function is a GNU extension.
This function retrieves just like
getutidthe 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
0and 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.
This function retrieves just like
getutlinethe 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
0and 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.
The
utmpnamefunction changes the name of the database to be examined to file, and closes any previously opened database. By defaultgetutent,getutid,getutlineandpututlineread from and write to the user accounting database.The following macros are defined for use as the file argument:
The
utmpnamefunction returns a value of0if the new name was successfully stored, and a value of-1to indicate an error. Note thatutmpnamedoes 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:
The
updwtmpfunction appends the entry *utmp to the database specified by wtmp_file. For possible values for the wtmp_file argument see theutmpnamefunction.
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
XPG Functions, or take a look at the BSD compatible functions in
Logging In and Out.