.\" 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
.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
.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
.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
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_type
+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 main part of
+.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
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
projects / apple / libc.git / blobdiff