svn commit: r201808 - user/ed/utmpx/lib/libc/gen

[Ed Schouten]

Author: ed
Date: Fri Jan  8 17:21:56 2010
New Revision: 201808
URL: http://svn.freebsd.org/changeset/base/201808

Log:
  Document utmpx a little further.

Modified:
  user/ed/utmpx/lib/libc/gen/getutxent.3

Modified: user/ed/utmpx/lib/libc/gen/getutxent.3
==============================================================================
--- user/ed/utmpx/lib/libc/gen/getutxent.3	Fri Jan  8 17:20:41 2010	(r201807)
+++ user/ed/utmpx/lib/libc/gen/getutxent.3	Fri Jan  8 17:21:56 2010	(r201808)
@@ -171,7 +171,178 @@ If the user login session is not perform
 is left blank.
 This field is only applicable to entries of type
 .Dv USER_PROCESS .
+.It Fa ut_pid
+The process identifier of the session leader of the login session.
+This field is only applicable to entries of type
+.Dv USER_PROCESS ,
+.Dv INIT_PROCESS ,
+.Dv LOGIN_PROCESS
+and
+.Dv DEAD_PROCESS .
+.It Fa ut_tv
+The time the event occured.
+This field is used for all types of entries.
 .El
+.Pp
+This implementation guarantees all inapplicable fields to be discarded.
+The
+.Fa ut_user ,
+.Fa ut_line
+and
+.Fa ut_host
+fields of the structure returned by the library functions are also
+guaranteed to be null-terminated in this implementation.
+.Pp
+The
+.Fn getutxent
+function can be used to read the next entry from the user accounting
+database.
+.Pp
+The
+.Fn getutxid
+function searches for the next entry in the database of which the
+behaviour is based on the
+.Fa ut_type
+field of
+.Fa id .
+If
+.Fa ut_type
+has a value of
+.Dv BOOT_TIME ,
+.Dv SHUTDOWN_TIME ,
+.Dv OLD_TIME
+or
+.Dv NEW_TIME ,
+it will return the next entry whose
+.Fa ut_type
+has an equal value.
+If
+.Fa ut_type
+has a value of
+.Dv INIT_PROCESS ,
+.Dv LOGIN_PROCESS ,
+.Dv USER_PROCESS
+or
+.Dv DEAD_PROCESS ,
+it will return the next entry whose
+.Fa ut_type
+has one of the previously mentioned values and whose
+.Fa ut_id
+is equal.
+.Pp
+The
+.Fn getutxline
+function searches for the next entry in the database whose
+.Fa ut_type
+has a value of
+.Dv LOGIN_PROCESS
+or
+.Dv USER_PROCESS
+and whose
+.Fa ut_line
+is equal to the the same field in
+.Fa line .
+.Pp
+The
+.Fn getutxuser
+function searches for the next entry in the database whose
+.Fa ut_type
+has a value of
+.Dv USER_PROCESS
+and whose
+.Fa ut_user
+is equal to
+.Fa user .
+.Pp
+The previously mentioned functions will automatically try to open the
+user accounting database if not already done so.
+The
+.Fn setutxdb
+and
+.Fn setutxent
+functions allow the database to be opened manually, causing the offset
+within the user accounting database to be rewound.
+The
+.Fn endutxent
+function closes the database.
+.Pp
+The
+.Fn setutxent
+database always opens the active sessions database.
+The
+.Fn setutxdb
+function opens the database identified by
+.Fa type ,
+whose value is either
+.Dv UTXDB_ACTIVE ,
+.Dv UTXDB_LASTLOGIN
+or
+.Dv UTXDB_LOG .
+It will open a custom file with filename
+.Fa file
+instead of the system-default if
+.Fa file
+is not null.
+Care must be taken that when using a custom filename,
+.Fa type
+still has to match with the actual format, since each database may use
+its own file format.
+.Pp
+The
+.Fn pututxline
+function writes record
+.Fa utmpx
+to the system-default user accounting databases.
+The value of
+.Fa ut_type
+determines which databases are modified.
+.Pp
+Entries of type
+.Dv BOOT_TIME ,
+.Dv SHUTDOWN_TIME ,
+.Dv OLD_TIME
+and
+.Dv NEW_TIME
+will only be written to
+.Pa /var/log/utx.log .
+.Pp
+Entries of type
+.Dv USER_PROCESS
+will also be written to
+.Pa /var/run/utx.active .
+It will only be written to
+.Pa /var/log/utx.lastlogin
+if
+.Fa ut_tv
+for that user has a greater value than the existing entry or when no
+entry for the user has been found.
+.Pp
+Entries of type
+.Dv DEAD_PROCESS
+will only be written to
+.Pa /var/log/utx.log
+and
+.Pa /var/run/utx.active
+if a corresponding
+.Dv USER_PROCESS ,
+.Dv INIT_PROCESS
+or
+.Dv DEAD_PROCESS
+entry whose
+.Fa ut_id
+is equal has been found in the latter.
+.Pp
+In addition, entries of type
+.Dv BOOT_TIME
+and
+.Dv SHUTDOWN_TIME
+will cause all entries in
+.Pa /var/run/utx.active
+to be discarded.
+.Pp
+All entries whose type has not been previously mentioned, are discarded
+by this implementation of
+.Fn pututxline .
 .Sh RETURN VALUES
 .Sh SEE ALSO
 .Sh STANDARDS