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