Libc-594.9.5.tar.gz

[apple/libc.git] / gen / NetBSD / endutxent.3.patch

--- 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