SIMPLE SOLUTIONS

GETPWNAM(3) - Linux manual

パスワードファイルのエントリーの取得.

2013-07-22
GETPWNAM(3) Linux Programmer's Manual GETPWNAM(3)

getpwnam, getpwnam_r, getpwuid, getpwuid_r - パスワードファイルのエントリーの取得

#include <sys/types.h> #include <pwd.h> struct passwd *getpwnam(const char *name); struct passwd *getpwuid(uid_t uid); int getpwnam_r(const char *name, struct passwd *pwd, char *buf, size_t buflen, struct passwd **result); int getpwuid_r(uid_t uid, struct passwd *pwd, char *buf, size_t buflen, struct passwd **result); glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照): getpwnam_r(), getpwuid_r(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE

getpwnam() 関数は、ユーザー名 name にマッチするパスワードデータベースのエントリーを 要素毎に分解し、各要素を格納した構造体へのポインターを返す (パスワードデータベースの例: ローカルのパスワードファイル /etc/passwd, NIS, LDAP)。 getpwuid() 関数は、ユーザー ID uid にマッチするパスワードデータベースのエントリーを 要素毎に分解し、各要素を格納した構造体へのポインターを返す。 passwd 構造体は、<pwd.h> で以下のように定義されている: struct passwd { char *pw_name; /* ユーザー名 */ char *pw_passwd; /* ユーザーのパスワード */ uid_t pw_uid; /* ユーザー ID */ gid_t pw_gid; /* グループ ID */ char *pw_gecos; /* ユーザー情報 */ char *pw_dir; /* ホームディレクトリ */ char *pw_shell; /* シェルプログラム */ }; これらのフィールドの詳しい情報については passwd(5) を参照のこと。 getpwnam_r() と getpwuid_r() 関数は、それぞれgetpwnam() と getpwuid() と同じ情報を取得するが、取得した passwd 構造体を pwd が指す領域に格納する。passwd 構造体のメンバーが指す文字列は、 サイズ buflen のバッファー buf に格納される。成功した場合 *result には結果へのポインターが格納される。エントリーが見つからなかった 場合やエラーが発生した場合には *result には NULL が入る。 呼び出し sysconf(_SC_GETPW_R_SIZE_MAX) は、 errno を変更せずに -1 を返すか、 buf の初期サイズの推奨値を 返す。(このサイズが小さすぎる場合、呼び出しは ERANGE で失敗し、この 場合には呼び出し側はバッファーを大きくしてから再度呼び出すことができる。)

getpwnam() と getpwuid() 関数は、 passwd 構造体へのポインターを返す。 一致するエントリーが見つからなかった場合や、エラーが発生した場合は NULL を返す。 エラーが起こった場合、 errno が適切に設定される。 呼び出しの後で errno をチェックしたい場合は、 呼び出しの前に (この値を) 0 に設定しておくべきである。 返り値は静的な領域を指しており、その後の getpwent(3), getpwnam(), getpwuid() の呼び出しで上書きされるかもしれない。 (返されたポインターを free(3) に渡さないこと。) 成功すると、 getpwnam_r() と getpwuid_r() は 0 を返し、 *result に pwd を設定する。 マッチするパスワードエントリーが見つからなかった場合には、 0 を返し、 *result に NULL を設定する。 エラーの場合、エラー番号を返し、 *result に NULL を設定する。

0 または ENOENT または ESRCH または EBADF または EPERM または ... 指定された name または uid が見つからなかった。 EINTR シグナルが捕捉された。 EIO I/O エラー。 EMFILE 呼び出し元プロセスがオープンしているファイル数が すでに上限 (OPEN_MAX) であった。 ENFILE システムでオープンされているファイル数がすでに上限であった。 ENOMEM passwd 構造体に割り当てるメモリーが十分なかった。 ERANGE 与えられたバッファー空間が不十分である。

/etc/passwd ローカルのパスワードデータベースファイル

マ 関数 getpwnam() と getpwuid() はスレッドセーフではない。 関数 getpwnam_r() と getpwuid_r() はスレッドセーフである。

SVr4, 4.3BSD, POSIX.1-2001. pw_gecos フィールドは POSIX では規定されていないが、 ほとんどの実装に存在する。

上記の「返り値」以下の記述は POSIX.1-2001 に拠る。 この標準は「(エントリーが) 見つからないこと」をエラーとしていないので、 そのような場合に errno がどのような値になるかを定めていない。 そのため、エラーを認識することは不可能である。 POSIX に準拠して、エントリーが見つからない場合は errno を変更しないようにすべきである、と主張する人もいるかもしれない。 様々な UNIX 系のシステムで試してみると、そのような場合には 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM といった様々な値が返される。 他の値が返されるかもしれない。 フィールド pw_dir には、ユーザーの作業ディレクトリ名の初期値が格納される。 ログインプロセスは、このフィールドの値を使って、 ログインシェルの HOME 環境変数を初期化する。 アプリケーションが、ユーザーのホームディレクトリを決定する場合には、 (getp‐ wuid(getuid())->pw_dir の値ではなく) HOME の値を検査するようにすべきである。 なぜなら、このようにすることで、ユーザーがログインセッション中で 「ホームディレクトリ」の意味を変更できるようになるからである。 別のユーザーのホームディレクトリ (の初期値) を知るには getpwnam("username")->pw_dir か同様の方法を使う必要がある。

以下のプログラムは getpwnam_r() の使用例を示したもので、コマンドライン引き数で渡されたユーザー名に対する 完全なユーザー名とユーザー ID を探すものである。 #include <pwd.h> #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <errno.h> int main(int argc, char *argv[]) { struct passwd pwd; struct passwd *result; char *buf; size_t bufsize; int s; if (argc != 2) { fprintf(stderr, "Usage: %s username\n", argv[0]); exit(EXIT_FAILURE); } bufsize = sysconf(_SC_GETPW_R_SIZE_MAX); if (bufsize == -1) /* 値を決定できなかった */ bufsize = 16384; /* 十分大きな値にすべき */ buf = malloc(bufsize); if (buf == NULL) { perror("malloc"); exit(EXIT_FAILURE); } s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result); if (result == NULL) { if (s == 0) printf("Not found\n"); else { errno = s; perror("getpwnam_r"); } exit(EXIT_FAILURE); } printf("Name: %s; UID: %ld\n", pwd.pw_gecos, (long) pwd.pw_uid); exit(EXIT_SUCCESS); }

endpwent(3), fgetpwent(3), getgrnam(3), getpw(3), getpwent(3), getspnam(3), putpwent(3), setpwent(3), passwd(5)

この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
GNU 2013-07-22 GETPWNAM(3)
getpwnam(3).txt (日本語 / Japanese)
Index English version of getpwnam(3)
Go top