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