gen/NetBSD/endutxent.3.patch

   1 --- endutxent.3.orig    2009-04-03 22:48:14.000000000 -0700
   2 +++ endutxent.3 2009-04-04 18:16:44.000000000 -0700
   3 @@ -34,7 +34,7 @@
   4  .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   5  .\" POSSIBILITY OF SUCH DAMAGE.
   6  .\"
   7 -.Dd September 26, 2002
   8 +.Dd June 29, 2006
   9  .Dt ENDUTXENT 3
  10  .Os
  11  .Sh NAME
  12 @@ -54,11 +54,11 @@
  13  .Ft struct utmpx *
  14  .Fn getutxent void
  15  .Ft struct utmpx *
  16 -.Fn getutxid "const struct utmpx *"
  17 +.Fn getutxid "const struct utmpx *id"
  18  .Ft struct utmpx *
  19 -.Fn getutxline "const struct utmpx *"
  20 +.Fn getutxline "const struct utmpx *line"
  21  .Ft struct utmpx *
  22 -.Fn pututxline "const struct utmpx *"
  23 +.Fn pututxline "const struct utmpx *utx"
  24  .Ft void
  25  .Fn setutxent void
  26  .Sh DESCRIPTION
  27 @@ -98,6 +98,7 @@
  28  .Xr utmpx 5
  29  entry line to the accounting database, replacing a previous entry for
  30  the same user if it exists.
  31 +Only the superuser may write to the accounting database.
  32  .Ss The utmpx structure
  33  The
  34  .Nm utmpx
  35 @@ -105,27 +106,21 @@
  36  .Pp
  37  .Bd -literal
  38  struct utmpx {
  39 -        char ut_name[_UTX_USERSIZE];    /* login name */
  40 -        char ut_id[_UTX_IDSIZE];        /* inittab id */
  41 -        char ut_line[_UTX_LINESIZE];    /* tty name */
  42 -        char ut_host[_UTX_HOSTSIZE];    /* host name */
  43 -        uint16_t ut_session;            /* session id used for windowing */
  44 -        uint16_t ut_type;               /* type of this entry */
  45 -        pid_t ut_pid;                   /* process id creating the entry */
  46 -        struct {
  47 -                uint16_t e_termination; /* process termination signal */
  48 -                uint16_t e_exit;        /* process exit status */
  49 -        } ut_exit;
  50 -        struct sockaddr_storage ut_ss;  /* address where entry was made from */
  51 -        struct timeval ut_tv;           /* time entry was created */
  52 -        uint32_t ut_pad[10];            /* reserved for future use */
  53 +       char ut_user[_UTX_USERSIZE];    /* login name */
  54 +       char ut_id[_UTX_IDSIZE];        /* id */
  55 +       char ut_line[_UTX_LINESIZE];    /* tty name */
  56 +       pid_t ut_pid;                   /* process id creating the entry */
  57 +       short ut_type;                  /* type of this entry */
  58 +       struct timeval ut_tv;           /* time entry was created */
  59 +       char ut_host[_UTX_HOSTSIZE];    /* host name */
  60 +       __uint32_t ut_pad[16];          /* reserved for future use */
  61  };
  62  .Ed
  63  .Pp
  64  Valid entries for
  65  .Fa ut_type
  66  are:
  67 -.Bl -tag -width LOGIN_PROCESSXX -compact -offset indent
  68 +.Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent
  69  .It Dv BOOT_TIME
  70  Time of a system boot.
  71  .It Dv DEAD_PROCESS
  72 @@ -143,11 +138,115 @@
  73  Time before system clock change.
  74  .It Dv RUN_LVL
  75  Run level.
  76 -Provided for compatibility, not used on
  77 -.Nx .
  78 +Provided for compatibility, not used.
  79  .It Dv USER_PROCESS
  80  A user process.
  81 +.It Dv SHUTDOWN_TIME
  82 +Time of system shutdown (extension to the standards).
  83  .El
  84 +.Pp
  85 +For each value of
  86 +.Fa ut_type ,
  87 +the other fields with meaningful values are as follows:
  88 +.Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent
  89 +.It Dv BOOT_TIME
  90 +.Fa ut_tv
  91 +.It Dv DEAD_PROCESS
  92 +.Fa ut_id ,
  93 +.Fa ut_pid ,
  94 +.Fa ut_tv
  95 +.It Dv EMPTY
  96 +(no others)
  97 +.It Dv INIT_PROCESS
  98 +.Fa ut_id ,
  99 +.Fa ut_pid ,
 100 +.Fa ut_tv
 101 +.It Dv LOGIN_PROCESS
 102 +.Fa ut_id ,
 103 +.Fa ut_user
 104 +(implementation-defined name of the login process),
 105 +.Fa ut_pid ,
 106 +.Fa ut_tv
 107 +.It Dv NEW_TIME
 108 +.Fa ut_tv
 109 +.It Dv OLD_TIME
 110 +.Fa ut_tv
 111 +.It Dv RUN_LVL
 112 +(no used)
 113 +.It Dv USER_PROCESS
 114 +.Fa ut_id ,
 115 +.Fa ut_user
 116 +(login name of the user),
 117 +.Fa ut_line ,
 118 +.Fa ut_pid ,
 119 +.Fa ut_host
 120 +(hostname of remote user)
 121 +.Fa ut_tv
 122 +.It Dv SHUTDOWN_TIME
 123 +.Fa ut_tv
 124 +.El
 125 +.Ss Other extensions to the standards
 126 +The
 127 +.Fa ut_type
 128 +value may also be OR-ed with the following masks:
 129 +.Bl -tag -width XXXX -compact -offset indent
 130 +.It Dv UTMPX_AUTOFILL_MASK
 131 +Depending on the main part of
 132 +.Fa ut_type
 133 +value, other fields are automatically filled in (as specified in the
 134 +meaningful fields table above).
 135 +In particular, the
 136 +.Fa ut_id
 137 +field will be set using the convention of the last four characters of the
 138 +.Fa ut_line
 139 +field (itself filled in automatically from the tty name of the device connected
 140 +to the standard input, output or error, whichever is available).
 141 +Note that it is more efficient to fill in as many values as are already
 142 +available beforehand, rather than have then automatically filled in.
 143 +.It Dv UTMPX_DEAD_IF_CORRESPONDING_MASK
 144 +When
 145 +.Fa ut_type
 146 +value is
 147 +.Dv DEAD_PROCESS, a call to
 148 +.Fn pututxline
 149 +will succeed only if a corresponding entry already exists with a
 150 +.Fa ut_type
 151 +value of
 152 +.Dv USER_PROCESS .
 153 +.El
 154 +.Pp
 155 +Note that the above mask values do not show up in any file format, or in
 156 +any subsequent reads of the data.
 157 +.Pp
 158 +To support
 159 +.Pa wtmpx
 160 +and
 161 +.Pa lastlogx
 162 +equivalent capability,
 163 +.Fn pututxline
 164 +automatically writes to the appropriate files.
 165 +Additional APIs to read these files is available in
 166 +.Xr endutxent_wtmp 3
 167 +and
 168 +.Xr getlastlogx 3 .
 169 +.Ss Backward compatibility
 170 +Successful calls to
 171 +.Fn pututxline
 172 +will automatically write equivalent entries into the
 173 +.Pa utmp ,
 174 +.Pa wtmp
 175 +and
 176 +.Pa lastlog
 177 +files.
 178 +Programs that read these old files should work as expected.
 179 +However, directly writing to these files does not make corresponding
 180 +entries in
 181 +.Pa utmpx
 182 +and the
 183 +.Pa wtmpx
 184 +and
 185 +.Pa lastlogx
 186 +equivalent files, so such write-access is deprecated.
 187  .Sh RETURN VALUES
 188  .Fn getutxent
 189  returns the next entry, or
 190 @@ -159,11 +258,45 @@
 191  return the matching structure on success, or
 192  .Dv NULL
 193  if no match was found.
 194 +.Pp
 195  .Fn pututxline
 196  returns the structure that was successfully written, or
 197 -.Dv NULL .
 198 +.Dv NULL
 199 +is returned and the global variable
 200 +.Va errno
 201 +is set to indicate the error.
 202 +.Sh ERRORS
 203 +No errors are defined for the
 204 +.Fn endutxent ,
 205 +.Fn getutxent ,
 206 +.Fn getutxid ,
 207 +.Fn getutxline ,
 208 +and
 209 +.Fn setutxent
 210 +functions.
 211 +.Pp
 212 +The
 213 +.Fn pututxline
 214 +function may fail if:
 215 +.Bl -tag -width Er
 216 +.It Bq Er EPERM
 217 +The process does not have appropriate privileges.
 218 +.It Bq Er EINVAL
 219 +The
 220 +.Dv UTMPX_DEAD_IF_CORRESPONDING_MASK
 221 +flags was specified along with
 222 +.Dv DEAD_PROCESS ,
 223 +but no corresponding entry with
 224 +.Dv USER_PROCESS
 225 +was found.
 226 +.El
 227 +.Pp
 228 +Other errors may be returned if
 229 +.Dv UTMPX_AUTOFILL_MASK
 230 +was specified, and a field could not be auto-filled.
 231  .Sh SEE ALSO
 232 -.Xr logwtmpx 3 ,
 233 +.Xr endutxent_wtmp 3 ,
 234 +.Xr getlastlogx 3 ,
 235  .Xr utmpx 5
 236  .Sh STANDARDS
 237  The