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 October 27, 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 SHUTDOWN_TIME ,
 305 .Dv OLD_TIME
 306 and
 307 .Dv NEW_TIME
 308 will only be written to
 309 .Pa /var/log/utx.log .
 310 .Pp
 311 Entries of type
 312 .Dv USER_PROCESS
 313 will also be written to
 314 .Pa /var/run/utx.active
 315 and
 316 .Pa /var/log/utx.lastlogin .
 317 .Pp
 318 Entries of type
 319 .Dv DEAD_PROCESS
 320 will only be written to
 321 .Pa /var/log/utx.log
 322 and
 323 .Pa /var/run/utx.active
 324 if a corresponding
 325 .Dv USER_PROCESS ,
 326 .Dv INIT_PROCESS
 327 or
 328 .Dv LOGIN_PROCESS
 329 entry whose
 330 .Fa ut_id
 331 is equal has been found in the latter.
 332 .Pp
 333 In addition, entries of type
 334 .Dv BOOT_TIME
 335 and
 336 .Dv SHUTDOWN_TIME
 337 will cause all existing entries in
 338 .Pa /var/run/utx.active
 339 to be discarded.
 340 .Pp
 341 All entries whose type has not been mentioned previously, are discarded
 342 by this implementation of
 343 .Fn pututxline .
 344 This implementation also ignores the value of
 345 .Fa ut_tv .
 346 .Sh RETURN VALUES
 347 The
 348 .Fn getutxent ,
 349 .Fn getutxid ,
 350 .Fn getutxline ,
 351 and
 352 .Fn getutxuser
 353 functions return a pointer to an
 354 .Vt utmpx
 355 structure that matches the mentioned constraints on success or
 356 .Dv NULL
 357 when reaching the end-of-file or when an error occurs.
 358 .Pp
 359 The
 360 .Fn pututxline
 361 function returns a pointer to an
 362 .Vt utmpx
 363 structure containing a copy of the structure written to disk upon
 364 success.
 365 It returns
 366 .Dv NULL
 367 when the provided
 368 .Vt utmpx
 369 is invalid, or
 370 .Fa ut_type
 371 has a value of
 372 .Dv DEAD_PROCESS
 373 and an entry with an identifier with a value equal to the field
 374 .Fa ut_id
 375 was not found; the global variable
 376 .Va errno
 377 is set to indicate the error.
 378 .Pp
 379 The
 380 .Fn setutxdb
 381 function returns 0 if the user accounting database was opened
 382 successfully.
 383 Otherwise, -1 is returned and the global variable
 384 .Va errno
 385 is set to indicate the error.
 386 .Sh ERRORS
 387 In addition to the error conditions described in
 388 .Xr open 2 ,
 389 .Xr fdopen 3 ,
 390 .Xr fopen 3 ,
 391 .Xr fseek 3 ,
 392 the
 393 .Fn pututxline
 394 function can generate the following errors:
 395 .Bl -tag -width Er
 396 .It Bq Er ESRCH
 397 The value of
 398 .Fa ut_type
 399 is DEAD_PROCESS, and the process entry could not be found.
 400 .It Bq Er EINVAL
 401 The value of
 402 .Fa ut_type
 403 is not supported by this implementation.
 404 .El
 405 In addition to the error conditions described in
 406 .Xr fopen 3 ,
 407 the
 408 .Fn setutxdb
 409 function can generate the following errors:
 410 .Bl -tag -width Er
 411 .It Bq Er EINVAL
 412 The
 413 .Fa type
 414 argument contains a value not supported by this implementation.
 415 .It Bq Er EFTYPE
 416 The file format is invalid.
 417 .El
 418 .Sh SEE ALSO
 419 .Xr last 1 ,
 420 .Xr write 1 ,
 421 .Xr getpid 2 ,
 422 .Xr gettimeofday 2 ,
 423 .Xr tty 4 ,
 424 .Xr ac 8 ,
 425 .Xr newsyslog 8 ,
 426 .Xr utx 8
 427 .Sh STANDARDS
 428 The
 429 .Fn endutxent ,
 430 .Fn getutxent ,
 431 .Fn getutxid ,
 432 .Fn getutxline
 433 and
 434 .Fn setutxent
 435 functions are expected to conform to
 436 .St -p1003.1-2008 .
 437 .Pp
 438 The
 439 .Fn pututxline
 440 function deviates from the standard by writing its records to multiple
 441 database files, depending on its
 442 .Fa ut_type .
 443 This prevents the need for special utility functions to update the other
 444 databases, such as the
 445 .Fn updlastlogx
 446 and
 447 .Fn updwtmpx
 448 functions which are available in other implementations.
 449 It also tries to replace
 450 .Dv DEAD_PROCESS
 451 entries in the active sessions database when storing
 452 .Dv USER_PROCESS
 453 entries and no entry with the same value for
 454 .Fa ut_id
 455 has been found.
 456 The standard always requires a new entry to be allocated, which could
 457 cause an unbounded growth of the database.
 458 .Pp
 459 The
 460 .Fn getutxuser
 461 and
 462 .Fn setutxdb
 463 functions,
 464 the
 465 .Fa ut_host
 466 field of the
 467 .Vt utmpx
 468 structure and
 469 .Dv SHUTDOWN_TIME
 470 are extensions.
 471 .Sh HISTORY
 472 These functions appeared in
 473 .Fx 9.0 .
 474 They replaced the
 475 .In utmp.h
 476 interface.
 477 .Sh AUTHORS
 478 .An Ed Schouten Aq ed@FreeBSD.org