1.\" $NetBSD: endutxent.3,v 1.1 2002/09/27 15:02:26 wiz 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 26, 2002 38.Dt ENDUTXENT 3 39.Os 40.Sh NAME 41.Nm entutxent , 42.Nm getutxent , 43.Nm getutxid , 44.Nm getutxline , 45.Nm pututxline , 46.Nm setutxent 47.Nd user accounting database functions 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.Fd #include \*[Lt]utmpx.h\*[Gt] 52.Ft void 53.Fn endutxent void 54.Ft struct utmpx * 55.Fn getutxent void 56.Ft struct utmpx * 57.Fn getutxid "const struct utmpx *" 58.Ft struct utmpx * 59.Fn getutxline "const struct utmpx *" 60.Ft struct utmpx * 61.Fn pututxline "const struct utmpx *" 62.Ft void 63.Fn setutxent void 64.Sh DESCRIPTION 65These functions provide access to the 66.Xr utmpx 5 67user accounting database. 68.Pp 69.Fn getutxent 70reads the next entry from the database; 71if the database was not yet open, it also opens it. 72.Fn setutxent 73resets the database, so that the next 74.Fn getutxent 75call will get the first entry. 76.Fn endutxent 77closes the database. 78.Pp 79.Fn getutxid 80returns the next entry of the type specified in its argument's 81.Va ut_type 82field, or 83.Dv NULL 84if none is found. 85.Fn getutxline 86returns the next 87.Dv LOGIN_PROCESS 88or 89.Dv USER_PROCESS 90entry which has the same name as specified in the 91.Va ut_line 92field, or 93.Dv NULL 94if no match is found. 95.Pp 96.Fn pututxline 97adds the argument 98.Xr utmpx 5 99entry line to the accounting database, replacing a previous entry for 100the same user if it exists. 101.Ss The utmpx structure 102The 103.Nm utmpx 104structure has the following definition: 105.Pp 106.Bd -literal 107struct utmpx { 108 char ut_name[_UTX_USERSIZE]; /* login name */ 109 char ut_id[_UTX_IDSIZE]; /* inittab id */ 110 char ut_line[_UTX_LINESIZE]; /* tty name */ 111 char ut_host[_UTX_HOSTSIZE]; /* host name */ 112 uint16_t ut_session; /* session id used for windowing */ 113 uint16_t ut_type; /* type of this entry */ 114 pid_t ut_pid; /* process id creating the entry */ 115 struct { 116 uint16_t e_termination; /* process termination signal */ 117 uint16_t e_exit; /* process exit status */ 118 } ut_exit; 119 struct sockaddr_storage ut_ss; /* address where entry was made from */ 120 struct timeval ut_tv; /* time entry was created */ 121 uint32_t ut_pad[10]; /* reserved for future use */ 122}; 123.Ed 124.Pp 125Valid entries for 126.Fa ut_type 127are: 128.Bl -tag -width LOGIN_PROCESSXX -compact -offset indent 129.It Dv BOOT_TIME 130Time of a system boot. 131.It Dv DEAD_PROCESS 132A session leader exited. 133.It Dv EMPTY 134No valid user accounting information. 135.It Dv INIT_PROCESS 136A process spawned by 137.Xr init 8 . 138.It Dv LOGIN_PROCESS 139The session leader of a logged-in user. 140.It Dv NEW_TIME 141Time after system clock change. 142.It Dv OLD_TIME 143Time before system clock change. 144.It Dv RUN_LVL 145Run level. 146Provided for compatibility, not used on 147.Nx "" . 148.It Dv USER_PROCESS 149A user process. 150.El 151.Sh RETURN VALUES 152.Fn getutxent 153returns the next entry, or 154.Dv NULL 155on failure (end of database or problems reading from the database). 156.Fn getutxid 157and 158.Fn getutxline 159return the matching structure on success, or 160.Dv NULL 161if no match was found. 162.Fn pututxline 163returns the structure that was successfully written, or 164.Dv NULL . 165.Sh SEE ALSO 166.Xr logwtmpx 3 , 167.Xr utmpx 5 168.Sh STANDARDS 169The 170.Fn entutxent , 171.Fn getutxent , 172.Fn getutxid , 173.Fn getutxline , 174.Fn pututxline , 175.Fn setutxent 176all conform to 177.St -p1003.1-2001 178(XSI extension), and previously to 179.St -xpg4.2 . 180The fields 181.Fa ut_user , 182.Fa ut_id , 183.Fa ut_line , 184.Fa ut_pid , 185.Fa ut_type , 186and 187.Fa ut_tv 188conform to 189.St -p1003.1-2001 190(XSI extension), and previously to 191.St -xpg4.2 . 192.\" .Fa ut_host , 193.\" .Fa ut_session , 194.\" .Fa ut_exit , 195.\" and 196.\" .Fa ut_ss 197.\" are from 198.\" SVR3/4? 199.\" .Dv RUN_LVL 200.\" is for compatibility with 201.\" what exactly? 202.\" .Sh HISTORY 203.\" The 204.\" .Nm utmpx , 205.\" .Nm wtmpx , 206.\" and 207.\" .Nm lastlogx 208.\" files first appeared in 209.\" SVR3? 4? 210