gen/endutxent.3

   1 .\"     $NetBSD: endutxent.3,v 1.5 2008/04/30 13:10:50 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Thomas Klausner.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd June 29, 2006
  31 .Dt ENDUTXENT 3
  32 .Os
  33 .Sh NAME
  34 .Nm endutxent ,
  35 .Nm getutxent ,
  36 .Nm getutxid ,
  37 .Nm getutxline ,
  38 .Nm pututxline ,
  39 .Nm setutxent
  40 .Nd user accounting database functions
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In utmpx.h
  45 .Ft void
  46 .Fn endutxent void
  47 .Ft struct utmpx *
  48 .Fn getutxent void
  49 .Ft struct utmpx *
  50 .Fn getutxid "const struct utmpx *id"
  51 .Ft struct utmpx *
  52 .Fn getutxline "const struct utmpx *line"
  53 .Ft struct utmpx *
  54 .Fn pututxline "const struct utmpx *utx"
  55 .Ft void
  56 .Fn setutxent void
  57 .Sh DESCRIPTION
  58 These functions provide access to the
  59 .Xr utmpx 5
  60 user accounting database.
  61 .Pp
  62 .Fn getutxent
  63 reads the next entry from the database;
  64 if the database was not yet open, it also opens it.
  65 .Fn setutxent
  66 resets the database, so that the next
  67 .Fn getutxent
  68 call will get the first entry.
  69 .Fn endutxent
  70 closes the database.
  71 .Pp
  72 .Fn getutxid
  73 returns the next entry of the type specified in its argument's
  74 .Va ut_type
  75 field, or
  76 .Dv NULL
  77 if none is found.
  78 .Fn getutxline
  79 returns the next
  80 .Dv LOGIN_PROCESS
  81 or
  82 .Dv USER_PROCESS
  83 entry which has the same name as specified in the
  84 .Va ut_line
  85 field, or
  86 .Dv NULL
  87 if no match is found.
  88 .Pp
  89 .Fn pututxline
  90 adds the argument
  91 .Xr utmpx 5
  92 entry line to the accounting database, replacing a previous entry for
  93 the same user if it exists.
  94 Only the superuser may write to the accounting database.
  95 .Ss The utmpx structure
  96 The
  97 .Nm utmpx
  98 structure has the following definition:
  99 .Pp
 100 .Bd -literal
 101 struct utmpx {
 102         char ut_user[_UTX_USERSIZE];    /* login name */
 103         char ut_id[_UTX_IDSIZE];        /* id */
 104         char ut_line[_UTX_LINESIZE];    /* tty name */
 105         pid_t ut_pid;                   /* process id creating the entry */
 106         short ut_type;                  /* type of this entry */
 107         struct timeval ut_tv;           /* time entry was created */
 108         char ut_host[_UTX_HOSTSIZE];    /* host name */
 109         __uint32_t ut_pad[16];          /* reserved for future use */
 110 };
 111 .Ed
 112 .Pp
 113 Valid entries for
 114 .Fa ut_type
 115 are:
 116 .Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent
 117 .It Dv BOOT_TIME
 118 Time of a system boot.
 119 .It Dv DEAD_PROCESS
 120 A session leader exited.
 121 .It Dv EMPTY
 122 No valid user accounting information.
 123 .It Dv INIT_PROCESS
 124 A process spawned by
 125 .Xr init 8 .
 126 .It Dv LOGIN_PROCESS
 127 The session leader of a logged-in user.
 128 .It Dv NEW_TIME
 129 Time after system clock change.
 130 .It Dv OLD_TIME
 131 Time before system clock change.
 132 .It Dv RUN_LVL
 133 Run level.
 134 Provided for compatibility, not used.
 135 .It Dv USER_PROCESS
 136 A user process.
 137 .It Dv SHUTDOWN_TIME
 138 Time of system shutdown (extension to the standards).
 139 .El
 140 .Pp
 141 For each value of
 142 .Fa ut_type ,
 143 the other fields with meaningful values are as follows:
 144 .Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent
 145 .It Dv BOOT_TIME
 146 .Fa ut_tv
 147 .It Dv DEAD_PROCESS
 148 .Fa ut_id ,
 149 .Fa ut_pid ,
 150 .Fa ut_tv
 151 .It Dv EMPTY
 152 (no others)
 153 .It Dv INIT_PROCESS
 154 .Fa ut_id ,
 155 .Fa ut_pid ,
 156 .Fa ut_tv
 157 .It Dv LOGIN_PROCESS
 158 .Fa ut_id ,
 159 .Fa ut_user
 160 (implementation-defined name of the login process),
 161 .Fa ut_pid ,
 162 .Fa ut_tv
 163 .It Dv NEW_TIME
 164 .Fa ut_tv
 165 .It Dv OLD_TIME
 166 .Fa ut_tv
 167 .It Dv RUN_LVL
 168 (no used)
 169 .It Dv USER_PROCESS
 170 .Fa ut_id ,
 171 .Fa ut_user
 172 (login name of the user),
 173 .Fa ut_line ,
 174 .Fa ut_pid ,
 175 .Fa ut_host
 176 (hostname of remote user)
 177 .Fa ut_tv
 178 .It Dv SHUTDOWN_TIME
 179 .Fa ut_tv
 180 .El
 181 .Ss Other extensions to the standards
 182 The
 183 .Fa ut_type
 184 value may also be OR-ed with the following masks:
 185 .Bl -tag -width XXXX -compact -offset indent
 186 .It Dv UTMPX_AUTOFILL_MASK
 187 Depending on the main part of
 188 .Fa ut_type
 189 value, other fields are automatically filled in (as specified in the
 190 meaningful fields table above).
 191 In particular, the
 192 .Fa ut_id
 193 field will be set using the convention of the last four characters of the
 194 .Fa ut_line
 195 field (itself filled in automatically from the tty name of the device connected
 196 to the standard input, output or error, whichever is available).
 197 Note that it is more efficient to fill in as many values as are already
 198 available beforehand, rather than have then automatically filled in.
 199 .It Dv UTMPX_DEAD_IF_CORRESPONDING_MASK
 200 When
 201 .Fa ut_type
 202 value is
 203 .Dv DEAD_PROCESS, a call to
 204 .Fn pututxline
 205 will succeed only if a corresponding entry already exists with a
 206 .Fa ut_type
 207 value of
 208 .Dv USER_PROCESS .
 209 .El
 210 .Pp
 211 Note that the above mask values do not show up in any file format, or in
 212 any subsequent reads of the data.
 213 .Pp
 214 To support
 215 .Pa wtmpx
 216 and
 217 .Pa lastlogx
 218 equivalent capability,
 219 .Fn pututxline
 220 automatically writes to the appropriate files.
 221 Additional APIs to read these files is available in
 222 .Xr endutxent_wtmp 3
 223 and
 224 .Xr getlastlogx 3 .
 225 .Ss Backward compatibility
 226 Successful calls to
 227 .Fn pututxline
 228 will automatically write equivalent entries into the
 229 .Pa utmp ,
 230 .Pa wtmp
 231 and
 232 .Pa lastlog
 233 files.
 234 Programs that read these old files should work as expected.
 235 However, directly writing to these files does not make corresponding
 236 entries in
 237 .Pa utmpx
 238 and the
 239 .Pa wtmpx
 240 and
 241 .Pa lastlogx
 242 equivalent files, so such write-access is deprecated.
 243 .Sh RETURN VALUES
 244 .Fn getutxent
 245 returns the next entry, or
 246 .Dv NULL
 247 on failure (end of database or problems reading from the database).
 248 .Fn getutxid
 249 and
 250 .Fn getutxline
 251 return the matching structure on success, or
 252 .Dv NULL
 253 if no match was found.
 254 .Pp
 255 .Fn pututxline
 256 returns the structure that was successfully written, or
 257 .Dv NULL
 258 is returned and the global variable
 259 .Va errno
 260 is set to indicate the error.
 261 .Sh ERRORS
 262 No errors are defined for the
 263 .Fn endutxent ,
 264 .Fn getutxent ,
 265 .Fn getutxid ,
 266 .Fn getutxline ,
 267 and
 268 .Fn setutxent
 269 functions.
 270 .Pp
 271 The
 272 .Fn pututxline
 273 function may fail if:
 274 .Bl -tag -width Er
 275 .It Bq Er EPERM
 276 The process does not have appropriate privileges.
 277 .It Bq Er EINVAL
 278 The
 279 .Dv UTMPX_DEAD_IF_CORRESPONDING_MASK
 280 flags was specified along with
 281 .Dv DEAD_PROCESS ,
 282 but no corresponding entry with
 283 .Dv USER_PROCESS
 284 was found.
 285 .El
 286 .Pp
 287 Other errors may be returned if
 288 .Dv UTMPX_AUTOFILL_MASK
 289 was specified, and a field could not be auto-filled.
 290 .Sh SEE ALSO
 291 .Xr endutxent_wtmp 3 ,
 292 .Xr getlastlogx 3 ,
 293 .Xr utmpx 5
 294 .Sh STANDARDS
 295 The
 296 .Fn endutxent ,
 297 .Fn getutxent ,
 298 .Fn getutxid ,
 299 .Fn getutxline ,
 300 .Fn pututxline ,
 301 .Fn setutxent
 302 all conform to
 303 .St -p1003.1-2001
 304 (XSI extension), and previously to
 305 .St -xpg4.2 .
 306 The fields
 307 .Fa ut_user ,
 308 .Fa ut_id ,
 309 .Fa ut_line ,
 310 .Fa ut_pid ,
 311 .Fa ut_type ,
 312 and
 313 .Fa ut_tv
 314 conform to
 315 .St -p1003.1-2001
 316 (XSI extension), and previously to
 317 .St -xpg4.2 .
 318 .\" .Fa ut_host ,
 319 .\" .Fa ut_session ,
 320 .\" .Fa ut_exit ,
 321 .\" and
 322 .\" .Fa ut_ss
 323 .\" are from
 324 .\" SVR3/4?
 325 .\" .Dv RUN_LVL
 326 .\" is for compatibility with
 327 .\" what exactly?
 328 .\" .Sh HISTORY
 329 .\" The
 330 .\" .Nm utmpx ,
 331 .\" .Nm wtmpx ,
 332 .\" and
 333 .\" .Nm lastlogx
 334 .\" files first appeared in
 335 .\" SVR3? 4?