-.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), Fri Apr 2 11:32:09 MET DST 1993
+.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de),
+.\" Fri Apr 2 11:32:09 MET DST 1993
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
.\" Modified 1995-02-26 by Michael Haardt
.\" Modified 1996-07-20 by Michael Haardt
-.\" Modified 1997-07-02 by Nicolás Lichtmaier <nick@debian.org>
+.\" Modified 1997-07-02 by Nicolás Lichtmaier <nick@debian.org>
.\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne
-.TH UTMP 5 2007-11-25 "Linux" "Linux Programmer's Manual"
+.TH UTMP 5 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
utmp, wtmp \- login records
.SH SYNOPSIS
.PP
.B Warning:
.I utmp
-must not be writable, because many system programs (foolishly)
+must not be writable by the user class "other",
+because many system programs (foolishly)
depend on its integrity.
You risk faked system logfiles and
modifications of system files if you leave
.I utmp
-writable to any user.
+writable to any user other than the owner and group owner of the file.
.PP
-The file is a sequence of entries with the following structure declared
-in the include file (note that this is only one of several definitions
+The file is a sequence of
+.I utmp
+structures,
+declared as follows in
+.IR <utmp.h>
+(note that this is only one of several definitions
around; details depend on the version of libc):
+.PP
.in +4n
-.nf
-.sp
-#define UT_UNKNOWN 0
-#define RUN_LVL 1
-#define BOOT_TIME 2
-#define NEW_TIME 3
-#define OLD_TIME 4
-#define INIT_PROCESS 5
-#define LOGIN_PROCESS 6
-#define USER_PROCESS 7
-#define DEAD_PROCESS 8
-#define ACCOUNTING 9
+.EX
+/* Values for ut_type field, below */
-#define UT_LINESIZE 12
-#define UT_NAMESIZE 32
+#define EMPTY 0 /* Record does not contain valid info
+ (formerly known as UT_UNKNOWN on Linux) */
+#define RUN_LVL 1 /* Change in system run-level (see
+ \fBinit\fP(8)) */
+#define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */
+#define NEW_TIME 3 /* Time after system clock change
+ (in \fIut_tv\fP) */
+#define OLD_TIME 4 /* Time before system clock change
+ (in \fIut_tv\fP) */
+#define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(8) */
+#define LOGIN_PROCESS 6 /* Session leader process for user login */
+#define USER_PROCESS 7 /* Normal process */
+#define DEAD_PROCESS 8 /* Terminated process */
+#define ACCOUNTING 9 /* Not implemented */
+
+#define UT_LINESIZE 32
+#define UT_NAMESIZE 32
#define UT_HOSTSIZE 256
-struct exit_status {
- short int e_termination; /* process termination status */
- short int e_exit; /* process exit status */
+struct exit_status { /* Type for ut_exit, below */
+ short int e_termination; /* Process termination status */
+ short int e_exit; /* Process exit status */
};
struct utmp {
- short ut_type; /* type of login */
- pid_t ut_pid; /* PID of login process */
- char ut_line[UT_LINESIZE]; /* device name of tty \- "/dev/" */
- char ut_id[4]; /* init id or abbrev. ttyname */
- char ut_user[UT_NAMESIZE]; /* user name */
- char ut_host[UT_HOSTSIZE]; /* hostname for remote login */
- struct exit_status ut_exit; /* The exit status of a process
- marked as DEAD_PROCESS */
-
+ short ut_type; /* Type of record */
+ pid_t ut_pid; /* PID of login process */
+ char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */
+ char ut_id[4]; /* Terminal name suffix,
+ or inittab(5) ID */
+ char ut_user[UT_NAMESIZE]; /* Username */
+ char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or
+ kernel version for run-level
+ messages */
+ struct exit_status ut_exit; /* Exit status of a process
+ marked as DEAD_PROCESS; not
+ used by Linux init (1 */
/* The ut_session and ut_tv fields must be the same size when
compiled 32- and 64-bit. This allows data files and shared
- memory to be shared between 32- and 64-bit applications */
+ memory to be shared between 32- and 64-bit applications. */
#if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32
- int32_t ut_session; /* Session ID, used for windowing */
+ int32_t ut_session; /* Session ID (\fBgetsid\fP(2)),
+ used for windowing */
struct {
- int32_t tv_sec; /* Seconds */
- int32_t tv_usec; /* Microseconds */
- } ut_tv; /* Time entry was made */
+ int32_t tv_sec; /* Seconds */
+ int32_t tv_usec; /* Microseconds */
+ } ut_tv; /* Time entry was made */
#else
- long int ut_session; /* Session ID, used for windowing */
- struct timeval ut_tv; /* Time entry was made */
+ long ut_session; /* Session ID */
+ struct timeval ut_tv; /* Time entry was made */
#endif
- int32_t ut_addr_v6[4]; /* IP address of remote host */
- char __unused[20]; /* Reserved for future use */
+ int32_t ut_addr_v6[4]; /* Internet address of remote
+ host; IPv4 address uses
+ just ut_addr_v6[0] */
+ char __unused[20]; /* Reserved for future use */
};
-/* Backwards compatibility hacks. */
+/* Backward compatibility hacks */
#define ut_name ut_user
#ifndef _NO_UT_TIME
#define ut_time ut_tv.tv_sec
#endif
#define ut_xtime ut_tv.tv_sec
#define ut_addr ut_addr_v6[0]
-.sp
-.fi
+.EE
.in
+.PP
This structure gives the name of the special file associated with the
user's terminal, the user's login name, and the time of login in the form
of
.BR time (2).
-String fields are terminated by \fB\(aq\e0\(aq\fP
+String fields are terminated by a null byte (\(aq\e0\(aq)
if they are shorter than the size
of the field.
.PP
The first entries ever created result from
-.BR init (8)
+.BR init (1)
processing
.BR inittab (5).
Before an entry is processed, though,
-.BR init (8)
+.BR init (1)
cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing
\fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each
record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP
and where no process with PID \fIut_pid\fP exists.
If no empty record
-with the needed \fIut_id\fP can be found, init creates a new one.
+with the needed \fIut_id\fP can be found,
+.BR init (1)
+creates a new one.
It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
.PP
\fIut_line\fP instead of the preferable \fIut_pid\fP.
.PP
When
-.BR init (8)
+.BR init (1)
finds that a process has exited, it locates its utmp
entry by \fIut_pid\fP, sets \fIut_type\fP to \fBDEAD_PROCESS\fP, and
clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes.
.PP
.BR xterm (1)
and other terminal emulators directly create a
-\fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the last
-two letters of \fI/dev/ttyp\fP\fI%c\fP or by using \fIp\fP\fI%d\fP for
-\fI/dev/pts/\fP\fI%d\fP.
+\fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the
+string that suffix part of the terminal name (the characters
+following \fI/dev/[pt]ty\fP).
If they find a \fBDEAD_PROCESS\fP for this ID,
they recycle it, otherwise they create a new entry.
If they can, they
cleans up utmp in the described way.
.PP
The \fIwtmp\fP file records all logins and logouts.
-Its format is exactly like \fIutmp\fP except that a null user name
+Its format is exactly like \fIutmp\fP except that a null username
indicates a logout
on the associated terminal.
Furthermore, the terminal name \fB~\fP
-with user name \fBshutdown\fP or \fBreboot\fP indicates a system
+with username \fBshutdown\fP or \fBreboot\fP indicates a system
shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP
logs the old/new system time when
.BR date (1)
changes it.
\fIwtmp\fP is maintained by
.BR login (1),
-.BR init (8),
+.BR init (1),
and some versions of
.BR getty (8)
(e.g.,
.BR mingetty (8)
or
.BR agetty (8)).
-Neither of these programs creates the file, so if it is
+None of these programs creates the file, so if it is
removed, record-keeping is turned off.
-.PP
-Note that on \fIbiarch\fP platforms, that is, systems which can run both
-32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
-\fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
-The same goes for \fIut_session\fP and \fIut_time\fP if they are present.
-This allows data files and shared memory to be shared between
-32-bit and 64-bit applications.
-Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
-then instead of the call:
-.in +4n
-.nf
-.sp
-gettimeofday((struct timeval *) &ut.ut_tv, NULL);
-.fi
-.in
-
-the following method of setting this field is recommended:
-.in +4n
-.nf
-.sp
-struct utmp ut;
-struct timeval tv;
-
-gettimeofday(&tv, NULL);
-ut.ut_tv.tv_sec = tv.tv_sec;
-ut.ut_tv.tv_usec = tv.tv_usec;
-.fi
-.in
.SH FILES
-/var/run/utmp
+.I /var/run/utmp
.br
-/var/log/wtmp
-.SH "CONFORMING TO"
+.I /var/log/wtmp
+.SH CONFORMING TO
+.PP
+POSIX.1 does not specify a
+.I utmp
+structure, but rather one named
+.IR utmpx ,
+with specifications for the fields
+.IR ut_type ,
+.IR ut_pid ,
+.IR ut_line ,
+.IR ut_id ,
+.IR ut_user ,
+and
+.IR ut_tv .
+POSIX.1 does not specify the lengths of the
+.I ut_line
+and
+.I ut_user
+fields.
+.PP
+Linux defines the
+.I utmpx
+structure to be the same as the
+.I utmp
+structure.
+.SS Comparison with historical systems
Linux utmp entries conform neither to v7/BSD nor to System V; they are a
mix of the two.
+.PP
v7/BSD has fewer fields; most importantly it lacks
\fIut_type\fP, which causes native v7/BSD-like programs to display (for
example) dead or login entries.
Further, there is no configuration file
which allocates slots to sessions.
BSD does so because it lacks \fIut_id\fP fields.
+.PP
In Linux (as in System V), the \fIut_id\fP field of a
record will never change once it has been set, which reserves that slot
without needing a configuration file.
Clearing \fIut_id\fP may result
in race conditions leading to corrupted utmp entries and potential
security holes.
-Clearing the above mentioned fields by filling them
-with null bytes is not required by System V semantics, but it allows to run
+Clearing the abovementioned fields by filling them
+with null bytes is not required by System V semantics,
+but makes it possible to run
many programs which assume BSD semantics and which do not modify utmp.
Linux uses the BSD conventions for line contents, as documented above.
.PP
-System V only uses the type field to mark them and logs informative messages
-such as \fB"new time"\fP in the line field.
-\fBUT_UNKNOWN\fP seems
-to be a Linux invention.
+.\" mtk: What is the referrent of "them" in the following sentence?
+.\" System V only uses the type field to mark them and logs
+.\" informative messages such as \fB"new time"\fP in the line field.
System V has no \fIut_host\fP or \fIut_addr_v6\fP fields.
+.SH NOTES
.PP
Unlike various other
systems, where utmp logging can be disabled by removing the file, utmp
must always exist on Linux.
If you want to disable
-.BR who (1)
+.BR who (1),
then do not make utmp world readable.
.PP
-Note that the \fIutmp\fP struct from libc5 has changed in libc6.
-Because of this,
-binaries using the old libc5 struct will corrupt
-.IR /var/run/utmp " and/or " /var/log/wtmp .
-.SH NOTES
The file format is machine-dependent, so it is recommended that it be
processed only on the machine architecture where it was created.
.PP
-Note that on platforms which can run both 32-bit and 64-bit applications
-(x86-64, ppc64, s390x, etc.), the sizes of the fields of a \fIutmp\fP struct
-must be the same in 32-bit mode as in 64-bit mode.
+Note that on \fIbiarch\fP platforms, that is, systems which can run both
+32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
+\fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
+The same goes for \fIut_session\fP and \fIut_time\fP if they are present.
+This allows data files and shared memory to be shared between
+32-bit and 64-bit applications.
This is achieved by changing the type of
.I ut_session
to
.I tv_sec
and
.IR tv_usec .
-(Thus, in order to fill it, first get the
-time into a real \fIstruct timeval\fP,
-then copy the two fields to
-.IR ut_tv .)
-.SH BUGS
-This man page is based on the libc5 one, things may work differently now.
-.SH "SEE ALSO"
+Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
+then instead of the call:
+.PP
+.in +4n
+.EX
+gettimeofday((struct timeval *) &ut.ut_tv, NULL);
+.EE
+.in
+.PP
+the following method of setting this field is recommended:
+.PP
+.in +4n
+.EX
+struct utmp ut;
+struct timeval tv;
+
+gettimeofday(&tv, NULL);
+ut.ut_tv.tv_sec = tv.tv_sec;
+ut.ut_tv.tv_usec = tv.tv_usec;
+.EE
+.in
+.\" .PP
+.\" Note that the \fIutmp\fP struct from libc5 has changed in libc6.
+.\" Because of this,
+.\" binaries using the old libc5 struct will corrupt
+.\" .IR /var/run/utmp " and/or " /var/log/wtmp .
+.\" .SH BUGS
+.\" This man page is based on the libc5 one, things may work differently now.
+.SH SEE ALSO
.BR ac (1),
.BR date (1),
+.BR init (1),
.BR last (1),
.BR login (1),
+.BR logname (1),
+.BR lslogins (1),
+.BR users (1),
+.BR utmpdump (1),
.BR who (1),
.BR getutent (3),
+.BR getutmp (3),
.BR login (3),
.BR logout (3),
.BR logwtmp (3),
-.BR updwtmp (3),
-.BR init (8)
+.BR updwtmp (3)
projects / thirdparty / man-pages.git / blobdiff