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.\" 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 December 20, 2010 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.Nm setutxdb 41.Nd user accounting database functions 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In utmpx.h 46.Ft void 47.Fn endutxent void 48.Ft struct utmpx * 49.Fn getutxent void 50.Ft struct utmpx * 51.Fn getutxid "const struct utmpx *" 52.Ft struct utmpx * 53.Fn getutxline "const struct utmpx *" 54.Ft struct utmpx * 55.Fn pututxline "const struct utmpx *" 56.Ft void 57.Fn setutxent void 58.Ft int 59.Fn setutxdb "utx_db_t db" "char *fname" 60.Sh DESCRIPTION 61These functions provide access to the 62.Xr utmpx 5 63and 64.Xr wtmpx 5 65user accounting database. 66.Pp 67.Fn getutxent 68reads the next entry from the database; 69if the database was not yet open, it also opens it. 70.Fn setutxent 71resets the database, so that the next 72.Fn getutxent 73call will get the first entry. 74.Fn endutxent 75closes the database. 76.Pp 77.Fn getutxid 78returns the next entry of the type specified in its argument's 79.Va ut_type 80field, or 81.Dv NULL 82if none is found. 83.Fn getutxline 84returns the next 85.Dv LOGIN_PROCESS 86or 87.Dv USER_PROCESS 88entry which has the same name as specified in the 89.Va ut_line 90field, or 91.Dv NULL 92if no match is found. 93.Pp 94.Fn pututxline 95adds the argument 96.Xr utmpx 5 97entry line to the accounting database, replacing a previous entry for 98the same user if it exists. 99.Pp 100By default the aforementioned functions work on the default 101.Xr utmpx 5 102database. The function 103.Fn setutxdb 104allows to change the database type being operated on, as well 105as changing the path to that database. 106The first parameter 107.Ar db 108can be 109.Dv UTX_DB_UTMPX 110or 111.Dv UTX_DB_WTMPX 112and specifies which database to open. If 113.Ar fname 114is 115.Dv NULL 116the default path for each of these is used as described in 117.Xr utmpx 5 118and 119.Xr wtmpx 5 . 120Otherwise the path specified in 121.Ar fname 122is used as the database. 123.Ss The utmpx structure 124The 125.Nm utmpx 126structure has the following definition: 127.Bd -literal 128struct utmpx { 129 char ut_name[_UTX_USERSIZE]; /* login name */ 130 char ut_id[_UTX_IDSIZE]; /* inittab id */ 131 char ut_line[_UTX_LINESIZE]; /* tty name */ 132 char ut_host[_UTX_HOSTSIZE]; /* host name */ 133 uint16_t ut_session; /* session id used for windowing */ 134 uint16_t ut_type; /* type of this entry */ 135 pid_t ut_pid; /* process id creating the entry */ 136 struct { 137 uint16_t e_termination; /* process termination signal */ 138 uint16_t e_exit; /* process exit status */ 139 } ut_exit; 140 struct sockaddr_storage ut_ss; /* address where entry was made from */ 141 struct timeval ut_tv; /* time entry was created */ 142 uint32_t ut_pad[10]; /* reserved for future use */ 143}; 144.Ed 145.Pp 146Valid entries for 147.Fa ut_type 148are: 149.Bl -tag -width LOGIN_PROCESSXX -compact -offset indent 150.It Dv BOOT_TIME 151Time of a system boot. 152.It Dv DEAD_PROCESS 153A session leader exited. 154.It Dv EMPTY 155No valid user accounting information. 156.It Dv INIT_PROCESS 157A process spawned by 158.Xr init 8 . 159.It Dv LOGIN_PROCESS 160The session leader of a logged-in user. 161.It Dv NEW_TIME 162Time after system clock change. 163.It Dv OLD_TIME 164Time before system clock change. 165.It Dv RUN_LVL 166Run level. 167Provided for compatibility, not used on 168.Nx . 169.It Dv USER_PROCESS 170A user process. 171.El 172.Sh RETURN VALUES 173.Fn getutxent 174returns the next entry, or 175.Dv NULL 176on failure (end of database or problems reading from the database). 177.Fn getutxid 178and 179.Fn getutxline 180return the matching structure on success, or 181.Dv NULL 182if no match was found. 183.Fn pututxline 184returns the structure that was successfully written, or 185.Dv NULL . 186.Fn setutxdb 187returns 188.Dv 0 189on success. Otherwise a negative value is returned and the global 190variable 191.Va errno 192is set to indicate the error. 193.Sh SEE ALSO 194.Xr logwtmpx 3 , 195.Xr utmpx 5 196.Sh STANDARDS 197The 198.Fn endutxent , 199.Fn getutxent , 200.Fn getutxid , 201.Fn getutxline , 202.Fn pututxline , 203.Fn setutxent 204all conform to 205.St -p1003.1-2001 206(XSI extension), and previously to 207.St -xpg4.2 . 208The fields 209.Fa ut_user , 210.Fa ut_id , 211.Fa ut_line , 212.Fa ut_pid , 213.Fa ut_type , 214and 215.Fa ut_tv 216conform to 217.St -p1003.1-2001 218(XSI extension), and previously to 219.St -xpg4.2 . 220.\" .Fa ut_host , 221.\" .Fa ut_session , 222.\" .Fa ut_exit , 223.\" and 224.\" .Fa ut_ss 225.\" are from 226.\" SVR3/4? 227.\" .Dv RUN_LVL 228.\" is for compatibility with 229.\" what exactly? 230.\" .Sh HISTORY 231.\" The 232.\" .Nm utmpx , 233.\" .Nm wtmpx , 234.\" and 235.\" .Nm lastlogx 236.\" files first appeared in 237.\" SVR3? 4? 238