1 .\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de),
2 .\" Fri Apr 2 11:32:09 MET DST 1993
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" The GNU General Public License's references to "object code"
10 .\" and "executables" are to be interpreted as the output of any
11 .\" document formatting or typesetting system, including
12 .\" intermediate and printed output.
14 .\" This manual is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public
20 .\" License along with this manual; if not, write to the Free
21 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
24 .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
25 .\" Modified 1995-02-26 by Michael Haardt
26 .\" Modified 1996-07-20 by Michael Haardt
27 .\" Modified 1997-07-02 by Nicolás Lichtmaier <nick@debian.org>
28 .\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne
29 .TH UTMP 5 2011-09-28 "Linux" "Linux Programmer's Manual"
31 utmp, wtmp \- login records
37 file allows one to discover information about who is currently using the
39 There may be more users currently using the system, because not
40 all programs use utmp logging.
44 must not be writable by the user class "other",
45 because many system programs (foolishly)
46 depend on its integrity.
47 You risk faked system logfiles and
48 modifications of system files if you leave
50 writable to any user other than the owner and group owner of the file.
52 The file is a sequence of
55 declared as follows in
57 (note that this is only one of several definitions
58 around; details depend on the version of libc):
62 /* Values for ut_type field, below */
64 #define EMPTY 0 /* Record does not contain valid info
65 (formerly known as UT_UNKNOWN on Linux) */
66 #define RUN_LVL 1 /* Change in system run-level (see
68 #define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */
69 #define NEW_TIME 3 /* Time after system clock change
71 #define OLD_TIME 4 /* Time before system clock change
73 #define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(8) */
74 #define LOGIN_PROCESS 6 /* Session leader process for user login */
75 #define USER_PROCESS 7 /* Normal process */
76 #define DEAD_PROCESS 8 /* Terminated process */
77 #define ACCOUNTING 9 /* Not implemented */
79 #define UT_LINESIZE 32
80 #define UT_NAMESIZE 32
81 #define UT_HOSTSIZE 256
83 struct exit_status { /* Type for ut_exit, below */
84 short int e_termination; /* Process termination status */
85 short int e_exit; /* Process exit status */
89 short ut_type; /* Type of record */
90 pid_t ut_pid; /* PID of login process */
91 char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */
92 char ut_id[4]; /* Terminal name suffix,
94 char ut_user[UT_NAMESIZE]; /* Username */
95 char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or
96 kernel version for run-level
98 struct exit_status ut_exit; /* Exit status of a process
99 marked as DEAD_PROCESS; not
100 used by Linux init(8) */
101 /* The ut_session and ut_tv fields must be the same size when
102 compiled 32- and 64-bit. This allows data files and shared
103 memory to be shared between 32- and 64-bit applications. */
104 #if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32
105 int32_t ut_session; /* Session ID (\fBgetsid\fP(2)),
106 used for windowing */
108 int32_t tv_sec; /* Seconds */
109 int32_t tv_usec; /* Microseconds */
110 } ut_tv; /* Time entry was made */
112 long ut_session; /* Session ID */
113 struct timeval ut_tv; /* Time entry was made */
116 int32_t ut_addr_v6[4]; /* Internet address of remote
117 host; IPv4 address uses
118 just ut_addr_v6[0] */
119 char __unused[20]; /* Reserved for future use */
122 /* Backward compatibility hacks */
123 #define ut_name ut_user
125 #define ut_time ut_tv.tv_sec
127 #define ut_xtime ut_tv.tv_sec
128 #define ut_addr ut_addr_v6[0]
132 This structure gives the name of the special file associated with the
133 user's terminal, the user's login name, and the time of login in the form
136 String fields are terminated by a null byte (\(aq\e0\(aq)
137 if they are shorter than the size
140 The first entries ever created result from
144 Before an entry is processed, though,
146 cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing
147 \fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each
148 record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP
149 and where no process with PID \fIut_pid\fP exists.
151 with the needed \fIut_id\fP can be found,
154 It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
155 current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
160 locates the entry by the PID, changes \fIut_type\fP to
161 \fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits
162 for connection to be established.
164 after a user has been
165 authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes
166 \fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP.
173 records may be located by
174 \fIut_line\fP instead of the preferable \fIut_pid\fP.
178 finds that a process has exited, it locates its utmp
179 entry by \fIut_pid\fP, sets \fIut_type\fP to \fBDEAD_PROCESS\fP, and
180 clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes.
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 \fI/dev/[pt]ty\fP).
187 If they find a \fBDEAD_PROCESS\fP for this ID,
188 they recycle it, otherwise they create a new entry.
190 will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that
191 they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP
195 sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to
198 After the telnet session ends,
200 cleans up utmp in the described way.
202 The \fIwtmp\fP file records all logins and logouts.
203 Its format is exactly like \fIutmp\fP except that a null username
205 on the associated terminal.
206 Furthermore, the terminal name \fB~\fP
207 with username \fBshutdown\fP or \fBreboot\fP indicates a system
208 shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP
209 logs the old/new system time when
212 \fIwtmp\fP is maintained by
221 None of these programs creates the file, so if it is
222 removed, record-keeping is turned off.
229 POSIX.1 does not specify a
231 structure, but rather one named
233 with specifications for the fields
241 POSIX.1 does not specify the lengths of the
249 structure to be the same as the
252 .SS Comparison with Historical Systems
253 Linux utmp entries conform neither to v7/BSD nor to System V; they are a
256 v7/BSD has fewer fields; most importantly it lacks
257 \fIut_type\fP, which causes native v7/BSD-like programs to display (for
258 example) dead or login entries.
259 Further, there is no configuration file
260 which allocates slots to sessions.
261 BSD does so because it lacks \fIut_id\fP fields.
263 In Linux (as in System V), the \fIut_id\fP field of a
264 record will never change once it has been set, which reserves that slot
265 without needing a configuration file.
266 Clearing \fIut_id\fP may result
267 in race conditions leading to corrupted utmp entries and potential
269 Clearing the abovementioned fields by filling them
270 with null bytes is not required by System V semantics,
271 but makes it possible to run
272 many programs which assume BSD semantics and which do not modify utmp.
273 Linux uses the BSD conventions for line contents, as documented above.
275 .\" mtk: What is the referrent of "them" in the following sentence?
276 .\" System V only uses the type field to mark them and logs
277 .\" informative messages such as \fB"new time"\fP in the line field.
278 System V has no \fIut_host\fP or \fIut_addr_v6\fP fields.
282 systems, where utmp logging can be disabled by removing the file, utmp
283 must always exist on Linux.
284 If you want to disable
286 then do not make utmp world readable.
288 The file format is machine-dependent, so it is recommended that it be
289 processed only on the machine architecture where it was created.
291 Note that on \fIbiarch\fP platforms, that is, systems which can run both
292 32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
293 \fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
294 The same goes for \fIut_session\fP and \fIut_time\fP if they are present.
295 This allows data files and shared memory to be shared between
296 32-bit and 64-bit applications.
297 This is achieved by changing the type of
309 Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
310 then instead of the call:
314 gettimeofday((struct timeval *) &ut.ut_tv, NULL);
318 the following method of setting this field is recommended:
325 gettimeofday(&tv, NULL);
326 ut.ut_tv.tv_sec = tv.tv_sec;
327 ut.ut_tv.tv_usec = tv.tv_usec;
331 Note that the \fIutmp\fP struct from libc5 has changed in libc6.
333 binaries using the old libc5 struct will corrupt
334 .IR /var/run/utmp " and/or " /var/log/wtmp .
336 This man page is based on the libc5 one, things may work differently now.