GETPWENT(3)

名称
getpwent, getpwnam, getpwuid, setpassent, setpwent, endpwent - パスワードデータベースを操作

ライブラリ
libc

書式
#include <sys/types.h> #include <pwd.h> struct passwd * getpwent(void) struct passwd * getpwnam(const char *login) struct passwd * getpwuid(uid_t uid) 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() 関数はパスワードデータベースを順次読み込みます。ユーザの完全な リストを処理したいプログラム向きです。

setpassent() 関数は 2 つの目的を果たすものです。まず getpwent() 関数がデータベースの最初へ「巻き戻す (rewind)」 ようにします。さらに stayopen が 0 でなければ、ファイル記述子をオープンしたままにします。 これにより、これらのルーチンに対するその後のアクセスすべてが 極めて高速化されます (ただし getpwent() の場合、デフォルトでファイル記述子をクローズしないので 後者の機能は不要です)。

長時間実行されているプログラムでファイル記述子をオープンした ままにしておくのは危険です。なぜなら、プログラムが実行されて いる間にデータベースが更新されると、オープンしたままにしている データベースは古い物になってしまうからです。

setpwent() 関数は、引数を 0 にした setpassent() と同じです。

endpwent() 関数は、オープンしているファイルをすべてクローズします。

これらのルーチンは、パスワードファイルを 「隠す (shadow)」目的で 書かれました。たとえば、暗号化パスワードにアクセスできる プログラムを限定できるようにです。これらのルーチンを 呼び出すプロセスの有効ユーザ ID が 0 ならば暗号化パスワードを返し、 その他の場合は戻り値である構造体のパスワードフィールドは ストリング ‘*’ を指すようになります。

YP/NIS の相互作用
yp(4) パスワード データベースが使用可能な場合、ローカルのデータベースに 要求されたパスワードエントリが見つからないと、 getpwnam() および getpwuid() 関数はそれぞれ、 “passwd.byname” および “passwd.byuid” YP マップを使用します。 passwd(5) で記述されているようにマップ全体が使用可能である場合は、 getpwent() 関数は YP マップ “passwd.byname” を一通り読みます。

戻り値
関数 getpwent(), getpwnam() および getpwuid() は、いずれも成功すると、 passwd 構造体への有効なポインタを返します。 ファイルの終端に到達するか、もしくはエラーが発生した場合は ヌルポインタを返します。 setpassent() 関数は、失敗した場合は 0 を、成功した場合は 1 を返します。 endpwent() および setpwent() 関数の戻り値はありません。

関連ファイル
/etc/pwd.db
    安全ではないパスワードデータベースファイル
/etc/spwd.db
    安全なパスワードデータベースファイル
/etc/master.passwd
    現在のパスワードファイル
/etc/passwd
    Version 7 形式のパスワードファイル

関連項目
getlogin(2), getgrent(3), yp(4), passwd(5), pwd_mkdb(8), vipw(8)

歴史
getpwent(), getpwnam(), getpwuid(), setpwent() および endpwent() 関数は、 AT&T UNIX で初めて登場しました。 setpassent() 関数は 4.3-RenoBSD で登場しました。

互換性
歴史的な理由で存在していた、 代替パスワードデータベースの規格を許した関数 setpwfile(3) は非推奨になっており、もう使用できません。

バグ
関数 getpwent(), getpwnam() および getpwuid() は、呼び出し結果を内部の静的オブジェクトに残し、 そのオブジェクトを指すポインタを返します。その後、 同じ関数を呼び出すと、同じオブジェクトを変更していきます。