Date: Thu, 11 Oct 2001 17:02:26 +0400 From: Yar Tikhiy <yar@freebsd.org> To: hackers@freebsd.org, doc@freebsd.org Subject: utmp(5) manpage revised Message-ID: <20011011170226.A2162@snark.rinet.ru>
next in thread | raw e-mail | index | archive | help
Hi everybody,
The current utmp(5) manpage language (not markup)
has a number of drawbacks and errors:
o There is no information for programmers on the actual structure
of the files the page describes.
o The C structure members aren't described.
o Despites the page language, neither utmp nor lastlog grow
continually or need rotation.
o It describes in a wrong way how a user's logout is recorded to wtmp.
o The login(3), logout(3) and logwtmp(3) functions aren't mentioned.
Here's a patch addressing all the issues. Review it please.
--
Yar
Index: utmp.5
===================================================================
RCS file: /home/ncvs/src/share/man/man5/utmp.5,v
retrieving revision 1.16
diff -u -r1.16 utmp.5
--- utmp.5 2001/10/11 11:29:37 1.16
+++ utmp.5 2001/10/11 12:59:35
@@ -57,12 +57,6 @@
the
.Nm wtmp
file.
-.Pp
-These files can grow rapidly on busy systems, so daily or weekly rotation
-is recommended.
-If any one of these files does not exist, it is not created.
-They must be created manually and are maintained by
-.Xr newsyslog 8 .
.Bd -literal -offset indent
#define _PATH_UTMP "/var/run/utmp"
#define _PATH_WTMP "/var/log/wtmp"
@@ -73,19 +67,39 @@
#define UT_HOSTSIZE 16
struct lastlog {
- time_t ll_time;
- char ll_line[UT_LINESIZE];
- char ll_host[UT_HOSTSIZE];
+ time_t ll_time; /* When user logged in */
+ char ll_line[UT_LINESIZE]; /* Terminal line name */
+ char ll_host[UT_HOSTSIZE]; /* Host user came from */
};
struct utmp {
- char ut_line[UT_LINESIZE];
- char ut_name[UT_NAMESIZE];
- char ut_host[UT_HOSTSIZE];
- time_t ut_time;
+ char ut_line[UT_LINESIZE]; /* Terminal line name */
+ char ut_name[UT_NAMESIZE]; /* User's login name */
+ char ut_host[UT_HOSTSIZE]; /* Host user came from */
+ time_t ut_time; /* When user logged in */
};
.Ed
.Pp
+The
+.Nm lastlog
+file is a linear array of
+.Fa lastlog
+structures indexed by a user's
+.Tn UID .
+The
+.Nm utmp
+file is a linear array of
+.Fa utmp
+structures indexed by a terminal line number
+(see
+.Xr ttyslot 3 ) .
+The
+.Nm wtmp
+file consists of
+.Fa utmp
+structures and is a binary log file,
+that is, grows linearly at its end.
+.Pp
Each time a user logs in, the
.Xr login 1
program looks up the user's
@@ -132,10 +146,19 @@
and appends the user's
.Fa utmp
record.
-The same
+The user's subsequent logout from the terminal
+line is marked by a special
.Fa utmp
-record, with an updated time stamp is later appended
-to the file when the user logs out (see
+record with
+.Fa ut_line
+set accordingly,
+.Fa ut_time
+updated, but
+.Fa ut_name
+and
+.Fa ut_host
+both empty
+(see
.Xr init 8 ) .
The
.Nm wtmp
@@ -184,6 +207,29 @@
.Ql \&{
indicates the new time.
.El
+.Sh NOTES
+The
+.Nm wtmp
+file can grow rapidly on busy systems, so daily or weekly rotation
+is recommended.
+It is maintained by
+.Xr newsyslog 8 .
+.Pp
+If any one of these files does not exist, it is not created by
+.Xr login 1 .
+They must be created manually.
+.Pp
+The supplied
+.Xr login 3 ,
+.Xr logout 3 ,
+and
+.Xr logwtmp 3
+utility functions should be used to perform
+the standard actions on the
+.Nm utmp
+and
+.Nm wtmp
+files.
.Sh FILES
.Bl -tag -width /var/log/lastlog -compact
.It Pa /var/run/utmp
@@ -204,6 +250,10 @@
.Xr login 1 ,
.Xr w 1 ,
.Xr who 1 ,
+.Xr login 3 ,
+.Xr logout 3 ,
+.Xr logwtmp 3 ,
+.Xr ttyslot 3 ,
.Xr ac 8 ,
.Xr init 8
.Sh HISTORY
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20011011170226.A2162>