EN JA
GETUTXENT(3)
GETUTXENT(3) FreeBSD Library Functions Manual GETUTXENT(3)

名称

endutxent, getutxent, getutxid, getutxline, getutxuser, pututxline, setutxdb, setutxentユーザアカウンティングデータベース関数

ライブラリ

Standard C Library (libc, -lc)

書式

#include < utmpx.h>

void
endutxent( void);

struct utmpx *
getutxent( void);

struct utmpx *
getutxid( const struct utmpx *id);

struct utmpx *
getutxline( const struct utmpx *line);

struct utmpx *
getutxuser( const char *user);

struct utmpx *
pututxline( const struct utmpx *utmpx);

int
setutxdb( int type, const char *file);

void
setutxent( void);

解説

これらの関数は、ユーザログインとログアウトのみならず、システムスタートアップとシャットダウン、システムのクロックへの変更のような、様々なシステム活動に関するレコードを格納するユーザアカウンティングデータベースを稼働させます。システムは、それぞれ異なる役割がある、3 つのデータベースに、これらのレコードを格納します:
/var/run/utx.active
現在の活発なユーザログインセッションのログ。このファイルは、伝統的な utmp ファイルと同様です。このファイルは、ユーザログインとログアウトレコードのような、プロセスに関連するエントリのみを含みます。
/var/log/utx.lastlogin
ユーザ毎の最後のユーザログインエントリのログ。このファイルは、伝統的な lastlog ファイルと同様です。このファイルは、少なくとも一度ログインしたことがあるユーザのためのユーザログインレコードのみを含みます。
/var/log/utx.log
追加の日付によってソートされたすべてのエントリのログ。このファイルは、伝統的な wtmp ファイルと同様です。このファイルは、次に説明されたレコードのタイプを含みます。

これらのデータベースの各エントリは、インクルードファイル < utmpx.h> にある構造体 utmpx によって定義されます:

struct utmpx { 
 short           ut_type;    /* エントリのタイプ. */ 
 struct timeval  ut_tv;      /* 時間エントリが作成された. */ 
 char            ut_id[];    /* レコード識別子. */ 
 pid_t           ut_pid;     /* プロセス ID. */ 
 char            ut_user[];  /* ユーザログイン名. */ 
 char            ut_line[];  /* デバイス名. */ 
 char            ut_host[];  /* リモートホスト名. */ 
};

ut_type フィールドは、次の値の 1 つがあるログエントリのタイプを表します:

EMPTY
有効なユーザアカウンティング情報は、なし。
BOOT_TIME
システムブートの時間を識別する。
SHUTDOWN_TIME
システムシャットダウンの時間を識別する。
OLD_TIME
システムクロックが変更された時間を識別する。
NEW_TIME
システムクロックが変更された後の時間を識別する。
USER_PROCESS
プロセスを識別する。
INIT_PROCESS
init プロセスによって spawn されたプロセスを識別する。
LOGIN_PROCESS
ログインユーザのセッションリーダを識別する。
DEAD_PROCESS
終了されたセッションリーダを識別する。

タイプ INIT_PROCESSLOGIN_PROCESS のエントリは、この実装では処理されていません。

構造体の中の他のフィールドは、次の通りです:

ut_tv
イベントが起こった時刻。このフィールドは、 EMPTY を除いて、すべてのタイプのエントリに使用されます。
ut_id
エントリを参照するために使用される識別子。 ut_id のために同じ値を含むデータベースに新しいエントリを書き込むことによって、ログインエントリを削除するか、または置き換えるために、この識別子を使用することができます。このフィールドは、タイプ USER_PROCESS, INIT_PROCESS, LOGIN_PROCESSDEAD_PROCESS のエントリのみに適用可能です。
ut_pid
ログインセッションのセッションリーダのプロセス識別子。このフィールドは、タイプ USER_PROCESS, INIT_PROCESS, LOGIN_PROCESSDEAD_PROCESS のエントリのみに適用可能です。
ut_user
ログインセッションに対応しているユーザログイン名。このフィールドは、タイプ USER_PROCESSINIT_PROCESS のエントリのみに適用可能です。 INIT_PROCESS エントリについて、このエントリは、通常ログインプロセスの名前を含んでいます。
ut_line
ユーザログインセッションを容易にするために使用されるデバイスに対応する、先導する /dev/ 接頭辞なしの、TTY キャラクタデバイスの名前。 TTY キャラクタデバイスが使用されていないなら、このフィールドは、空白のままにされます。このフィールドは、タイプ USER_PROCESSLOGIN_PROCESS のエントリのみに適用可能です。
ut_host
ユーザログインを実行するために接続された、リモートシステムのネットワークホスト名。ユーザログインセッションがネットワークを越えて実行されていないなら、このフィールドは、空白のままにされます。このフィールドは、タイプ USER_PROCESS のエントリのみに適用可能です。

この実装は、すべての不適切なフィールドが破棄されていることを保証します。ライブラリ関数によって返された構造体の ut_user, ut_lineut_host フィールドは、この実装でヌル文字で終了されていることも保証されます。

ユーザアカウンティングデータベースから次のエントリを読み込むために getutxent() 関数を使用することができます。

