Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
UTMP(5)				 File formats			       UTMP(5)

       utmp, wtmp - login records

       #include	<utmp.h>

       The utmp	file allows one	to discover information	about who is currently
       using the system.  There	may be more users currently using the  system,
       because not all programs	use utmp logging.

       Warning:	utmp must not be writable, because many	system programs	(fool-
       ishly) depend on	its integrity.	You risk  faked	 system	 logfiles  and
       modifications of	system files if	you leave utmp writable	to any user.

       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
       around; details depend on the version of	libc):

	      #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

	      #define UT_LINESIZE	    12
	      #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 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. */
		long ut_session;	    /* session ID, used	for windowing*/
		struct timeval ut_tv;	    /* time entry was made.  */
		int32_t	ut_addr_v6[4];	    /* IP address of remote host.  */
		char pad[20];		    /* Reserved	for future use.	 */

	      /* Backwards compatibility hacks.	 */
	      #define ut_name ut_user
	      #ifndef _NO_UT_TIME
	      #define ut_time ut_tv.tv_sec
	      #define ut_xtime ut_tv.tv_sec
	      #define ut_addr ut_addr_v6[0]

       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	 time(2).   String  fields  are	terminated by '\0' if they are
       shorter than the	size of	the field.

       The first entries ever created result  from  init(8)  processing	 init-
       tab(5).	 Before	 an entry is processed,	though,	init(8)	cleans up utmp
       by setting ut_type to  DEAD_PROCESS,  clearing  ut_user,	 ut_host,  and
       ut_time	 with  null  bytes  for	 each  record  which  ut_type  is  not
       DEAD_PROCESS or RUN_LVL and where no process with  PID  ut_pid  exists.
       If  no  empty record with the needed ut_id can be found,	init creates a
       new one.	 It sets ut_id from the	inittab, ut_pid	 and  ut_time  to  the
       current values, and ut_type to INIT_PROCESS.

       getty(8)	 locates  the  entry  by  the  pid,  changes  ut_type  to  LO-
       GIN_PROCESS, changes ut_time, sets ut_line, and waits for connection to
       be established.	login(8), after	a user has been	authenticated, changes
       ut_type to USER_PROCESS,	changes	ut_time, and sets ut_host and ut_addr.
       Depending  on  getty(8) and login(8), records may be located by ut_line
       instead of the preferable ut_pid.

       When init(8) finds that a process has exited, it	locates	its utmp entry
       by  ut_pid,  sets  ut_type to DEAD_PROCESS, and clears ut_user, ut_host
       and ut_time with	null bytes.

       xterm(1)	and other terminal emulators directly  create  a  USER_PROCESS
       record  and  generate  the  ut_id  by  using  the  last	two letters of
       /dev/ttyp%c  or	by  using  p%d	for  /dev/pts/%d.   If	they  find   a
       DEAD_PROCESS  for this id, they recycle it, otherwise they create a new
       entry.  If they can, they will mark it as DEAD_PROCESS on  exiting  and
       it  is advised that they	null ut_line, ut_time, ut_user,	and ut_host as

       xdm(8) should not create	a utmp record, because there  is  no  assigned
       terminal.   Letting  it create one will result in errors, such as 'fin-
       ger: cannot stat	/dev/machine.dom'.  It	should	create	wtmp  entries,
       though, just like ftpd(8) does.

       telnetd(8)  sets	 up  a	LOGIN_PROCESS entry and	leaves the rest	to lo-
       gin(8) as usual.	 After the telnet session ends,	telnetd(8)  cleans  up
       utmp in the described way.

       The  wtmp  file	records	all logins and logouts.	 Its format is exactly
       like utmp except	that a null user name indicates	a logout on the	 asso-
       ciated  terminal.   Furthermore,	 the  terminal name "~"	with user name
       "shutdown" or "reboot" indicates	a system shutdown or  reboot  and  the
       pair  of	 terminal  names  "|"/"}"  logs	 the  old/new system time when
       date(1) changes it.  wtmp is maintained by login(1), init(1), and  some
       versions	 of  getty(1).	Neither	of these programs creates the file, so
       if it is	removed, record-keeping	is turned off.


       Linux utmp entries conform neither to v7/BSD nor	to SYSV;  they	are  a
       mix  of	the  two.   v7/BSD has fewer fields; most importantly it lacks
       ut_type,	which causes native v7/BSD-like	programs to display (for exam-
       ple)  dead  or  login entries.  Further,	there is no configuration file
       which allocates slots to	sessions.  BSD does so because it lacks	 ut_id
       fields.	 In Linux (as in SYSV),	the ut_id field	of a record will never
       change once it has been set, which reserves that	slot without needing a
       configuration file.  Clearing ut_id may result in race conditions lead-
       ing to corrupted	utmp entries and and potential security	holes.	Clear-
       ing  the	 above mentioned fields	by filling them	with null bytes	is not
       required	by SYSV	semantics, but it allows 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.

       SYSV only uses the type field to	mark them and  logs  informative  mes-
       sages such as e.g. "new time" in	the line field.	UT_UNKNOWN seems to be
       a Linux invention.  SYSV	has no ut_host or ut_addr_v6 fields.

       Unlike various other systems, where utmp	logging	can be disabled	by re-
       moving  the file, utmp must always exist	on Linux.  If you want to dis-
       able who(1) then	do not make utmp world readable.

       Note that the utmp struct from libc5 has	changed	in libc6.  Because  of
       this,  binaries	using  the old libc5 struct will corrupt /var/run/utmp
       and/or /var/log/wtmp.  Debian systems include  a	 patched  libc5	 which
       uses  the  new  utmp  format.  The problem still	exists with wtmp since
       it's accessed directly in libc5.

       The file	format is machine dependent, so	it is recommended that	it  be
       processed only on the machine architecture where	it was created.

       This  manpage  is  based	 on the	libc5 one, things may work differently

       ac(1), date(1), getutent(3), init(8),  last(1),	login(1),  updwtmp(3),

				  1997-07-02			       UTMP(5)


Want to link to this manual page? Use this URL:

home | help