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