1.\" $NetBSD: utmp.5,v 1.16 2010/03/22 18:58:32 joerg 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 43The file 44.In utmp.h 45declares the structures used to record information about current 46users in the file 47.Nm utmp , 48logins and logouts in the file 49.Nm wtmp , 50and last logins in the file 51.Nm lastlog . 52The time stamps of date changes, shutdowns and reboots are also logged in 53the 54.Nm wtmp 55file. 56.Pp 57The 58.Nm wtmp 59file can grow rapidly on busy systems, and is normally rotated with 60.Xr newsyslog 8 . 61.Pp 62These files must be created manually; 63if 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 73struct lastlog { 74 time_t ll_time; 75 char ll_line[UT_LINESIZE]; 76 char ll_host[UT_HOSTSIZE]; 77}; 78 79struct 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 87Each time a user logs in, the 88.Xr login 1 89program looks up the user's 90.Tn UID 91in the file 92.Nm lastlog . 93If it is found, the timestamp of the last time the user logged 94in, the terminal line and the hostname 95are written to the standard output, providing the login is not set 96.Em quiet ; 97see 98.Xr login 1 . 99The 100.Xr login 1 101program then records the new login time in the file 102.Nm lastlog . 103.Pp 104After the new 105.Fa lastlog 106record is written, 107.\" the 108.\" .Xr libutil 3 109.\" routine 110the file 111.Nm utmp 112is opened and the 113.Fa utmp 114record for the user inserted. 115This record remains there until 116the user logs out at which time it is deleted (by clearing 117the user and host fields, and updating the timestamp field). 118The 119.Nm utmp 120file is used by the programs 121.Xr rwho 1 , 122.Xr users 1 , 123.Xr w 1 , 124and 125.Xr who 1 . 126.Pp 127Next, the 128.Xr login 1 129program opens the file 130.Nm wtmp , 131and appends the user's 132.Fa utmp 133record. 134When the user logs out, a 135.Fa utmp 136record with the tty line, an updated time stamp, and cleared user and host 137fields is appended to the file by 138.Xr init 8 . 139The 140.Nm wtmp 141file is used by the programs 142.Xr last 1 143and 144.Xr ac 8 . 145.Pp 146In the event of a date change, a shutdown or reboot, the 147following items are logged in the 148.Nm wtmp 149file. 150.Pp 151.Bl -tag -width shutdownxx -compact 152.It Li reboot 153.It Li shutdown 154A system reboot or shutdown has been initiated. 155The character 156.Ql \&~ 157is placed in the field 158.Fa ut_line , 159and 160.Li reboot 161or 162.Li shutdown 163in the field 164.Fa ut_name 165(see 166.Xr shutdown 8 167and 168.Xr reboot 8 ) . 169.Pp 170.It Li date 171The system time has been manually or automatically updated by 172.Xr date 1 . 173The command name 174.Em date 175is recorded in the field 176.Fa ut_name . 177In the field 178.Fa ut_line , 179the character 180.Ql \\*(Ba 181indicates the time prior to the change, and the character 182.Ql \&{ 183indicates the new time. 184.El 185.Sh FILES 186.Bl -tag -width /var/log/lastlog -compact 187.It Pa /var/run/utmp 188The 189.Nm utmp 190file. 191.It Pa /var/log/wtmp 192The 193.Nm wtmp 194file. 195.It Pa /var/log/lastlog 196The 197.Nm lastlog 198file. 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 211A 212.Nm utmp 213and 214.Nm wtmp 215file format appeared in 216.At v6 . 217The 218.Nm lastlog 219file format appeared in 220.Bx 3.0 . 221