1UTMP(5)                    Linux Programmer's Manual                   UTMP(5)
2
3
4

NAME

6       utmp, wtmp - login records
7

SYNOPSIS

9       #include <utmp.h>
10

DESCRIPTION

12       The utmp file allows one to discover information about who is currently
13       using the system.  There may be more users currently using the  system,
14       because not all programs use utmp logging.
15
16       Warning: utmp must not be writable, because many system programs (fool‐
17       ishly) depend on its integrity.  You risk  faked  system  logfiles  and
18       modifications of system files if you leave utmp writable to any user.
19
20       The file is a sequence of entries with the following structure declared
21       in the include file (note that this is only one of several  definitions
22       around; details depend on the version of libc):
23
24          #define UT_UNKNOWN      0
25          #define RUN_LVL         1
26          #define BOOT_TIME       2
27          #define NEW_TIME        3
28          #define OLD_TIME        4
29          #define INIT_PROCESS    5
30          #define LOGIN_PROCESS   6
31          #define USER_PROCESS    7
32          #define DEAD_PROCESS    8
33          #define ACCOUNTING      9
34
35          #define UT_LINESIZE     12
36          #define UT_NAMESIZE     32
37          #define UT_HOSTSIZE     256
38
39          struct exit_status {
40            short int e_termination;    /* process termination status */
41            short int e_exit;           /* process exit status */
42          };
43
44          struct utmp {
45            short ut_type;              /* type of login */
46            pid_t ut_pid;               /* PID of login process */
47            char ut_line[UT_LINESIZE];  /* device name of tty - "/dev/" */
48            char ut_id[4];              /* init id or abbrev. ttyname */
49            char ut_user[UT_NAMESIZE];  /* user name */
50            char ut_host[UT_HOSTSIZE];  /* hostname for remote login */
51            struct exit_status ut_exit; /* The exit status of a process
52                                           marked as DEAD_PROCESS */
53
54            /* The ut_session and ut_tv fields must be the same size when
55               compiled 32- and 64-bit.  This allows data files and shared
56               memory to be shared between 32- and 64-bit applications */
57          #if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32
58            int32_t ut_session;         /* Session ID, used for windowing */
59            struct {
60              int32_t tv_sec;           /* Seconds */
61              int32_t tv_usec;          /* Microseconds */
62            } ut_tv;                    /* Time entry was made */
63          #else
64             long int ut_session;        /* Session ID, used for windowing */
65             struct timeval ut_tv;       /* Time entry was made */
66          #endif
67
68            int32_t ut_addr_v6[4];       /* IP address of remote host */
69            char __unused[20];           /* Reserved for future use */
70          };
71
72          /* Backwards compatibility hacks.  */
73          #define ut_name ut_user
74          #ifndef _NO_UT_TIME
75          #define ut_time ut_tv.tv_sec
76          #endif
77          #define ut_xtime ut_tv.tv_sec
78          #define ut_addr ut_addr_v6[0]
79
80       This  structure  gives the name of the special file associated with the
81       user's terminal, the user's login name, and the time of  login  in  the
82       form  of  time(2).   String  fields  are terminated by '\0' if they are
83       shorter than the size of the field.
84
85       The first entries ever created result  from  init(8)  processing  init‐
86       tab(5).   Before  an entry is processed, though, init(8) cleans up utmp
87       by setting ut_type to  DEAD_PROCESS,  clearing  ut_user,  ut_host,  and
88       ut_time   with  null  bytes  for  each  record  which  ut_type  is  not
89       DEAD_PROCESS or RUN_LVL and where no process with  PID  ut_pid  exists.
90       If  no  empty record with the needed ut_id can be found, init creates a
91       new one.  It sets ut_id from the inittab, ut_pid  and  ut_time  to  the
92       current values, and ut_type to INIT_PROCESS.
93
94       getty(8)   locates   the   entry   by   the  PID,  changes  ut_type  to
95       LOGIN_PROCESS, changes ut_time, sets ut_line, and waits for  connection
96       to  be  established.   login(8),  after  a user has been authenticated,
97       changes ut_type to USER_PROCESS, changes ut_time, and sets ut_host  and
98       ut_addr.  Depending on getty(8) and login(8), records may be located by
99       ut_line instead of the preferable ut_pid.
100
101       When init(8) finds that a process has exited, it locates its utmp entry
102       by  ut_pid,  sets  ut_type to DEAD_PROCESS, and clears ut_user, ut_host
103       and ut_time with null bytes.
104
105       xterm(1) and other terminal emulators directly  create  a  USER_PROCESS
106       record  and  generate  the  ut_id  by  using  the  last  two letters of
107       /dev/ttyp%c  or  by  using  p%d  for  /dev/pts/%d.   If  they  find   a
108       DEAD_PROCESS  for this ID, they recycle it, otherwise they create a new
109       entry.  If they can, they will mark it as DEAD_PROCESS on  exiting  and
110       it  is advised that they null ut_line, ut_time, ut_user, and ut_host as
111       well.
112
113       xdm(8) should not create a utmp record, because there  is  no  assigned
114       terminal.   Letting  it create one will result in errors, such as 'fin‐
115       ger: cannot stat /dev/machine.dom'.  It  should  create  wtmp  entries,
116       though, just like ftpd(8) does.
117
118       telnetd(8)  sets  up  a  LOGIN_PROCESS  entry  and  leaves  the rest to
119       login(8) as usual.  After the telnet session ends, telnetd(8) cleans up
120       utmp in the described way.
121
122       The  wtmp  file  records all logins and logouts.  Its format is exactly
123       like utmp except that a null user name indicates a logout on the  asso‐
124       ciated terminal.  Furthermore, the terminal name ~ with user name shut‐
125       down or reboot indicates a system shutdown or reboot and  the  pair  of
126       terminal  names  |/}  logs the old/new system time when date(1) changes
127       it.  wtmp is maintained by login(1),  init(1),  and  some  versions  of
128       getty(8).   Neither  of  these  programs  creates the file, so if it is
129       removed, record-keeping is turned off.
130
131       Note that on biarch platforms, i.e. systems which can run  both  32-bit
132       and 64-bit applications (x86-64, ppc64, s390x, etc.), ut_tv is the same
133       size in 32-bit mode as in 64-bit mode.  The same  goes  for  ut_session
134       and  ut_time  if  they  are present.  This allows data files and shared
135       memory to be shared between  32-bit  and  64-bit  applications.   Since
136       ut_tv may not be the same as struct timeval, then instead of the call:
137
138              gettimeofday((struct timeval *) &ut.ut_tv, NULL);
139
140
141       the following method of setting this field is recommended:
142
143              struct utmp ut;
144              struct timeval tv;
145
146              gettimeofday(&tv, NULL);
147              ut.ut_tv.tv_sec = tv.tv_sec;
148              ut.ut_tv.tv_usec = tv.tv_usec;
149
150

