lib/libc/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 .\"
  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 September 10, 2019
  31 .Dt ENDUTXENT 3
  32 .Os
  33 .Sh NAME
  34 .Nm endutxent ,
  35 .Nm getutxent ,
  36 .Nm getutxid ,
  37 .Nm getutxline ,
  38 .Nm getutxuser ,
  39 .Nm pututxline ,
  40 .Nm setutxent ,
  41 .Nm setutxdb
  42 .Nd user accounting database functions
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In utmpx.h
  47 .Ft void
  48 .Fn endutxent void
  49 .Ft struct utmpx *
  50 .Fn getutxent void
  51 .Ft struct utmpx *
  52 .Fn getutxid "const struct utmpx *"
  53 .Ft struct utmpx *
  54 .Fn getutxline "const struct utmpx *"
  55 .Ft struct utmpx *
  56 .Fn getutxuser "const char *user"
  57 .Ft struct utmpx *
  58 .Fn pututxline "const struct utmpx *"
  59 .Ft void
  60 .Fn setutxent void
  61 .Ft int
  62 .Fn setutxdb "utx_db_t db" "const char *fname"
  63 .Sh DESCRIPTION
  64 These functions provide access to the
  65 .Xr utmpx 5
  66 and
  67 .Xr wtmpx 5
  68 user accounting database.
  69 .Pp
  70 .Fn getutxent
  71 reads the next entry from the database;
  72 if the database was not yet open, it also opens it.
  73 .Fn setutxent
  74 resets the database, so that the next
  75 .Fn getutxent
  76 call will get the first entry.
  77 .Fn endutxent
  78 closes the database.
  79 .Pp
  80 .Fn getutxid
  81 returns the next entry of the type specified in its argument's
  82 .Va ut_type
  83 field, or
  84 .Dv NULL
  85 if none is found.
  86 .Fn getutxline
  87 returns the next
  88 .Dv LOGIN_PROCESS
  89 or
  90 .Dv USER_PROCESS
  91 entry which has the same name as specified in the
  92 .Va ut_line
  93 field, or
  94 .Dv NULL
  95 if no match is found.
  96 .Pp
  97 .Fn getutxuser
  98 searches for the next entry in the database whose
  99 .Fa ut_type
 100 has a value of
 101 .Dv USER_PROCESS
 102 and whose
 103 .Fa ut_user
 104 is equal to
 105 .Fa user .
 106 .Pp
 107 .Fn pututxline
 108 adds the argument
 109 .Xr utmpx 5
 110 entry line to the accounting database, replacing a previous entry for
 111 the same user if it exists.
 112 .Pp
 113 By default the aforementioned functions work on the default
 114 .Xr utmpx 5
 115 database. The function
 116 .Fn setutxdb
 117 allows to change the database type being operated on, as well
 118 as changing the path to that database.
 119 The first parameter
 120 .Ar db
 121 can be
 122 .Dv UTX_DB_UTMPX
 123 or
 124 .Dv UTX_DB_WTMPX
 125 and specifies which database to open. If
 126 .Ar fname
 127 is
 128 .Dv NULL
 129 the default path for each of these is used as described in
 130 .Xr utmpx 5
 131 and
 132 .Xr wtmpx 5 .
 133 Otherwise the path specified in
 134 .Ar fname
 135 is used as the database.
 136 .Ss The utmpx structure
 137 The
 138 .Nm utmpx
 139 structure has the following definition:
 140 .Bd -literal
 141 struct utmpx {
 142         char ut_name[_UTX_USERSIZE];    /* login name */
 143         char ut_id[_UTX_IDSIZE];        /* inittab id */
 144         char ut_line[_UTX_LINESIZE];    /* tty name */
 145         char ut_host[_UTX_HOSTSIZE];    /* host name */
 146         uint16_t ut_session;            /* session id used for windowing */
 147         short ut_type;                  /* type of this entry */
 148         pid_t ut_pid;                   /* process id creating the entry */
 149         struct {
 150                 uint16_t e_termination; /* process termination signal */
 151                 uint16_t e_exit;        /* process exit status */
 152         } ut_exit;
 153         struct sockaddr_storage ut_ss;  /* address where entry was made from */
 154         struct timeval ut_tv;           /* time entry was created */
 155         uint32_t ut_pad[10];            /* reserved for future use */
 156 };
 157 .Ed
 158 .Pp
 159 Valid entries for
 160 .Fa ut_type
 161 are:
 162 .Bl -tag -width LOGIN_PROCESSXX -compact -offset indent
 163 .It Dv BOOT_TIME
 164 Time of a system boot.
 165 .It Dv DEAD_PROCESS
 166 A session leader exited.
 167 .It Dv EMPTY
 168 No valid user accounting information.
 169 .It Dv INIT_PROCESS
 170 A process spawned by
 171 .Xr init 8 .
 172 .It Dv LOGIN_PROCESS
 173 The session leader of a logged-in user.
 174 .It Dv NEW_TIME
 175 Time after system clock change.
 176 .It Dv OLD_TIME
 177 Time before system clock change.
 178 .It Dv RUN_LVL
 179 Run level.
 180 Provided for compatibility, not used on
 181 .Nx .
 182 .It Dv USER_PROCESS
 183 A user process.
 184 .El
 185 .Sh RETURN VALUES
 186 .Fn getutxent
 187 returns the next entry, or
 188 .Dv NULL
 189 on failure (end of database or problems reading from the database).
 190 .Fn getutxid
 191 and
 192 .Fn getutxline
 193 return the matching structure on success, or
 194 .Dv NULL
 195 if no match was found.
 196 .Fn pututxline
 197 returns the structure that was successfully written, or
 198 .Dv NULL .
 199 .Fn setutxdb
 200 returns
 201 .Dv 0
 202 on success. Otherwise a negative value is returned and the global
 203 variable
 204 .Va errno
 205 is set to indicate the error.
 206 .Sh SEE ALSO
 207 .Xr wtmpcvt 1 ,
 208 .Xr logwtmpx 3 ,
 209 .Xr utmpx 5
 210 .Sh STANDARDS
 211 The
 212 .Fn endutxent ,
 213 .Fn getutxent ,
 214 .Fn getutxid ,
 215 .Fn getutxline ,
 216 .Fn pututxline ,
 217 .Fn setutxent
 218 all conform to
 219 .St -p1003.1-2001
 220 (XSI extension), and previously to
 221 .St -xpg4.2 .
 222 The fields
 223 .Fa ut_user ,
 224 .Fa ut_id ,
 225 .Fa ut_line ,
 226 .Fa ut_pid ,
 227 .Fa ut_type ,
 228 and
 229 .Fa ut_tv
 230 conform to
 231 .St -p1003.1-2001
 232 (XSI extension), and previously to
 233 .St -xpg4.2 .
 234 .\" .Fa ut_host ,
 235 .\" .Fa ut_session ,
 236 .\" .Fa ut_exit ,
 237 .\" and
 238 .\" .Fa ut_ss
 239 .\" are from
 240 .\" SVR3/4?
 241 .\" .Dv RUN_LVL
 242 .\" is for compatibility with
 243 .\" what exactly?
 244 .\" .Sh HISTORY
 245 .\" The
 246 .\" .Nm utmpx ,
 247 .\" .Nm wtmpx ,
 248 .\" and
 249 .\" .Nm lastlogx
 250 .\" files first appeared in
 251 .\" SVR3? 4?