getutidのヘルプ・マニュアル
日本語 英語
getutid --help
man getutid
GETUTENT(3) Linux Programmer’s Manual GETUTENT(3)
名前
getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
utmp ファイルのエントリにアクセスする
書式
#include
struct utmp *getutent(void);
struct utmp *getutid(struct utmp *ut);
struct utmp *getutline(struct utmp *ut);
struct utmp *pututline(struct utmp *ut);
void setutent(void);
void endutent(void);
int utmpname(const char *file);
説明
新しいアプリケーションでは、これらの関数の "utmpx" 版を使用すべきである
。これらは POSIX.1 で規定されている。「準拠」の節を参照。
utmpname() は、他の utmp 関数がアクセスする (utmp フォーマットの) ファ
イルの名前を指定する。他の関数を使う前に utmpname() を使ってファイル 名
の 指定を行わなかった場合は、 で定義されている _PATH_UTMP がフ
ァイル名とみなされる。
setutent() は、ファイルポインタを utmp ファイルの先頭に移動する。一般的
には、他の関数を使う前にこの関数を呼び出しておくと良いだろう。
endutent() は utmp ファイルをクローズする。ユーザーコードで他の関数を使
ってこのファイルにアクセスを行った時は、最後にこの関数を呼び出すべき で
ある。
getutent() は utmp ファイルの現在のファイル位置から一行読み込み、行の各
フィールドの内容を収めた構造体へのポインタを返す。この構造体の 定 義 は
utmp(5) に書かれている。
getutid() は、 utmp ファイル中の現在の位置から順方向 (末尾に向かう方向)
へ ut に基く検索を行う。 ut->ut_type が RUN_LVL, BOOT_TIME, NEW_TIME,
OLD_TIME のいずれかなら、 getutid() は ut_type フィールドが ut->ut_type
に一致する最初のエン ト リ を 探 す 。 ut->ut_type が INIT_PROCESS,
LOGIN_PROCESS, USER_PROCESS, DEAD_PROCESS のいずれかなら、 getutid() は
ut_id フィールドが ut->ut_id に一致する最初のエントリを探す。
getutline() は、 utmp ファイルの現在の位置から末尾に向かって検索を行 う
。 ut_type が USER_PROCESS または LOGIN_PROCESS で、 ut_line フィールド
が ut->ut_line にマッチする最初の行を返す。
pututline() は utmp 構造体 ut の内容を utmp ファイルに書き出す。 putut-
line() は getutid() を用いて、新たなエントリを挿入するのにふさわしい場
所を探す。 ut を挿入するふさわしい場所が見つからない場合は、新たなエ ン
トリをファイルの末尾に追加する。
返り値
getutent(), getutid(), getutline() は、成功すると struct utmp へのポイ
ンタを返す。失敗すると NULL を返す (レコードが見つからなかった場合も 失
敗 となる)。この struct utmp は静的な記憶領域に確保され、次にこれらの関
数を呼び出した際に上書きされるかもしれない。
pututline() は成功すると ut を返す。失敗すると NULL を返す。
utmpname() は、新しい名前の格納に成功すると 0 を返し、失敗すると -1 を
返す。
エラー
ENOMEM メモリ不足。
ESRCH レコードが見つからなかった。
関数 setutent(), pututent(), getut*() は open(2) に書かれている理由でも
失敗することがある。
ファイル
/var/run/utmp 現在ログイン中のユーザーのデータベース
/var/log/wtmp 過去のユーザーログインのデータベース
準拠
XPG2, SVr4.
XPG2 と SVID 2 では、 pututline() 関数は値を返さないとさ れ て お り 、
(AIX, HP-UX, Linux libc5 などの) 多くのシステムではそうなっている。 HP-
UX では、上述の pututline() と同じプロトタイプを持つ新しい関数 _putut-
line() が導入されている (この関数は Linux libc5 にもある)。
現 在では、Linux 以外のシステムでは、これらの関数は全て廃止されている。
SUSv1 の後に出てきた POSIX.1-2001 では、もはやこれらの関数はなく、代 わ
りに以下のものを使う。
#include
struct utmpx *getutxent(void);
struct utmpx *getutxid(const struct utmpx *);
struct utmpx *getutxline(const struct utmpx *);
struct utmpx *pututxline(const struct utmpx *);
void setutxent(void);
void endutxent(void);
こ れらの関数は glibc により提供されており、 "x" がない関数と同じ処理を
行うが、 struct utmpx を使用する。 Linux では、この構 造 体 の 定 義 は
struct utmp と 同じになっている。完全を期すために、glibc では utmpx-
name() も提供している。この関数は POSIX.1 では規定されていない。
Linux 以外のシステムでは、 utmpx 構造体は utmp 構造体の上位集合 (super-
set) になっていて、追加のフィールドがあったり、既存のフィールドのサイズ
が大きくなっていたりするものもある。複数のファイルが使用されている場 合
も あり、多くの場合 /var/*/utmpx と /var/*/wtmpx というファイルが使われ
る。
一方、 Linux glibc では複数の utmpx ファイル は使われていない。 utmp 構
造体が十分に大きいからである。 getutxent() などの関数は getutent() など
の別名となっている。
注意
glibc での注意
上記の関数群はスレッド・セーフではない。 glibc にはリエント ラ ン ト 版
(reentrant) が追加されている。
#define _GNU_SOURCE /* or _SVID_SOURCE or _BSD_SOURCE */
#include
int getutent_r(struct utmp *ubuf, struct utmp **ubufp);
int getutid_r(struct utmp *ut,
struct utmp *ubuf, struct utmp **ubufp);
int getutline_r(struct utmp *ut,
struct utmp *ubuf, struct utmp **ubufp);
これらの関数は GNU での拡張であり、末尾の _r をとった名前の関数と同様の
機能を持つ。 ubuf パラメータは結果を格納する場所を指定する。成功する と
0 を返し、結果へのポインタを *ubufp に書き込む。エラーの場合 -1 を返す
。上記の関数に対応する utmpx 版は存在しない (POSIX.1 ではこれらの関数を
規定されていない)。
例
以 下の例では、 utmp のレコードの追加・削除を行っている。このコードは、
擬似端末 (pseudo terminal) から実行されることを想定している。実際のアプ
リケーションでは getpwuid(3) と ttyname(3) の戻り値を検査するべきである
。
#include
#include
#include
#include
#include
int
main(int argc, char *argv[])
{
struct utmp entry;
system("echo before adding entry:;who");
entry.ut_type = USER_PROCESS;
entry.ut_pid = getpid();
strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
/* only correct for ptys named /dev/tty[pqr][0-9a-z] */
strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
time(&entry.ut_time);
strcpy(entry.ut_user, getpwuid(getuid())->pw_name);
memset(entry.ut_host, 0, UT_HOSTSIZE);
entry.ut_addr = 0;
setutent();
pututline(&entry);
system("echo after adding entry:;who");
entry.ut_type = DEAD_PROCESS;
memset(entry.ut_line, 0, UT_LINESIZE);
entry.ut_time = 0;
memset(entry.ut_user, 0, UT_NAMESIZE);
setutent();
pututline(&entry);
system("echo after removing entry:;who");
endutent();
exit(EXIT_SUCCESS);
}
関連項目
getutmp(3), utmp(5), feature_test_macros(7)
2008-06-29 GETUTENT(3)
GETUTENT(3) Linux Programmer’s Manual GETUTENT(3)
NAME
getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
access utmp file entries
SYNOPSIS
#include
struct utmp *getutent(void);
struct utmp *getutid(struct utmp *ut);
struct utmp *getutline(struct utmp *ut);
struct utmp *pututline(struct utmp *ut);
void setutent(void);
void endutent(void);
int utmpname(const char *file);
DESCRIPTION
New applications should use the POSIX.1-specified "utmpx" versions of
these functions; see CONFORMING TO.
utmpname() sets the name of the utmp-format file for the other utmp
functions to access. If utmpname() is not used to set the filename
before the other functions are used, they assume _PATH_UTMP, as defined
in .
setutent() rewinds the file pointer to the beginning of the utmp file.
It is generally a good idea to call it before any of the other func-
tions.
endutent() closes the utmp file. It should be called when the user
code is done accessing the file with the other functions.
getutent() reads a line from the current file position in the utmp
file. It returns a pointer to a structure containing the fields of the
line. The definition of this structure is shown in utmp(5).
getutid() searches forward from the current file position in the utmp
file based upon ut. If ut->ut_type is one of RUN_LVL, BOOT_TIME,
NEW_TIME, or OLD_TIME, getutid() will find the first entry whose
ut_type field matches ut->ut_type. If ut->ut_type is one of INIT_PRO-
CESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS, getutid() will find
the first entry whose ut_id field matches ut->ut_id.
getutline() searches forward from the current file position in the utmp
file. It scans entries whose ut_type is USER_PROCESS or LOGIN_PROCESS
and returns the first one whose ut_line field matches ut->ut_line.
pututline() writes the utmp structure ut into the utmp file. It uses
getutid() to search for the proper place in the file to insert the new
entry. If it cannot find an appropriate slot for ut, pututline() will
append the new entry to the end of the file.
RETURN VALUE
getutent(), getutid(), and getutline() return a pointer to a struct
utmp on success, and NULL on failure (which includes the "record not
found" case). This struct utmp is allocated in static storage, and may
be overwritten by subsequent calls.
On success pututline() returns ut; on failure, it returns NULL.
utmpname() returns 0 if the new name was successfully stored, or -1 on
failure.
ERRORS
ENOMEM Out of memory.
ESRCH Record not found.
setutent(), pututent(), and the getut* () functions can also fail for
the reasons described in open(2).
FILES
/var/run/utmp database of currently logged-in users
/var/log/wtmp database of past user logins
CONFORMING TO
XPG2, SVr4.
In XPG2 and SVID 2 the function pututline() is documented to return
void, and that is what it does on many systems (AIX, HP-UX, Linux
libc5). HP-UX introduces a new function _pututline() with the proto-
type given above for pututline() (also found in Linux libc5).
All these functions are obsolete now on non-Linux systems.
POSIX.1-2001, following SUSv1, does not have any of these functions,
but instead uses
#include
struct utmpx *getutxent(void);
struct utmpx *getutxid(const struct utmpx *);
struct utmpx *getutxline(const struct utmpx *);
struct utmpx *pututxline(const struct utmpx *);
void setutxent(void);
void endutxent(void);
These functions are provided by glibc, and perform the same task as
their equivalents without the "x", but use struct utmpx, defined on
Linux to be the same as struct utmp. For completeness, glibc also pro-
vides utmpxname(), although this function is not specified by POSIX.1.
On some other systems, the utmpx structure is a superset of the utmp
structure, with additional fields, and larger versions of the existing
fields, and parallel files are maintained, often /var/*/utmpx and
/var/*/wtmpx.
Linux glibc on the other hand does not use a parallel utmpx file since
its utmp structure is already large enough. The functions getutxent()
etc. are aliases for getutent() etc.
NOTES
Glibc Notes
The above functions are not thread-safe. Glibc adds reentrant versions
#define _GNU_SOURCE /* or _SVID_SOURCE or _BSD_SOURCE */
#include
int getutent_r(struct utmp *ubuf, struct utmp **ubufp);
int getutid_r(struct utmp *ut,
struct utmp *ubuf, struct utmp **ubufp);
int getutline_r(struct utmp *ut,
struct utmp *ubuf, struct utmp **ubufp);
These functions are GNU extensions, analogs of the functions of the
same name without the _r suffix. The ubuf argument gives these func-
tions a place to store their result. On success they return 0, and a
pointer to the result is written in *ubufp. On error these functions
return -1. There are no utmpx equivalents of the above functions.
(POSIX.1 does not specify such functions.)
EXAMPLE
The following example adds and removes a utmp record, assuming it is
run from within a pseudo terminal. For usage in a real application,
you should check the return values of getpwuid(3) and ttyname(3).
#include
#include
#include
#include
#include
int
main(int argc, char *argv[])
{
struct utmp entry;
system("echo before adding entry:;who");
entry.ut_type = USER_PROCESS;
entry.ut_pid = getpid();
strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
/* only correct for ptys named /dev/tty[pqr][0-9a-z] */
strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
time(&entry.ut_time);
strcpy(entry.ut_user, getpwuid(getuid())->pw_name);
memset(entry.ut_host, 0, UT_HOSTSIZE);
entry.ut_addr = 0;
setutent();
pututline(&entry);
system("echo after adding entry:;who");
entry.ut_type = DEAD_PROCESS;
memset(entry.ut_line, 0, UT_LINESIZE);
entry.ut_time = 0;
memset(entry.ut_user, 0, UT_NAMESIZE);
setutent();
pututline(&entry);
system("echo after removing entry:;who");
endutent();
exit(EXIT_SUCCESS);
}
SEE ALSO
getutmp(3), utmp(5), feature_test_macros(7)
COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
2008-06-29 GETUTENT(3)