lib/libc/gen/getutxent.3

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