share/man/man5/utmp.5

   1 .\"     $NetBSD: utmp.5,v 1.14 2004/02/17 12:32:25 grant Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)utmp.5      8.2 (Berkeley) 3/17/94
  31 .\"
  32 .Dd May 14, 2003
  33 .Dt UTMP 5
  34 .Os
  35 .Sh NAME
  36 .Nm utmp ,
  37 .Nm wtmp ,
  38 .Nm lastlog
  39 .Nd login records
  40 .Sh SYNOPSIS
  41 .In utmp.h
  42 .Sh DESCRIPTION
  43 The file
  44 .Aq Pa utmp.h
  45 declares the structures used to record information about current
  46 users in the file
  47 .Nm utmp ,
  48 logins and logouts in the file
  49 .Nm wtmp ,
  50 and last logins in the file
  51 .Nm lastlog .
  52 The time stamps of date changes, shutdowns and reboots are also logged in
  53 the
  54 .Nm wtmp
  55 file.
  56 .Pp
  57 The
  58 .Nm wtmp
  59 file can grow rapidly on busy systems, and is normally rotated with
  60 .Xr newsyslog 8 .
  61 .Pp
  62 These files must be created manually;
  63 if they do not exist, they are not created automatically.
  64 .Bd -literal -offset indent
  65 #define _PATH_UTMP      "/var/run/utmp"
  66 #define _PATH_WTMP      "/var/log/wtmp"
  67 #define _PATH_LASTLOG   "/var/log/lastlog"
  68
  69 #define UT_NAMESIZE     8
  70 #define UT_LINESIZE     8
  71 #define UT_HOSTSIZE     16
  72
  73 struct lastlog {
  74         time_t  ll_time;
  75         char    ll_line[UT_LINESIZE];
  76         char    ll_host[UT_HOSTSIZE];
  77 };
  78
  79 struct utmp {
  80         char    ut_line[UT_LINESIZE];
  81         char    ut_name[UT_NAMESIZE];
  82         char    ut_host[UT_HOSTSIZE];
  83         time_t  ut_time;
  84 };
  85 .Ed
  86 .Pp
  87 Each time a user logs in, the
  88 .Xr login 1
  89 program looks up the user's
  90 .Tn UID
  91 in the file
  92 .Nm lastlog .
  93 If it is found, the timestamp of the last time the user logged
  94 in, the terminal line and the hostname
  95 are written to the standard output, providing the login is not set
  96 .Em quiet ;
  97 see
  98 .Xr login 1 .
  99 The
 100 .Xr login 1
 101 program then records the new login time in the file
 102 .Nm lastlog .
 103 .Pp
 104 After the new
 105 .Fa lastlog
 106 record is written,
 107 .\" the
 108 .\" .Xr libutil 3
 109 .\" routine
 110 the file
 111 .Nm utmp
 112 is opened and the
 113 .Fa utmp
 114 record for the user inserted.
 115 This record remains there until
 116 the user logs out at which time it is deleted (by clearing
 117 the user and host fields, and updating the timestamp field).
 118 The
 119 .Nm utmp
 120 file is used by the programs
 121 .Xr rwho 1 ,
 122 .Xr users 1 ,
 123 .Xr w 1 ,
 124 and
 125 .Xr who 1 .
 126 .Pp
 127 Next, the
 128 .Xr login 1
 129 program opens the file
 130 .Nm wtmp ,
 131 and appends the user's
 132 .Fa utmp
 133 record.
 134 When the user logs out, a
 135 .Fa utmp
 136 record with the tty line, an updated time stamp, and cleared user and host
 137 fields is appended to the file by
 138 .Xr init 8 .
 139 The
 140 .Nm wtmp
 141 file is used by the programs
 142 .Xr last 1
 143 and
 144 .Xr ac 8 .
 145 .Pp
 146 In the event of a date change, a shutdown or reboot, the
 147 following items are logged in the
 148 .Nm wtmp
 149 file.
 150 .Pp
 151 .Bl -tag -width shutdownxx -compact
 152 .It Li reboot
 153 .It Li shutdown
 154 A system reboot or shutdown has been initiated.
 155 The character
 156 .Ql \&~
 157 is placed in the field
 158 .Fa ut_line ,
 159 and
 160 .Li reboot
 161 or
 162 .Li shutdown
 163 in the field
 164 .Fa ut_name
 165 (see
 166 .Xr shutdown 8
 167 and
 168 .Xr reboot 8 ) .
 169 .Pp
 170 .It Li date
 171 The system time has been manually or automatically updated by
 172 .Xr date 1 .
 173 The command name
 174 .Em date
 175 is recorded in the field
 176 .Fa ut_name .
 177 In the field
 178 .Fa ut_line ,
 179 the character
 180 .Ql \\*(Ba
 181 indicates the time prior to the change, and the character
 182 .Ql \&{
 183 indicates the new time.
 184 .El
 185 .Sh FILES
 186 .Bl -tag -width /var/log/lastlog -compact
 187 .It Pa /var/run/utmp
 188 The
 189 .Nm utmp
 190 file.
 191 .It Pa /var/log/wtmp
 192 The
 193 .Nm wtmp
 194 file.
 195 .It Pa /var/log/lastlog
 196 The
 197 .Nm lastlog
 198 file.
 199 .El
 200 .Sh SEE ALSO
 201 .Xr last 1 ,
 202 .Xr login 1 ,
 203 .Xr w 1 ,
 204 .Xr who 1 ,
 205 .Xr utmpx 5 ,
 206 .Xr ac 8 ,
 207 .Xr init 8 ,
 208 .Xr lastlogin 8 ,
 209 .Xr newsyslog 8
 210 .Sh HISTORY
 211 A
 212 .Nm utmp
 213 and
 214 .Nm wtmp
 215 file format appeared in
 216 .At v6 .
 217 The
 218 .Nm lastlog
 219 file format appeared in
 220 .Bx 3.0 .