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