Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
getgrnam, getgrnam_r, getgrgid, getgrgid_r - グループファイルエントリーの取り出し
書式
#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
|| /* glibc 2.19 以前: */ _BSD_SOURCE || _SVID_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 を設定する。
エラー
0 または ENOENT または ESRCH または EBADF または EPERM または ...
指定された name または gid が見つからなかった。
EINTR シグナルが捕捉された。signal(7) 参照。
EIO I/O エラー。
EMFILE オープンされたファイルディスクリプター数がプロセス毎の上限に達している。
ENFILE オープンされたファイルの総数がシステム全体の上限に達している。
ENOMEM group 構造体を割り当てるためのメモリーが不十分。
ERANGE 与えられたバッファー空間が不十分である。
ファイル
/etc/group
ローカルのグループデータベースファイル
属性
この節で使用されている用語の説明については、 attributes(7) を参照。
┌─────────────────┬───────────────┬─────────────────────────────┐
│インターフェース │ 属性 │ 値 │
├─────────────────┼───────────────┼─────────────────────────────┤
│getgrnam() │ Thread safety │ MT-Unsafe race:grnam locale │
├─────────────────┼───────────────┼─────────────────────────────┤
│getgrgid() │ Thread safety │ MT-Unsafe race:grgid locale │
├─────────────────┼───────────────┼─────────────────────────────┤
│getgrnam_r(), │ Thread safety │ MT-Safe locale │
│getgrgid_r() │ │ │
└─────────────────┴───────────────┴─────────────────────────────┘
準拠
POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
注意
上記の「返り値」以下の記述は POSIX.1 に拠る。 この標準は「(エントリーが) 見つからないこ
と」をエラーとしていないので、 そのような場合に errno がどのような値になるかを定めていな
い。 そのため、エラーを認識することは不可能である。 POSIX に準拠して、エントリーが見つから
ない場合は errno を変更しないようにすべきである、と主張する人もいるかもしれない。 様々な
UNIX 系のシステムで試してみると、そのような場合には 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK,
EPERM といった様々な値が返される。 他の値が返されるかもしれない。
関連項目
endgrent(3), fgetgrent(3), getgrent(3), getpwnam(3), setgrent(3), group(5)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。
2017-09-15 GETGRNAM(3)