GETPWENT(3) | FreeBSD Library Functions Manual | GETPWENT(3) |
名称
getpwent, getpwent_r, getpwnam, getpwnam_r, getpwuid, getpwuid_r, setpassent, setpwent, endpwent — パスワードデータベース操作ライブラリ
Standard C Library (libc, -lc)書式
#include < sys/types.h>#include < pwd.h>
struct passwd *
getpwent( void);
int
getpwent_r( struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result);
struct passwd *
getpwnam( const char *login);
int
getpwnam_r( const char *name, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result);
struct passwd *
getpwuid( uid_t uid);
int
getpwuid_r( uid_t uid, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result);
int
setpassent( int stayopen);
void
setpwent( void);
void
endpwent( void);
解説
これらの関数は、 passwd(5) に記述されたパスワードデータベースファイルを操作します。データベースの各エントリは、インクルードファイル < pwd.h> にある構造体 passwd で定義されます。次の通りです。
struct passwd { char *pw_name; /* ユーザ名 */ char *pw_passwd; /* 暗号化されたパスワード */ uid_t pw_uid; /* ユーザ uid */ gid_t pw_gid; /* ユーザ gid */ time_t pw_change; /* パスワードの変更時刻 */ char *pw_class; /* ユーザアクセスクラス */ char *pw_gecos; /* ハネウエルログイン情報 */ char *pw_dir; /* ホームディレクトリ */ char *pw_shell; /* デフォルトのシェル */ time_t pw_expire; /* アカウント有効期限 */ int pw_fields; /* 内部: 充てんフィールド */ };
関数 getpwnam() は、与えられたログイン名を、 getpwuid() は、与えられたユーザ ID をそれぞれパスワードデータベースで検索し、常に最初に遭遇したエントリを返します。
getpwent() 関数は、パスワードデータベースを順次読み込みます。ユーザの完全なリストを処理したいプログラム向きです。
機能 getpwent_r(), getpwnam_r() および getpwuid_r() は、それぞれ getpwent(), getpwnam() および getpwuid() のスレッドセーフバージョンです。呼び出し側は、 pwd, buffer, bufsize および result 引数で検索の結果のための記憶域を提供しなければなりません。これらの関数が成功するとき、 pwd 引数は、満たされ、そして、その引数へのポインタは、 result に収納されます。エントリが見つけられないか、またはエラーが発生すると、 result は、 NULL に設定されます。
setpassent() 関数は、 2 つの目的を果たすものです。最初に getpwent() 関数がデータベースの最初へ ``リワインド'' します。さらに stayopen が 0 でなければ、ファイル記述子をオープンしたままにされ、以後のルーチンのすべてのアクセスがきわめて高速化されます。 (デフォルトでファイル記述子をクローズしないので getpwent() のためには、後者の機能は不要です。)
長時間実行されているプログラムでファイル記述子をオープンしたままにしておくのは危険です。なぜなら、プログラムが実行されている間にデータベースが更新されると、オープンしたままにしているデータベースは、古い物になってしまうからです。
setpwent() 関数は、引数を 0 にした setpassent() と同じです。
endpwent() 関数は、オープンしているファイルをすべてクローズします。
これらのルーチンは、パスワードファイルを ``隠す(shadow)'' ために書かれました。たとえば、暗号化されたパスワードにアクセスできるプログラムを限定できるようにです。これらのルーチンを呼び出すプロセスの実効 UID が 0 ならば暗号化パスワードを返し、その他の場合は、戻された構造体のパスワードフィールドは、文字列‘ *
’を指します。
戻り値
関数 getpwent(), getpwnam() および getpwuid() は、成功すれば passwd 構造体への有効なポインタ返し、エントリが見つけられないか、またはエラーが発生するなら、 NULL を返します。エラーが発生すると、 errno は、設定されます。存在しないエントリとエラーを区別する必要があるなら、これらの関数のいずれかを呼び出す前にプログラムは、明白に errno を 0 に設定しなければならないことに注意してください。関数 getpwent_r(), getpwnam_r() および getpwuid_r() は、エラーが発生しなかったなら 0 かまたは失敗を示すエラー番号を返します。一致するエントリが見つけられないなら、それは、エラーではありません。 (したがって、 result が NULL で、リターン値が 0 であるなら、一致エントリは、存在しません。)setpassent() 関数は、失敗した場合は、0 を、成功した場合は、 1 を返します。 endpwent() および setpwent() 関数の戻り値は、ありません。
関連ファイル
- /etc/pwd.db
- 安全ではないパスワードデータベースファイル
- /etc/spwd.db
- 安全なパスワードデータベースファイル
- /etc/master.passwd
- 現在のパスワードファイル
- /etc/passwd
- Version 7 形式のパスワードファイル
互換性
代替パスワードデータベースの規格を許した歴史的な関数 setpwfile(3) は、非推奨になっており、もう使用できません。エラー
これらのルーチンは、次に加えて open(2), dbopen(3), socket(2) および connect(2) で明記されたエラーのいずれかで失敗するかもしれません。- [ ERANGE]
- buffer と bufsize 引数で指定されたバッファは、結果を格納するために不十分のサイズでした。呼び出し側は、より大きなバッファで再試行するべきです。
規格
getpwent(), getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), setpwent(), および endpwent() 関数は、 ISO/IEC 9945-1:1996 (“POSIX.1”) に適合しています。歴史
getpwent(), getpwnam(), getpwuid(), setpwent() と endpwent() 関数は、 Version 7 AT&T UNIX で登場しました。 setpassent() 関数は、 4.3BSD-Reno で登場しました。 getpwent_r(), getpwnam_r() と getpwuid_r() 関数は、 FreeBSD 5.1 で登場しました。バグ
関数 getpwent(), getpwnam() と getpwuid() は、それらの結果を内部の静的オブジェクトに残し、そのオブジェクトのポインタを返します。後に続く同じ関数の呼び出しは、その同じオブジェクトを修正します。関数 getpwent(), getpwent_r(), endpwent(), setpassent() と setpwent() は、ネットワークでつながれた環境でほとんど役に立たなくなり、可能であれば、避けられるべきです。複数のソースが nsswitch.conf(5) で指定されるなら、 getpwent() と getpwent_r() 関数は、二重化された情報を削除する試みを行ないません。
April 16, 2003 | FreeBSD |