gen/NetBSD/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 September 26, 2002
  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 *"
  58 .Ft struct utmpx *
  59 .Fn getutxline "const struct utmpx *"
  60 .Ft struct utmpx *
  61 .Fn pututxline "const struct utmpx *"
  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 .Ss The utmpx structure
 102 The
 103 .Nm utmpx
 104 structure has the following definition:
 105 .Pp
 106 .Bd -literal
 107 struct utmpx {
 108         char ut_name[_UTX_USERSIZE];    /* login name */
 109         char ut_id[_UTX_IDSIZE];        /* inittab id */
 110         char ut_line[_UTX_LINESIZE];    /* tty name */
 111         char ut_host[_UTX_HOSTSIZE];    /* host name */
 112         uint16_t ut_session;            /* session id used for windowing */
 113         uint16_t ut_type;               /* type of this entry */
 114         pid_t ut_pid;                   /* process id creating the entry */
 115         struct {
 116                 uint16_t e_termination; /* process termination signal */
 117                 uint16_t e_exit;        /* process exit status */
 118         } ut_exit;
 119         struct sockaddr_storage ut_ss;  /* address where entry was made from */
 120         struct timeval ut_tv;           /* time entry was created */
 121         uint32_t ut_pad[10];            /* reserved for future use */
 122 };
 123 .Ed
 124 .Pp
 125 Valid entries for
 126 .Fa ut_type
 127 are:
 128 .Bl -tag -width LOGIN_PROCESSXX -compact -offset indent
 129 .It Dv BOOT_TIME
 130 Time of a system boot.
 131 .It Dv DEAD_PROCESS
 132 A session leader exited.
 133 .It Dv EMPTY
 134 No valid user accounting information.
 135 .It Dv INIT_PROCESS
 136 A process spawned by
 137 .Xr init 8 .
 138 .It Dv LOGIN_PROCESS
 139 The session leader of a logged-in user.
 140 .It Dv NEW_TIME
 141 Time after system clock change.
 142 .It Dv OLD_TIME
 143 Time before system clock change.
 144 .It Dv RUN_LVL
 145 Run level.
 146 Provided for compatibility, not used on
 147 .Nx .
 148 .It Dv USER_PROCESS
 149 A user process.
 150 .El
 151 .Sh RETURN VALUES
 152 .Fn getutxent
 153 returns the next entry, or
 154 .Dv NULL
 155 on failure (end of database or problems reading from the database).
 156 .Fn getutxid
 157 and
 158 .Fn getutxline
 159 return the matching structure on success, or
 160 .Dv NULL
 161 if no match was found.
 162 .Fn pututxline
 163 returns the structure that was successfully written, or
 164 .Dv NULL .
 165 .Sh SEE ALSO
 166 .Xr logwtmpx 3 ,
 167 .Xr utmpx 5
 168 .Sh STANDARDS
 169 The
 170 .Fn endutxent ,
 171 .Fn getutxent ,
 172 .Fn getutxid ,
 173 .Fn getutxline ,
 174 .Fn pututxline ,
 175 .Fn setutxent
 176 all conform to
 177 .St -p1003.1-2001
 178 (XSI extension), and previously to
 179 .St -xpg4.2 .
 180 The fields
 181 .Fa ut_user ,
 182 .Fa ut_id ,
 183 .Fa ut_line ,
 184 .Fa ut_pid ,
 185 .Fa ut_type ,
 186 and
 187 .Fa ut_tv
 188 conform to
 189 .St -p1003.1-2001
 190 (XSI extension), and previously to
 191 .St -xpg4.2 .
 192 .\" .Fa ut_host ,
 193 .\" .Fa ut_session ,
 194 .\" .Fa ut_exit ,
 195 .\" and
 196 .\" .Fa ut_ss
 197 .\" are from
 198 .\" SVR3/4?
 199 .\" .Dv RUN_LVL
 200 .\" is for compatibility with
 201 .\" what exactly?
 202 .\" .Sh HISTORY
 203 .\" The
 204 .\" .Nm utmpx ,
 205 .\" .Nm wtmpx ,
 206 .\" and
 207 .\" .Nm lastlogx
 208 .\" files first appeared in
 209 .\" SVR3? 4?