Debian Codegraph @

upstream/debian-unstable/man5/utmp.5

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