Utmp

NAME

SYNOPSIS

  use User::Utmp qw(:constants :utmpx);
  @utmp = getutx();

or, using utmp:

  use User::Utmp qw(:constants :utmp);
  @utmp = getut();

DESCRIPTION

The exact location of these files in the file system varies between operating systems, but they are typically stored in directories like /var/adm, /var/run, or /var/log. The Single UNIX Specification specifies an API for reading from and writing to these files.

The utmpx file format and functions were derived from the older utmp file format and functions. For compatibility reasons, many systems still support the utmp functions and maintain utmp database files. It is recommended, however, to use the utmpx functions instead of the obsolete utmp functions.

The User::Utmp module provides functions for reading and writing utmpx and utmp files by providing a Perl interface to the system functions.

Utmpx and utmp records are represented in Perl by hash references. The hash keys are the names of the elements of the utmpx structure. For details consult utmpx(4) (utmpx(5) on some systems). The hash values are (mostly) the same as in C.

As an example, here is a typical record as it may be returned by the getutxent(), getutxid(), getutxline() or the corresponding utmp functions:

  {ut_tv   => {tv_sec => 1141256698, tv_usec => 0},
   ut_line => "ttyp0",
   ut_time => 1141256698,
   ut_id   => "p0",
   ut_host => ":0.0",
   ut_exit => {e_termination => 0, e_exit => 2},
   ut_pid  => 4577,
   ut_user => "mxp",
   ut_type => USER_PROCESS,}

The array returned by the getutx() and getut() functions is composed of hash references like this.  

Utmpx functions

getutx()

Reads a utmpx-like file and converts it to a Perl array of hashes. See above for a description of the hashes.

Note that "ut_addr" (if provided by the utmpx implementation) 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.

For compatibility with utmp, User::Utmp provides a "ut_time" field which contains the same value as the "ut_tv.tv_sec" field.

The following functions are equivalent to the C functions of the same names; refer to your system's documentation for details.

endutxent()

Closes the database.

getutxent()

Read the next entry from the database. Returns a hash ref or undef if the end of the database is reached.

getutxid()

This function takes a hash ref as argument and searches for a database entry matching the values for the "ut_type" and "ut_id" keys specified in the argument. Returns a hash ref or undef if no matching entry could be found.

getutxline()

This function takes a hash ref as argument and searches for an entry of the type LOGIN_PROCESS or USER_PROCESS which also has a "ut_line" value matching that in the argument.

pututxline()

Writes out the supplied utmpx record into the current database. pututxline() 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 pututxline() creates the utmp file if it doesn't exist is implementation-dependent.

setutxent()

Resets the current database.

utmpxname()

Allows the user to change the name of the file being examined from the default file (see the section ``Constants'' below) to any other file. The name provided to utmpxname() will then be used for all following utmpx functions.

This is a vendor extension, which may not be available on all systems.

Utmp functions

getut()

Reads a utmp-like file and converts it to a Perl array of hashes. See above for a description of the hashes.

Note that "ut_addr" (if provided by the utmpx implementation) 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.

The following functions are equivalent to the C functions of the same names; refer to your system's documentation for details. Since utmp is not formally standardized, not all functions may be available on your system, or their behavior may vary.

endutent()

Closes the database.

getutent()

Read the next entry from the database. Returns a hash ref or undef if the end of the database is reached.

getutid()

This function takes a hash ref as argument and searches for a database entry matching the values for the "ut_type" and "ut_id" keys specified in the argument. Returns a hash ref or undef if no matching entry could be found.

getutline()

This function takes a hash ref as argument and searches for an entry of the type LOGIN_PROCESS or USER_PROCESS which also has a "ut_line" value matching that in the argument.

pututline()

Writes out the supplied utmp record into the utmp file. pututline() 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 pututline() creates the utmp file if it doesn't exist is implementation-dependent.

setutent()

Resets the current database.

utmpname()

Allows the user to change the name of the file being examined from the default file (typically something like /etc/utmp or /var/run/utmp; see the section ``Constants'' below) to any other file. In this case, the name provided to utmpname() will be used for the getut() and pututline() functions. On some operating systems, this may also implicitly set the database for utmpx functions.

Constants

HAS_UTMPX

True if User::Utmp was built with support for utmpx.

UTMP_FILE UTMPX_FILE WTMP_FILE WTMPX_FILE

The default databases. These constants may not be available on all platforms.

BOOT_TIME DEAD_PROCESS EMPTY INIT_PROCESS LOGIN_PROCESS NEW_TIME OLD_TIME RUN_LVL USER_PROCESS

Values used in the ut_type field. EMPTY is also used on Linux (instead of the non-standard UT_UNKNOWN used in some Linux versions).

EXAMPLES

NOTES

RESTRICTIONS

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

AUTHOR

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

Utmpx functions

Utmp functions

Constants

EXAMPLES

NOTES

RESTRICTIONS

AUTHOR

SEE ALSO