UTMP(5)                    File formats                   UTMP(5)

NAME
       utmp, wtmp - login records

SYNOPSIS
       #include <utmp.h>

DESCRIPTION
       The utmp file allows one to discover information about who
       is currently using the system.  There may  be  more  users
       currently  using  the system, because not all programs use
       utmp logging.

       Warning: utmp must not be writable,  because  many  system
       programs  (foolishly)  depend  on its integrity.  You risk
       faked system logfiles and modifications of system files if
       you leave utmp writable to any user.

       The  file  is  a  sequence  of  entries with the following
       structure declared in the include file (note that this  is
       only  one of several definitions around; details depend on
       the version of libc):

              #define UT_UNKNOWN            0
              #define RUN_LVL               1
              #define BOOT_TIME             2
              #define NEW_TIME              3
              #define OLD_TIME              4
              #define INIT_PROCESS          5
              #define LOGIN_PROCESS         6
              #define USER_PROCESS          7
              #define DEAD_PROCESS          8
              #define ACCOUNTING            9

              #define UT_LINESIZE           12
              #define UT_NAMESIZE           32
              #define UT_HOSTSIZE           256

              struct exit_status {
                short int e_termination;    /* process termination status.  */
                short int e_exit;           /* process exit status.  */
              };

              struct utmp {
                short ut_type;              /* type of login */
                pid_t ut_pid;               /* pid of login process */
                char ut_line[UT_LINESIZE];  /* device name of tty - "/dev/" */
                char ut_id[4];              /* init id or abbrev. ttyname */
                char ut_user[UT_NAMESIZE];  /* user name */
                char ut_host[UT_HOSTSIZE];  /* hostname for remote login */
                struct exit_status ut_exit; /* The exit status of a process
                                               marked as DEAD_PROCESS. */
                long ut_session;            /* session ID, used for windowing*/
                struct timeval ut_tv;       /* time entry was made.  */
                int32_t ut_addr_v6[4];      /* IP address of remote host.  */
                char pad[20];               /* Reserved for future use.  */
              };

              /* Backwards compatibility hacks.  */
              #define ut_name ut_user
              #ifndef _NO_UT_TIME
              #define ut_time ut_tv.tv_sec
              #endif
              #define ut_xtime ut_tv.tv_sec
              #define ut_addr ut_addr_v6[0]

       This structure gives the name of the special file  associ-
       ated  with the user's terminal, the user's login name, and
       the time of login in the form of time(2).   String  fields
       are  terminated  by '\0' if they are shorter than the size
       of the field.

       The first entries ever created result  from  init(8)  pro-
       cessing inittab(5).  Before an entry is processed, though,
       init(8) cleans up utmp by setting ut_type to DEAD_PROCESS,
       clearing  ut_user, ut_host and ut_time with null bytes for
       each record which ut_type is not DEAD_PROCESS  or  RUN_LVL
       and  where no process with PID ut_pid exists.  If no empty
       record with the needed ut_id can be found, init creates  a
       new  one.   It  sets  ut_id  from  the inittab, ut_pid and
       ut_time to the current values and ut_type to INIT_PROCESS.

       getty(8)  locates the entry by the pid, changes ut_type to
       LOGIN_PROCESS, changes ut_time, sets ut_line and waits for
       connection  to be established.  login(8), after a user has
       been  authenticated,  changes  ut_type  to   USER_PROCESS,
       changes  ut_time  and sets ut_host and ut_addr.  Depending
       on getty(8)  and  login(8),  records  may  be  located  by
       ut_line instead of the preferable ut_pid.

       When  init(8)  finds that a process has exited, it locates
       its utmp entry by ut_pid, sets ut_type to DEAD_PROCESS and
       clears ut_user, ut_host and ut_time with null bytes.

       xterm(1)  and  other  terminal emulators directly create a
       USER_PROCESS record and generate the ut_id  by  using  the
       last  two  letters  of  /dev/ttyp%c  or  by  using p%d for
       /dev/pts/%d.  If they find a  DEAD_PROCESS  for  this  id,
       they  recycle  it,  otherwise they create a new entry.  If
       they can, they will mark it as DEAD_PROCESS on exiting and
       it is advised that they null ut_line, ut_time, ut_user and
       ut_host as well.

       xdm(8) should not create an utmp record, because there  is
       no  assigned  terminal.  Letting it create one will result
       in trouble like: finger: can  not  stat  /dev/machine.dom.
       It  should  create wtmp entries, though, just like ftpd(8)
       does.

       telnetd(8) sets up a LOGIN_PROCESS entry  and  leaves  the
       rest to login(8) as usual.  After the telnet session ends,
       telnetd(8) cleans up utmp in the described way.

       The wtmp file records all logins and logouts.  Its  format
       is  exactly  like  utmp except that a null user name indi-
       cates a logout on the associated  terminal.   Furthermore,
       the  terminal  name  "~"  with  user  name  "shutdown"  or
       "reboot" indicates a system shutdown  or  reboot  and  the
       pair  of  terminal  names  "|"/"}" logs the old/new system
       time when date(1)  changes  it.   wtmp  is  maintained  by
       login(1), and init(1) and some versions of getty(1).  Nei-
       ther of these programs creates  the  file,  so  if  it  is
       removed record-keeping is turned off.

FILES
       /var/run/utmp
       /var/log/wtmp

CONFORMING TO
       Linux  utmp entries conform neither to v7/BSD nor to SYSV:
       They are a mix of the two.  v7/BSD has fewer fields;  most
       importantly  it lacks ut_type, which causes native v7/BSD-
       like programs to  display  (for  example)  dead  or  login
       entries.   Further  there  is  no configuration file which
       allocates slots to sessions.   BSD  does  so,  because  it
       lacks  ut_id  fields.   In  Linux  (as in SYSV), the ut_id
       field of a record will never change once it has been  set,
       which  reserves  that slot without needing a configuration
       file.  Clearing ut_id may result in race conditions  lead-
       ing  to  corrupted utmp entries and and potential security
       holes.  Clearing the above  mentioned  fields  by  filling
       them  with  null  bytes is not required by SYSV semantics,
       but it allows to run many programs which assume BSD seman-
       tics  and  which  do  not modify utmp.  Linux uses the BSD
       conventions for line contents, as documented above.

       SYSV only uses the type field to mark them and logs infor-
       mative messages such as e.g. "new time" in the line field.
       UT_UNKNOWN seems to be a Linux  invention.   SYSV  has  no
       ut_host or ut_addr_v6 fields.

       Unlike  various  other  systems, where utmp logging can be
       disabled by removing the file, utmp must always  exist  on
       Linux.   If  you  want  to disable who(1) then do not make
       utmp world readable.

       Note that the utmp struct from libc5 has changed in libc6.
       Because  of this, binaries using the old libc5 struct will
       corrupt /var/run/utmp and/or /var/log/wtmp.   Debian  sys-
       tems  include a patched libc5 which uses the new utmp for-
       mat.  The  problem  still  exists  with  wtmp  since  it's
       accessed directly in libc5.

RESTRICTIONS
       The file format is machine dependent, so it is recommended
       that it be processed  only  on  the  machine  architecture
       where it got created.

BUGS
       This  manpage  is  based on the libc5 one, things may work
       differently now.

SEE ALSO
       ac(1), date(1), getutent(3), init(8),  last(1),  login(1),
       updwtmp(3), who(1)

                           July 2, 1997                         1