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