--- endutxent.3.orig 2007-04-08 18:49:40.000000000 -0700 +++ endutxent.3 2007-04-08 19:03:43.000000000 -0700 @@ -34,7 +34,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd September 26, 2002 +.Dd June 29, 2006 .Dt ENDUTXENT 3 .Os .Sh NAME @@ -54,11 +54,11 @@ .Ft struct utmpx * .Fn getutxent void .Ft struct utmpx * -.Fn getutxid "const struct utmpx *" +.Fn getutxid "const struct utmpx *id" .Ft struct utmpx * -.Fn getutxline "const struct utmpx *" +.Fn getutxline "const struct utmpx *line" .Ft struct utmpx * -.Fn pututxline "const struct utmpx *" +.Fn pututxline "const struct utmpx *utx" .Ft void .Fn setutxent void .Sh DESCRIPTION @@ -98,6 +98,7 @@ .Xr utmpx 5 entry line to the accounting database, replacing a previous entry for the same user if it exists. +Only the superuser may write to the accounting database. .Ss The utmpx structure The .Nm utmpx @@ -105,27 +106,21 @@ .Pp .Bd -literal struct utmpx { - char ut_name[_UTX_USERSIZE]; /* login name */ - char ut_id[_UTX_IDSIZE]; /* inittab id */ - char ut_line[_UTX_LINESIZE]; /* tty name */ - char ut_host[_UTX_HOSTSIZE]; /* host name */ - uint16_t ut_session; /* session id used for windowing */ - uint16_t ut_type; /* type of this entry */ - pid_t ut_pid; /* process id creating the entry */ - struct { - uint16_t e_termination; /* process termination signal */ - uint16_t e_exit; /* process exit status */ - } ut_exit; - struct sockaddr_storage ut_ss; /* address where entry was made from */ - struct timeval ut_tv; /* time entry was created */ - uint32_t ut_pad[10]; /* reserved for future use */ + char ut_user[_UTX_USERSIZE]; /* login name */ + char ut_id[_UTX_IDSIZE]; /* id */ + char ut_line[_UTX_LINESIZE]; /* tty name */ + pid_t ut_pid; /* process id creating the entry */ + short ut_type; /* type of this entry */ + struct timeval ut_tv; /* time entry was created */ + char ut_host[_UTX_HOSTSIZE]; /* host name */ + __uint32_t ut_pad[16]; /* reserved for future use */ }; .Ed .Pp Valid entries for .Fa ut_type are: -.Bl -tag -width LOGIN_PROCESSXX -compact -offset indent +.Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent .It Dv BOOT_TIME Time of a system boot. .It Dv DEAD_PROCESS @@ -143,11 +138,115 @@ Time before system clock change. .It Dv RUN_LVL Run level. -Provided for compatibility, not used on -.Nx . +Provided for compatibility, not used. .It Dv USER_PROCESS A user process. +.It Dv SHUTDOWN_TIME +Time of system shutdown (extension to the standards). .El +.Pp +For each value of +.Fa ut_type , +the other fields with meaningful values are as follows: +.Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent +.It Dv BOOT_TIME +.Fa ut_tv +.It Dv DEAD_PROCESS +.Fa ut_id , +.Fa ut_pid , +.Fa ut_tv +.It Dv EMPTY +(no others) +.It Dv INIT_PROCESS +.Fa ut_id , +.Fa ut_pid , +.Fa ut_tv +.It Dv LOGIN_PROCESS +.Fa ut_id , +.Fa ut_user +(implementation-defined name of the login process), +.Fa ut_pid , +.Fa ut_tv +.It Dv NEW_TIME +.Fa ut_tv +.It Dv OLD_TIME +.Fa ut_tv +.It Dv RUN_LVL +(no used) +.It Dv USER_PROCESS +.Fa ut_id , +.Fa ut_user +(login name of the user), +.Fa ut_line , +.Fa ut_pid , +.Fa ut_host +(hostname of remote user) +.Fa ut_tv +.It Dv SHUTDOWN_TIME +.Fa ut_tv +.El +.Ss Other extensions to the standards +The +.Fa ut_tv +value may also be OR-ed with the following masks: +.Bl -tag -width XXXX -compact -offset indent +.It Dv UTMPX_AUTOFILL_MASK +Depending on the +.Fa ut_type +value, other fields are automatically filled in (as specified in the +meaningful fields table above). +In particular, the +.Fa ut_id +field will be set using the convention of the last four characters of the +.Fa ut_line +field (itself filled in automatically from the tty name of the device connected +to the standard input, output or error, whichever is available). +Note that it is more efficient to fill in as many values as are already +available beforehand, rather than have then automatically filled in. +.It Dv UTMPX_DEAD_IF_CORRESPONDING_MASK +When +.Fa ut_type +value is +.Dv DEAD_PROCESS, a call to +.Fn pututxline +will succeed only if a corresponding entry already exists with a +.Fa ut_type +value of +.Dv USER_PROCESS . +.El +.Pp +Note that the above mask values do not show up in any file format, or in +any subsequent reads of the data. +.Pp +To support +.Pa wtmpx +and +.Pa lastlogx +equivalent capability, +.Fn pututxline +automatically writes to the appropriate files. +Additional APIs to read these files is available in +.Xr endutxent_wtmp 3 +and +.Xr getlastlogx 3 . +.Ss Backward compatibility +Successful calls to +.Fn pututxline +will automatically write equivalent entries into the +.Pa utmp , +.Pa wtmp +and +.Pa lastlog +files. +Programs that read these old files should work as expected. +However, directly writing to these files does not make corresponding +entries in +.Pa utmpx +and the +.Pa wtmpx +and +.Pa lastlogx +equivalent files, so such write-access is deprecated. .Sh RETURN VALUES .Fn getutxent returns the next entry, or @@ -159,11 +258,45 @@ return the matching structure on success, or .Dv NULL if no match was found. +.Pp .Fn pututxline returns the structure that was successfully written, or -.Dv NULL . +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +No errors are defined for the +.Fn endutxent , +.Fn getutxent , +.Fn getutxid , +.Fn getutxline , +and +.Fn setutxent +functions. +.Pp +The +.Fn pututxline +function may fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The process does not have appropriate privileges. +.It Bq Er EINVAL +The +.Dv UTMPX_DEAD_IF_CORRESPONDING_MASK +flags was specified along with +.Dv DEAD_PROCESS , +but no corresponding entry with +.Dv USER_PROCESS +was found. +.El +.Pp +Other errors may be returned if +.Dv UTMPX_AUTOFILL_MASK +was specified, and a field could not be auto-filled. .Sh SEE ALSO -.Xr logwtmpx 3 , +.Xr endutxent_wtmp 3 , +.Xr getlastlogx 3 , .Xr utmpx 5 .Sh STANDARDS The