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 .\" $DragonFly: src/share/man/man5/utmp.5,v 1.2 2003/06/17 04:37:00 dillon Exp $
  35 .\"
  36 .Dd November 14, 2001
  37 .Dt UTMP 5
  38 .Os
  39 .Sh NAME
  40 .Nm utmp ,
  41 .Nm wtmp ,
  42 .Nm lastlog
  43 .Nd login records
  44 .Sh SYNOPSIS
  45 .In sys/types.h
  46 .In utmp.h
  47 .Sh DESCRIPTION
  48 The file
  49 .Aq Pa utmp.h
  50 declares the structures used to record information about current
  51 users in the file
  52 .Nm ,
  53 logins and logouts in the file
  54 .Nm wtmp ,
  55 and last logins in the file
  56 .Nm lastlog .
  57 The time stamps of date changes, shutdowns and reboots are also logged in
  58 the
  59 .Nm wtmp
  60 file.
  61 .Bd -literal -offset indent
  62 #define _PATH_UTMP      "/var/run/utmp"
  63 #define _PATH_WTMP      "/var/log/wtmp"
  64 #define _PATH_LASTLOG   "/var/log/lastlog"
  65
  66 #define UT_NAMESIZE     16
  67 #define UT_LINESIZE     8
  68 #define UT_HOSTSIZE     16
  69
  70 struct lastlog {
  71         time_t  ll_time;                /* When user logged in */
  72         char    ll_line[UT_LINESIZE];   /* Terminal line name */
  73         char    ll_host[UT_HOSTSIZE];   /* Host user came from */
  74 };
  75
  76 struct utmp {
  77         char    ut_line[UT_LINESIZE];   /* Terminal line name */
  78         char    ut_name[UT_NAMESIZE];   /* User's login name */
  79         char    ut_host[UT_HOSTSIZE];   /* Host user came from */
  80         time_t  ut_time;                /* When user logged in */
  81 };
  82 .Ed
  83 .Pp
  84 The
  85 .Nm lastlog
  86 file is a linear array of
  87 .Vt lastlog
  88 structures indexed by a user's
  89 .Tn UID .
  90 The
  91 .Nm
  92 file is a linear array of
  93 .Vt utmp
  94 structures indexed by a terminal line number
  95 (see
  96 .Xr ttyslot 3 ) .
  97 The
  98 .Nm wtmp
  99 file consists of
 100 .Vt utmp
 101 structures and is a binary log file,
 102 that is, grows linearly at its end.
 103 .Pp
 104 Each time a user logs in, the
 105 .Xr login 1
 106 program looks up the user's
 107 .Tn UID
 108 in the file
 109 .Nm lastlog .
 110 If it is found, the timestamp of the last time the user logged
 111 in, the terminal line and the hostname
 112 are written to the standard output (unless the login is
 113 .Em quiet ,
 114 see
 115 .Xr login 1 ) .
 116 The
 117 .Xr login 1
 118 program then records the new login time in the file
 119 .Nm lastlog .
 120 .Pp
 121 After the new
 122 .Vt lastlog
 123 record is written,
 124 .\" the
 125 .\" .Xr libutil 3
 126 .\" routine
 127 the file
 128 .Nm
 129 is opened and the
 130 .Vt utmp
 131 record for the user is inserted.
 132 This record remains there until
 133 the user logs out at which time it is deleted.
 134 The
 135 .Nm
 136 file is used by the programs
 137 .Xr rwho 1 ,
 138 .Xr users 1 ,
 139 .Xr w 1 ,
 140 and
 141 .Xr who 1 .
 142 .Pp
 143 Next, the
 144 .Xr login 1
 145 program opens the file
 146 .Nm wtmp ,
 147 and appends the user's
 148 .Vt utmp
 149 record.
 150 The user's subsequent logout from the terminal
 151 line is marked by a special
 152 .Vt utmp
 153 record with
 154 .Va ut_line
 155 set accordingly,
 156 .Va ut_time
 157 updated, but
 158 .Va ut_name
 159 and
 160 .Va ut_host
 161 both empty
 162 (see
 163 .Xr init 8 ) .
 164 The
 165 .Nm wtmp
 166 file is used by the programs
 167 .Xr last 1
 168 and
 169 .Xr ac 8 .
 170 .Pp
 171 In the event of a date change, a shutdown or reboot, the
 172 following items are logged in the
 173 .Nm wtmp
 174 file.
 175 .Pp
 176 .Bl -tag -width ".Li shutdown" -compact
 177 .It Li reboot
 178 .It Li shutdown
 179 A system reboot or shutdown has been initiated.
 180 The character
 181 .Ql \&~
 182 is placed in the field
 183 .Va ut_line ,
 184 and
 185 .Li reboot
 186 or
 187 .Li shutdown
 188 in the field
 189 .Va ut_name
 190 (see
 191 .Xr shutdown 8
 192 and
 193 .Xr reboot 8 ) .
 194 .Pp
 195 .It Li date
 196 The system time has been manually or automatically updated
 197 (see
 198 .Xr date 1 ) .
 199 The command name
 200 .Li date
 201 is recorded in the field
 202 .Va ut_name .
 203 In the field
 204 .Va ut_line ,
 205 the character
 206 .Ql \&|
 207 indicates the time prior to the change, and the character
 208 .Ql \&{
 209 indicates the new time.
 210 .El
 211 .Sh NOTES
 212 The
 213 .Nm wtmp
 214 file can grow rapidly on busy systems, so daily or weekly rotation
 215 is recommended.
 216 It is maintained by
 217 .Xr newsyslog 8 .
 218 .Pp
 219 If any one of these files does not exist, it is not created by
 220 .Xr login 1 .
 221 They must be created manually.
 222 .Pp
 223 The supplied
 224 .Xr login 3 ,
 225 .Xr logout 3 ,
 226 and
 227 .Xr logwtmp 3
 228 utility functions should be used to perform
 229 the standard actions on the
 230 .Nm
 231 and
 232 .Nm wtmp
 233 files in order to maintain the portability across
 234 systems with different formats of those files.
 235 .Sh FILES
 236 .Bl -tag -width ".Pa /var/log/lastlog" -compact
 237 .It Pa /var/run/utmp
 238 The
 239 .Nm
 240 file.
 241 .It Pa /var/log/wtmp
 242 The
 243 .Nm wtmp
 244 file.
 245 .It Pa /var/log/lastlog
 246 The
 247 .Nm lastlog
 248 file.
 249 .El
 250 .Sh SEE ALSO
 251 .Xr last 1 ,
 252 .Xr login 1 ,
 253 .Xr w 1 ,
 254 .Xr who 1 ,
 255 .Xr login 3 ,
 256 .Xr logout 3 ,
 257 .Xr logwtmp 3 ,
 258 .Xr ttyslot 3 ,
 259 .Xr ac 8 ,
 260 .Xr init 8
 261 .Sh HISTORY
 262 A
 263 .Nm
 264 and
 265 .Nm wtmp
 266 file format appeared in
 267 .At v6 .
 268 The
 269 .Nm lastlog
 270 file format appeared in
 271 .Bx 3.0 .