setutxdb(3): Constify the file name argument.
[dragonfly.git] / lib / libc / gen / endutxent.3
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 August 30, 2019
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" "const char *fname"
60 .Sh DESCRIPTION
61 These functions provide access to the
62 .Xr utmpx 5
63 and
64 .Xr wtmpx 5
65 user accounting database.
66 .Pp
67 .Fn getutxent
68 reads the next entry from the database;
69 if the database was not yet open, it also opens it.
70 .Fn setutxent
71 resets the database, so that the next
72 .Fn getutxent
73 call will get the first entry.
74 .Fn endutxent
75 closes the database.
76 .Pp
77 .Fn getutxid
78 returns the next entry of the type specified in its argument's
79 .Va ut_type
80 field, or
81 .Dv NULL
82 if none is found.
83 .Fn getutxline
84 returns the next
85 .Dv LOGIN_PROCESS
86 or
87 .Dv USER_PROCESS
88 entry which has the same name as specified in the
89 .Va ut_line
90 field, or
91 .Dv NULL
92 if no match is found.
93 .Pp
94 .Fn pututxline
95 adds the argument
96 .Xr utmpx 5
97 entry line to the accounting database, replacing a previous entry for
98 the same user if it exists.
99 .Pp
100 By default the aforementioned functions work on the default
101 .Xr utmpx 5
102 database. The function
103 .Fn setutxdb
104 allows to change the database type being operated on, as well
105 as changing the path to that database.
106 The first parameter
107 .Ar db
108 can be
109 .Dv UTX_DB_UTMPX
110 or
111 .Dv UTX_DB_WTMPX
112 and specifies which database to open. If
113 .Ar fname
114 is
115 .Dv NULL
116 the default path for each of these is used as described in
117 .Xr utmpx 5
118 and
119 .Xr wtmpx 5 .
120 Otherwise the path specified in
121 .Ar fname
122 is used as the database.
123 .Ss The utmpx structure
124 The
125 .Nm utmpx
126 structure has the following definition:
127 .Bd -literal
128 struct 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         short 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
146 Valid entries for
147 .Fa ut_type
148 are:
149 .Bl -tag -width LOGIN_PROCESSXX -compact -offset indent
150 .It Dv BOOT_TIME
151 Time of a system boot.
152 .It Dv DEAD_PROCESS
153 A session leader exited.
154 .It Dv EMPTY
155 No valid user accounting information.
156 .It Dv INIT_PROCESS
157 A process spawned by
158 .Xr init 8 .
159 .It Dv LOGIN_PROCESS
160 The session leader of a logged-in user.
161 .It Dv NEW_TIME
162 Time after system clock change.
163 .It Dv OLD_TIME
164 Time before system clock change.
165 .It Dv RUN_LVL
166 Run level.
167 Provided for compatibility, not used on
168 .Nx .
169 .It Dv USER_PROCESS
170 A user process.
171 .El
172 .Sh RETURN VALUES
173 .Fn getutxent
174 returns the next entry, or
175 .Dv NULL
176 on failure (end of database or problems reading from the database).
177 .Fn getutxid
178 and
179 .Fn getutxline
180 return the matching structure on success, or
181 .Dv NULL
182 if no match was found.
183 .Fn pututxline
184 returns the structure that was successfully written, or
185 .Dv NULL .
186 .Fn setutxdb
187 returns
188 .Dv 0
189 on success. Otherwise a negative value is returned and the global
190 variable
191 .Va errno
192 is set to indicate the error.
193 .Sh SEE ALSO
194 .Xr logwtmpx 3 ,
195 .Xr utmpx 5
196 .Sh STANDARDS
197 The
198 .Fn endutxent ,
199 .Fn getutxent ,
200 .Fn getutxid ,
201 .Fn getutxline ,
202 .Fn pututxline ,
203 .Fn setutxent
204 all conform to
205 .St -p1003.1-2001
206 (XSI extension), and previously to
207 .St -xpg4.2 .
208 The fields
209 .Fa ut_user ,
210 .Fa ut_id ,
211 .Fa ut_line ,
212 .Fa ut_pid ,
213 .Fa ut_type ,
214 and
215 .Fa ut_tv
216 conform 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?