man5/utmp.5

   1 .\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), Fri Apr  2 11:32:09 MET DST 1993
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
  24 .\" Modified 1995-02-26 by Michael Haardt
  25 .\" Modified 1996-07-20 by Michael Haardt
  26 .\" Modified 1997-07-02 by Nicolás Lichtmaier <nick@debian.org>
  27 .\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne
  28 .TH UTMP 5 2004-10-31 "File formats" "Linux Programmer's Manual"
  29 .SH NAME
  30 utmp, wtmp \- login records
  31 .SH SYNOPSIS
  32 #include <utmp.h>
  33 .SH DESCRIPTION
  34 The
  35 .I utmp
  36 file allows one to discover information about who is currently using the
  37 system.
  38 There may be more users currently using the system, because not
  39 all programs use utmp logging.
  40 .PP
  41 .B Warning:
  42 .I utmp
  43 must not be writable, because many system programs (foolishly)
  44 depend on its integrity.
  45 You risk faked system logfiles and
  46 modifications of system files if you leave
  47 .I utmp
  48 writable to any user.
  49 .PP
  50 The file is a sequence of entries with the following structure declared
  51 in the include file (note that this is only one of several definitions
  52 around; details depend on the version of libc):
  53 .in +3
  54 .nf
  55 .sp
  56 .ta 3i
  57 #define UT_UNKNOWN      0
  58 #define RUN_LVL         1
  59 #define BOOT_TIME       2
  60 #define NEW_TIME        3
  61 #define OLD_TIME        4
  62 #define INIT_PROCESS    5
  63 #define LOGIN_PROCESS   6
  64 #define USER_PROCESS    7
  65 #define DEAD_PROCESS    8
  66 #define ACCOUNTING      9
  67
  68 #define UT_LINESIZE     12
  69 #define UT_NAMESIZE     32
  70 #define UT_HOSTSIZE     256
  71
  72 struct exit_status {
  73     short int e_termination;    /* process termination status */
  74     short int e_exit;           /* process exit status */
  75 };
  76
  77 struct utmp {
  78     short ut_type;              /* type of login */
  79     pid_t ut_pid;               /* PID of login process */
  80     char ut_line[UT_LINESIZE];  /* device name of tty \- "/dev/" */
  81     char ut_id[4];              /* init id or abbrev. ttyname */
  82     char ut_user[UT_NAMESIZE];  /* user name */
  83     char ut_host[UT_HOSTSIZE];  /* hostname for remote login */
  84     struct exit_status ut_exit; /* The exit status of a process
  85                                    marked as DEAD_PROCESS */
  86
  87     /* The ut_session and ut_tv fields must be the same size when
  88        compiled 32- and 64-bit.  This allows data files and shared
  89        memory to be shared between 32- and 64-bit applications */
  90 #if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32
  91     int32_t ut_session;         /* Session ID, 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 int ut_session;        /* Session ID, used for windowing */
  98      struct timeval ut_tv;       /* Time entry was made */
  99 #endif
 100
 101     int32_t ut_addr_v6[4];       /* IP address of remote host */
 102     char __unused[20];           /* Reserved for future use */
 103 };
 104
 105 /* Backwards compatibility hacks.  */
 106 #define ut_name ut_user
 107 #ifndef _NO_UT_TIME
 108 #define ut_time ut_tv.tv_sec
 109 #endif
 110 #define ut_xtime ut_tv.tv_sec
 111 #define ut_addr ut_addr_v6[0]
 112 .sp
 113 .fi
 114 .in
 115 This structure gives the name of the special file associated with the
 116 user's terminal, the user's login name, and the time of login in the form
 117 of
 118 .BR time (2).
 119 String fields are terminated by \fB'\e0'\fP if they are shorter than the size
 120 of the field.
 121 .PP
 122 The first entries ever created result from
 123 .BR init (8)
 124 processing
 125 .BR inittab (5).
 126 Before an entry is processed, though,
 127 .BR init (8)
 128 cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing
 129 \fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each
 130 record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP
 131 and where no process with PID \fIut_pid\fP exists.
 132 If no empty record
 133 with the needed \fIut_id\fP can be found, init creates a new one.
 134 It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
 135 current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
 136 .PP
 137 .BR getty (8)
 138 locates the entry by the PID, changes \fIut_type\fP to
 139 \fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits
 140 for connection to be established.
 141 .BR login (8),
 142 after a user has been
 143 authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes
 144 \fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP.
 145 Depending on
 146 .BR getty (8)
 147 and
 148 .BR login (8),
 149 records may be located by
 150 \fIut_line\fP instead of the preferable \fIut_pid\fP.
 151 .PP
 152 When
 153 .BR init (8)
 154 finds that a process has exited, it locates its utmp
 155 entry by \fIut_pid\fP, sets \fIut_type\fP to \fBDEAD_PROCESS\fP, and
 156 clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes.
 157 .PP
 158 .BR xterm (1)
 159 and other terminal emulators directly create a
 160 \fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the last
 161 two letters of \fI/dev/ttyp\fP\fI%c\fP or by using \fIp\fP\fI%d\fP for
 162 \fI/dev/pts/\fP\fI%d\fP.
 163 If they find a \fBDEAD_PROCESS\fP for this ID,
 164 they recycle it, otherwise they create a new entry.
 165 If they can, they
 166 will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that
 167 they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP
 168 as well.
 169 .PP
 170 .BR xdm (8)
 171 should not create a utmp record, because there is no
 172 assigned terminal.
 173 Letting it create one will result in errors, such
 174 as 'finger: cannot stat /dev/machine.dom'.
 175 It should create wtmp entries, though, just like
 176 .BR ftpd (8)
 177 does.
 178 .PP
 179 .BR telnetd (8)
 180 sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to
 181 .BR login (8)
 182 as usual.
 183 After the telnet session ends,
 184 .BR telnetd (8)
 185 cleans up utmp in the described way.
 186 .PP
 187 The \fIwtmp\fP file records all logins and logouts.
 188 Its format is exactly like \fIutmp\fP except that a null user name
 189 indicates a logout
 190 on the associated terminal.
 191 Furthermore, the terminal name \fB~\fP
 192 with user name \fBshutdown\fP or \fBreboot\fP indicates a system
 193 shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP
 194 logs the old/new system time when
 195 .BR date (1)
 196 changes it.
 197 \fIwtmp\fP is maintained by
 198 .BR login (1),
 199 .BR init (1),
 200 and some versions of
 201 .BR getty (8).
 202 Neither of these programs creates the file, so if it is
 203 removed, record-keeping is turned off.
 204 .PP
 205 Note that on \fIbiarch\fP platforms, i.e. systems which can run both
 206 32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
 207 \fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
 208 The same goes for \fIut_session\fP and \fIut_time\fP if they are present.
 209 This allows data files and shared memory to be shared between
 210 32-bit and 64-bit applications.
 211 Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
 212 then instead of the call:
 213 .RS
 214 .nf
 215 .sp
 216 .ta 3i
 217 gettimeofday((struct timeval *) &ut.ut_tv, NULL);
 218 .fi
 219 .RE
 220
 221 the following method of setting this field is recommended:
 222 .RS
 223 .nf
 224 .sp
 225 .ta 3i
 226 struct utmp ut;
 227 struct timeval tv;
 228
 229 gettimeofday(&tv, NULL);
 230 ut.ut_tv.tv_sec = tv.tv_sec;
 231 ut.ut_tv.tv_usec = tv.tv_usec;
 232 .fi
 233 .RE
 234 .SH FILES
 235 /var/run/utmp
 236 .br
 237 /var/log/wtmp
 238 .SH "CONFORMING TO"
 239 Linux utmp entries conform neither to v7/BSD nor to System V; they are a
 240 mix of the two.  v7/BSD has fewer fields; most importantly it lacks
 241 \fIut_type\fP, which causes native v7/BSD-like programs to display (for
 242 example) dead or login entries.
 243 Further, there is no configuration file
 244 which allocates slots to sessions.
 245 BSD does so because it lacks \fIut_id\fP fields.
 246 In Linux (as in System V), the \fIut_id\fP field of a
 247 record will never change once it has been set, which reserves that slot
 248 without needing a configuration file.
 249 Clearing \fIut_id\fP may result
 250 in race conditions leading to corrupted utmp entries and potential
 251 security holes.
 252 Clearing the above mentioned fields by filling them
 253 with null bytes is not required by System V semantics, but it allows to run
 254 many programs which assume BSD semantics and which do not modify utmp.
 255 Linux uses the BSD conventions for line contents, as documented above.
 256 .PP
 257 System V only uses the type field to mark them and logs informative messages
 258 such as e.g.\& \fB"new time"\fP in the line field. \fBUT_UNKNOWN\fP seems
 259 to be a Linux invention.
 260 System V has no \fIut_host\fP or \fIut_addr_v6\fP fields.
 261 .PP
 262 Unlike various other
 263 systems, where utmp logging can be disabled by removing the file, utmp
 264 must always exist on Linux.
 265 If you want to disable
 266 .BR who (1)
 267 then do not make utmp world readable.
 268 .PP
 269 Note that the utmp struct from libc5 has changed in libc6.
 270 Because of this,
 271 binaries using the old libc5 struct will corrupt
 272 .IR /var/run/utmp " and/or " /var/log/wtmp .
 273 Debian systems include a patched libc5 which uses the new utmp format.
 274 The problem still exists with wtmp since it's accessed directly in
 275 libc5.
 276 .SH NOTES
 277 The file format is machine dependent, so it is recommended that it be
 278 processed only on the machine architecture where it was created.
 279 .PP
 280 Note that on platforms which can run both 32-bit and 64-bit applications
 281 (x86-64, ppc64, s390x, etc.), the sizes of the fields of a struct utmp
 282 must be the same in 32-bit mode as in 64-bit mode.
 283 This is achieved by changing the type of
 284 .I ut_session
 285 to
 286 .IR int32_t ,
 287 and that of
 288 .I ut_tv
 289 to a struct with two
 290 .I int32_t
 291 fields
 292 .I tv_sec
 293 and
 294 .IR tv_usec .
 295 (Thus, in order to fill it, first get the
 296 time into a real \fIstruct timeval\fP,
 297 then copy the two fields to
 298 .IR ut_tv .)
 299 .SH BUGS
 300 This manpage is based on the libc5 one, things may work differently now.
 301 .SH "SEE ALSO"
 302 .BR ac (1),
 303 .BR date (1),
 304 .BR last (1),
 305 .BR login (1),
 306 .BR who (1),
 307 .BR getutent (3),
 308 .BR updwtmp (3),
 309 .BR init (8)