書式

#include <sys/types.h>
#include <grp.h>

---

struct group *getgrnam(const char *name);

---

struct group *getgrgid(gid_t gid);

---

int getgrnam_r(const char *name, struct group *grp,
char *buf, size_t buflen, struct group **result);

---

int getgrgid_r(gid_t gid, struct group *grp,
char *buf, size_t buflen, struct group **result);

glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):

getgrnam_r(), getgrgid_r():

_POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE

説明

getgrnam() 関数は、グループ名 name にマッチするグループ・データベースのエントリを 要素毎に分解し、各要素を格納した構造体へのポインタを返す (パスワード・データベースの例: ローカルのグループファイル /etc/group, NIS, LDAP)。

getgrgid() 関数は、グループ ID uid にマッチするグループ・データベースのエントリを 要素毎に分解し、各要素を格納した構造体へのポインタを返す。

group 構造体は <grp.h> で以下のように定義されている:

struct group {
    char   *gr_name;       /* グループ名 */
    char   *gr_passwd;     /* グループのパスワード */
    gid_t   gr_gid;        /* グループ ID */
    char  **gr_mem;        /* グループのメンバ */
};

この構造体のフィールドの詳細は group(5) を参照のこと。

getgrnam_r() と getgrgid_r() 関数は、それぞれ getgrnam() と getgrgid() と同じ情報を取得するが、取得した group 構造体を grp が指す領域に格納する。group 構造体のメンバーが指す文字列は、 サイズ buflen のバッファ buf に格納される。成功した場合 *gbufp には結果へのポインタが格納される。エントリが見つからなかった 場合やエラーが発生した場合には *result には NULL が入る。

呼び出し

    sysconf(_SC_GETGR_R_SIZE_MAX)

は、 errno を変更せずに -1 を返すか、 buf の初期サイズの推奨値を 返す。(このサイズが小さすぎる場合、呼び出しは ERANGE で失敗し、この 場合には呼び出し側はバッファを大きくしてから再度呼び出すことができる。)

返り値

getgrnam() と getgrgid() 関数は、 group 構造体へのポインタを返す。 マッチするエントリが見つからなかった場合や、 エラーが発生した場合は NULL を返す。 エラーが起こった場合、 errno が適切に設定される。 呼び出しの後で errno をチェックしたい場合は、 呼び出しの前に (この値を) 0 に設定しておくべきである。

返り値は静的な領域を指しており、その後の getgrent(3), getgrgid(), getgrnam() の呼び出しで上書きされるかもしれない。 (返されたポインタを free(3) に渡さないこと。)

成功すると、 getgrnam_r() と getgrgid_r() は 0 を返し、 *result に grp を設定する。 マッチするグループ・エントリが見つからなかった場合には、 0 を返し、 *result に NULL を設定する。 エラーの場合、エラー番号を返し、 *result に NULL を設定する。

ファイル

/etc/group

ローカルのグループ・データベースファイル

属性

マルチスレッディング (pthreads(7) 参照)

関数 getgrnam() と getgrgid() はスレッドセーフではない。

関数 getgrnam_r() と getgrgid_r() はスレッドセーフである。

準拠

SVr4, 4.3BSD, POSIX.1-2001.

注意

上記の「返り値」以下の記述は POSIX.1-2001 に拠る。 この標準は「(エントリが) 見つからないこと」をエラーとしていないので、 そのような場合に errno がどのような値になるかを定めていない。 そのため、エラーを認識することは不可能である。 POSIX に準拠して、エントリが見つからない場合は errno を変更しないようにすべきである、と主張する人もいるかもしれない。 様々な UNIX 系のシステムで試してみると、そのような場合には 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM といった様々な値が返される。 他の値が返されるかもしれない。

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。