{ "content": [ { "type": "text", "text": "# utmp (man)\n\n## NAME\n\nutmp, wtmp - login records\n\n## DESCRIPTION\n\nThe utmp file allows one to discover information about who is currently using the system.\nThere may be more users currently using the system, because not all programs use utmp log‐\nging.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (1 subsections)\n- **DESCRIPTION**\n- **FILES**\n- **CONFORMING TO** (1 subsections)\n- **NOTES**\n- **SEE ALSO**\n- **COLOPHON**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "utmp", "section": "", "mode": "man", "summary": "utmp, wtmp - login records", "synopsis": "", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "ac", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/ac/1/json" }, { "name": "date", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/date/1/json" }, { "name": "init", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/init/1/json" }, { "name": "last", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/last/1/json" }, { "name": "login", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/login/1/json" }, { "name": "logname", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/logname/1/json" }, { "name": "lslogins", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/lslogins/1/json" }, { "name": "users", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/users/1/json" }, { "name": "utmpdump", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/utmpdump/1/json" }, { "name": "who", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/who/1/json" }, { "name": "getutent", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/getutent/3/json" }, { "name": "getutmp", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/getutmp/3/json" }, { "name": "login", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/login/3/json" }, { "name": "logout", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/logout/3/json" }, { "name": "logwtmp", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/logwtmp/3/json" }, { "name": "updwtmp", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/updwtmp/3/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "#include ", "lines": 1 } ] }, { "name": "DESCRIPTION", "lines": 116, "subsections": [] }, { "name": "FILES", "lines": 3, "subsections": [] }, { "name": "CONFORMING TO", "lines": 6, "subsections": [ { "name": "Comparison with historical systems", "lines": 15 } ] }, { "name": "NOTES", "lines": 26, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "utmp, wtmp - login records\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "#include ", "content": "" } ] }, "DESCRIPTION": { "content": "The utmp file allows one to discover information about who is currently using the system.\nThere may be more users currently using the system, because not all programs use utmp log‐\nging.\n\nWarning: utmp must not be writable by the user class \"other\", because many system programs\n(foolishly) depend on its integrity. You risk faked system logfiles and modifications of\nsystem files if you leave utmp writable to any user other than the owner and group owner of\nthe file.\n\nThe file is a sequence of utmp structures, declared as follows in (note that this is\nonly one of several definitions around; details depend on the version of libc):\n\n/* Values for uttype field, below */\n\n#define EMPTY 0 /* Record does not contain valid info\n(formerly known as UTUNKNOWN on Linux) */\n#define RUNLVL 1 /* Change in system run-level (see\ninit(1)) */\n#define BOOTTIME 2 /* Time of system boot (in uttv) */\n#define NEWTIME 3 /* Time after system clock change\n(in uttv) */\n#define OLDTIME 4 /* Time before system clock change\n(in uttv) */\n#define INITPROCESS 5 /* Process spawned by init(1) */\n#define LOGINPROCESS 6 /* Session leader process for user login */\n#define USERPROCESS 7 /* Normal process */\n#define DEADPROCESS 8 /* Terminated process */\n#define ACCOUNTING 9 /* Not implemented */\n\n#define UTLINESIZE 32\n#define UTNAMESIZE 32\n#define UTHOSTSIZE 256\n\nstruct exitstatus { /* Type for utexit, below */\nshort etermination; /* Process termination status */\nshort eexit; /* Process exit status */\n};\n\nstruct utmp {\nshort uttype; /* Type of record */\npidt utpid; /* PID of login process */\nchar utline[UTLINESIZE]; /* Device name of tty - \"/dev/\" */\nchar utid[4]; /* Terminal name suffix,\nor inittab(5) ID */\nchar utuser[UTNAMESIZE]; /* Username */\nchar uthost[UTHOSTSIZE]; /* Hostname for remote login, or\nkernel version for run-level\nmessages */\nstruct exitstatus utexit; /* Exit status of a process\nmarked as DEADPROCESS; not\nused by Linux init(1) */\n/* The utsession and uttv fields must be the same size when\ncompiled 32- and 64-bit. This allows data files and shared\nmemory to be shared between 32- and 64-bit applications. */\n#if WORDSIZE == 64 && defined WORDSIZECOMPAT32\nint32t utsession; /* Session ID (getsid(2)),\nused for windowing */\nstruct {\nint32t tvsec; /* Seconds */\nint32t tvusec; /* Microseconds */\n} uttv; /* Time entry was made */\n#else\nlong utsession; /* Session ID */\nstruct timeval uttv; /* Time entry was made */\n#endif\n\nint32t utaddrv6[4]; /* Internet address of remote\nhost; IPv4 address uses\njust utaddrv6[0] */\nchar unused[20]; /* Reserved for future use */\n};\n\n/* Backward compatibility hacks */\n#define utname utuser\n#ifndef NOUTTIME\n#define uttime uttv.tvsec\n#endif\n#define utxtime uttv.tvsec\n#define utaddr utaddrv6[0]\n\nThis structure gives the name of the special file associated with the user's terminal, the\nuser's login name, and the time of login in the form of time(2). String fields are termi‐\nnated by a null byte ('\\0') if they are shorter than the size of the field.\n\nThe first entries ever created result from init(1) processing inittab(5). Before an entry is\nprocessed, though, init(1) cleans up utmp by setting uttype to DEADPROCESS, clearing\nutuser, uthost, and uttime with null bytes for each record which uttype is not\nDEADPROCESS or RUNLVL and where no process with PID utpid exists. If no empty record with\nthe needed utid can be found, init(1) creates a new one. It sets utid from the inittab,\nutpid and uttime to the current values, and uttype to INITPROCESS.\n\nmingetty(8) (or agetty(8)) locates the entry by the PID, changes uttype to LOGINPROCESS,\nchanges uttime, sets utline, and waits for connection to be established. login(1), after a\nuser has been authenticated, changes uttype to USERPROCESS, changes uttime, and sets\nuthost and utaddr. Depending on mingetty(8) (or agetty(8)) and login(1), records may be\nlocated by utline instead of the preferable utpid.\n\nWhen init(1) finds that a process has exited, it locates its utmp entry by utpid, sets\nuttype to DEADPROCESS, and clears utuser, uthost, and uttime with null bytes.\n\nxterm(1) and other terminal emulators directly create a USERPROCESS record and generate the\nutid by using the string that suffix part of the terminal name (the characters following\n/dev/[pt]ty). If they find a DEADPROCESS for this ID, they recycle it, otherwise they cre‐\nate a new entry. If they can, they will mark it as DEADPROCESS on exiting and it is advised\nthat they null utline, uttime, utuser, and uthost as well.\n\ntelnetd(8) sets up a LOGINPROCESS entry and leaves the rest to login(1) as usual. After the\ntelnet session ends, telnetd(8) cleans up utmp in the described way.\n\nThe wtmp file records all logins and logouts. Its format is exactly like utmp except that a\nnull username indicates a logout on the associated terminal. Furthermore, the terminal name\n~ with username shutdown or reboot indicates a system shutdown or reboot and the pair of ter‐\nminal names |/} logs the old/new system time when date(1) changes it. wtmp is maintained by\nlogin(1), init(1), and some versions of getty(8) (e.g., mingetty(8) or agetty(8)). None of\nthese programs creates the file, so if it is removed, record-keeping is turned off.\n", "subsections": [] }, "FILES": { "content": "/var/run/utmp\n/var/log/wtmp\n", "subsections": [] }, "CONFORMING TO": { "content": "POSIX.1 does not specify a utmp structure, but rather one named utmpx, with specifications\nfor the fields uttype, utpid, utline, utid, utuser, and uttv. POSIX.1 does not specify\nthe lengths of the utline and utuser fields.\n\nLinux defines the utmpx structure to be the same as the utmp structure.\n", "subsections": [ { "name": "Comparison with historical systems", "content": "Linux utmp entries conform neither to v7/BSD nor to System V; they are a mix of the two.\n\nv7/BSD has fewer fields; most importantly it lacks uttype, which causes native v7/BSD-like\nprograms to display (for example) dead or login entries. Further, there is no configuration\nfile which allocates slots to sessions. BSD does so because it lacks utid fields.\n\nIn Linux (as in System V), the utid field of a record will never change once it has been\nset, which reserves that slot without needing a configuration file. Clearing utid may re‐\nsult in race conditions leading to corrupted utmp entries and potential security holes.\nClearing the abovementioned fields by filling them with null bytes is not required by System\nV semantics, but makes it possible to run many programs which assume BSD semantics and which\ndo not modify utmp. Linux uses the BSD conventions for line contents, as documented above.\n\nSystem V has no uthost or utaddrv6 fields.\n" } ] }, "NOTES": { "content": "Unlike various other systems, where utmp logging can be disabled by removing the file, utmp\nmust always exist on Linux. If you want to disable who(1), then do not make utmp world read‐\nable.\n\nThe file format is machine-dependent, so it is recommended that it be processed only on the\nmachine architecture where it was created.\n\nNote that on biarch platforms, that is, systems which can run both 32-bit and 64-bit applica‐\ntions (x86-64, ppc64, s390x, etc.), uttv is the same size in 32-bit mode as in 64-bit mode.\nThe same goes for utsession and uttime if they are present. This allows data files and\nshared memory to be shared between 32-bit and 64-bit applications. This is achieved by\nchanging the type of utsession to int32t, and that of uttv to a struct with two int32t\nfields tvsec and tvusec. Since uttv may not be the same as struct timeval, then instead\nof the call:\n\ngettimeofday((struct timeval *) &ut.uttv, NULL);\n\nthe following method of setting this field is recommended:\n\nstruct utmp ut;\nstruct timeval tv;\n\ngettimeofday(&tv, NULL);\nut.uttv.tvsec = tv.tvsec;\nut.uttv.tvusec = tv.tvusec;\n", "subsections": [] }, "SEE ALSO": { "content": "ac(1), date(1), init(1), last(1), login(1), logname(1), lslogins(1), users(1), utmpdump(1),\nwho(1), getutent(3), getutmp(3), login(3), logout(3), logwtmp(3), updwtmp(3)\n", "subsections": [] }, "COLOPHON": { "content": "This page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2020-12-21 UTMP(5)", "subsections": [] } } } }