| blob | 1d7291e7f112a24c483f7b354706731c68b41899 |
1 .\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de),
2 .\" Fri Apr 2 11:32:09 MET DST 1993
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
7 .\" Modified 1995-02-26 by Michael Haardt
8 .\" Modified 1996-07-20 by Michael Haardt
9 .\" Modified 1997-07-02 by Nicolás Lichtmaier <nick@debian.org>
10 .\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne
11 .TH utmp 5 (date) "Linux man-pages (unreleased)"
12 .SH NAME
13 utmp, wtmp \- login records
14 .SH SYNOPSIS
15 .nf
16 .B #include <utmp.h>
17 .fi
18 .SH DESCRIPTION
19 The
20 .I utmp
21 file allows one to discover information about who is currently using the
22 system.
23 There may be more users currently using the system, because not
24 all programs use utmp logging.
25 .P
26 .B Warning:
27 .I utmp
28 must not be writable by the user class "other",
29 because many system programs (foolishly)
30 depend on its integrity.
31 You risk faked system logfiles and
32 modifications of system files if you leave
33 .I utmp
34 writable to any user other than the owner and group owner of the file.
35 .P
36 The file is a sequence of
37 .I utmp
38 structures,
39 declared as follows in
40 .I <utmp.h>
41 (note that this is only one of several definitions
42 around; details depend on the version of libc):
43 .P
44 .in +4n
45 .EX
46 /* Values for ut_type field, below */
47 \&
48 #define EMPTY 0 /* Record does not contain valid info
49 (formerly known as UT_UNKNOWN on Linux) */
50 #define RUN_LVL 1 /* Change in system run\-level (see
51 \c
52 .BR init (1))\ \c
53 */
54 #define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */
55 #define NEW_TIME 3 /* Time after system clock change
56 (in \fIut_tv\fP) */
57 #define OLD_TIME 4 /* Time before system clock change
58 (in \fIut_tv\fP) */
59 #define INIT_PROCESS 5 /* Process spawned by \c
60 .BR init (1)\ \c
61 */
62 #define LOGIN_PROCESS 6 /* Session leader process for user login */
63 #define USER_PROCESS 7 /* Normal process */
64 #define DEAD_PROCESS 8 /* Terminated process */
65 #define ACCOUNTING 9 /* Not implemented */
66 \&
67 #define UT_LINESIZE 32
68 #define UT_NAMESIZE 32
69 #define UT_HOSTSIZE 256
70 \&
71 struct exit_status { /* Type for ut_exit, below */
72 short e_termination; /* Process termination status */
73 short e_exit; /* Process exit status */
74 };
75 \&
76 struct utmp {
77 short ut_type; /* Type of record */
78 pid_t ut_pid; /* PID of login process */
79 char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */
80 char ut_id[4]; /* Terminal name suffix,
81 or inittab(5) ID */
82 char ut_user[UT_NAMESIZE]; /* Username */
83 char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or
84 kernel version for run\-level
85 messages */
86 struct exit_status ut_exit; /* Exit status of a process
87 marked as DEAD_PROCESS; not
88 used by Linux \c
89 .BR init (1)\ \c
90 */
91 /* The ut_session and ut_tv fields must be the same size when
92 compiled 32\- and 64\-bit. This allows data files and shared
93 memory to be shared between 32\- and 64\-bit applications. */
94 #if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32
95 int32_t ut_session; /* Session ID (\c
96 .BR getsid (2) ),
97 used for windowing */
98 struct {
99 int32_t tv_sec; /* Seconds */
100 int32_t tv_usec; /* Microseconds */
101 } ut_tv; /* Time entry was made */
102 #else
103 long ut_session; /* Session ID */
104 struct timeval ut_tv; /* Time entry was made */
105 #endif
106 \&
107 int32_t ut_addr_v6[4]; /* Internet address of remote
108 host; IPv4 address uses
109 just ut_addr_v6[0] */
110 char __unused[20]; /* Reserved for future use */
111 };
112 \&
113 /* Backward compatibility hacks */
114 #define ut_name ut_user
115 #ifndef _NO_UT_TIME
116 #define ut_time ut_tv.tv_sec
117 #endif
118 #define ut_xtime ut_tv.tv_sec
119 #define ut_addr ut_addr_v6[0]
120 .EE
121 .in
122 .P
123 This structure gives the name of the special file associated with the
124 user's terminal, the user's login name, and the time of login in the form
125 of
126 .BR time (2).
127 String fields are terminated by a null byte (\[aq]\[rs]0\[aq])
128 if they are shorter than the size
129 of the field.
130 .P
131 The first entries ever created result from
132 .BR init (1)
133 processing
134 .BR inittab (5).
135 Before an entry is processed, though,
136 .BR init (1)
137 cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing
138 \fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each
139 record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP
140 and where no process with PID \fIut_pid\fP exists.
141 If no empty record
142 with the needed \fIut_id\fP can be found,
143 .BR init (1)
144 creates a new one.
145 It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
146 current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
147 .P
148 .BR mingetty (8)
149 (or
150 .BR agetty (8))
151 locates the entry by the PID, changes \fIut_type\fP to
152 \fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits
153 for connection to be established.
154 .BR login (1),
155 after a user has been
156 authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes
157 \fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP.
158 Depending on
159 .BR mingetty (8)
160 (or
161 .BR agetty (8))
162 and
163 .BR login (1),
164 records may be located by
165 \fIut_line\fP instead of the preferable \fIut_pid\fP.
166 .P
167 When
168 .BR init (1)
169 finds that a process has exited, it locates its utmp entry by
170 .IR ut_pid ,
171 sets
172 .I ut_type
173 to
174 .BR DEAD_PROCESS ,
175 and clears
176 .IR ut_user ,
177 .IR ut_host ,
178 and
179 .I ut_time
180 with null bytes.
181 .P
182 .BR xterm (1)
183 and other terminal emulators directly create a
184 \fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the
185 string that suffix part of the terminal name (the characters
186 following
187 .IR /dev/ [pt] ty ).
188 If they find a \fBDEAD_PROCESS\fP for this ID,
189 they recycle it, otherwise they create a new entry.
190 If they can, they
191 will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that
192 they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP
193 as well.
194 .P
195 .BR telnetd (8)
196 sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to
197 .BR login (1)
198 as usual.
199 After the telnet session ends,
200 .BR telnetd (8)
201 cleans up utmp in the described way.
202 .P
203 The \fIwtmp\fP file records all logins and logouts.
204 Its format is exactly like \fIutmp\fP except that a null username
205 indicates a logout
206 on the associated terminal.
207 Furthermore, the terminal name \fB\[ti]\fP
208 with username \fBshutdown\fP or \fBreboot\fP indicates a system
209 shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP
210 logs the old/new system time when
211 .BR date (1)
212 changes it.
213 \fIwtmp\fP is maintained by
214 .BR login (1),
215 .BR init (1),
216 and some versions of
217 .BR getty (8)
218 (e.g.,
219 .BR mingetty (8)
220 or
221 .BR agetty (8)).
222 None of these programs creates the file, so if it is
223 removed, record-keeping is turned off.
224 .SH FILES
225 .I /var/run/utmp
226 .br
227 .I /var/log/wtmp
228 .SH VERSIONS
229 POSIX.1 does not specify a
230 .I utmp
231 structure, but rather one named
232 .I utmpx
233 (as part of the XSI extension),
234 with specifications for the fields
235 .IR ut_type ,
236 .IR ut_pid ,
237 .IR ut_line ,
238 .IR ut_id ,
239 .IR ut_user ,
240 and
241 .IR ut_tv .
242 POSIX.1 does not specify the lengths of the
243 .I ut_line
244 and
245 .I ut_user
246 fields.
247 .P
248 Linux defines the
249 .I utmpx
250 structure to be the same as the
251 .I utmp
252 structure.
253 .SH STANDARDS
254 Linux.
255 .SH HISTORY
256 Linux utmp entries conform neither to v7/BSD nor to System V; they are a
257 mix of the two.
258 .P
259 v7/BSD has fewer fields; most importantly it lacks
260 \fIut_type\fP, which causes native v7/BSD-like programs to display (for
261 example) dead or login entries.
262 Further, there is no configuration file
263 which allocates slots to sessions.
264 BSD does so because it lacks \fIut_id\fP fields.
265 .P
266 In Linux (as in System V), the \fIut_id\fP field of a
267 record will never change once it has been set, which reserves that slot
268 without needing a configuration file.
269 Clearing \fIut_id\fP may result
270 in race conditions leading to corrupted utmp entries and potential
271 security holes.
272 Clearing the abovementioned fields by filling them
273 with null bytes is not required by System V semantics,
274 but makes it possible to run
275 many programs which assume BSD semantics and which do not modify utmp.
276 Linux uses the BSD conventions for line contents, as documented above.
277 .P
278 .\" mtk: What is the referrent of "them" in the following sentence?
279 .\" System V only uses the type field to mark them and logs
280 .\" informative messages such as \fB"new time"\fP in the line field.
281 System V has no \fIut_host\fP or \fIut_addr_v6\fP fields.
282 .SH NOTES
283 Unlike various other
284 systems, where utmp logging can be disabled by removing the file, utmp
285 must always exist on Linux.
286 If you want to disable
287 .BR who (1),
288 then do not make utmp world readable.
289 .P
290 The file format is machine-dependent, so it is recommended that it be
291 processed only on the machine architecture where it was created.
292 .P
293 Note that on \fIbiarch\fP platforms, that is, systems which can run both
294 32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
295 \fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
296 The same goes for \fIut_session\fP and \fIut_time\fP if they are present.
297 This allows data files and shared memory to be shared between
298 32-bit and 64-bit applications.
299 This is achieved by changing the type of
300 .I ut_session
301 to
302 .IR int32_t ,
303 and that of
304 .I ut_tv
305 to a struct with two
306 .I int32_t
307 fields
308 .I tv_sec
309 and
310 .IR tv_usec .
311 Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
312 then instead of the call:
313 .P
314 .in +4n
315 .EX
316 gettimeofday((struct timeval *) &ut.ut_tv, NULL);
317 .EE
318 .in
319 .P
320 the following method of setting this field is recommended:
321 .P
322 .in +4n
323 .EX
324 struct utmp ut;
325 struct timeval tv;
326 \&
327 gettimeofday(&tv, NULL);
328 ut.ut_tv.tv_sec = tv.tv_sec;
329 ut.ut_tv.tv_usec = tv.tv_usec;
330 .EE
331 .in
332 .\" .P
333 .\" Note that the \fIutmp\fP struct from libc5 has changed in libc6.
334 .\" Because of this,
335 .\" binaries using the old libc5 struct will corrupt
336 .\" .IR /var/run/utmp " and/or " /var/log/wtmp .
337 .\" .SH BUGS
338 .\" This man page is based on the libc5 one, things may work differently now.
339 .SH SEE ALSO
340 .BR ac (1),
341 .BR date (1),
342 .BR init (1),
343 .BR last (1),
344 .BR login (1),
345 .BR logname (1),
346 .BR lslogins (1),
347 .BR users (1),
348 .BR utmpdump (1),
349 .BR who (1),
350 .BR getutent (3),
351 .BR getutmp (3),
352 .BR login (3),
353 .BR logout (3),
354 .BR logwtmp (3),
355 .BR updwtmp (3)