Print this page
3124 Remove any existing references to utmp, use utmpx instead
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/getutxent.3c
+++ new/usr/src/man/man3c/getutxent.3c
1 1 '\" te
2 2 .\" Copyright 1989 AT&T. Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH GETUTXENT 3C "Jul 27, 2004"
6 +.TH GETUTXENT 3C "Nov 21, 2014"
7 7 .SH NAME
8 8 getutxent, getutxid, getutxline, pututxline, setutxent, endutxent, utmpxname,
9 9 getutmp, getutmpx, updwtmp, updwtmpx \- user accounting database functions
10 10 .SH SYNOPSIS
11 11 .LP
12 12 .nf
13 13 #include <utmpx.h>
14 14
15 15 \fBstruct utmpx *\fR\fBgetutxent\fR(\fBvoid\fR);
16 16 .fi
17 17
18 18 .LP
19 19 .nf
20 20 \fBstruct utmpx *\fR\fBgetutxid\fR(\fBconst struct utmpx *\fR\fIid\fR);
21 21 .fi
22 22
23 23 .LP
24 24 .nf
25 25 \fBstruct utmpx *\fR\fBgetutxline\fR(\fBconst struct utmpx *\fR\fIline\fR);
26 26 .fi
27 27
28 28 .LP
29 29 .nf
30 30 \fBstruct utmpx *\fR\fBpututxline\fR(\fBconst struct utmpx *\fR\fIutmpx\fR);
31 31 .fi
32 32
33 33 .LP
34 34 .nf
35 35 \fBvoid\fR \fBsetutxent\fR(\fBvoid\fR);
36 36 .fi
37 37
38 38 .LP
39 39 .nf
40 40 \fBvoid\fR \fBendutxent\fR(\fBvoid\fR);
41 41 .fi
42 42
43 43 .LP
44 44 .nf
45 45 \fBint\fR \fButmpxname\fR(\fBconst char *\fR\fIfile\fR);
46 46 .fi
47 47
48 48 .LP
49 49 .nf
50 50 \fBvoid\fR \fBgetutmp\fR(\fBstruct utmpx *\fR\fIutmpx\fR, \fBstruct utmp *\fR\fIutmp\fR);
51 51 .fi
52 52
53 53 .LP
54 54 .nf
55 55 \fBvoid\fR \fBgetutmpx\fR(\fBstruct utmp *\fR\fIutmp\fR, \fBstruct utmpx *\fR\fIutmpx\fR);
56 56 .fi
57 57
58 58 .LP
59 59 .nf
60 60 \fBvoid\fR \fBupdwtmp\fR(\fBchar *\fR\fIwfile\fR, \fBstruct utmp *\fR\fIutmp\fR);
61 61 .fi
62 62
63 63 .LP
64 64 .nf
65 65 \fBvoid\fR \fBupdwtmpx\fR(\fBchar *\fR\fIwfilex\fR, \fBstruct utmpx *\fR\fIutmpx\fR);
66 66 .fi
67 67
68 68 .SH DESCRIPTION
69 69 .sp
70 70 .LP
71 71 These functions provide access to the user accounting database, \fButmpx\fR
72 72 (see \fButmpx\fR(4)). Entries in the database are described by the definitions
73 73 and data structures in \fB<utmpx.h>\fR\&.
74 74 .sp
75 75 .LP
76 76 The \fButmpx\fR structure contains the following members:
77 77 .sp
78 78 .in +2
79 79 .nf
80 80 char ut_user[32]; /* user login name */
81 81 char ut_id[4]; /* /etc/inittab id */
82 82 /* (usually line #) */
83 83 char ut_line[32]; /* device name */
84 84 /* (console, lnxx) */
85 85 pid_t ut_pid; /* process id */
86 86 short ut_type; /* type of entry */
87 87 struct exit_status ut_exit; /* exit status of a process */
88 88 /* marked as DEAD_PROCESS */
89 89 struct timeval ut_tv; /* time entry was made */
90 90 int ut_session; /* session ID, used for */
91 91 /* windowing */
92 92 short ut_syslen; /* significant length of */
93 93 /* ut_host */
94 94 /* including terminating null */
95 95 char ut_host[257]; /* host name, if remote */
96 96 .fi
97 97 .in -2
98 98
99 99 .sp
100 100 .LP
101 101 The \fBexit_status\fR structure includes the following members:
102 102 .sp
103 103 .in +2
104 104 .nf
105 105 short e_termination; /* termination status */
106 106 short e_exit; /* exit status */
107 107 .fi
108 108 .in -2
109 109
110 110 .SS "\fBgetutxent()\fR"
111 111 .sp
112 112 .LP
113 113 The \fBgetutxent()\fR function reads in the next entry from a \fButmpx\fR
114 114 database. If the database is not already open, it opens it. If it reaches the
115 115 end of the database, it fails.
116 116 .SS "\fBgetutxid()\fR"
117 117 .sp
118 118 .LP
119 119 The \fBgetutxid()\fR function searches forward from the current point in the
120 120 \fButmpx\fR database until it finds an entry with a \fBut_type\fR matching
121 121 \fIid\fR->\fBut_type\fR, if the type specified is \fBRUN_LVL\fR,
122 122 \fBBOOT_TIME\fR, \fBDOWN_TIME\fR, \fBOLD_TIME\fR, or \fBNEW_TIME\fR. If the
123 123 type specified in \fIid\fR is \fBINIT_PROCESS\fR, \fBLOGIN_PROCESS\fR,
124 124 \fBUSER_PROCESS\fR, or \fBDEAD_PROCESS\fR, then \fBgetutxid()\fR will return a
125 125 pointer to the first entry whose type is one of these four and whose
126 126 \fBut_id\fR member matches \fIid\fR->\fBut_id\fR. If the end of database is
127 127 reached without a match, it fails.
128 128 .SS "\fBgetutxline()\fR"
129 129 .sp
130 130 .LP
131 131 The \fBgetutxline()\fR function searches forward from the current point in the
132 132 \fButmpx\fR database until it finds an entry of the type \fBLOGIN_PROCESS\fR or
133 133 \fBUSER_PROCESS\fR which also has a \fIut_line\fR string matching the
134 134 \fIline\fR->\fBut_line\fR string. If the end of the database is reached
135 135 without a match, it fails.
136 136 .SS "\fBpututxline()\fR"
137 137 .sp
138 138 .LP
139 139 The \fBpututxline()\fR function writes the supplied \fButmpx\fR structure into
140 140 the \fButmpx\fR database. It uses \fBgetutxid()\fR to search forward for the
141 141 proper place if it finds that it is not already at the proper place. It is
142 142 expected that normally the user of \fBpututxline()\fR will have searched for
143 143 the proper entry using one of the \fBgetutx()\fR routines. If so,
144 144 \fBpututxline()\fR will not search. If \fBpututxline()\fR does not find a
145 145 matching slot for the new entry, it will add a new entry to the end of the
146 146 database. It returns a pointer to the \fButmpx\fR structure. When called by a
147 147 non-root user, \fBpututxline()\fR invokes a \fBsetuid()\fR root program to
148 148 verify and write the entry, since the \fButmpx\fR database is normally writable
149 149 only by root. In this event, the \fBut_name\fR member must correspond to the
150 150 actual user name associated with the process; the \fBut_type\fR member must be
151 151 either \fBUSER_PROCESS\fR or \fBDEAD_PROCESS\fR; and the \fBut_line\fR member
152 152 must be a device special file and be writable by the user.
153 153 .SS "\fBsetutxent()\fR"
154 154 .sp
155 155 .LP
156 156 The \fBsetutxent()\fR function resets the input stream to the beginning. This
157 157 should be done before each search for a new entry if it is desired that the
158 158 entire database be examined.
159 159 .SS "\fBendutxent()\fR"
160 160 .sp
161 161 .LP
162 162 The \fBendutxent()\fR function closes the currently open database.
163 163 .SS "\fButmpxname()\fR"
164 164 .sp
165 165 .LP
166 166 The \fButmpxname()\fR function allows the user to change the name of the
167 167 database file examined from \fB/var/adm/utmpx\fR to any other file, most often
168 168 \fB/var/adm/wtmpx\fR. If the file does not exist, this will not be apparent
169 169 until the first attempt to reference the file is made. The \fButmpxname()\fR
170 170 function does not open the file, but closes the old file if it is currently
171 171 open and saves the new file name. The new file name must end with the "x"
172 172 character to allow the name of the corresponding \fButmp\fR file to be easily
173 173 obtainable.; otherwise, an error value of \fB0\fR is returned. The function
174 174 returns \fB1\fR on success.
175 175 .SS "\fBgetutmp()\fR"
176 176 .sp
177 177 .LP
178 178 The \fBgetutmp()\fR function copies the information stored in the members of
179 179 the \fButmpx\fR structure to the corresponding members of the \fButmp\fR
180 180 structure. If the information in any member of \fButmpx\fR does not fit in the
181 181 corresponding \fButmp\fR member, the data is silently truncated. (See
182 182 \fBgetutent\fR(3C) for \fButmp\fR structure)
183 183 .SS "\fBgetutmpx()\fR"
184 184 .sp
185 185 .LP
186 186 The \fBgetutmpx()\fR function copies the information stored in the members of
187 187 the \fButmp\fR structure to the corresponding members of the \fButmpx\fR
188 188 structure. (See \fBgetutent\fR(3C) for \fButmp\fR structure)
189 189 .SS "\fBupdwtmp()\fR"
190 190 .sp
191 191 .LP
192 192 The \fBupdwtmp()\fR function can be used in two ways.
193 193 .sp
194 194 .LP
195 195 If \fIwfile\fR is \fB/var/adm/wtmp\fR, the \fButmp\fR format record supplied by
196 196 the caller is converted to a \fButmpx \fRformat record and the
197 197 \fB/var/adm/wtmpx\fR file is updated (because the \fB/var/adm/wtmp\fR file no
198 198 longer exists, operations on \fBwtmp\fR are converted to operations on
199 199 \fBwtmpx\fR by the library functions.
200 200 .sp
201 201 .LP
202 202 If \fIwfile\fR is a file other than \fB/var/adm/wtmp\fR, it is assumed to be an
203 203 old file in \fButmp\fR format and is updated directly with the \fButmp\fR
204 204 format record supplied by the caller.
205 205 .SS "\fBupdwtmpx()\fR"
206 206 .sp
207 207 .LP
208 208 The \fBupdwtmpx()\fR function writes the contents of the \fButmpx\fR structure
209 209 pointed to by \fIutmpx\fR to the database.
210 210 .SS "\fButmpx\fR structure"
211 211 .sp
212 212 .LP
213 213 The values of the \fBe_termination\fR and \fBe_exit\fR members of the
214 214 \fBut_exit\fR structure are valid only for records of type \fBDEAD_PROCESS\fR.
215 215 For \fButmpx\fR entries created by \fBinit\fR(1M), these values are set
216 216 according to the result of the \fBwait()\fR call that \fBinit\fR performs on
217 217 the process when the process exits. See the \fBwait\fR(3C), manual page for the
218 218 values \fBinit\fR uses. Applications creating \fButmpx\fR entries can set
219 219 \fBut_exit\fR values using the following code example:
220 220 .sp
221 221 .in +2
222 222 .nf
223 223 u->ut_exit.e_termination = WTERMSIG(process->p_exit)
224 224 u->ut_exit.e_exit = WEXITSTATUS(process->p_exit)
225 225 .fi
226 226 .in -2
227 227
|
↓ open down ↓ |
211 lines elided |
↑ open up ↑ |
228 228 .sp
229 229 .LP
230 230 See \fBwait.h\fR(3HEAD) for descriptions of the \fBWTERMSIG\fR and
231 231 \fBWEXITSTATUS\fR macros.
232 232 .sp
233 233 .LP
234 234 The \fBut_session\fR member is not acted upon by the operating system. It is
235 235 used by applications interested in creating \fButmpx\fR entries.
236 236 .sp
237 237 .LP
238 -For records of type \fBUSER_PROCESS\fR, the \fBnonuser()\fR and
239 -\fBnonuserx()\fR macros use the value of the \fBut_exit.e_exit\fR member to
240 -mark \fButmpx\fR entries as real logins (as opposed to multiple xterms started
241 -by the same user on a window system). This allows the system utilities that
242 -display users to obtain an accurate indication of the number of actual users,
243 -while still permitting each \fBpty\fR to have a \fButmpx\fR record (as most
244 -applications expect.). The \fBNONROOT_USER\fR macro defines the value that
245 -\fBlogin\fR places in the \fBut_exit.e_exit\fR member.
238 +For records of type \fBUSER_PROCESS\fR, the \fBnonuserx()\fR macro uses
239 +value of the \fBut_exit.e_exit\fR member to mark \fButmpx\fR entries as real
240 +logins (as opposed to multiple xterms started by the same user on a window
241 +system). This allows the system utilities that display users to obtain an
242 +accurate indication of the number of actual users, while still permitting each
243 +\fBpty\fR to have a \fButmpx\fR record (as most applications expect). The
244 +\fBNONROOT_USRX\fR macro defines the value that \fBlogin\fR places in the
245 +\fBut_exit.e_exit\fR member.
246 246 .SH RETURN VALUES
247 247 .sp
248 248 .LP
249 249 Upon successful completion, \fBgetutxent()\fR, \fBgetutxid()\fR, and
250 250 \fBgetutxline()\fR each return a pointer to a \fButmpx\fR structure containing
251 251 a copy of the requested entry in the user accounting database. Otherwise a
252 252 null pointer is returned.
253 253 .sp
254 254 .LP
255 255 The return value may point to a static area which is overwritten by a
256 256 subsequent call to \fBgetutxid ()\fR or \fBgetutxline()\fR.
257 257 .sp
258 258 .LP
259 259 Upon successful completion, \fBpututxline()\fR returns a pointer to a
260 260 \fButmpx\fR structure containing a copy of the entry added to the user
261 261 accounting database. Otherwise a null pointer is returned.
262 262 .sp
263 263 .LP
264 264 The \fBendutxent()\fR and \fBsetutxent()\fR functions return no value.
265 265 .sp
266 266 .LP
267 267 A null pointer is returned upon failure to read, whether for permissions or
268 268 having reached the end of file, or upon failure to write.
269 269 .SH USAGE
270 270 .sp
271 271 .LP
272 272 These functions use buffered standard I/O for input, but \fBpututxline()\fR
273 273 uses an unbuffered write to avoid race conditions between processes trying to
274 274 modify the \fButmpx\fR and \fBwtmpx\fR files.
275 275 .sp
276 276 .LP
277 277 Applications should not access the \fButmpx\fR and \fBwtmpx\fR databases
278 278 directly, but should use these functions to ensure that these databases are
279 279 maintained consistently.
280 280 .SH FILES
281 281 .sp
282 282 .ne 2
283 283 .na
284 284 \fB\fB/var/adm/utmpx\fR\fR
285 285 .ad
286 286 .RS 18n
287 287 user access and accounting information
288 288 .RE
289 289
290 290 .sp
291 291 .ne 2
292 292 .na
293 293 \fB\fB/var/adm/wtmpx\fR\fR
294 294 .ad
295 295 .RS 18n
296 296 history of user access and accounting information
297 297 .RE
298 298
299 299 .SH ATTRIBUTES
300 300 .sp
301 301 .LP
302 302 See \fBattributes\fR(5) for descriptions of the following attributes:
303 303 .sp
304 304
305 305 .sp
306 306 .TS
307 307 box;
308 308 c | c
309 309 l | l .
310 310 ATTRIBUTE TYPE ATTRIBUTE VALUE
311 311 _
312 312 Interface Stability See below.
313 313 _
314 314 MT-Level Unsafe
315 315 .TE
316 316
317 317 .sp
318 318 .LP
319 319 The \fBendutxent()\fR, \fBgetutxent()\fR, \fBgetutxid()\fR, \fBgetutxline()\fR,
320 320 \fBpututxline()\fR, and \fBsetutxent()\fR functions are Standard.
321 321 .SH SEE ALSO
322 322 .sp
323 323 .LP
324 324 \fBgetutent\fR(3C), \fBttyslot\fR(3C), \fBwait\fR(3C), \fBwait.h\fR(3HEAD),
325 325 \fButmpx\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)
326 326 .SH NOTES
327 327 .sp
328 328 .LP
329 329 The most current entry is saved in a static structure. Multiple accesses
330 330 require that it be copied before further accesses are made. On each call to
331 331 either \fBgetutxid()\fR or \fBgetutxline()\fR, the routine examines the static
332 332 structure before performing more I/O. If the contents of the static structure
333 333 match what it is searching for, it looks no further. For this reason, to use
334 334 \fBgetutxline()\fR to search for multiple occurrences it would be necessary to
335 335 zero out the static after each success, or \fBgetutxline()\fR would just return
336 336 the same structure over and over again. There is one exception to the rule
337 337 about emptying the structure before further reads are done. The implicit read
338 338 done by \fBpututxline()\fR (if it finds that it is not already at the correct
339 339 place in the file) will not hurt the contents of the static structure returned
340 340 by the \fBgetutxent()\fR, \fBgetutxid()\fR, or \fBgetutxline()\fR routines, if
341 341 the user has just modified those contents and passed the pointer back to
342 342 \fBpututxline()\fR.
|
↓ open down ↓ |
87 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX