| blob | 06a443345a02cdfa46a1208c33511ee81c36544a |
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?