FILES

152       /var/run/utmp
153       /var/log/wtmp
154

CONFORMING TO

156       Linux  utmp entries conform neither to v7/BSD nor to System V; they are
157       a mix of the two.  v7/BSD has fewer fields; most importantly  it  lacks
158       ut_type, which causes native v7/BSD-like programs to display (for exam‐
159       ple) dead or login entries.  Further, there is  no  configuration  file
160       which  allocates slots to sessions.  BSD does so because it lacks ut_id
161       fields.  In Linux (as in System V), the ut_id field of  a  record  will
162       never  change  once  it  has been set, which reserves that slot without
163       needing a configuration file.  Clearing ut_id may result in race condi‐
164       tions  leading  to corrupted utmp entries and potential security holes.
165       Clearing the above mentioned fields by filling them with null bytes  is
166       not  required by System V semantics, but it allows to run many programs
167       which assume BSD semantics and which do not modify  utmp.   Linux  uses
168       the BSD conventions for line contents, as documented above.
169
170       System  V  only  uses  the type field to mark them and logs informative
171       messages such as e.g. "new time" in the line field. UT_UNKNOWN seems to
172       be a Linux invention.  System V has no ut_host or ut_addr_v6 fields.
173
174       Unlike  various  other  systems,  where utmp logging can be disabled by
175       removing the file, utmp must always exist on Linux.   If  you  want  to
176       disable who(1) then do not make utmp world readable.
177
178       Note  that  the utmp struct from libc5 has changed in libc6. Because of
179       this, binaries using the old libc5 struct  will  corrupt  /var/run/utmp
180       and/or  /var/log/wtmp.   Debian  systems  include a patched libc5 which
181       uses the new utmp format.  The problem still  exists  with  wtmp  since
182       it's accessed directly in libc5.
183

RESTRICTIONS

185       The  file  format is machine dependent, so it is recommended that it be
186       processed only on the machine architecture where it was created.
187
188       Note that on platforms which can run both 32-bit  and  64-bit  applica‐
189       tions (x86-64, ppc64, s390x, etc.), the sizes of the fields of a struct
190       utmp must be the same in 32-bit  mode  as  in  64-bit  mode.   This  is
191       achieved  by  changing  the  type of ut_session to int32_t, and that of
192       ut_tv to a struct with two int32_t fields tv_sec and  tv_usec.   (Thus,
193       in  order  to  fill  it, first get the time into a real struct timeval,
194       then copy the two fields to ut_tv.)
195

BUGS

197       This manpage is based on the libc5 one,  things  may  work  differently
198       now.
199

SEE ALSO

201       ac(1),  date(1),  last(1),  login(1),  who(1), getutent(3), updwtmp(3),
202       init(8)
203
204
205
206File formats                      2004-10-31                           UTMP(5)
Impressum