Debian Codegraph @

upstream/debian-unstable/man3/getutent.3

raw
1 '\" t
2 .\" Copyright 1995, Mark D. Roth <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH getutent 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getutent, getutid, getutline, pututline, setutent, endutent,
10 utmpname \- access utmp file entries
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <utmp.h>
17 .P
18 .B struct utmp *getutent(void);
19 .BI "struct utmp *getutid(const struct utmp *" ut );
20 .BI "struct utmp *getutline(const struct utmp *" ut );
21 .P
22 .BI "struct utmp *pututline(const struct utmp *" ut );
23 .P
24 .B void setutent(void);
25 .B void endutent(void);
26 .P
27 .BI "int utmpname(const char *" path );
28 .fi
29 .SH DESCRIPTION
30 New applications should use
31 the POSIX.1-specified "utmpx" versions of these functions;
32 see STANDARDS.
33 .P
34 .BR utmpname ()
35 sets the pathname of the utmp-format file for the other utmp
36 functions to access.
37 If
38 .BR utmpname ()
39 is not used to set the pathname
40 before the other functions are used, they assume
41 .BR _PATH_UTMP ,
42 as defined in
43 .IR <paths.h> .
44 .P
45 .BR setutent ()
46 rewinds the file pointer to the beginning of the utmp file.
47 It is generally a good idea to call it before any of the other
48 functions.
49 .P
50 .BR endutent ()
51 closes the utmp file.
52 It should be called when the user
53 code is done accessing the file with the other functions.
54 .P
55 .BR getutent ()
56 reads a line from the current file position in the utmp file.
57 It returns a pointer to a structure containing the fields of
58 the line.
59 The definition of this structure is shown in
60 .BR utmp (5).
61 .P
62 .BR getutid ()
63 searches forward from the current file position in the utmp
64 file based upon
65 .IR ut .
66 If
67 .I ut\->ut_type
68 is one of
69 .BR RUN_LVL ,
70 .BR BOOT_TIME ,
71 .BR NEW_TIME ,
72 or
73 .BR OLD_TIME ,
74 .BR getutid ()
75 will
76 find the first entry whose
77 .I ut_type
78 field matches
79 .IR ut\->ut_type .
80 If
81 .I ut\->ut_type
82 is one of
83 .BR INIT_PROCESS ,
84 .BR LOGIN_PROCESS ,
85 .BR USER_PROCESS ,
86 or
87 .BR DEAD_PROCESS ,
88 .BR getutid ()
89 will find the
90 first entry whose
91 .I ut_id
92 field matches
93 .IR ut\->ut_id .
94 .P
95 .BR getutline ()
96 searches forward from the current file position in the utmp file.
97 It scans entries whose
98 .I ut_type
99 is
100 .B USER_PROCESS
101 or
102 .B LOGIN_PROCESS
103 and returns the first one whose
104 .I ut_line
105 field
106 matches
107 .IR ut\->ut_line .
108 .P
109 .BR pututline ()
110 writes the
111 .I utmp
112 structure
113 .I ut
114 into the utmp file.
115 It uses
116 .BR getutid ()
117 to search for the proper place in the file to insert
118 the new entry.
119 If it cannot find an appropriate slot for
120 .IR ut ,
121 .BR pututline ()
122 will append the new entry to the end of the file.
123 .SH RETURN VALUE
124 .BR getutent (),
125 .BR getutid (),
126 and
127 .BR getutline ()
128 return a pointer to a
129 .I struct\ utmp
130 on success,
131 and NULL on failure (which includes the "record not found" case).
132 This
133 .I struct\ utmp
134 is allocated in static storage,
135 and may be overwritten by subsequent calls.
136 .P
137 On success
138 .BR pututline ()
139 returns
140 .IR ut ;
141 on failure, it returns NULL.
142 .P
143 .BR utmpname ()
144 returns 0 if the new name was successfully stored, or \-1 on failure.
145 .P
146 On failure, these functions
147 .I errno
148 set to indicate the error.
149 .SH ERRORS
150 .TP
151 .B ENOMEM
152 Out of memory.
153 .TP
154 .B ESRCH
155 Record not found.
156 .P
157 .BR setutent (),
158 .BR pututline (),
159 and the
160 .BR getut* ()
161 functions can also fail for the reasons described in
162 .BR open (2).
163 .SH FILES
164 .TP
165 .I /var/run/utmp
166 database of currently logged-in users
167 .TP
168 .I /var/log/wtmp
169 database of past user logins
170 .SH ATTRIBUTES
171 For an explanation of the terms used in this section, see
172 .BR attributes (7).
173 .TS
174 allbox;
175 lb lb lbx
176 l l l.
177 Interface Attribute Value
178 T{
179 .na
180 .nh
181 .BR getutent ()
182 T} Thread safety T{
183 .na
184 .nh
185 MT-Unsafe init race:utent
186 race:utentbuf sig:ALRM timer
187 T}
188 T{
189 .na
190 .nh
191 .BR getutid (),
192 .BR getutline ()
193 T} Thread safety T{
194 .na
195 .nh
196 MT-Unsafe init race:utent
197 sig:ALRM timer
198 T}
199 T{
200 .na
201 .nh
202 .BR pututline ()
203 T} Thread safety T{
204 .na
205 .nh
206 MT-Unsafe race:utent
207 sig:ALRM timer
208 T}
209 T{
210 .na
211 .nh
212 .BR setutent (),
213 .BR endutent (),
214 .BR utmpname ()
215 T} Thread safety MT-Unsafe race:utent
216 .TE
217 .P
218 In the above table,
219 .I utent
220 in
221 .I race:utent
222 signifies that if any of the functions
223 .BR setutent (),
224 .BR getutent (),
225 .BR getutid (),
226 .BR getutline (),
227 .BR pututline (),
228 .BR utmpname (),
229 or
230 .BR endutent ()
231 are used in parallel in different threads of a program,
232 then data races could occur.
233 .SH STANDARDS
234 None.
235 .SH HISTORY
236 XPG2, SVr4.
237 .P
238 In XPG2 and SVID 2 the function
239 .BR pututline ()
240 is documented to return void, and that is what it does on many systems
241 (AIX, HP-UX).
242 HP-UX introduces a new function
243 .BR _pututline ()
244 with the prototype given above for
245 .BR pututline ().
246 .P
247 All these functions are obsolete now on non-Linux systems.
248 POSIX.1-2001 and POSIX.1-2008, following SUSv1,
249 does not have any of these functions, but instead uses
250 .P
251 .RS 4
252 .EX
253 .B #include <utmpx.h>
254 .P
255 .B struct utmpx *getutxent(void);
256 .B struct utmpx *getutxid(const struct utmpx *);
257 .B struct utmpx *getutxline(const struct utmpx *);
258 .B struct utmpx *pututxline(const struct utmpx *);
259 .B void setutxent(void);
260 .B void endutxent(void);
261 .EE
262 .RE
263 .P
264 These functions are provided by glibc,
265 and perform the same task as their equivalents without the "x", but use
266 .IR "struct utmpx" ,
267 defined on Linux to be the same as
268 .IR "struct utmp" .
269 For completeness, glibc also provides
270 .BR utmpxname (),
271 although this function is not specified by POSIX.1.
272 .P
273 On some other systems,
274 the
275 .I utmpx
276 structure is a superset of the
277 .I utmp
278 structure,
279 with additional fields, and larger versions of the existing fields,
280 and parallel files are maintained, often
281 .I /var/*/utmpx
282 and
283 .IR /var/*/wtmpx .
284 .P
285 Linux glibc on the other hand does not use a parallel
286 .I utmpx
287 file
288 since its
289 .I utmp
290 structure is already large enough.
291 The "x" functions listed above are just aliases for
292 their counterparts without the "x" (e.g.,
293 .BR getutxent ()
294 is an alias for
295 .BR getutent ()).
296 .SH NOTES
297 .SS glibc notes
298 The above functions are not thread-safe.
299 glibc adds reentrant versions
300 .P
301 .nf
302 .B #include <utmp.h>
303 .P
304 .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
305 .BI "int getutid_r(struct utmp *" ut ,
306 .BI " struct utmp *" ubuf ", struct utmp **" ubufp );
307 .BI "int getutline_r(struct utmp *" ut ,
308 .BI " struct utmp *" ubuf ", struct utmp **" ubufp );
309 .fi
310 .P
311 Feature Test Macro Requirements for glibc (see
312 .BR feature_test_macros (7)):
313 .P
314 .BR getutent_r (),
315 .BR getutid_r (),
316 .BR getutline_r ():
317 .nf
318 _GNU_SOURCE
319 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
320 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
321 .fi
322 .P
323 These functions are GNU extensions, analogs of the functions of the
324 same name without the _r suffix.
325 The
326 .I ubuf
327 argument gives these functions a place to store their result.
328 On success, they return 0, and a pointer to the result is written in
329 .IR *ubufp .
330 On error, these functions return \-1.
331 There are no utmpx equivalents of the above functions.
332 (POSIX.1 does not specify such functions.)
333 .SH EXAMPLES
334 The following example adds and removes a utmp record, assuming it is run
335 from within a pseudo terminal.
336 For usage in a real application, you
337 should check the return values of
338 .BR getpwuid (3)
339 and
340 .BR ttyname (3).
341 .P
342 .\" SRC BEGIN (getutent.c)
343 .EX
344 #include <err.h>
345 #include <pwd.h>
346 #include <stdlib.h>
347 #include <string.h>
348 #include <time.h>
349 #include <unistd.h>
350 #include <utmp.h>
351 \&
352 int
353 main(void)
354 {
355 struct utmp entry;
356 \&
357 if (system("echo before adding entry:;who") == \-1)
358 err(EXIT_FAILURE, "system");
359 \&
360 entry.ut_type = USER_PROCESS;
361 entry.ut_pid = getpid();
362 strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
363 /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
364 strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
365 entry.ut_time = time(NULL);
366 strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
367 memset(entry.ut_host, 0, UT_HOSTSIZE);
368 entry.ut_addr = 0;
369 setutent();
370 if (pututline(&entry) == NULL)
371 err(EXIT_FAILURE, "pututline");
372 \&
373 if (system("echo after adding entry:;who") == \-1)
374 err(EXIT_FAILURE, "system");
375 \&
376 entry.ut_type = DEAD_PROCESS;
377 memset(entry.ut_line, 0, UT_LINESIZE);
378 entry.ut_time = 0;
379 memset(entry.ut_user, 0, UT_NAMESIZE);
380 setutent();
381 if (pututline(&entry) == NULL)
382 err(EXIT_FAILURE, "pututline");
383 \&
384 if (system("echo after removing entry:;who") == \-1)
385 err(EXIT_FAILURE, "system");
386 \&
387 endutent();
388 exit(EXIT_SUCCESS);
389 }
390 .EE
391 .\" SRC END
392 .SH SEE ALSO
393 .BR getutmp (3),
394 .BR utmp (5)