kazmax - Linux で自宅サーバー

getutent - ライブラリコールの説明 - Linux コマンド集 一覧表

  1. 名前
  2. 書式
  3. 説明
  4. 返り値
  5. リエントラント版
  6. ファイル
  7. 準拠
  8. 関連項目

名前

getutent, getutid, getutline, pututline, setutent, endutent, utmpname - utmp ファイルのエントリにアクセスする

書式

#include <utmp.h>
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);
void utmpname(const char * file );

説明

utmpname () は、他の utmp 関数がアクセスする (utmp フォーマットの) ファイルの名前を指定する。他の関数を使う前に utmpname () を使って ファイル名の指定を行わなかった場合は、 <path.h> で 定義されている _PATH_UTMP がファイル名とみなされる。

setutent () は、ファイルポインタを utmp ファイルの先頭に移動する。 一般的には、他の関数を使う前にこの関数を呼び出しておくと良いだろう。

endutent () は utmp ファイルをクローズする。ユーザーコードで 他の関数を使ってこのファイルにアクセスを行った時は、最後にこの関数を 呼び出すべきである。

getutent () は utmp ファイルの現在のファイル位置から一行読み込み、 行の各フィールドの内容を収めた構造体へのポインタを返す。

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 ファイルに 書き出す。 pututline () は getutid () を用いて、新たなエントリを 挿入するのにふさわしい場所を探す。 ut を挿入するふさわしい場所が 見つからない場合は、新たなエントリをファイルの末尾に追加する。

返り値

getutent (), getutid (), getutline (), pututline () は 成功時は struct utmp へのポインタを返し、失敗時は NULL を返す。 この struct utmp は静的な記憶領域に確保され、次にこれらの関数を 呼び出した際に上書きされるかもしれない。

リエントラント版

上記の関数群はスレッド・セーフではない。 glibc にはリエントラント版 (reentrant) が追加されている。

#define _GNU_SOURCE
    /* or _SVID_SOURCE or _BSD_SOURCE */#include <utmp.h>

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 を返す。

以下の例では、 utmp のレコードの追加・削除を行っている。このコードは、 擬似端末 (pseudo terminal) から実行されることを想定している。 実際のアプリケーションでは getpwuid ()と ttyname ()の戻り値を検査するべきである。

#include <string.h>
#include <stdlib.h>
#include <pwd.h>
#include <unistd.h>
#include <utmp.h>


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(0)+strlen("/dev/")); /* only correct for ptys named /dev/tty[pqr][0-9a-z] */ strcpy(entry.ut_id,ttyname(0)+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(); return 0; }

ファイル

/var/run/utmp 現在ログイン中のユーザーのデータベース
/var/log/wtmp 過去のユーザーログインのデータベース

準拠

XPG2, SVr4.

XPG2 と SVID 2 では、pututline () 関数は値を返さないとされており、 (AIX, HP-UX, Linux libc5 などの) 多くのシステムではそうなっている。 HP-UX では、上述の pututline () と同じプロトタイプを持つ 新しい関数 _pututline () が導入されている (この関数は Linux libc5 にもある)。

現在では、Linux 以外のシステムでは、これらの関数は全て廃止されている。 SUSv1 の後に出てきた POSIX.1-2001 では、もはやこれらの関数はなく、 代わりに以下のものを使う。
#include <utmpx.h>
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);
utmpx 構造体は utmp 構造体のスーパーセットで、 フィールドが追加されていたり、既存のフィールドのサイズが 大きくなったりしている。 対応するファイルは普通 /var/*/utmpx/var/*/wtmpx である。

一方、 Linux glibc は utmpx を使っていない。 utmp 構造体が十分に大きいからである。 getutxent などの関数は getutent などの別名となっている。

関連項目

  utmp (5)