]>
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 | .\" | |
27 | .\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de> | |
28 | .\" | |
29 | .TH GETUTENT 3 1996-07-25 "" "Library functions" | |
30 | .SH NAME | |
31 | getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- access utmp file entries | |
32 | .SH SYNOPSIS | |
33 | .B #include <utmp.h> | |
34 | .sp | |
35 | .B struct utmp *getutent(void); | |
36 | .br | |
37 | .BI "struct utmp *getutid(struct utmp *" ut ); | |
38 | .br | |
39 | .BI "struct utmp *getutline(struct utmp *" ut ); | |
40 | .sp | |
41 | .BI "struct utmp *pututline(struct utmp *" ut ); | |
42 | .sp | |
43 | .B void setutent(void); | |
44 | .br | |
45 | .B void endutent(void); | |
46 | .sp | |
47 | .BI "void utmpname(const char *" file ); | |
48 | .SH DESCRIPTION | |
49 | \fButmpname\fP() sets the name of the utmp-format file for the other utmp | |
50 | functions to access. If \fButmpname\fP() is not used to set the filename | |
51 | before the other functions are used, they assume \fB_PATH_UTMP\fP, as | |
52 | defined in \fI<paths.h>\fP. | |
53 | .PP | |
54 | \fBsetutent\fP() rewinds the file pointer to the beginning of the utmp file. | |
55 | It is generally a Good Idea to call it before any of the other | |
56 | functions. | |
57 | .PP | |
58 | \fBendutent\fP() closes the utmp file. It should be called when the user | |
59 | code is done accessing the file with the other functions. | |
60 | .PP | |
61 | \fBgetutent\fP() reads a line from the current file position in the utmp | |
62 | file. It returns a pointer to a structure containing the fields of | |
63 | the line. | |
64 | .PP | |
65 | \fBgetutid\fP() searches forward from the current file position in the utmp | |
66 | file based upon \fIut\fP. If \fIut\fP->ut_type is one of \fBRUN_LVL\fP, | |
67 | \fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, \fBgetutid\fP() will | |
68 | find the first entry whose \fIut_type\fP field matches \fIut\fP->ut_type. | |
69 | If \fIut\fP->ut_type is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, | |
70 | \fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, \fBgetutid\fP() will find the | |
71 | first entry whose ut_id field matches \fIut\fP->ut_id. | |
72 | .PP | |
73 | \fBgetutline\fP() searches forward from the current file position in the | |
74 | utmp file. It scans entries whose ut_type is \fBUSER_PROCESS\fP | |
75 | or \fBLOGIN_PROCESS\fP and returns the first one whose ut_line field | |
76 | matches \fIut\fP->ut_line. | |
77 | .PP | |
78 | \fBpututline\fP() writes the utmp structure \fIut\fP into the utmp file. It | |
79 | uses \fBgetutid\fP() to search for the proper place in the file to insert | |
80 | the new entry. If it cannot find an appropriate slot for \fIut\fP, | |
81 | \fBpututline\fP() will append the new entry to the end of the file. | |
82 | .SH "RETURN VALUE" | |
83 | \fBgetutent\fP(), \fBgetutid\fP(), \fBgetutline\fP() and \fBpututline\fP() | |
84 | return a pointer to a \fBstruct utmp\fP on success, and NULL on failure. | |
85 | This \fBstruct utmp\fP is allocated in static storage, and may be | |
86 | overwritten by subsequent calls. | |
87 | .SH "REENTRANT VERSIONS" | |
88 | These above functions are not thread-safe. Glibc adds reentrant versions | |
89 | .sp | |
90 | .nf | |
91 | .BR "#define _GNU_SOURCE" " /* or _SVID_SOURCE or _BSD_SOURCE */ | |
92 | .B #include <utmp.h> | |
93 | .sp | |
94 | .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); | |
95 | .sp | |
96 | .BI "int getutid_r(struct utmp *" ut , | |
97 | .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); | |
98 | .sp | |
99 | .BI "int getutline_r(struct utmp *" ut , | |
100 | .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); | |
101 | .fi | |
102 | .sp | |
103 | These functions are GNU extensions, analogs of the functions of the | |
104 | same name without the _r suffix. The | |
105 | .I ubuf | |
106 | parameter gives these functions a place to store their result. | |
107 | On success they return 0, and a pointer to the result is written in | |
108 | .RI * ubufp . | |
109 | On error these functions return \-1. | |
110 | .SH EXAMPLE | |
111 | The following example adds and removes a utmp record, assuming it is run | |
112 | from within a pseudo terminal. For usage in a real application, you | |
113 | should check the return values of getpwuid() and ttyname(). | |
114 | .PP | |
115 | .nf | |
116 | #include <string.h> | |
117 | #include <stdlib.h> | |
118 | #include <pwd.h> | |
119 | #include <unistd.h> | |
120 | #include <utmp.h> | |
121 | ||
122 | int main(int argc, char *argv[]) | |
123 | { | |
124 | struct utmp entry; | |
125 | ||
126 | system("echo before adding entry:;who"); | |
127 | ||
128 | entry.ut_type=USER_PROCESS; | |
129 | entry.ut_pid=getpid(); | |
130 | strcpy(entry.ut_line,ttyname(0)+strlen("/dev/")); | |
8c383102 | 131 | /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */ |
fea681da MK |
132 | strcpy(entry.ut_id,ttyname(0)+strlen("/dev/tty")); |
133 | time(&entry.ut_time); | |
8c383102 | 134 | strcpy(entry.ut_user,getpwuid(getuid())\->pw_name); |
fea681da MK |
135 | memset(entry.ut_host,0,UT_HOSTSIZE); |
136 | entry.ut_addr=0; | |
137 | setutent(); | |
138 | pututline(&entry); | |
139 | ||
140 | system("echo after adding entry:;who"); | |
141 | ||
142 | entry.ut_type=DEAD_PROCESS; | |
143 | memset(entry.ut_line,0,UT_LINESIZE); | |
144 | entry.ut_time=0; | |
145 | memset(entry.ut_user,0,UT_NAMESIZE); | |
146 | setutent(); | |
147 | pututline(&entry); | |
148 | ||
149 | system("echo after removing entry:;who"); | |
150 | ||
151 | endutent(); | |
152 | return 0; | |
153 | } | |
154 | .fi | |
155 | .SH FILES | |
156 | /var/run/utmp database of currently logged-in users | |
157 | .br | |
158 | /var/log/wtmp database of past user logins | |
159 | .SH "CONFORMING TO" | |
160 | XPG 2, SVID 2, Linux FSSTND 1.2 | |
161 | .LP | |
63aa9df0 | 162 | In XPG2 and SVID2 the function \fIpututline\fP() is documented |
fea681da MK |
163 | to return void, and that is what it does on many systems |
164 | (AIX, HPUX, Linux libc5). | |
63aa9df0 MK |
165 | HPUX introduces a new function \fI_pututline\fP() with the prototype |
166 | given above for \fIpututline\fP() (also found in Linux libc5). | |
fea681da MK |
167 | .LP |
168 | All these functions are obsolete now on non-Linux systems. | |
169 | POSIX 1003.1-2001, following XPG4.2, | |
170 | does not have any of these functions, but instead uses | |
171 | .sp | |
172 | .B #include <utmpx.h> | |
173 | .sp | |
174 | .B struct utmpx *getutxent(void); | |
175 | .br | |
176 | .B struct utmpx *getutxid(const struct utmpx *); | |
177 | .br | |
178 | .B struct utmpx *getutxline(const struct utmpx *); | |
179 | .br | |
180 | .B struct utmpx *pututxline(const struct utmpx *); | |
181 | .br | |
182 | .B void setutxent(void); | |
183 | .br | |
184 | .B void endutxent(void); | |
185 | .sp | |
186 | The \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, | |
187 | with additional fields, and larger versions of the existing fields. | |
188 | The corresponding files are often | |
189 | .I /var/*/utmpx | |
190 | and | |
191 | .IR /var/*/wtmpx . | |
192 | .LP | |
193 | Linux glibc on the other hand does not use \fIutmpx\fP since its | |
194 | \fIutmp\fP structure is already large enough. The functions \fIgetutxent\fP | |
195 | etc. are aliases for \fIgetutent\fP etc. | |
196 | .SH "SEE ALSO" | |
197 | .BR utmp (5) |