setutxdb(3): Constify the file name argument.
[dragonfly.git] / lib / libc / gen / endutxent.3
CommitLineData
43f8178f
AH
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.\"
7bb7a6ed 30.Dd August 30, 2019
43f8178f
AH
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
7bb7a6ed 59.Fn setutxdb "utx_db_t db" "const char *fname"
43f8178f
AH
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 .
54b11114 120Otherwise the path specified in
43f8178f
AH
121.Ar fname
122is used as the database.
123.Ss The utmpx structure
124The
125.Nm utmpx
126structure has the following definition:
43f8178f
AH
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 */
14f65205 134 short ut_type; /* type of this entry */
43f8178f
AH
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?