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_PROCESS と LOGIN_PROCESS のエントリは、この実装では処理されていません。
構造体の中の他のフィールドは、次の通りです:
- ut_tv
- イベントが起こった時刻。このフィールドは、 EMPTY を除いて、すべてのタイプのエントリに使用されます。
- ut_id
- エントリを参照するために使用される識別子。 ut_id のために同じ値を含むデータベースに新しいエントリを書き込むことによって、ログインエントリを削除するか、または置き換えるために、この識別子を使用することができます。このフィールドは、タイプ USER_PROCESS, INIT_PROCESS, LOGIN_PROCESS と DEAD_PROCESS のエントリのみに適用可能です。
- ut_pid
- ログインセッションのセッションリーダのプロセス識別子。このフィールドは、タイプ USER_PROCESS, INIT_PROCESS, LOGIN_PROCESS と DEAD_PROCESS のエントリのみに適用可能です。
- ut_user
- ログインセッションに対応しているユーザログイン名。このフィールドは、タイプ USER_PROCESS と INIT_PROCESS のエントリのみに適用可能です。 INIT_PROCESS エントリについて、このエントリは、通常ログインプロセスの名前を含んでいます。
- ut_line
- ユーザログインセッションを容易にするために使用されるデバイスに対応する、先導する /dev/ 接頭辞なしの、TTY キャラクタデバイスの名前。 TTY キャラクタデバイスが使用されていないなら、このフィールドは、空白のままにされます。このフィールドは、タイプ USER_PROCESS と LOGIN_PROCESS のエントリのみに適用可能です。
- ut_host
- ユーザログインを実行するために接続された、リモートシステムのネットワークホスト名。ユーザログインセッションがネットワークを越えて実行されていないなら、このフィールドは、空白のままにされます。このフィールドは、タイプ USER_PROCESS のエントリのみに適用可能です。
この実装は、すべての不適切なフィールドが破棄されていることを保証します。ライブラリ関数によって返された構造体の ut_user, ut_line と ut_host フィールドは、この実装でヌル文字で終了されていることも保証されます。
ユーザアカウンティングデータベースから次のエントリを読み込むために getutxent() 関数を使用することができます。
getutxid() 関数は、振る舞いが id の ut_type フィールドに基づいているデータベースの次のエントリを検索します。 ut_type に BOOT_TIME, SHUTDOWN_TIME, OLD_TIME または NEW_TIME の値があるなら、 ut_type に等しい値がある次のエントリを返します。 ut_type に USER_PROCESS, INIT_PROCESS, LOGIN_PROCESS または DEAD_PROCESS の値があるなら、 ut_type に、以前に述べられた値の 1 つがあり、 ut_id が等しい次のエントリを返します。
getutxline() 関数は、 ut_type に、 USER_PROCESS または LOGIN_PROCESS の値があり、 ut_line が line の同じフィールドに等しい、データベースの次のエントリを検索します。
getutxuser() 関数は、 ut_type に USER_PROCESS の値があり、 ut_user が user と等しい、データベースの次のエントリを検索します。
以前に述べられた関数は、まだオープンされていないなら、自動的にユーザアカウンティングデータベースをオープンしようと試みます。 setutxdb() と setutxent() 関数によって、ユーザアカウンティングデータベース中のオフセットをリワインドして、データベースは、手動でオープンすることができます。 endutxent() 関数は、データベースをクローズします。
setutxent() データベースは、常にアクティブなセッションデータベースをオープンします。 setutxdb() 関数は、値が UTXDB_ACTIVE, UTXDB_LASTLOGIN または UTXDB_LOG のいずれかである type によって識別されるデータベースをオープンします。 file が null でないなら、システムのデフォルトの代わりにファイル名 file でカスタムファイルをオープンします。カスタムファイル名をを使用するとき、各データベースがそれ自体のファイル形式を使用するかもしれないので、 type は、まだ実際の形式にマッチしなければならないことに、注意しなければなりません。
pututxline() 関数は、システムのデフォルトのユーザアカウンティングデータベースにレコード utmpx を書き込みます。 ut_type の値は、どのデータベースが変更されているかを決定します。
タイプ SHUTDOWN_TIME, OLD_TIME と NEW_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_TIME と SHUTDOWN_TIME のエントリによって、 /var/run/utx.active に存在するすべてのエントリは、廃棄されます。
タイプが以前に述べられていないすべてのエントリは、 pututxline() のこの実装によって廃棄されます。また、この実装は、 ut_tv の値を無視します。
戻り値
getutxent(), getutxid(), getutxline() と getutxuser() 関数は、成功すれば、言及された制約にマッチする utmpx 構造体へのポインタを返し、ファイルの終りに到達するとき、またはエラーが発生するとき、 NULL を返します。pututxline() 関数は、成功すれば、ディスクに書き込まれた構造体のコピーを含む utmpx 構造体へのポインタを返します。提供された utmpx が無効であるとき、または ut_type に DEAD_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 の値が、この実装によってサポートされていません。
- [ 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 は、拡張です。
作者
<ed@FreeBSD.org>October 27, 2011 | FreeBSD |