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