名前

       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.79 の一部  である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。