名称

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 引数で指定されたバッファは、結果を格納するために不十分のサイズでした。呼び出し側は、より大きなバッファで再試行するべきです。

関連項目

getlogin(2), getgrent(3), nsswitch.conf(5), passwd(5), pwd_mkdb(8), vipw(8), yp(8)

規格

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() 関数は、二重化された情報を削除する試みを行ないません。