NAME

User::Utmp - Perl access to utmp- and utmpx-style databases

SYNOPSIS

use User::Utmp qw(utmpname getut putut);
utmpname("file");
@utmp = getut();
putut(\%entry);

or, on systems supporting utmpx:

use User::Utmp qw(utmpname getutx putut);
utmpname("file");
@utmp = getutx();
putut(\%entry);

DESCRIPTION

The User::Utmp modules provides functions for reading utmp and utmpx files, and experimental support for writing utmp files. The following functions are provided:

getut()

Reads a utmp-like file and converts it to a Perl array of hashes. Each array element (a reference to a hash) represents one utmp record. The hash keys are the names of the elements of the utmp structure as described in utmp(4). The hash values are (mostly) the same as in C.

Note that even if ut_addr (if provided by the utmp implementation) is declared as long, it contains an Internet address (four bytes in network order), not a number. It is therefore converted to a string suitable as parameter to gethostbyname(). If the record doesn't describe a remote login ut_addr is the empty string.

getutx()

Reads a utmpx-like file and converts it to a Perl array of hashes. Each array element (a reference to a hash) represents one utmp record. The hash keys are the names of the elements of the utmpx structure as described in utmpx(4) or getutx(3). The hash values are (mostly) the same as in C.

Note that even if ut_addr (if provided by the utmpx implementation) is declared as long, it contains an Internet address (four bytes in network order), not a number. It is therefore converted to a string suitable as parameter to gethostbyname(). If the record doesn't describe a remote login ut_addr is the empty string.

putut()

Writes out the supplied utmp record into the utmp file. putut() takes a reference to a hash which has the same structure and contents as the elements of the array returned by getut(). Whether or not putut() creates the utmp file if it doesn't exist is implementation-dependent.

utmpname()

Allows the user to change the name of the file being examined from the default file (typically /etc/utmp or, for utmpx, /etc/utmpx) to any other file. In this case, the name provided to utmpname() will be used for the getut(), getutx(), and putut() functions.

User::Utmp also provides the following utmp constants as functions:

BOOT_TIME DEAD_PROCESS EMPTY INIT_PROCESS LOGIN_PROCESS NEW_TIME OLD_TIME RUN_LVL USER_PROCESS

EMPTY is also use on Linux (instead of the non-standard UT_UNKNOWN). Additionally, the function User::Utmp::HAS_UTMPX() returns 1 if User::Utmp was built with utmpx support.

RESTRICTIONS

Reading the whole file into an array might not be the most efficient approach for potentially large files like /etc/wtmp.

This module is based on the traditional, non-reentrant utmp functions; it is therefore not thread-safe.

AUTHOR

Michael Piotrowski <mxp@dynalabs.de>

SEE ALSO

utmp(4), getut(3), utmpx(4), getutx(3)