1 .\" Copyright 1995 Mark D. Roth (roth@uiuc.edu)
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.
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.
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.
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,
23 .\" References consulted:
24 .\" Linux libc source code
27 .\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt
28 .\" <michael@cantor.informatik.rwth-aachen.de>
30 .\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved.
31 .\" Translated 1998-03-15, NAKANO Takeo <nakano@apm.seikei.ac.jp>
32 .\" Updated 2001-10-16, Kentaro Shirakata <argrath@ub32.org>
33 .\" Updated 2002-01-03, Kentaro Shirakata <argrath@ub32.org>
34 .\" Updated 2005-03-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
35 .\" Updated 2008-08-11, Akihiro MOTOKI, LDP v3.05
37 .TH GETUTENT 3 2008-06-29 "" "Linux Programmer's Manual"
40 .\"O getutent, getutid, getutline, pututline, setutent, endutent,
41 .\"O utmpname \- access utmp file entries
42 getutent, getutid, getutline, pututline, setutent, endutent, utmpname \-
43 utmp ¥Õ¥¡¥¤¥ë¤Î¥¨¥ó¥È¥ê¤Ë¥¢¥¯¥»¥¹¤¹¤ë
48 .B struct utmp *getutent(void);
50 .BI "struct utmp *getutid(struct utmp *" ut );
52 .BI "struct utmp *getutline(struct utmp *" ut );
54 .BI "struct utmp *pututline(struct utmp *" ut );
56 .B void setutent(void);
58 .B void endutent(void);
60 .BI "int utmpname(const char *" file );
63 .\"O New applications should use the POSIX.1-specified "utmpx" versions of
64 .\"O these functions; see CONFORMING TO.
65 ¿·¤·¤¤¥¢¥×¥ê¥±¡¼¥·¥ç¥ó¤Ç¤Ï¡¢¤³¤ì¤é¤Î´Ø¿ô¤Î "utmpx" ÈǤò»ÈÍѤ¹¤Ù¤¤Ç¤¢¤ë¡£
66 ¤³¤ì¤é¤Ï POSIX.1 ¤Çµ¬Äꤵ¤ì¤Æ¤¤¤ë¡£¡Ö½àµò¡×¤ÎÀá¤ò»²¾È¡£
69 .\"O sets the name of the utmp-format file for the other utmp
70 .\"O functions to access.
73 .\"O is not used to set the filename
74 .\"O before the other functions are used, they assume \fB_PATH_UTMP\fP, as
75 .\"O defined in \fI<paths.h>\fP.
77 ¤Ï¡¢Â¾¤Î utmp ´Ø¿ô¤¬¥¢¥¯¥»¥¹¤¹¤ë (utmp ¥Õ¥©¡¼¥Þ¥Ã¥È¤Î)
78 ¥Õ¥¡¥¤¥ë¤Î̾Á°¤ò»ØÄꤹ¤ë¡£Â¾¤Î´Ø¿ô¤ò»È¤¦Á°¤Ë
81 ¥Õ¥¡¥¤¥ë̾¤Î»ØÄê¤ò¹Ô¤ï¤Ê¤«¤Ã¤¿¾ì¹ç¤Ï¡¢ \fI<path.h>\fP ¤Ç
82 ÄêµÁ¤µ¤ì¤Æ¤¤¤ë \fB_PATH_UTMP\fP ¤¬¥Õ¥¡¥¤¥ë̾¤È¤ß¤Ê¤µ¤ì¤ë¡£
85 .\"O rewinds the file pointer to the beginning of the utmp file.
86 .\"O It is generally a good idea to call it before any of the other
89 ¤Ï¡¢¥Õ¥¡¥¤¥ë¥Ý¥¤¥ó¥¿¤ò utmp ¥Õ¥¡¥¤¥ë¤ÎÀèƬ¤Ë°ÜÆ°¤¹¤ë¡£
90 °ìÈÌŪ¤Ë¤Ï¡¢Â¾¤Î´Ø¿ô¤ò»È¤¦Á°¤Ë¤³¤Î´Ø¿ô¤ò¸Æ¤Ó½Ð¤·¤Æ¤ª¤¯¤ÈÎɤ¤¤À¤í¤¦¡£
93 .\"O closes the utmp file.
94 .\"O It should be called when the user
95 .\"O code is done accessing the file with the other functions.
97 ¤Ï utmp ¥Õ¥¡¥¤¥ë¤ò¥¯¥í¡¼¥º¤¹¤ë¡£¥æ¡¼¥¶¡¼¥³¡¼¥É¤Ç
98 ¾¤Î´Ø¿ô¤ò»È¤Ã¤Æ¤³¤Î¥Õ¥¡¥¤¥ë¤Ë¥¢¥¯¥»¥¹¤ò¹Ô¤Ã¤¿»þ¤Ï¡¢ºÇ¸å¤Ë¤³¤Î´Ø¿ô¤ò
102 .\"O reads a line from the current file position in the utmp file.
103 .\"O It returns a pointer to a structure containing the fields of
106 ¤Ï utmp ¥Õ¥¡¥¤¥ë¤Î¸½ºß¤Î¥Õ¥¡¥¤¥ë°ÌÃÖ¤«¤é°ì¹ÔÆɤ߹þ¤ß¡¢
107 ¹Ô¤Î³Æ¥Õ¥£¡¼¥ë¥É¤ÎÆâÍƤò¼ý¤á¤¿¹½Â¤ÂΤؤΥݥ¤¥ó¥¿¤òÊÖ¤¹¡£
108 .\"O The definition of this structure is shown in
115 .\"O searches forward from the current file position in the utmp
116 .\"O file based upon \fIut\fP.
117 .\"O If \fIut\fP\->ut_type is one of \fBRUN_LVL\fP,
118 .\"O \fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP,
121 .\"O find the first entry whose \fIut_type\fP field matches \fIut\fP\->ut_type.
122 .\"O If \fIut\fP\->ut_type is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP,
123 .\"O \fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP,
126 .\"O first entry whose
128 .\"O field matches \fIut\fP\->ut_id.
130 ¤Ï¡¢ utmp ¥Õ¥¡¥¤¥ëÃæ¤Î¸½ºß¤Î°ÌÃÖ¤«¤é½çÊý¸þ
131 (ËöÈø¤Ë¸þ¤«¤¦Êý¸þ) ¤Ø \fIut\fP ¤Ë´ð¤¯¸¡º÷¤ò¹Ô¤¦¡£ \fIut\fP\->ut_type ¤¬
132 \fBRUN_LVL\fP, \fBBOOT_TIME\fP, \fBNEW_TIME\fP, \fBOLD_TIME\fP ¤Î
135 ¤Ï \fBut_type\fP ¥Õ¥£¡¼¥ë¥É¤¬
136 \fIut\fP\->ut_type ¤Ë°ìÃפ¹¤ëºÇ½é¤Î¥¨¥ó¥È¥ê¤òõ¤¹¡£
137 \fIut\fP\->ut_type ¤¬ \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP,
138 \fBUSER_PROCESS\fP, \fBDEAD_PROCESS\fP ¤Î¤¤¤º¤ì¤«¤Ê¤é¡¢
142 ¥Õ¥£¡¼¥ë¥É¤¬ \fIut\fP\->ut_id ¤Ë
143 °ìÃפ¹¤ëºÇ½é¤Î¥¨¥ó¥È¥ê¤òõ¤¹¡£
145 .\"O .BR getutline ()
146 .\"O searches forward from the current file position in the utmp file.
147 .\"O It scans entries whose
149 .\"O is \fBUSER_PROCESS\fP
150 .\"O or \fBLOGIN_PROCESS\fP and returns the first one whose
153 .\"O matches \fIut\->ut_line\fP.
155 ¤Ï¡¢ utmp ¥Õ¥¡¥¤¥ë¤Î¸½ºß¤Î°ÌÃÖ¤«¤éËöÈø¤Ë¸þ¤«¤Ã¤Æ¸¡º÷¤ò¹Ô¤¦¡£
157 ¤¬ \fBUSER_PROCESS\fP ¤Þ¤¿¤Ï \fBLOGIN_PROCESS\fP ¤Ç¡¢
159 ¥Õ¥£¡¼¥ë¥É¤¬ \fIut\fP->ut_line ¤Ë¥Þ¥Ã¥Á¤¹¤ëºÇ½é¤Î¹Ô¤òÊÖ¤¹¡£
161 .\"O .BR pututline ()
164 .\"O structure \fIut\fP into the utmp file.
167 .\"O to search for the proper place in the file to insert
169 .\"O If it cannot find an appropriate slot for \fIut\fP,
170 .\"O .BR pututline ()
171 .\"O will append the new entry to the end of the file.
175 ¹½Â¤ÂÎ \fIut\fP ¤ÎÆâÍƤò utmp ¥Õ¥¡¥¤¥ë¤Ë½ñ¤½Ð¤¹¡£
179 ¤òÍѤ¤¤Æ¡¢¿·¤¿¤Ê¥¨¥ó¥È¥ê¤ò
180 ÁÞÆþ¤¹¤ë¤Î¤Ë¤Õ¤µ¤ï¤·¤¤¾ì½ê¤òõ¤¹¡£ \fIut\fP ¤òÁÞÆþ¤¹¤ë¤Õ¤µ¤ï¤·¤¤¾ì½ê¤¬
181 ¸«¤Ä¤«¤é¤Ê¤¤¾ì¹ç¤Ï¡¢¿·¤¿¤Ê¥¨¥ó¥È¥ê¤ò¥Õ¥¡¥¤¥ë¤ÎËöÈø¤ËÄɲ乤롣
182 .\"O .SH "RETURN VALUE"
184 .\"O .BR getutent (),
187 .\"O .BR getutline ()
188 .\"O return a pointer to a \fIstruct utmp\fP on success,
189 .\"O and NULL on failure (which includes the "record not found" case).
190 .\"O This \fIstruct utmp\fP is allocated in static storage, and may be
191 .\"O overwritten by subsequent calls.
195 ¤Ï¡¢À®¸ù¤¹¤ë¤È \fIstruct utmp\fP ¤Ø¤Î¥Ý¥¤¥ó¥¿¤òÊÖ¤¹¡£
196 ¼ºÇÔ¤¹¤ë¤È NULL ¤òÊÖ¤¹ (¥ì¥³¡¼¥É¤¬¸«¤Ä¤«¤é¤Ê¤«¤Ã¤¿¾ì¹ç¤â¼ºÇԤȤʤë)¡£
197 ¤³¤Î \fIstruct utmp\fP ¤ÏÀÅŪ¤Êµ²±Îΰè¤Ë³ÎÊݤµ¤ì¡¢¼¡¤Ë¤³¤ì¤é¤Î´Ø¿ô¤ò
198 ¸Æ¤Ó½Ð¤·¤¿ºÝ¤Ë¾å½ñ¤¤µ¤ì¤ë¤«¤â¤·¤ì¤Ê¤¤¡£
201 .\"O .BR pututline ()
204 .\"O on failure, it returns NULL.
208 ¤òÊÖ¤¹¡£¼ºÇÔ¤¹¤ë¤È NULL ¤òÊÖ¤¹¡£
211 .\"O returns 0 if the new name was successfully stored, or \-1 on failure.
213 ¤Ï¡¢¿·¤·¤¤Ì¾Á°¤Î³ÊǼ¤ËÀ®¸ù¤¹¤ë¤È 0 ¤òÊÖ¤·¡¢¼ºÇÔ¤¹¤ë¤È \-1 ¤òÊÖ¤¹¡£
222 .\"O Record not found.
223 ¥ì¥³¡¼¥É¤¬¸«¤Ä¤«¤é¤Ê¤«¤Ã¤¿¡£
225 .\"O .BR setutent (),
226 .\"O .BR pututent (),
229 .\"O functions can also fail for the reasons described in
237 ¤Ë½ñ¤«¤ì¤Æ¤¤¤ëÍýͳ¤Ç¤â¼ºÇÔ¤¹¤ë¤³¤È¤¬¤¢¤ë¡£
240 .\"O /var/run/utmp database of currently logged-in users
242 .\"O /var/log/wtmp database of past user logins
243 /var/run/utmp ¸½ºß¥í¥°¥¤¥óÃæ¤Î¥æ¡¼¥¶¡¼¤Î¥Ç¡¼¥¿¥Ù¡¼¥¹
245 /var/log/wtmp ²áµî¤Î¥æ¡¼¥¶¡¼¥í¥°¥¤¥ó¤Î¥Ç¡¼¥¿¥Ù¡¼¥¹
246 .\"O .SH "CONFORMING TO"
250 .\"O In XPG2 and SVID 2 the function
251 .\"O .BR pututline ()
253 .\"O to return void, and that is what it does on many systems
254 .\"O (AIX, HP-UX, Linux libc5).
255 XPG2 ¤È SVID 2 ¤Ç¤Ï¡¢
257 ´Ø¿ô¤ÏÃͤòÊÖ¤µ¤Ê¤¤¤È¤µ¤ì¤Æ¤ª¤ê¡¢
258 (AIX, HP-UX, Linux libc5 ¤Ê¤É¤Î) ¿¤¯¤Î¥·¥¹¥Æ¥à¤Ç¤Ï¤½¤¦¤Ê¤Ã¤Æ¤¤¤ë¡£
259 .\"O HP-UX introduces a new function
260 .\"O .BR _pututline ()
261 .\"O with the prototype given above for
262 .\"O .BR pututline ()
263 .\"O (also found in Linux libc5).
266 ¤ÈƱ¤¸¥×¥í¥È¥¿¥¤¥×¤ò»ý¤Ä
270 (¤³¤Î´Ø¿ô¤Ï Linux libc5 ¤Ë¤â¤¢¤ë)¡£
272 .\"O All these functions are obsolete now on non-Linux systems.
273 ¸½ºß¤Ç¤Ï¡¢Linux °Ê³°¤Î¥·¥¹¥Æ¥à¤Ç¤Ï¡¢¤³¤ì¤é¤Î´Ø¿ô¤ÏÁ´¤ÆÇѻߤµ¤ì¤Æ¤¤¤ë¡£
274 .\"O POSIX.1-2001, following SUSv1,
275 .\"O does not have any of these functions, but instead uses
276 SUSv1 ¤Î¸å¤Ë½Ð¤Æ¤¤¿ POSIX.1-2001 ¤Ç¤Ï¡¢¤â¤Ï¤ä¤³¤ì¤é¤Î´Ø¿ô¤Ï¤Ê¤¯¡¢
277 Âå¤ï¤ê¤Ë°Ê²¼¤Î¤â¤Î¤ò»È¤¦¡£
279 .B #include <utmpx.h>
281 .B struct utmpx *getutxent(void);
283 .B struct utmpx *getutxid(const struct utmpx *);
285 .B struct utmpx *getutxline(const struct utmpx *);
287 .B struct utmpx *pututxline(const struct utmpx *);
289 .B void setutxent(void);
291 .B void endutxent(void);
293 .\"O These functions are provided by glibc,
294 .\"O and perform the same task as their equivalents without the "x", but use
295 .\"O .IR "struct utmpx" ,
296 .\"O defined on Linux to be the same as
297 .\"O .IR "struct utmp" .
298 .\"O For completeness, glibc also provides
299 .\"O .BR utmpxname (),
300 .\"O although this function is not specified by POSIX.1.
301 ¤³¤ì¤é¤Î´Ø¿ô¤Ï glibc ¤Ë¤è¤êÄ󶡤µ¤ì¤Æ¤ª¤ê¡¢
302 "x" ¤¬¤Ê¤¤´Ø¿ô¤ÈƱ¤¸½èÍý¤ò¹Ô¤¦¤¬¡¢
305 Linux ¤Ç¤Ï¡¢¤³¤Î¹½Â¤ÂΤÎÄêµÁ¤Ï
308 ´°Á´¤ò´ü¤¹¤¿¤á¤Ë¡¢glibc ¤Ç¤Ï
310 ¤âÄ󶡤·¤Æ¤¤¤ë¡£¤³¤Î´Ø¿ô¤Ï POSIX.1 ¤Ç¤Ïµ¬Äꤵ¤ì¤Æ¤¤¤Ê¤¤¡£
312 .\"O On some other systems,
313 .\"O the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
314 .\"O with additional fields, and larger versions of the existing fields,
315 .\"O and parallel files are maintained, often
318 .\"O .IR /var/*/wtmpx .
319 Linux °Ê³°¤Î¥·¥¹¥Æ¥à¤Ç¤Ï¡¢
320 \fIutmpx\fP ¹½Â¤ÂÎ¤Ï \fIutmp\fP ¹½Â¤ÂΤξå°Ì½¸¹ç (superset) ¤Ë¤Ê¤Ã¤Æ¤¤¤Æ¡¢
321 ÄɲäΥե£¡¼¥ë¥É¤¬¤¢¤Ã¤¿¤ê¡¢´û¸¤Î¥Õ¥£¡¼¥ë¥É¤Î¥µ¥¤¥º¤¬Â礤¯¤Ê¤Ã¤Æ¤¤¤¿¤ê
322 ¤¹¤ë¤â¤Î¤â¤¢¤ë¡£Ê£¿ô¤Î¥Õ¥¡¥¤¥ë¤¬»ÈÍѤµ¤ì¤Æ¤¤¤ë¾ì¹ç¤â¤¢¤ê¡¢Â¿¤¯¤Î¾ì¹ç
326 ¤È¤¤¤¦¥Õ¥¡¥¤¥ë¤¬»È¤ï¤ì¤ë¡£
328 .\"O Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
329 .\"O since its \fIutmp\fP structure is already large enough.
330 .\"O The functions \fBgetutxent\fP()
331 .\"O etc. are aliases for \fBgetutent\fP() etc.
332 °ìÊý¡¢ Linux glibc ¤Ç¤ÏÊ£¿ô¤Î \fIutmpx\fP ¥Õ¥¡¥¤¥ë ¤Ï»È¤ï¤ì¤Æ¤¤¤Ê¤¤¡£
333 \fIutmp\fP ¹½Â¤ÂΤ¬½½Ê¬¤ËÂ礤¤¤«¤é¤Ç¤¢¤ë¡£
334 \fIgetutxent\fP() ¤Ê¤É¤Î´Ø¿ô¤Ï \fIgetutent\fP() ¤Ê¤É¤ÎÊÌ̾¤È¤Ê¤Ã¤Æ¤¤¤ë¡£
339 .\"O The above functions are not thread-safe.
340 .\"O Glibc adds reentrant versions
341 ¾åµ¤Î´Ø¿ô·²¤Ï¥¹¥ì¥Ã¥É¡¦¥»¡¼¥Õ¤Ç¤Ï¤Ê¤¤¡£
342 glibc ¤Ë¤Ï¥ê¥¨¥ó¥È¥é¥ó¥ÈÈÇ (reentrant) ¤¬Äɲ䵤ì¤Æ¤¤¤ë¡£
345 .BR "#define _GNU_SOURCE" " /* or _SVID_SOURCE or _BSD_SOURCE */"
348 .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
350 .BI "int getutid_r(struct utmp *" ut ,
351 .BI " struct utmp *" ubuf ", struct utmp **" ubufp );
353 .BI "int getutline_r(struct utmp *" ut ,
354 .BI " struct utmp *" ubuf ", struct utmp **" ubufp );
357 .\"O These functions are GNU extensions, analogs of the functions of the
358 .\"O same name without the _r suffix.
361 .\"O argument gives these functions a place to store their result.
362 .\"O On success they return 0, and a pointer to the result is written in
364 .\"O On error these functions return \-1.
365 .\"O There are no utmpx equivalents of the above functions.
366 .\"O (POSIX.1 does not specify such functions.)
367 ¤³¤ì¤é¤Î´Ø¿ô¤Ï GNU ¤Ç¤Î³ÈÄ¥¤Ç¤¢¤ê¡¢ËöÈø¤Î _r ¤ò¤È¤Ã¤¿Ì¾Á°¤Î´Ø¿ô¤È
370 ¥Ñ¥é¥á¡¼¥¿¤Ï·ë²Ì¤ò³ÊǼ¤¹¤ë¾ì½ê¤ò»ØÄꤹ¤ë¡£
371 À®¸ù¤¹¤ë¤È 0 ¤òÊÖ¤·¡¢·ë²Ì¤Ø¤Î¥Ý¥¤¥ó¥¿¤ò
373 ¤Ë½ñ¤¹þ¤à¡£¥¨¥é¡¼¤Î¾ì¹ç \-1 ¤òÊÖ¤¹¡£
374 ¾åµ¤Î´Ø¿ô¤ËÂбþ¤¹¤ë utmpx ÈǤϸºß¤·¤Ê¤¤
375 (POSIX.1 ¤Ç¤Ï¤³¤ì¤é¤Î´Ø¿ô¤òµ¬Äꤵ¤ì¤Æ¤¤¤Ê¤¤)¡£
378 .\"O The following example adds and removes a utmp record, assuming it is run
379 .\"O from within a pseudo terminal.
380 .\"O For usage in a real application, you
381 .\"O should check the return values of
382 .\"O .BR getpwuid (3)
384 .\"O .BR ttyname (3).
385 °Ê²¼¤ÎÎã¤Ç¤Ï¡¢ utmp ¤Î¥ì¥³¡¼¥É¤ÎÄɲᦺï½ü¤ò¹Ô¤Ã¤Æ¤¤¤ë¡£¤³¤Î¥³¡¼¥É¤Ï¡¢
386 µ¼»÷üËö (pseudo terminal) ¤«¤é¼Â¹Ô¤µ¤ì¤ë¤³¤È¤òÁÛÄꤷ¤Æ¤¤¤ë¡£
387 ¼ÂºÝ¤Î¥¢¥×¥ê¥±¡¼¥·¥ç¥ó¤Ç¤Ï
391 ¤ÎÌá¤êÃͤò¸¡ºº¤¹¤ë¤Ù¤¤Ç¤¢¤ë¡£
401 main(int argc, char *argv[])
405 system("echo before adding entry:;who");
407 entry.ut_type = USER_PROCESS;
408 entry.ut_pid = getpid();
409 strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
410 /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
411 strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
412 time(&entry.ut_time);
413 strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
414 memset(entry.ut_host, 0, UT_HOSTSIZE);
419 system("echo after adding entry:;who");
421 entry.ut_type = DEAD_PROCESS;
422 memset(entry.ut_line, 0, UT_LINESIZE);
424 memset(entry.ut_user, 0, UT_NAMESIZE);
428 system("echo after removing entry:;who");
438 .BR feature_test_macros (7)