Date: Fri, 8 Jan 2010 17:21:57 +0000 (UTC) From: Ed Schouten <ed@FreeBSD.org> To: src-committers@freebsd.org, svn-src-user@freebsd.org Subject: svn commit: r201808 - user/ed/utmpx/lib/libc/gen Message-ID: <201001081721.o08HLvgu039063@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201001081721.o08HLvgu039063>