1Utmp(3)               User Contributed Perl Documentation              Utmp(3)
2
3
4

NAME

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

SYNOPSIS

9         use User::Utmp qw(:constants :utmpx);
10         @utmp = getutx();
11
12       or, using utmp:
13
14         use User::Utmp qw(:constants :utmp);
15         @utmp = getut();
16

DESCRIPTION

18       UNIX systems record information about current and past logins in a user
19       accounting database.  This database is realized by two files: File
20       utmpx contains a record of all users currently logged onto the system,
21       while file wtmpx contains a record of all logins and logouts.  Some
22       systems (such as HP-UX and AIX) also maintain a third file containing
23       failed login attempts.  The information in these files is used by
24       commands such as who(1), last(1), write(1), or login(1).
25
26       The exact location of these files in the file system varies between
27       operating systems, but they are typically stored in directories like
28       /var/adm, /var/run, or /var/log.  The Single UNIX Specification
29       specifies an API for reading from and writing to these files.
30
31       The utmpx file format and functions were derived from the older utmp
32       file format and functions.  For compatibility reasons, many systems
33       still support the utmp functions and maintain utmp database files.  It
34       is recommended, however, to use the utmpx functions instead of the
35       obsolete utmp functions.
36
37       The User::Utmp module provides functions for reading and writing utmpx
38       and utmp files by providing a Perl interface to the system functions.
39
40       Utmpx and utmp records are represented in Perl by hash references.  The
41       hash keys are the names of the elements of the utmpx structure.  For
42       details consult utmpx(4) (utmpx(5) on some systems).  The hash values
43       are (mostly) the same as in C.
44
45       As an example, here is a typical record as it may be returned by the
46       getutxent(), getutxid(), getutxline() or the corresponding utmp
47       functions:
48
49         {ut_tv   => {tv_sec => 1141256698, tv_usec => 0},
50          ut_line => "ttyp0",
51          ut_time => 1141256698,
52          ut_id   => "p0",
53          ut_host => ":0.0",
54          ut_exit => {e_termination => 0, e_exit => 2},
55          ut_pid  => 4577,
56          ut_user => "mxp",
57          ut_type => USER_PROCESS,}
58
59       The array returned by the getutx() and getut() functions is composed of
60       hash references like this.
61
62   Utmpx functions
63       User::Utmp offers a high-level function for reading a utmpx database,
64       getutx(), and access to the lower-level utmpx functions defined by the
65       Single UNIX Specification and vendor extensions.
66
67       getutx()
68           Reads a utmpx-like file and converts it to a Perl array of hashes.
69           See above for a description of the hashes.
70
71           Note that "ut_addr" (if provided by the utmpx implementation)
72           contains an Internet address (four bytes in network order), not a
73           number.  It is therefore converted to a string suitable as
74           parameter to gethostbyname().  If the record doesn't describe a
75           remote login "ut_addr" is the empty string.
76
77           For compatibility with utmp, User::Utmp provides a "ut_time" field
78           which contains the same value as the "ut_tv.tv_sec" field.
79
80       The following functions are equivalent to the C functions of the same
81       names; refer to your system's documentation for details.
82
83       endutxent()
84           Closes the database.
85
86       getutxent()
87           Read the next entry from the database.  Returns a hash ref or undef
88           if the end of the database is reached.
89
90       getutxid()
91           This function takes a hash ref as argument and searches for a
92           database entry matching the values for the "ut_type" and "ut_id"
93           keys specified in the argument.  Returns a hash ref or undef if no
94           matching entry could be found.
95
96       getutxline()
97           This function takes a hash ref as argument and searches for an
98           entry of the type LOGIN_PROCESS or USER_PROCESS which also has a
99           "ut_line" value matching that in the argument.
100
101       pututxline()
102           Writes out the supplied utmpx record into the current database.
103           pututxline() takes a reference to a hash which has the same
104           structure and contents as the elements of the array returned by
105           getut().  Whether or not pututxline() creates the utmp file if it
106           doesn't exist is implementation-dependent.
107
108       setutxent()
109           Resets the current database.
110
111       utmpxname()
112           Allows the user to change the name of the file being examined from
113           the default file (see the section "Constants" below) to any other
114           file.  The name provided to utmpxname() will then be used for all
115           following utmpx functions.
116
117           This is a vendor extension, which may not be available on all
118           systems.
119
120   Utmp functions
121       User::Utmp offers a high-level function for reading a utmp database,
122       getut(), and access to the lower-level utmp functions.
123
124       getut()
125           Reads a utmp-like file and converts it to a Perl array of hashes.
126           See above for a description of the hashes.
127
128           Note that "ut_addr" (if provided by the utmpx implementation)
129           contains an Internet address (four bytes in network order), not a
130           number.  It is therefore converted to a string suitable as
131           parameter to gethostbyname().  If the record doesn't describe a
132           remote login "ut_addr" is the empty string.
133
134       The following functions are equivalent to the C functions of the same
135       names; refer to your system's documentation for details.  Since utmp is
136       not formally standardized, not all functions may be available on your
137       system, or their behavior may vary.
138
139       endutent()
140           Closes the database.
141
142       getutent()
143           Read the next entry from the database.  Returns a hash ref or undef
144           if the end of the database is reached.
145
146       getutid()
147           This function takes a hash ref as argument and searches for a
148           database entry matching the values for the "ut_type" and "ut_id"
149           keys specified in the argument.  Returns a hash ref or undef if no
150           matching entry could be found.
151
152       getutline()
153           This function takes a hash ref as argument and searches for an
154           entry of the type LOGIN_PROCESS or USER_PROCESS which also has a
155           "ut_line" value matching that in the argument.
156
157       pututline()
158           Writes out the supplied utmp record into the utmp file.
159           pututline() takes a reference to a hash which has the same
160           structure and contents as the elements of the array returned by
161           getut().  Whether or not pututline() creates the utmp file if it
162           doesn't exist is implementation-dependent.
163
164       setutent()
165           Resets the current database.
166
167       utmpname()
168           Allows the user to change the name of the file being examined from
169           the default file (typically something like /etc/utmp or
170           /var/run/utmp; see the section "Constants" below) to any other
171           file.  In this case, the name provided to utmpname() will be used
172           for the getut() and pututline() functions.  On some operating
173           systems, this may also implicitly set the database for utmpx
174           functions.
175
176   Constants
177       User::Utmp also provides the following constants as functions:
178
179       HAS_UTMPX
180           True if User::Utmp was built with support for utmpx.
181
182       UTMP_FILE UTMPX_FILE WTMP_FILE WTMPX_FILE
183           The default databases.  These constants may not be available on all
184           platforms.
185
186       BOOT_TIME DEAD_PROCESS EMPTY INIT_PROCESS LOGIN_PROCESS NEW_TIME
187       OLD_TIME RUN_LVL USER_PROCESS
188           Values used in the ut_type field.  EMPTY is also used on Linux
189           (instead of the non-standard UT_UNKNOWN used in some Linux
190           versions).
191

EXAMPLES

193       See the files example.pl and test.pl in the distribution for usage
194       examples.
195

NOTES

197       The utmpx interface is standardized in the the Single UNIX Specificaton
198       and should therefore be used in preference to the legacy utmp
199       functions.  Some systems only provide minimal utmp support.
200

RESTRICTIONS

202       Reading the whole file into an array might not be the most efficient
203       approach for very large databases.
204
205       This module is based on the non-reentrant utmpx and utmp functions; it
206       is therefore not thread-safe.
207

AUTHOR

209       Michael Piotrowski <mxp@dynalabs.de>
210

SEE ALSO

212       utmpx(4), utmp(4); on some systems: utmpx(5), utmp(5)
213
214
215
216perl v5.36.0                      2023-01-20                           Utmp(3)
Impressum