- Uniformly use .In for header file references.
[dragonfly.git] / share / man / man5 / utmp.5
CommitLineData
984263bc
MD
1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)utmp.5 8.2 (Berkeley) 3/17/94
33.\" $FreeBSD: src/share/man/man5/utmp.5,v 1.9.2.8 2001/12/17 11:30:15 ru Exp $
44cb301e 34.\" $DragonFly: src/share/man/man5/utmp.5,v 1.3 2006/05/26 19:39:40 swildner Exp $
984263bc
MD
35.\"
36.Dd November 14, 2001
37.Dt UTMP 5
38.Os
39.Sh NAME
40.Nm utmp ,
41.Nm wtmp ,
42.Nm lastlog
43.Nd login records
44.Sh SYNOPSIS
45.In sys/types.h
46.In utmp.h
47.Sh DESCRIPTION
48The file
44cb301e 49.In utmp.h
984263bc
MD
50declares the structures used to record information about current
51users in the file
52.Nm ,
53logins and logouts in the file
54.Nm wtmp ,
55and last logins in the file
56.Nm lastlog .
57The time stamps of date changes, shutdowns and reboots are also logged in
58the
59.Nm wtmp
60file.
61.Bd -literal -offset indent
62#define _PATH_UTMP "/var/run/utmp"
63#define _PATH_WTMP "/var/log/wtmp"
64#define _PATH_LASTLOG "/var/log/lastlog"
65
66#define UT_NAMESIZE 16
67#define UT_LINESIZE 8
68#define UT_HOSTSIZE 16
69
70struct lastlog {
71 time_t ll_time; /* When user logged in */
72 char ll_line[UT_LINESIZE]; /* Terminal line name */
73 char ll_host[UT_HOSTSIZE]; /* Host user came from */
74};
75
76struct utmp {
77 char ut_line[UT_LINESIZE]; /* Terminal line name */
78 char ut_name[UT_NAMESIZE]; /* User's login name */
79 char ut_host[UT_HOSTSIZE]; /* Host user came from */
80 time_t ut_time; /* When user logged in */
81};
82.Ed
83.Pp
84The
85.Nm lastlog
86file is a linear array of
87.Vt lastlog
88structures indexed by a user's
89.Tn UID .
90The
91.Nm
92file is a linear array of
93.Vt utmp
94structures indexed by a terminal line number
95(see
96.Xr ttyslot 3 ) .
97The
98.Nm wtmp
99file consists of
100.Vt utmp
101structures and is a binary log file,
102that is, grows linearly at its end.
103.Pp
104Each time a user logs in, the
105.Xr login 1
106program looks up the user's
107.Tn UID
108in the file
109.Nm lastlog .
110If it is found, the timestamp of the last time the user logged
111in, the terminal line and the hostname
112are written to the standard output (unless the login is
113.Em quiet ,
114see
115.Xr login 1 ) .
116The
117.Xr login 1
118program then records the new login time in the file
119.Nm lastlog .
120.Pp
121After the new
122.Vt lastlog
123record is written,
124.\" the
125.\" .Xr libutil 3
126.\" routine
127the file
128.Nm
129is opened and the
130.Vt utmp
131record for the user is inserted.
132This record remains there until
133the user logs out at which time it is deleted.
134The
135.Nm
136file is used by the programs
137.Xr rwho 1 ,
138.Xr users 1 ,
139.Xr w 1 ,
140and
141.Xr who 1 .
142.Pp
143Next, the
144.Xr login 1
145program opens the file
146.Nm wtmp ,
147and appends the user's
148.Vt utmp
149record.
150The user's subsequent logout from the terminal
151line is marked by a special
152.Vt utmp
153record with
154.Va ut_line
155set accordingly,
156.Va ut_time
157updated, but
158.Va ut_name
159and
160.Va ut_host
161both empty
162(see
163.Xr init 8 ) .
164The
165.Nm wtmp
166file is used by the programs
167.Xr last 1
168and
169.Xr ac 8 .
170.Pp
171In the event of a date change, a shutdown or reboot, the
172following items are logged in the
173.Nm wtmp
174file.
175.Pp
176.Bl -tag -width ".Li shutdown" -compact
177.It Li reboot
178.It Li shutdown
179A system reboot or shutdown has been initiated.
180The character
181.Ql \&~
182is placed in the field
183.Va ut_line ,
184and
185.Li reboot
186or
187.Li shutdown
188in the field
189.Va ut_name
190(see
191.Xr shutdown 8
192and
193.Xr reboot 8 ) .
194.Pp
195.It Li date
196The system time has been manually or automatically updated
197(see
198.Xr date 1 ) .
199The command name
200.Li date
201is recorded in the field
202.Va ut_name .
203In the field
204.Va ut_line ,
205the character
206.Ql \&|
207indicates the time prior to the change, and the character
208.Ql \&{
209indicates the new time.
210.El
211.Sh NOTES
212The
213.Nm wtmp
214file can grow rapidly on busy systems, so daily or weekly rotation
215is recommended.
216It is maintained by
217.Xr newsyslog 8 .
218.Pp
219If any one of these files does not exist, it is not created by
220.Xr login 1 .
221They must be created manually.
222.Pp
223The supplied
224.Xr login 3 ,
225.Xr logout 3 ,
226and
227.Xr logwtmp 3
228utility functions should be used to perform
229the standard actions on the
230.Nm
231and
232.Nm wtmp
233files in order to maintain the portability across
234systems with different formats of those files.
235.Sh FILES
236.Bl -tag -width ".Pa /var/log/lastlog" -compact
237.It Pa /var/run/utmp
238The
239.Nm
240file.
241.It Pa /var/log/wtmp
242The
243.Nm wtmp
244file.
245.It Pa /var/log/lastlog
246The
247.Nm lastlog
248file.
249.El
250.Sh SEE ALSO
251.Xr last 1 ,
252.Xr login 1 ,
253.Xr w 1 ,
254.Xr who 1 ,
255.Xr login 3 ,
256.Xr logout 3 ,
257.Xr logwtmp 3 ,
258.Xr ttyslot 3 ,
259.Xr ac 8 ,
260.Xr init 8
261.Sh HISTORY
262A
263.Nm
264and
265.Nm wtmp
266file format appeared in
267.At v6 .
268The
269.Nm lastlog
270file format appeared in
271.Bx 3.0 .