1Utmp(3) User Contributed Perl Documentation Utmp(3)
2
6 User::Utmp - Perl access to utmp- and utmpx-style databases
7
9 use User::Utmp qw(:constants :utmpx);
10 @utmp = getutx();
11 or, using utmp:
13 use User::Utmp qw(:constants :utmp);
15 @utmp = getut();
16
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 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 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 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 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 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 {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 The array returned by the getutx() and getut() functions is composed of
60 hash references like this.
61 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 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 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 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 The following functions are equivalent to the C functions of the same
81 names; refer to your system's documentation for details.
82 endutxent()
84 Closes the database.
85 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 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 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 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 setutxent()
109 Resets the current database.
110 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 This is a vendor extension, which may not be available on all
118 systems.
119 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 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 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 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 endutent()
140 Closes the database.
141 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 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 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 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 setutent()
165 Resets the current database.
166 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 Constants
177 User::Utmp also provides the following constants as functions:
178 HAS_UTMPX
180 True if User::Utmp was built with support for utmpx.
181 UTMP_FILE UTMPX_FILE WTMP_FILE WTMPX_FILE
183 The default databases. These constants may not be available on all
184 platforms.
185 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
193 See the files example.pl and test.pl in the distribution for usage
194 examples.
195
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
202 Reading the whole file into an array might not be the most efficient
203 approach for very large databases.
204 This module is based on the non-reentrant utmpx and utmp functions; it
206 is therefore not thread-safe.
207
209 Michael Piotrowski <mxp@dynalabs.de>
210
212 utmpx(4), utmp(4); on some systems: utmpx(5), utmp(5)
213perl v5.36.0 2023-01-20 Utmp(3)