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