1 .\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de),
2 .\" Fri Apr 2 11:32:09 MET DST 1993
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
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)"
13 utmp, wtmp \- login records
21 file allows one to discover information about who is currently using the
23 There may be more users currently using the system, because not
24 all programs use utmp logging.
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
34 writable to any user other than the owner and group owner of the file.
36 The file is a sequence of
39 declared as follows in
41 (note that this is only one of several definitions
42 around; details depend on the version of libc):
46 /* Values for ut_type field, below */
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
52 #define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */
53 #define NEW_TIME 3 /* Time after system clock change
55 #define OLD_TIME 4 /* Time before system clock change
57 #define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(1) */
58 #define LOGIN_PROCESS 6 /* Session leader process for user login */
59 #define USER_PROCESS 7 /* Normal process */
60 #define DEAD_PROCESS 8 /* Terminated process */
61 #define ACCOUNTING 9 /* Not implemented */
63 #define UT_LINESIZE 32
64 #define UT_NAMESIZE 32
65 #define UT_HOSTSIZE 256
67 struct exit_status { /* Type for ut_exit, below */
68 short e_termination; /* Process termination status */
69 short e_exit; /* Process exit status */
73 short ut_type; /* Type of record */
74 pid_t ut_pid; /* PID of login process */
75 char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */
76 char ut_id[4]; /* Terminal name suffix,
78 char ut_user[UT_NAMESIZE]; /* Username */
79 char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or
80 kernel version for run\-level
82 struct exit_status ut_exit; /* Exit status of a process
83 marked as DEAD_PROCESS; not
84 used by Linux init(1) */
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 (\fBgetsid\fP(2)),
92 int32_t tv_sec; /* Seconds */
93 int32_t tv_usec; /* Microseconds */
94 } ut_tv; /* Time entry was made */
96 long ut_session; /* Session ID */
97 struct timeval ut_tv; /* Time entry was made */
100 int32_t ut_addr_v6[4]; /* Internet address of remote
101 host; IPv4 address uses
102 just ut_addr_v6[0] */
103 char __unused[20]; /* Reserved for future use */
106 /* Backward compatibility hacks */
107 #define ut_name ut_user
109 #define ut_time ut_tv.tv_sec
111 #define ut_xtime ut_tv.tv_sec
112 #define ut_addr ut_addr_v6[0]
116 This structure gives the name of the special file associated with the
117 user's terminal, the user's login name, and the time of login in the form
120 String fields are terminated by a null byte (\[aq]\e0\[aq])
121 if they are shorter than the size
124 The first entries ever created result from
128 Before an entry is processed, though,
130 cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing
131 \fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each
132 record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP
133 and where no process with PID \fIut_pid\fP exists.
135 with the needed \fIut_id\fP can be found,
138 It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
139 current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
144 locates the entry by the PID, changes \fIut_type\fP to
145 \fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits
146 for connection to be established.
148 after a user has been
149 authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes
150 \fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP.
157 records may be located by
158 \fIut_line\fP instead of the preferable \fIut_pid\fP.
162 finds that a process has exited, it locates its utmp entry by
176 and other terminal emulators directly create a
177 \fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the
178 string that suffix part of the terminal name (the characters
181 If they find a \fBDEAD_PROCESS\fP for this ID,
182 they recycle it, otherwise they create a new entry.
184 will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that
185 they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP
189 sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to
192 After the telnet session ends,
194 cleans up utmp in the described way.
196 The \fIwtmp\fP file records all logins and logouts.
197 Its format is exactly like \fIutmp\fP except that a null username
199 on the associated terminal.
200 Furthermore, the terminal name \fB\[ti]\fP
201 with username \fBshutdown\fP or \fBreboot\fP indicates a system
202 shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP
203 logs the old/new system time when
206 \fIwtmp\fP is maintained by
215 None of these programs creates the file, so if it is
216 removed, record-keeping is turned off.
222 POSIX.1 does not specify a
224 structure, but rather one named
226 (as part of the XSI extension),
227 with specifications for the fields
235 POSIX.1 does not specify the lengths of the
243 structure to be the same as the
249 Linux utmp entries conform neither to v7/BSD nor to System V; they are a
252 v7/BSD has fewer fields; most importantly it lacks
253 \fIut_type\fP, which causes native v7/BSD-like programs to display (for
254 example) dead or login entries.
255 Further, there is no configuration file
256 which allocates slots to sessions.
257 BSD does so because it lacks \fIut_id\fP fields.
259 In Linux (as in System V), the \fIut_id\fP field of a
260 record will never change once it has been set, which reserves that slot
261 without needing a configuration file.
262 Clearing \fIut_id\fP may result
263 in race conditions leading to corrupted utmp entries and potential
265 Clearing the abovementioned fields by filling them
266 with null bytes is not required by System V semantics,
267 but makes it possible to run
268 many programs which assume BSD semantics and which do not modify utmp.
269 Linux uses the BSD conventions for line contents, as documented above.
271 .\" mtk: What is the referrent of "them" in the following sentence?
272 .\" System V only uses the type field to mark them and logs
273 .\" informative messages such as \fB"new time"\fP in the line field.
274 System V has no \fIut_host\fP or \fIut_addr_v6\fP fields.
277 systems, where utmp logging can be disabled by removing the file, utmp
278 must always exist on Linux.
279 If you want to disable
281 then do not make utmp world readable.
283 The file format is machine-dependent, so it is recommended that it be
284 processed only on the machine architecture where it was created.
286 Note that on \fIbiarch\fP platforms, that is, systems which can run both
287 32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
288 \fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
289 The same goes for \fIut_session\fP and \fIut_time\fP if they are present.
290 This allows data files and shared memory to be shared between
291 32-bit and 64-bit applications.
292 This is achieved by changing the type of
304 Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
305 then instead of the call:
309 gettimeofday((struct timeval *) &ut.ut_tv, NULL);
313 the following method of setting this field is recommended:
320 gettimeofday(&tv, NULL);
321 ut.ut_tv.tv_sec = tv.tv_sec;
322 ut.ut_tv.tv_usec = tv.tv_usec;
326 .\" Note that the \fIutmp\fP struct from libc5 has changed in libc6.
328 .\" binaries using the old libc5 struct will corrupt
329 .\" .IR /var/run/utmp " and/or " /var/log/wtmp .
331 .\" This man page is based on the libc5 one, things may work differently now.