share/man/man5/utmp.5

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)utmp.5      8.2 (Berkeley) 3/17/94
  29 .\" $FreeBSD: src/share/man/man5/utmp.5,v 1.9.2.8 2001/12/17 11:30:15 ru Exp $
  30 .\" $DragonFly: src/share/man/man5/utmp.5,v 1.3 2006/05/26 19:39:40 swildner Exp $
  31 .\"
  32 .Dd November 14, 2001
  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 sys/types.h
  42 .In utmp.h
  43 .Sh DESCRIPTION
  44 The file
  45 .In utmp.h
  46 declares the structures used to record information about current
  47 users in the file
  48 .Nm ,
  49 logins and logouts in the file
  50 .Nm wtmp ,
  51 and last logins in the file
  52 .Nm lastlog .
  53 The time stamps of date changes, shutdowns and reboots are also logged in
  54 the
  55 .Nm wtmp
  56 file.
  57 .Bd -literal -offset indent
  58 #define _PATH_UTMP      "/var/run/utmp"
  59 #define _PATH_WTMP      "/var/log/wtmp"
  60 #define _PATH_LASTLOG   "/var/log/lastlog"
  61
  62 #define UT_NAMESIZE     16
  63 #define UT_LINESIZE     8
  64 #define UT_HOSTSIZE     16
  65
  66 struct lastlog {
  67         time_t  ll_time;                /* When user logged in */
  68         char    ll_line[UT_LINESIZE];   /* Terminal line name */
  69         char    ll_host[UT_HOSTSIZE];   /* Host user came from */
  70 };
  71
  72 struct utmp {
  73         char    ut_line[UT_LINESIZE];   /* Terminal line name */
  74         char    ut_name[UT_NAMESIZE];   /* User's login name */
  75         char    ut_host[UT_HOSTSIZE];   /* Host user came from */
  76         time_t  ut_time;                /* When user logged in */
  77 };
  78 .Ed
  79 .Pp
  80 The
  81 .Nm lastlog
  82 file is a linear array of
  83 .Vt lastlog
  84 structures indexed by a user's
  85 .Tn UID .
  86 The
  87 .Nm
  88 file is a linear array of
  89 .Vt utmp
  90 structures indexed by a terminal line number
  91 (see
  92 .Xr ttyslot 3 ) .
  93 The
  94 .Nm wtmp
  95 file consists of
  96 .Vt utmp
  97 structures and is a binary log file,
  98 that is, grows linearly at its end.
  99 .Pp
 100 Each time a user logs in, the
 101 .Xr login 1
 102 program looks up the user's
 103 .Tn UID
 104 in the file
 105 .Nm lastlog .
 106 If it is found, the timestamp of the last time the user logged
 107 in, the terminal line and the hostname
 108 are written to the standard output (unless the login is
 109 .Em quiet ,
 110 see
 111 .Xr login 1 ) .
 112 The
 113 .Xr login 1
 114 program then records the new login time in the file
 115 .Nm lastlog .
 116 .Pp
 117 After the new
 118 .Vt lastlog
 119 record is written,
 120 .\" the
 121 .\" .Xr libutil 3
 122 .\" routine
 123 the file
 124 .Nm
 125 is opened and the
 126 .Vt utmp
 127 record for the user is inserted.
 128 This record remains there until
 129 the user logs out at which time it is deleted.
 130 The
 131 .Nm
 132 file is used by the programs
 133 .Xr rwho 1 ,
 134 .Xr users 1 ,
 135 .Xr w 1 ,
 136 and
 137 .Xr who 1 .
 138 .Pp
 139 Next, the
 140 .Xr login 1
 141 program opens the file
 142 .Nm wtmp ,
 143 and appends the user's
 144 .Vt utmp
 145 record.
 146 The user's subsequent logout from the terminal
 147 line is marked by a special
 148 .Vt utmp
 149 record with
 150 .Va ut_line
 151 set accordingly,
 152 .Va ut_time
 153 updated, but
 154 .Va ut_name
 155 and
 156 .Va ut_host
 157 both empty
 158 (see
 159 .Xr init 8 ) .
 160 The
 161 .Nm wtmp
 162 file is used by the programs
 163 .Xr last 1
 164 and
 165 .Xr ac 8 .
 166 .Pp
 167 In the event of a date change, a shutdown or reboot, the
 168 following items are logged in the
 169 .Nm wtmp
 170 file.
 171 .Pp
 172 .Bl -tag -width ".Li shutdown" -compact
 173 .It Li reboot
 174 .It Li shutdown
 175 A system reboot or shutdown has been initiated.
 176 The character
 177 .Ql \&~
 178 is placed in the field
 179 .Va ut_line ,
 180 and
 181 .Li reboot
 182 or
 183 .Li shutdown
 184 in the field
 185 .Va ut_name
 186 (see
 187 .Xr shutdown 8
 188 and
 189 .Xr reboot 8 ) .
 190 .Pp
 191 .It Li date
 192 The system time has been manually or automatically updated
 193 (see
 194 .Xr date 1 ) .
 195 The command name
 196 .Li date
 197 is recorded in the field
 198 .Va ut_name .
 199 In the field
 200 .Va ut_line ,
 201 the character
 202 .Ql \&|
 203 indicates the time prior to the change, and the character
 204 .Ql \&{
 205 indicates the new time.
 206 .El
 207 .Sh NOTES
 208 The
 209 .Nm wtmp
 210 file can grow rapidly on busy systems, so daily or weekly rotation
 211 is recommended.
 212 It is maintained by
 213 .Xr newsyslog 8 .
 214 .Pp
 215 If any one of these files does not exist, it is not created by
 216 .Xr login 1 .
 217 They must be created manually.
 218 .Pp
 219 The supplied
 220 .Xr login 3 ,
 221 .Xr logout 3 ,
 222 and
 223 .Xr logwtmp 3
 224 utility functions should be used to perform
 225 the standard actions on the
 226 .Nm
 227 and
 228 .Nm wtmp
 229 files in order to maintain the portability across
 230 systems with different formats of those files.
 231 .Sh FILES
 232 .Bl -tag -width ".Pa /var/log/lastlog" -compact
 233 .It Pa /var/run/utmp
 234 The
 235 .Nm
 236 file.
 237 .It Pa /var/log/wtmp
 238 The
 239 .Nm wtmp
 240 file.
 241 .It Pa /var/log/lastlog
 242 The
 243 .Nm lastlog
 244 file.
 245 .El
 246 .Sh SEE ALSO
 247 .Xr last 1 ,
 248 .Xr login 1 ,
 249 .Xr w 1 ,
 250 .Xr who 1 ,
 251 .Xr login 3 ,
 252 .Xr logout 3 ,
 253 .Xr logwtmp 3 ,
 254 .Xr ttyslot 3 ,
 255 .Xr ac 8 ,
 256 .Xr init 8
 257 .Sh HISTORY
 258 A
 259 .Nm
 260 and
 261 .Nm wtmp
 262 file format appeared in
 263 .At v6 .
 264 The
 265 .Nm lastlog
 266 file format appeared in
 267 .Bx 3.0 .