1 .\" Copyright (c) 2010 Ed Schouten <ed@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
39 .Nd user accounting database functions
49 .Fn getutxid "const struct utmpx *id"
51 .Fn getutxline "const struct utmpx *line"
53 .Fn getutxuser "const char *user"
55 .Fn pututxline "const struct utmpx *utmpx"
57 .Fn setutxdb "int type" "const char *file"
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
65 The system stores these records in three databases, each having a
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
73 This file only contains process related entries, such as user login and
75 .It Pa /var/log/utx.lastlogin
76 Log of last user login entries per user.
77 This file is similar to the traditional
80 This file only contains user login records for users who have at least
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
87 This file may contain any type of record described below.
90 Each entry in these databases is defined by the structure
92 found in the include file
94 .Bd -literal -offset indent
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. */
108 field indicates the type of the log entry, which can have one of the
110 .Bl -tag -width LOGIN_PROCESS
112 No valid user accounting information.
114 Identifies time of system boot.
116 Identifies time of system shutdown.
118 Identifies time when system clock changed.
120 Identifies time after system clock changed.
122 Identifies a process.
124 Identifies a process spawned by the init process.
126 Identifies the session leader of a logged-in user.
128 Identifies a session leader who has exited.
135 are not processed by this implementation.
137 Other fields inside the structure are:
138 .Bl -tag -width ut_user
140 The time the event occurred.
141 This field is used for all types of entries, except
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
148 This field is only applicable to entries of type
155 The process identifier of the session leader of the login session.
156 This field is only applicable to entries of type
163 The user login name corresponding with the login session.
164 This field is only applicable to entries of type
170 entries this entry typically contains the name of the login process.
172 The name of the TTY character device, without the leading
174 prefix, corresponding with the device used to facilitate the user login
176 If no TTY character device is used, this field is left blank.
177 This field is only applicable to entries of type
182 The network hostname of the remote system, connecting to perform a user
184 If the user login session is not performed across a network, this field
186 This field is only applicable to entries of type
190 This implementation guarantees all inapplicable fields are discarded.
196 fields of the structure returned by the library functions are also
197 guaranteed to be null-terminated in this implementation.
201 function can be used to read the next entry from the user accounting
206 function searches for the next entry in the database of which the
207 behaviour is based on the
219 it will return the next entry whose
230 it will return the next entry whose
232 has one of the previously mentioned values and whose
238 function searches for the next entry in the database whose
246 is equal to the same field in
251 function searches for the next entry in the database whose
260 The previously mentioned functions will automatically try to open the
261 user accounting database if not already done so.
266 functions allow the database to be opened manually, causing the offset
267 within the user accounting database to be rewound.
270 function closes the database.
274 database always opens the active sessions database.
277 function opens the database identified by
279 whose value is either
284 It will open a custom file with filename
286 instead of the system-default if
289 Care must be taken that when using a custom filename,
291 still has to match with the actual format, since each database may use
296 function writes record
298 to the system-default user accounting databases.
301 determines which databases are modified.
308 will only be written to
309 .Pa /var/log/utx.log .
313 will also be written to
314 .Pa /var/run/utx.active
316 .Pa /var/log/utx.lastlogin .
320 will only be written to
323 .Pa /var/run/utx.active
331 is equal has been found in the latter.
333 In addition, entries of type
337 will cause all existing entries in
338 .Pa /var/run/utx.active
341 All entries whose type has not been mentioned previously, are discarded
342 by this implementation of
344 This implementation also ignores the value of
353 functions return a pointer to an
355 structure that matches the mentioned constraints on success or
357 when reaching the end-of-file or when an error occurs.
361 function returns a pointer to an
363 structure containing a copy of the structure written to disk upon
373 and an entry with an identifier with a value equal to the field
375 was not found; the global variable
377 is set to indicate the error.
381 function returns 0 if the user accounting database was opened
383 Otherwise, -1 is returned and the global variable
385 is set to indicate the error.
387 In addition to the error conditions described in
394 function can generate the following errors:
399 is DEAD_PROCESS, and the process entry could not be found.
403 is not supported by this implementation.
405 In addition to the error conditions described in
409 function can generate the following errors:
414 argument contains a value not supported by this implementation.
416 The file format is invalid.
435 functions are expected to conform to
440 function deviates from the standard by writing its records to multiple
441 database files, depending on its
443 This prevents the need for special utility functions to update the other
444 databases, such as the
448 functions which are available in other implementations.
449 It also tries to replace
451 entries in the active sessions database when storing
453 entries and no entry with the same value for
456 The standard always requires a new entry to be allocated, which could
457 cause an unbounded growth of the database.
472 These functions appeared in
478 .An Ed Schouten Aq ed@FreeBSD.org