gen/endutxent.3.orig

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