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