1.\" $NetBSD: endutxent.3,v 1.7 2020/07/05 01:09:48 christos 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 58These functions provide access to the 59.Xr utmpx 5 60user accounting database. 61.Pp 62.Fn getutxent 63reads the next entry from the database; 64if the database was not yet open, it also opens it. 65.Fn setutxent 66resets the database, so that the next 67.Fn getutxent 68call will get the first entry. 69.Fn endutxent 70closes the database. 71.Pp 72.Fn getutxid 73returns the next entry of the type specified in its argument's 74.Va ut_type 75field, or 76.Dv NULL 77if none is found. 78.Fn getutxline 79returns the next 80.Dv LOGIN_PROCESS 81or 82.Dv USER_PROCESS 83entry which has the same name as specified in the 84.Va ut_line 85field, or 86.Dv NULL 87if no match is found. 88.Pp 89.Fn pututxline 90adds the argument 91.Xr utmpx 5 92entry line to the accounting database, replacing a previous entry for 93the same user if it exists. 94.Ss The utmpx structure 95The 96.Nm utmpx 97structure has the following definition: 98.Pp 99.Bd -literal 100struct 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 118Valid entries for 119.Fa ut_type 120are: 121.Bl -tag -width LOGIN_PROCESSXX -compact -offset indent 122.It Dv BOOT_TIME 123Time of a system boot. 124.It Dv DEAD_PROCESS 125A session leader exited. 126.It Dv EMPTY 127No valid user accounting information. 128.It Dv INIT_PROCESS 129A process spawned by 130.Xr init 8 . 131.It Dv LOGIN_PROCESS 132The session leader of a logged-in user. 133.It Dv NEW_TIME 134Time after system clock change. 135.It Dv OLD_TIME 136Time before system clock change. 137.It Dv RUN_LVL 138Run level. 139Provided for compatibility, not used on 140.Nx . 141.It Dv USER_PROCESS 142A user process. 143.El 144.Sh RETURN VALUES 145.Fn getutxent 146returns the next entry, or 147.Dv NULL 148on failure (end of database or problems reading from the database). 149.Fn getutxid 150and 151.Fn getutxline 152return the matching structure on success, or 153.Dv NULL 154if no match was found. 155.Fn pututxline 156returns 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 162The 163.Fn endutxent , 164.Fn getutxent , 165.Fn getutxid , 166.Fn getutxline , 167.Fn pututxline , 168.Fn setutxent 169all conform to 170.St -p1003.1-2001 171(XSI extension), and previously to 172.St -xpg4.2 . 173The fields 174.Fa ut_user , 175.Fa ut_id , 176.Fa ut_line , 177.Fa ut_pid , 178.Fa ut_type , 179and 180.Fa ut_tv 181conform 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? 203