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