getutxid() 関数は、振る舞いが idut_type フィールドに基づいているデータベースの次のエントリを検索します。 ut_typeBOOT_TIME, SHUTDOWN_TIME, OLD_TIME または NEW_TIME の値があるなら、 ut_type に等しい値がある次のエントリを返します。 ut_typeUSER_PROCESS, INIT_PROCESS, LOGIN_PROCESS または DEAD_PROCESS の値があるなら、 ut_type に、以前に述べられた値の 1 つがあり、 ut_id が等しい次のエントリを返します。

getutxline() 関数は、 ut_type に、 USER_PROCESS または LOGIN_PROCESS の値があり、 ut_lineline の同じフィールドに等しい、データベースの次のエントリを検索します。

getutxuser() 関数は、 ut_typeUSER_PROCESS の値があり、 ut_useruser と等しい、データベースの次のエントリを検索します。

以前に述べられた関数は、まだオープンされていないなら、自動的にユーザアカウンティングデータベースをオープンしようと試みます。 setutxdb() と setutxent() 関数によって、ユーザアカウンティングデータベース中のオフセットをリワインドして、データベースは、手動でオープンすることができます。 endutxent() 関数は、データベースをクローズします。

setutxent() データベースは、常にアクティブなセッションデータベースをオープンします。 setutxdb() 関数は、値が UTXDB_ACTIVE, UTXDB_LASTLOGIN または UTXDB_LOG のいずれかである type によって識別されるデータベースをオープンします。 file が null でないなら、システムのデフォルトの代わりにファイル名 file でカスタムファイルをオープンします。カスタムファイル名をを使用するとき、各データベースがそれ自体のファイル形式を使用するかもしれないので、 type は、まだ実際の形式にマッチしなければならないことに、注意しなければなりません。

pututxline() 関数は、システムのデフォルトのユーザアカウンティングデータベースにレコード utmpx を書き込みます。 ut_type の値は、どのデータベースが変更されているかを決定します。

タイプ SHUTDOWN_TIME, OLD_TIMENEW_TIME のエントリは、 /var/log/utx.log だけに書き込まれます。

また、タイプ USER_PROCESS のエントリは、 /var/run/utx.active/var/log/utx.lastlogin に書き込まれます。

ut_id が等しい、対応する USER_PROCESS, INIT_PROCESS または LOGIN_PROCESS エントリが後で見つけられたなら、タイプ DEAD_PROCESS のエントリは、 /var/log/utx.log/var/run/utx.active だけに書き込まれます。

さらに、タイプ BOOT_TIMESHUTDOWN_TIME のエントリによって、 /var/run/utx.active に存在するすべてのエントリは、廃棄されます。

タイプが以前に述べられていないすべてのエントリは、 pututxline() のこの実装によって廃棄されます。また、この実装は、 ut_tv の値を無視します。

戻り値

getutxent(), getutxid(), getutxline() と getutxuser() 関数は、成功すれば、言及された制約にマッチする utmpx 構造体へのポインタを返し、ファイルの終りに到達するとき、またはエラーが発生するとき、 NULL を返します。

pututxline() 関数は、成功すれば、ディスクに書き込まれた構造体のコピーを含む utmpx 構造体へのポインタを返します。提供された utmpx が無効であるとき、または ut_typeDEAD_PROCESS の値があり、フィールド ut_id に等しい値がある識別子があるエントリが、見つけられなかったとき、 NULL を返します。クローバル変数 errno は、エラー示すように設定されます。

setutxdb() 関数は、ユーザアカウンティングデータベースのオープンが成功したなら、 0 を返します。そうでなければ、-1 を返し、グローバル変数 errno は、エラーを示す値が設定されます。

エラー

open(2), fdopen(3), fopen(3), fseek(3), に説明されたエラー条件に加えて、 pututxline() 関数は、次のエラーを発生させるかもしれません:
[ ESRCH]
ut_type の値が、DEAD_PROCESS で、プロセスエントリを見つけることができませんでした。
[ EINVAL]
ut_type の値が、この実装によってサポートされていません。
fopen(3) に説明されたエラー条件に加えて、 setutxdb() 関数は、次のエラーを発生させるかもしれません:
[ EINVAL]
type 引数が、この実装によってサポートされない値を含んでいます。
[ EFTYPE]
ファイル形式が無効です。

規格

endutxent(), getutxent(), getutxid(), getutxline() と setutxent() 関数は、 IEEE Std 1003.1-2008 (“POSIX.1”) に適合するはずです。

pututxline() 関数は、 ut_type によって、複数のデータベースファイルにそのレコードを書き込むことによって、標準から外れています。これは、他の実装で利用可能な、 updlastlogx() と updwtmpx() 関数のように、他のデータベースを更新するために特別なユーティリティ関数の必要がありません。また、 USER_PROCESS エントリを格納するとき、アクティブなセッションデータベースの DEAD_PROCESS エントリを置き換えようとし、 ut_id のための同じ値があるエントリが見つけられません。標準は、データベースの制限のない成長を引き起こすかもしれない、常に新しいエントリが割り付けられることを必要とします。

getutxuser() と setutxdb() 関数、 utmpx 構造体の ut_host フィールドと SHUTDOWN_TIME は、拡張です。

歴史

これらの関数は、 FreeBSD 9.0 で登場しました。それらは、 < utmp.h> インタフェースに置き換えられました。

作者

Ed Schouten <ed@FreeBSD.org>
October 27, 2011 FreeBSD