1.\" Copyright (c) 2010 Ed Schouten <ed@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 19, 2011 28.Dt GETUTXENT 3 29.Os 30.Sh NAME 31.Nm endutxent , 32.Nm getutxent , 33.Nm getutxid , 34.Nm getutxline , 35.Nm getutxuser , 36.Nm pututxline , 37.Nm setutxdb , 38.Nm setutxent 39.Nd user accounting database functions 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In utmpx.h 44.Ft void 45.Fn endutxent "void" 46.Ft struct utmpx * 47.Fn getutxent "void" 48.Ft struct utmpx * 49.Fn getutxid "const struct utmpx *id" 50.Ft struct utmpx * 51.Fn getutxline "const struct utmpx *line" 52.Ft struct utmpx * 53.Fn getutxuser "const char *user" 54.Ft struct utmpx * 55.Fn pututxline "const struct utmpx *utmpx" 56.Ft int 57.Fn setutxdb "int type" "const char *file" 58.Ft void 59.Fn setutxent "void" 60.Sh DESCRIPTION 61These functions operate on the user accounting database which stores 62records of various system activities, such as user login and logouts, 63but also system startups and shutdowns and modifications to the system's 64clock. 65The system stores these records in three databases, each having a 66different purpose: 67.Bl -tag -width indent 68.It Pa /var/run/utx.active 69Log of currently active user login sessions. 70This file is similar to the traditional 71.Pa utmp 72file. 73This file only contains process related entries, such as user login and 74logout records. 75.It Pa /var/log/utx.lastlogin 76Log of last user login entries per user. 77This file is similar to the traditional 78.Pa lastlog 79file. 80This file only contains user login records for users who have at least 81logged in once. 82.It Pa /var/log/utx.log 83Log of all entries, sorted by date of addition. 84This file is similar to the traditional 85.Pa wtmp 86file. 87This file may contain any type of record described below. 88.El 89.Pp 90Each entry in these databases is defined by the structure 91.Vt utmpx 92found in the include file 93.In utmpx.h : 94.Bd -literal -offset indent 95struct utmpx { 96 short ut_type; /* Type of entry. */ 97 struct timeval ut_tv; /* Time entry was made. */ 98 char ut_id[]; /* Record identifier. */ 99 pid_t ut_pid; /* Process ID. */ 100 char ut_user[]; /* User login name. */ 101 char ut_line[]; /* Device name. */ 102 char ut_host[]; /* Remote hostname. */ 103}; 104.Ed 105.Pp 106The 107.Fa ut_type 108field indicates the type of the log entry, which can have one of the 109following values: 110.Bl -tag -width LOGIN_PROCESS 111.It Dv EMPTY 112No valid user accounting information. 113.It Dv BOOT_TIME 114Identifies time of system boot. 115.It Dv SHUTDOWN_TIME 116Identifies time of system shutdown. 117.It Dv OLD_TIME 118Identifies time when system clock changed. 119.It Dv NEW_TIME 120Identifies time after system clock changed. 121.It Dv USER_PROCESS 122Identifies a process. 123.It Dv INIT_PROCESS 124Identifies a process spawned by the init process. 125.It Dv LOGIN_PROCESS 126Identifies the session leader of a logged-in user. 127.It Dv DEAD_PROCESS 128Identifies a session leader who has exited. 129.El 130.Pp 131Entries of type 132.Dv INIT_PROCESS 133and 134.Dv LOGIN_PROCESS 135are not processed by this implementation. 136.Pp 137Other fields inside the structure are: 138.Bl -tag -width ut_user 139.It Fa ut_tv 140The time the event occurred. 141This field is used for all types of entries, except 142.Dv EMPTY . 143.It Fa ut_id 144An identifier that is used to refer to the entry. 145This identifier can be used to remove or replace a login entry by 146writing a new entry to the database containing the same value for 147.Fa ut_id . 148This field is only applicable to entries of type 149.Dv USER_PROCESS , 150.Dv INIT_PROCESS , 151.Dv LOGIN_PROCESS 152and 153.Dv DEAD_PROCESS . 154.It Fa ut_pid 155The process identifier of the session leader of the login session. 156This field is only applicable to entries of type 157.Dv USER_PROCESS , 158.Dv INIT_PROCESS , 159.Dv LOGIN_PROCESS 160and 161.Dv DEAD_PROCESS . 162.It Fa ut_user 163The user login name corresponding with the login session. 164This field is only applicable to entries of type 165.Dv USER_PROCESS 166and 167.Dv INIT_PROCESS . 168For 169.Dv INIT_PROCESS 170entries this entry typically contains the name of the login process. 171.It Fa ut_line 172The name of the TTY character device, without the leading 173.Pa /dev/ 174prefix, corresponding with the device used to facilitate the user login 175session. 176If no TTY character device is used, this field is left blank. 177This field is only applicable to entries of type 178.Dv USER_PROCESS 179and 180.Dv LOGIN_PROCESS . 181.It Fa ut_host 182The network hostname of the remote system, connecting to perform a user 183login. 184If the user login session is not performed across a network, this field 185is left blank. 186This field is only applicable to entries of type 187.Dv USER_PROCESS . 188.El 189.Pp 190This implementation guarantees all inapplicable fields are discarded. 191The 192.Fa ut_user , 193.Fa ut_line 194and 195.Fa ut_host 196fields of the structure returned by the library functions are also 197guaranteed to be null-terminated in this implementation. 198.Pp 199The 200.Fn getutxent 201function can be used to read the next entry from the user accounting 202database. 203.Pp 204The 205.Fn getutxid 206function searches for the next entry in the database of which the 207behaviour is based on the 208.Fa ut_type 209field of 210.Fa id . 211If 212.Fa ut_type 213has a value of 214.Dv BOOT_TIME , 215.Dv SHUTDOWN_TIME , 216.Dv OLD_TIME 217or 218.Dv NEW_TIME , 219it will return the next entry whose 220.Fa ut_type 221has an equal value. 222If 223.Fa ut_type 224has a value of 225.Dv USER_PROCESS , 226.Dv INIT_PROCESS , 227.Dv LOGIN_PROCESS 228or 229.Dv DEAD_PROCESS , 230it will return the next entry whose 231.Fa ut_type 232has one of the previously mentioned values and whose 233.Fa ut_id 234is equal. 235.Pp 236The 237.Fn getutxline 238function searches for the next entry in the database whose 239.Fa ut_type 240has a value of 241.Dv USER_PROCESS 242or 243.Dv LOGIN_PROCESS 244and whose 245.Fa ut_line 246is equal to the the same field in 247.Fa line . 248.Pp 249The 250.Fn getutxuser 251function searches for the next entry in the database whose 252.Fa ut_type 253has a value of 254.Dv USER_PROCESS 255and whose 256.Fa ut_user 257is equal to 258.Fa user . 259.Pp 260The previously mentioned functions will automatically try to open the 261user accounting database if not already done so. 262The 263.Fn setutxdb 264and 265.Fn setutxent 266functions allow the database to be opened manually, causing the offset 267within the user accounting database to be rewound. 268The 269.Fn endutxent 270function closes the database. 271.Pp 272The 273.Fn setutxent 274database always opens the active sessions database. 275The 276.Fn setutxdb 277function opens the database identified by 278.Fa type , 279whose value is either 280.Dv UTXDB_ACTIVE , 281.Dv UTXDB_LASTLOGIN 282or 283.Dv UTXDB_LOG . 284It will open a custom file with filename 285.Fa file 286instead of the system-default if 287.Fa file 288is not null. 289Care must be taken that when using a custom filename, 290.Fa type 291still has to match with the actual format, since each database may use 292its own file format. 293.Pp 294The 295.Fn pututxline 296function writes record 297.Fa utmpx 298to the system-default user accounting databases. 299The value of 300.Fa ut_type 301determines which databases are modified. 302.Pp 303Entries of type 304.Dv BOOT_TIME , 305.Dv SHUTDOWN_TIME , 306.Dv OLD_TIME 307and 308.Dv NEW_TIME 309will only be written to 310.Pa /var/log/utx.log . 311.Pp 312Entries of type 313.Dv USER_PROCESS 314will also be written to 315.Pa /var/run/utx.active 316and 317.Pa /var/log/utx.lastlogin . 318.Pp 319Entries of type 320.Dv DEAD_PROCESS 321will only be written to 322.Pa /var/log/utx.log 323and 324.Pa /var/run/utx.active 325if a corresponding 326.Dv USER_PROCESS , 327.Dv INIT_PROCESS 328or 329.Dv LOGIN_PROCESS 330entry whose 331.Fa ut_id 332is equal has been found in the latter. 333.Pp 334In addition, entries of type 335.Dv BOOT_TIME 336and 337.Dv SHUTDOWN_TIME 338will cause all entries in 339.Pa /var/run/utx.active 340to be discarded. 341.Pp 342All entries whose type has not been mentioned previously, are discarded 343by this implementation of 344.Fn pututxline . 345This implementation also ignores the value of 346.Fa ut_tv . 347.Sh RETURN VALUES 348The 349.Fn getutxent , 350.Fn getutxid , 351.Fn getutxline , 352and 353.Fn getutxuser 354functions return a pointer to an 355.Vt utmpx 356structure that matches the mentioned constraints on success or 357.Dv NULL 358when reaching the end-of-file or when an error occurs. 359.Pp 360The 361.Fn pututxline 362function returns a pointer to an 363.Vt utmpx 364structure containing a copy of the structure written to disk upon 365success. 366It returns 367.Dv NULL 368when the provided 369.Vt utmpx 370is invalid, or 371.Fa ut_type 372has a value of 373.Dv DEAD_PROCESS 374and an entry with an identifier with a value equal to the field 375.Fa ut_id 376was not found; the global variable 377.Va errno 378is set to indicate the error. 379.Pp 380The 381.Fn setutxdb 382function returns 0 if the user accounting database was opened 383successfully. 384Otherwise, -1 is returned and the global variable 385.Va errno 386is set to indicate the error. 387.Sh ERRORS 388In addition to the error conditions described in 389.Xr fdopen 3 , 390.Xr fopen 3 , 391.Xr fseek 3 , 392.Xr open 3 , 393the 394.Fn pututxline 395function can generate the following errors: 396.Bl -tag -width Er 397.It Bq Er ESRCH 398The value of 399.Fa ut_type 400is DEAD_PROCESS, and the process entry could not be found. 401.It Bq Er EINVAL 402The value of 403.Fa ut_type 404is not supported by this implementation. 405.El 406In addition to the error conditions described in 407.Xr fopen 3 , 408the 409.Fn setutxdb 410function can generate the following errors: 411.Bl -tag -width Er 412.It Bq Er EINVAL 413The 414.Fa type 415argument contains a value not supported by this implementation. 416.It Bq Er EFTYPE 417The file format is invalid. 418.El 419.Sh SEE ALSO 420.Xr last 1 , 421.Xr write 1 , 422.Xr wtmpcvt 1 , 423.Xr getpid 2 , 424.Xr gettimeofday 2 , 425.Xr tty 4 , 426.Xr ac 8 , 427.Xr newsyslog 8 , 428.Xr utxrm 8 429.Sh STANDARDS 430The 431.Fn endutxent , 432.Fn getutxent , 433.Fn getutxid , 434.Fn getutxline 435and 436.Fn setutxent 437functions are expected to conform to 438.St -p1003.1-2008 . 439.Pp 440The 441.Fn pututxline 442function deviates from the standard by writing its records to multiple 443database files, depending on its 444.Fa ut_type . 445This prevents the need for special utility functions to update the other 446databases, such as the 447.Fn updlastlogx 448and 449.Fn updwtmpx 450functions which are available in other implementations. 451It also tries to replace 452.Dv DEAD_PROCESS 453entries in the active sessions database when storing 454.Dv USER_PROCESS 455entries and no entry with the same value for 456.Fa ut_id 457has been found. 458The standard always requires a new entry to be allocated, which could 459cause an unbounded growth of the database. 460.Pp 461The 462.Fn getutxuser 463and 464.Fn setutxdb 465functions, 466the 467.Fa ut_host 468field of the 469.Vt utmpx 470structure and 471.Dv SHUTDOWN_TIME 472are extensions. 473.Sh HISTORY 474These functions appeared in 475.Fx 9.0 . 476They replaced the 477.In utmp.h 478interface. 479.Sh AUTHORS 480.An Ed Schouten Aq ed@FreeBSD.org 481