Skip site navigation (1)Skip section navigation (2)
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-hackers" 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>