diff options
Diffstat (limited to 'lib/libulog/ulog_getutxent.3')
-rw-r--r-- | lib/libulog/ulog_getutxent.3 | 81 |
1 files changed, 72 insertions, 9 deletions
diff --git a/lib/libulog/ulog_getutxent.3 b/lib/libulog/ulog_getutxent.3 index 5960a90..99c1ea1 100644 --- a/lib/libulog/ulog_getutxent.3 +++ b/lib/libulog/ulog_getutxent.3 @@ -24,11 +24,13 @@ .\" .\" $FreeBSD$ .\" -.Dd December 2, 2009 +.Dd December 5, 2009 .Os .Dt ULOG_GETUTXENT 3 .Sh NAME .Nm ulog_getutxent , +.Nm ulog_getutxline , +.Nm ulog_pututxline , .Nm ulog_setutxent , .Nm ulog_endutxent .Nd read user login records @@ -38,6 +40,10 @@ .In ulog.h .Ft struct ulog_utmpx * .Fn ulog_getutxent "void" +.Ft struct ulog_utmpx * +.Fn ulog_getutxline "const struct ulog_utmpx *line" +.Ft struct ulog_utmpx * +.Fn ulog_pututxline "const struct ulog_utmpx *utmpx" .Ft void .Fn ulog_setutxent "void" .Ft void @@ -49,10 +55,12 @@ function returns a pointer to an object, with the following structure, containing stored information of an active user login session. .Bd -literal struct ulog_utmpx { - char *ut_user; /* Username. */ - char *ut_line; /* TTY device. */ - char *ut_host; /* Remote hostname. */ - short ut_type; /* Type of entry. */ + char ut_user[]; /* Username. */ + char ut_id[]; /* Private data. */ + char ut_line[]; /* TTY device. */ + char ut_host[]; /* Remote hostname. */ + pid_t ut_pid; /* Process identifier. */ + short ut_type; /* Type of entry. */ struct timeval ut_tv; /* Timestamp. */ }; .Ed @@ -61,6 +69,9 @@ The fields are as follows: .Bl -tag -width ut_user .It Fa ut_user The username of the logged in user. +.It Fa ut_id +Private data that can be used to later identify the record. +This implementation is not capable of storing this value on disk. .It Fa ut_line The pathname of the TTY device, without the leading .Pa /dev/ @@ -68,6 +79,9 @@ directory. .It Fa ut_host An optional hostname of a remote system, if the login session is provided through a networked login service. +.It Fa ut_pid +Process identifier of the session leader of the login session. +This implementation is not capable of storing this value on disk. .It Fa ut_type The .Fa ut_type @@ -76,28 +90,42 @@ following values: .Bl -tag -width SHUTDOWN_TIME .It Dv EMPTY No valid user accounting information. +.It Dv BOOT_TIME +Identifies time of system boot. .It Dv OLD_TIME Identifies time when system clock changed. .It Dv NEW_TIME Identifies time after system clock changed. .It Dv USER_PROCESS Identifies a process. +.It Dv INIT_PROCESS +Identifies a process spawned by the init process. +.It Dv LOGIN_PROCESS +Identifies the session leader of a logged-in user. .It Dv DEAD_PROCESS Identifies a session leader who has exited. .It Dv SHUTDOWN_TIME Identifies time when system was shut down. -.It Dv REBOOT_TIME -Identifies time when system was rebooted. .El .It Fa ut_tv Timestamp indicating when the entry was last modified. .El .Pp +This implementation guarantees all strings returned in the structure to +be null terminated. +.Pp The .Fn ulog_getutxent function reads the next entry from the utmp file, opening the file if necessary. The +.Fn ulog_getutxline +function reads entries from the utmp file, until finding an entry which +shares the same +.Fa ut_line +as the structure +.Fa line . +The .Fn ulog_setutxent opens the file, closing it first if already opened. The @@ -106,15 +134,50 @@ function closes any open files. .Pp The .Fn ulog_getutxent -function reads from the beginning of the file until and EOF is +and +.Fn ulog_getutxline +functions read from the beginning of the file until and EOF is encountered. +.Pp +The +.Fn ulog_pututxline +function writes a new entry to the file. .Sh RETURN VALUES The .Fn ulog_getutxent -function returns a null pointer on EOF or error. +and +.Fn ulog_getutxline +functions return a null pointer on EOF or error. .Sh SEE ALSO .Xr ulog_login 3 , +.Xr ulog_setutxfile 3 , .Xr utmp 5 +.Sh STANDARDS +This interface is similar to +.In utmpx.h +described in +.St -p1003.1-2008 , +but incompatible. +The underlying file format does not allow a correctly behaving +implementation of the standardized interface. +.Pp +This programming interface has been designed to ease the migration +towards +.In utmpx.h . +If +.Dv _ULOG_POSIX_NAMES +is set before inclusion of +.In ulog.h , +it is also possible to use the +.Vt utmpx +structure and the +.Fn getutxent , +.Fn getutxline , +.Fn pututxline , +.Fn setutxent +and +.Fn endutxent +functions. .Sh HISTORY These functions appeared in .Fx 9.0 . |