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