1 .\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de),
2 .\" Fri Apr 2 11:32:09 MET DST 1993
4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
5 .\" This is free documentation; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License as
7 .\" published by the Free Software Foundation; either version 2 of
8 .\" the License, or (at your option) any later version.
10 .\" The GNU General Public License's references to "object code"
11 .\" and "executables" are to be interpreted as the output of any
12 .\" document formatting or typesetting system, including
13 .\" intermediate and printed output.
15 .\" This manual is distributed in the hope that it will be useful,
16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 .\" GNU General Public License for more details.
20 .\" You should have received a copy of the GNU General Public
21 .\" License along with this manual; if not, see
22 .\" <http://www.gnu.org/licenses/>.
25 .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
26 .\" Modified 1995-02-26 by Michael Haardt
27 .\" Modified 1996-07-20 by Michael Haardt
28 .\" Modified 1997-07-02 by Nicolás Lichtmaier <nick@debian.org>
29 .\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne
30 .TH UTMP 5 2017-09-15 "Linux" "Linux Programmer's Manual"
32 utmp, wtmp \- login records
38 file allows one to discover information about who is currently using the
40 There may be more users currently using the system, because not
41 all programs use utmp logging.
45 must not be writable by the user class "other",
46 because many system programs (foolishly)
47 depend on its integrity.
48 You risk faked system logfiles and
49 modifications of system files if you leave
51 writable to any user other than the owner and group owner of the file.
53 The file is a sequence of
56 declared as follows in
58 (note that this is only one of several definitions
59 around; details depend on the version of libc):
63 /* Values for ut_type field, below */
65 #define EMPTY 0 /* Record does not contain valid info
66 (formerly known as UT_UNKNOWN on Linux) */
67 #define RUN_LVL 1 /* Change in system run-level (see
69 #define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */
70 #define NEW_TIME 3 /* Time after system clock change
72 #define OLD_TIME 4 /* Time before system clock change
74 #define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(8) */
75 #define LOGIN_PROCESS 6 /* Session leader process for user login */
76 #define USER_PROCESS 7 /* Normal process */
77 #define DEAD_PROCESS 8 /* Terminated process */
78 #define ACCOUNTING 9 /* Not implemented */
80 #define UT_LINESIZE 32
81 #define UT_NAMESIZE 32
82 #define UT_HOSTSIZE 256
84 struct exit_status { /* Type for ut_exit, below */
85 short int e_termination; /* Process termination status */
86 short int e_exit; /* Process exit status */
90 short ut_type; /* Type of record */
91 pid_t ut_pid; /* PID of login process */
92 char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */
93 char ut_id[4]; /* Terminal name suffix,
95 char ut_user[UT_NAMESIZE]; /* Username */
96 char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or
97 kernel version for run-level
99 struct exit_status ut_exit; /* Exit status of a process
100 marked as DEAD_PROCESS; not
101 used by Linux init (1 */
102 /* The ut_session and ut_tv fields must be the same size when
103 compiled 32- and 64-bit. This allows data files and shared
104 memory to be shared between 32- and 64-bit applications. */
105 #if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32
106 int32_t ut_session; /* Session ID (\fBgetsid\fP(2)),
107 used for windowing */
109 int32_t tv_sec; /* Seconds */
110 int32_t tv_usec; /* Microseconds */
111 } ut_tv; /* Time entry was made */
113 long ut_session; /* Session ID */
114 struct timeval ut_tv; /* Time entry was made */
117 int32_t ut_addr_v6[4]; /* Internet address of remote
118 host; IPv4 address uses
119 just ut_addr_v6[0] */
120 char __unused[20]; /* Reserved for future use */
123 /* Backward compatibility hacks */
124 #define ut_name ut_user
126 #define ut_time ut_tv.tv_sec
128 #define ut_xtime ut_tv.tv_sec
129 #define ut_addr ut_addr_v6[0]
133 This structure gives the name of the special file associated with the
134 user's terminal, the user's login name, and the time of login in the form
137 String fields are terminated by a null byte (\(aq\e0\(aq)
138 if they are shorter than the size
141 The first entries ever created result from
145 Before an entry is processed, though,
147 cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing
148 \fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each
149 record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP
150 and where no process with PID \fIut_pid\fP exists.
152 with the needed \fIut_id\fP can be found,
155 It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
156 current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
161 locates the entry by the PID, changes \fIut_type\fP to
162 \fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits
163 for connection to be established.
165 after a user has been
166 authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes
167 \fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP.
174 records may be located by
175 \fIut_line\fP instead of the preferable \fIut_pid\fP.
179 finds that a process has exited, it locates its utmp
180 entry by \fIut_pid\fP, sets \fIut_type\fP to \fBDEAD_PROCESS\fP, and
181 clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes.
184 and other terminal emulators directly create a
185 \fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the
186 string that suffix part of the terminal name (the characters
187 following \fI/dev/[pt]ty\fP).
188 If they find a \fBDEAD_PROCESS\fP for this ID,
189 they recycle it, otherwise they create a new entry.
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
196 sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to
199 After the telnet session ends,
201 cleans up utmp in the described way.
203 The \fIwtmp\fP file records all logins and logouts.
204 Its format is exactly like \fIutmp\fP except that a null username
206 on the associated terminal.
207 Furthermore, the terminal name \fB~\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
213 \fIwtmp\fP is maintained by
222 None of these programs creates the file, so if it is
223 removed, record-keeping is turned off.
230 POSIX.1 does not specify a
232 structure, but rather one named
234 with specifications for the fields
242 POSIX.1 does not specify the lengths of the
250 structure to be the same as the
253 .SS Comparison with historical systems
254 Linux utmp entries conform neither to v7/BSD nor to System V; they are a
257 v7/BSD has fewer fields; most importantly it lacks
258 \fIut_type\fP, which causes native v7/BSD-like programs to display (for
259 example) dead or login entries.
260 Further, there is no configuration file
261 which allocates slots to sessions.
262 BSD does so because it lacks \fIut_id\fP fields.
264 In Linux (as in System V), the \fIut_id\fP field of a
265 record will never change once it has been set, which reserves that slot
266 without needing a configuration file.
267 Clearing \fIut_id\fP may result
268 in race conditions leading to corrupted utmp entries and potential
270 Clearing the abovementioned fields by filling them
271 with null bytes is not required by System V semantics,
272 but makes it possible to run
273 many programs which assume BSD semantics and which do not modify utmp.
274 Linux uses the BSD conventions for line contents, as documented above.
276 .\" mtk: What is the referrent of "them" in the following sentence?
277 .\" System V only uses the type field to mark them and logs
278 .\" informative messages such as \fB"new time"\fP in the line field.
279 System V has no \fIut_host\fP or \fIut_addr_v6\fP fields.
283 systems, where utmp logging can be disabled by removing the file, utmp
284 must always exist on Linux.
285 If you want to disable
287 then do not make utmp world readable.
289 The file format is machine-dependent, so it is recommended that it be
290 processed only on the machine architecture where it was created.
292 Note that on \fIbiarch\fP platforms, that is, systems which can run both
293 32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
294 \fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
295 The same goes for \fIut_session\fP and \fIut_time\fP if they are present.
296 This allows data files and shared memory to be shared between
297 32-bit and 64-bit applications.
298 This is achieved by changing the type of
310 Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
311 then instead of the call:
315 gettimeofday((struct timeval *) &ut.ut_tv, NULL);
319 the following method of setting this field is recommended:
326 gettimeofday(&tv, NULL);
327 ut.ut_tv.tv_sec = tv.tv_sec;
328 ut.ut_tv.tv_usec = tv.tv_usec;
332 .\" Note that the \fIutmp\fP struct from libc5 has changed in libc6.
334 .\" binaries using the old libc5 struct will corrupt
335 .\" .IR /var/run/utmp " and/or " /var/log/wtmp .
337 .\" This man page is based on the libc5 one, things may work differently now.