]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1995 Mark D. Roth (roth@uiuc.edu) |
2 | .\" | |
3 | .\" This is free documentation; you can redistribute it and/or | |
4 | .\" modify it under the terms of the GNU General Public License as | |
5 | .\" published by the Free Software Foundation; either version 2 of | |
6 | .\" the License, or (at your option) any later version. | |
7 | .\" | |
8 | .\" The GNU General Public License's references to "object code" | |
9 | .\" and "executables" are to be interpreted as the output of any | |
10 | .\" document formatting or typesetting system, including | |
11 | .\" intermediate and printed output. | |
12 | .\" | |
13 | .\" This manual is distributed in the hope that it will be useful, | |
14 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | .\" GNU General Public License for more details. | |
17 | .\" | |
18 | .\" You should have received a copy of the GNU General Public | |
19 | .\" License along with this manual; if not, write to the Free | |
20 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
21 | .\" USA. | |
22 | .\" | |
23 | .\" References consulted: | |
24 | .\" Linux libc source code | |
25 | .\" Solaris manpages | |
26 | .\" | |
ce515cd4 MK |
27 | .\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt |
28 | .\" <michael@cantor.informatik.rwth-aachen.de> | |
fea681da | 29 | .\" |
043945ef | 30 | .TH GETUTENT 3 2008-06-29 "" "Linux Programmer's Manual" |
fea681da | 31 | .SH NAME |
ce515cd4 MK |
32 | getutent, getutid, getutline, pututline, setutent, endutent, |
33 | utmpname \- access utmp file entries | |
fea681da MK |
34 | .SH SYNOPSIS |
35 | .B #include <utmp.h> | |
36 | .sp | |
37 | .B struct utmp *getutent(void); | |
38 | .br | |
39 | .BI "struct utmp *getutid(struct utmp *" ut ); | |
40 | .br | |
41 | .BI "struct utmp *getutline(struct utmp *" ut ); | |
42 | .sp | |
43 | .BI "struct utmp *pututline(struct utmp *" ut ); | |
44 | .sp | |
45 | .B void setutent(void); | |
46 | .br | |
47 | .B void endutent(void); | |
48 | .sp | |
ce515cd4 | 49 | .BI "int utmpname(const char *" file ); |
fea681da | 50 | .SH DESCRIPTION |
490b25e1 MK |
51 | New applications should use the POSIX.1-specified "utmpx" versions of |
52 | these functions; see CONFORMING TO. | |
53 | ||
60a90ecd MK |
54 | .BR utmpname () |
55 | sets the name of the utmp-format file for the other utmp | |
c13182ef | 56 | functions to access. |
60a90ecd MK |
57 | If |
58 | .BR utmpname () | |
59 | is not used to set the filename | |
fea681da MK |
60 | before the other functions are used, they assume \fB_PATH_UTMP\fP, as |
61 | defined in \fI<paths.h>\fP. | |
62 | .PP | |
60a90ecd MK |
63 | .BR setutent () |
64 | rewinds the file pointer to the beginning of the utmp file. | |
acabf1c1 | 65 | It is generally a good idea to call it before any of the other |
fea681da MK |
66 | functions. |
67 | .PP | |
60a90ecd MK |
68 | .BR endutent () |
69 | closes the utmp file. | |
c13182ef | 70 | It should be called when the user |
fea681da MK |
71 | code is done accessing the file with the other functions. |
72 | .PP | |
60a90ecd | 73 | .BR getutent () |
acabf1c1 | 74 | reads a line from the current file position in the utmp file. |
c13182ef | 75 | It returns a pointer to a structure containing the fields of |
fea681da | 76 | the line. |
ff6953dc MK |
77 | The defintion of this structure is shown in |
78 | .BR utmp (5). | |
fea681da | 79 | .PP |
60a90ecd MK |
80 | .BR getutid () |
81 | searches forward from the current file position in the utmp | |
c13182ef | 82 | file based upon \fIut\fP. |
acabf1c1 | 83 | If \fIut\->ut_type\fP is one of \fBRUN_LVL\fP, |
60a90ecd MK |
84 | \fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, |
85 | .BR getutid () | |
86 | will | |
acabf1c1 MK |
87 | find the first entry whose \fIut_type\fP field matches \fIut\->ut_type\fP. |
88 | If \fIut\->ut_type\fP is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, | |
60a90ecd MK |
89 | \fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, |
90 | .BR getutid () | |
91 | will find the | |
acabf1c1 MK |
92 | first entry whose |
93 | .I ut_id | |
94 | field matches \fIut\->ut_id\fP. | |
fea681da | 95 | .PP |
60a90ecd | 96 | .BR getutline () |
acabf1c1 MK |
97 | searches forward from the current file position in the utmp file. |
98 | It scans entries whose | |
99 | .I ut_type | |
100 | is \fBUSER_PROCESS\fP | |
101 | or \fBLOGIN_PROCESS\fP and returns the first one whose | |
102 | .I ut_line | |
103 | field | |
104 | matches \fIut\->ut_line\fP. | |
fea681da | 105 | .PP |
60a90ecd | 106 | .BR pututline () |
acabf1c1 MK |
107 | writes the |
108 | .I utmp | |
109 | structure \fIut\fP into the utmp file. | |
60a90ecd MK |
110 | It uses |
111 | .BR getutid () | |
112 | to search for the proper place in the file to insert | |
c13182ef MK |
113 | the new entry. |
114 | If it cannot find an appropriate slot for \fIut\fP, | |
60a90ecd MK |
115 | .BR pututline () |
116 | will append the new entry to the end of the file. | |
fea681da | 117 | .SH "RETURN VALUE" |
60a90ecd MK |
118 | .BR getutent (), |
119 | .BR getutid (), | |
60a90ecd | 120 | and |
043945ef | 121 | .BR getutline () |
853a397f MK |
122 | return a pointer to a \fIstruct utmp\fP on success, |
123 | and NULL on failure (which includes the "record not found" case). | |
89f9f5b2 | 124 | This \fIstruct utmp\fP is allocated in static storage, and may be |
fea681da | 125 | overwritten by subsequent calls. |
ce515cd4 | 126 | |
043945ef MK |
127 | On success |
128 | .BR pututline () | |
129 | returns | |
130 | .IR ut ; | |
131 | on failure, it returns NULL. | |
132 | ||
ce515cd4 MK |
133 | .BR utmpname () |
134 | returns 0 if the new name was successfully stored, or \-1 on failure. | |
2b587e09 MK |
135 | .SH ERRORS |
136 | .TP | |
137 | .B ENOMEM | |
138 | Out of memory. | |
139 | .TP | |
140 | .B ESRCH | |
141 | Record not found. | |
142 | .PP | |
143 | .BR setutent (), | |
144 | .BR pututent (), | |
145 | and the | |
146 | .B getut* () | |
147 | functions can also fail for the reasons described in | |
148 | .BR open (2). | |
2b2581ee MK |
149 | .SH FILES |
150 | /var/run/utmp database of currently logged-in users | |
151 | .br | |
152 | /var/log/wtmp database of past user logins | |
153 | .SH "CONFORMING TO" | |
154 | XPG2, SVr4. | |
155 | .LP | |
156 | In XPG2 and SVID 2 the function | |
157 | .BR pututline () | |
158 | is documented to return void, and that is what it does on many systems | |
159 | (AIX, HP-UX, Linux libc5). | |
988db661 | 160 | HP-UX introduces a new function |
2b2581ee | 161 | .BR _pututline () |
988db661 | 162 | with the prototype given above for |
2b2581ee MK |
163 | .BR pututline () |
164 | (also found in Linux libc5). | |
165 | .LP | |
166 | All these functions are obsolete now on non-Linux systems. | |
167 | POSIX.1-2001, following SUSv1, | |
168 | does not have any of these functions, but instead uses | |
169 | .sp | |
170 | .B #include <utmpx.h> | |
171 | .sp | |
172 | .B struct utmpx *getutxent(void); | |
173 | .br | |
174 | .B struct utmpx *getutxid(const struct utmpx *); | |
175 | .br | |
176 | .B struct utmpx *getutxline(const struct utmpx *); | |
177 | .br | |
178 | .B struct utmpx *pututxline(const struct utmpx *); | |
179 | .br | |
180 | .B void setutxent(void); | |
181 | .br | |
182 | .B void endutxent(void); | |
490b25e1 MK |
183 | .PP |
184 | These functions are provided by glibc, | |
185 | and perform the same task as their equivalents without the "x", but use | |
186 | .IR "struct utmpx" , | |
187 | defined on Linux to be the same as | |
188 | .IR "struct utmp" . | |
189 | For completeness, glibc also provides | |
190 | .BR utmpxname (), | |
191 | although this function is not specified by POSIX.1. | |
192 | .PP | |
5018c1b4 MK |
193 | On some other systems, |
194 | the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, | |
5412da6f MK |
195 | with additional fields, and larger versions of the existing fields, |
196 | and parallel files are maintained, often | |
2b2581ee MK |
197 | .I /var/*/utmpx |
198 | and | |
199 | .IR /var/*/wtmpx . | |
200 | .LP | |
5412da6f MK |
201 | Linux glibc on the other hand does not use a parallel \fIutmpx\fP file |
202 | since its \fIutmp\fP structure is already large enough. | |
203 | The functions \fBgetutxent\fP() | |
204 | etc. are aliases for \fBgetutent\fP() etc. | |
d597239c MK |
205 | .SH NOTES |
206 | .SS Glibc Notes | |
6b8fa90b | 207 | The above functions are not thread-safe. |
c13182ef | 208 | Glibc adds reentrant versions |
fea681da MK |
209 | .sp |
210 | .nf | |
c10859eb | 211 | .BR "#define _GNU_SOURCE" " /* or _SVID_SOURCE or _BSD_SOURCE */" |
fea681da MK |
212 | .B #include <utmp.h> |
213 | .sp | |
214 | .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); | |
215 | .sp | |
216 | .BI "int getutid_r(struct utmp *" ut , | |
217 | .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); | |
218 | .sp | |
219 | .BI "int getutline_r(struct utmp *" ut , | |
220 | .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); | |
221 | .fi | |
222 | .sp | |
223 | These functions are GNU extensions, analogs of the functions of the | |
c13182ef MK |
224 | same name without the _r suffix. |
225 | The | |
fea681da MK |
226 | .I ubuf |
227 | parameter gives these functions a place to store their result. | |
228 | On success they return 0, and a pointer to the result is written in | |
acabf1c1 | 229 | .IR *ubufp . |
fea681da | 230 | On error these functions return \-1. |
5018c1b4 | 231 | There are no utmpx equivalents of the above functions. |
23c36287 | 232 | (POSIX.1 does not sdpecify such functions.) |
fea681da MK |
233 | .SH EXAMPLE |
234 | The following example adds and removes a utmp record, assuming it is run | |
c13182ef MK |
235 | from within a pseudo terminal. |
236 | For usage in a real application, you | |
237 | should check the return values of | |
fb186734 | 238 | .BR getpwuid (3) |
c13182ef | 239 | and |
fb186734 | 240 | .BR ttyname (3). |
fea681da MK |
241 | .PP |
242 | .nf | |
243 | #include <string.h> | |
244 | #include <stdlib.h> | |
245 | #include <pwd.h> | |
246 | #include <unistd.h> | |
247 | #include <utmp.h> | |
248 | ||
c13182ef | 249 | int |
cf0a9ace | 250 | main(int argc, char *argv[]) |
fea681da | 251 | { |
cf0a9ace | 252 | struct utmp entry; |
fea681da | 253 | |
cf0a9ace | 254 | system("echo before adding entry:;who"); |
fea681da | 255 | |
8de12063 MK |
256 | entry.ut_type = USER_PROCESS; |
257 | entry.ut_pid = getpid(); | |
258 | strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/")); | |
cf0a9ace | 259 | /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */ |
8de12063 | 260 | strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty")); |
cf0a9ace | 261 | time(&entry.ut_time); |
8de12063 MK |
262 | strcpy(entry.ut_user, getpwuid(getuid())\->pw_name); |
263 | memset(entry.ut_host, 0, UT_HOSTSIZE); | |
264 | entry.ut_addr = 0; | |
cf0a9ace MK |
265 | setutent(); |
266 | pututline(&entry); | |
fea681da | 267 | |
cf0a9ace | 268 | system("echo after adding entry:;who"); |
fea681da | 269 | |
8de12063 MK |
270 | entry.ut_type = DEAD_PROCESS; |
271 | memset(entry.ut_line, 0, UT_LINESIZE); | |
272 | entry.ut_time = 0; | |
273 | memset(entry.ut_user, 0, UT_NAMESIZE); | |
cf0a9ace MK |
274 | setutent(); |
275 | pututline(&entry); | |
fea681da | 276 | |
cf0a9ace | 277 | system("echo after removing entry:;who"); |
fea681da | 278 | |
cf0a9ace | 279 | endutent(); |
5bc8c34c | 280 | exit(EXIT_SUCCESS); |
fea681da MK |
281 | } |
282 | .fi | |
fea681da | 283 | .SH "SEE ALSO" |
0a90178c MK |
284 | .BR utmp (5), |
285 | .BR feature_test_macros (7) |