gen/endutxent.3

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