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