1.\" $OpenBSD: utmp.5,v 1.23 2014/01/21 03:15:46 schwarze 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: January 21 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 rwho 1 , 121.Xr users 1 , 122.Xr w 1 , 123and 124.Xr who 1 . 125.Pp 126Next, the 127.Xr login 1 128program opens the 129.Nm wtmp 130file and appends the user's 131.Fa utmp 132record. 133When the user logs out, a 134.Fa utmp 135record with the tty line, an updated timestamp, and zeroed name and host 136fields is appended to the file (see 137.Xr init 8 ) . 138The 139.Nm wtmp 140file is used by the programs 141.Xr last 1 142and 143.Xr ac 8 . 144.Pp 145In the event of a date change, shutdown, or reboot, the 146following items are logged in the 147.Nm wtmp 148file: 149.Pp 150.Bl -tag -width shutdownxx -compact 151.It Li reboot 152.It Li shutdown 153A system reboot or shutdown has been initiated. 154A tilde 155.Pq Sq \&~ 156character is placed in the field 157.Fa ut_line , 158and 159.Dq reboot 160or 161.Dq shutdown 162in the field 163.Fa ut_name 164(see 165.Xr shutdown 8 166and 167.Xr reboot 8 ) . 168.Pp 169.It Li date 170The system time has been manually or automatically updated (see 171.Xr date 1 ) . 172The command name 173.Xr date 1 174is recorded in the field 175.Fa ut_name . 176In the field 177.Fa ut_line , 178the 179.Dq \&| 180character indicates the time prior to the change and the 181.Dq \&{ 182character indicates the new time. 183.El 184.Sh FILES 185.Bl -tag -width /var/log/lastlog -compact 186.It Pa /var/run/utmp 187.It Pa /var/log/wtmp 188.It Pa /var/log/lastlog 189.El 190.Sh SEE ALSO 191.Xr last 1 , 192.Xr login 1 , 193.Xr who 1 , 194.Xr ac 8 , 195.Xr init 8 , 196.Xr newsyslog 8 197.Sh HISTORY 198A 199.Nm utmp 200and 201.Nm wtmp 202file format appeared in 203.At v3 . 204The 205.Nm lastlog 206file format appeared in 207.Bx 3.0 . 208.Sh CAVEATS 209The strings in the 210.Fa utmp 211and 212.Fa lastlog 213structures are 214.Em not 215normal 216.Sq C 217strings and are thus not guaranteed to be null terminated. 218