Provided by: manpages-ja-dev_0.5.0.0.20131015+dfsg-2_all 
名前
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
ローカルのパスワード・データベースファイル
属性
マルチスレッディング (pthreads(7) 参照) 関数 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 環境変数を初期化する。 アプリケー
ションが、ユーザのホーム・ディレクトリを決定する場合には、 (getpwuid(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.54 の一部 である。プロジェクト
の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。