名前
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 *gbuf,
char *buf, size_t buflen, struct group **gbufp);
int getgrgid_r(gid_t gid, struct group *gbuf,
char *buf, size_t buflen, struct group **gbufp);
説明
getgrnam() 関数は、グループ名 name にマッチするグループ・データベースのエントリを 要素毎に分解し、各要素を格納した構造体へのポインタを返す (パスワード・データベースの例: ローカルのグループファイル /etc/group, NIS, LDAP)。
getgrgid() 関数は、グループ ID uid にマッチするグループ・データベースのエントリを 要素毎に分解し、各要素を格納した構造体へのポインタを返す。
getgrnam_r() と getgrgid_r() 関数は (上記の関数と) 同じ情報を取得するが、 取得した group 構造体を gbuf が指す領域に格納する。 この group 構造体には文字列へのポインタが含まれ、 これらの文字列はサイズ buflen のバッファ buf に格納される。 成功した場合 *gbufp には結果へのポインタが格納される。 エントリが見つからなかった場合やエラーが発生した場合には *gbufp には NULL が入る。
group 構造体は、<grp.h> で以下のように定義されている:
struct group { char *gr_name; /* グループ名 */ char *gr_passwd; /* グループのバスワード */ gid_t gr_gid; /* グループ ID */ char **gr_mem; /* グループのメンバ */ };
buf に最大必要なサイズは、 sysconf(3) に引き数 _SC_GETGR_R_SIZE_MAX を指定して実行することで分かる。
返り値
getgrnam() と getgrgid() 関数は、 group 構造体へのポインタを返す。 一致するエントリが見つからなかった場合や、エラーが発生した場合は NULL を返す。 エラーが起こった場合、 errno が適切に設定される。 呼び出しの後で errno をチェックしたい場合は、 呼び出しの前に (この値を) 0 に設定しておくべきである。
返り値は静的な領域を指しており、その後の getgrent(), getgrgid(), getgrnam() の呼び出しで上書きされるかもしれない。
getgrnam_r() と getgrgid_r() 関数は、 成功した場合に 0 を返す。 エラーの場合は、エラー番号が返される。
エラー
| 0 または ENOENT または ESRCH または EBADF または EPERM または ... | |
| 指定された name または gid が見つからなかった。 | |
| EINTR | シグナルがキャッチされた。 |
| EIO | I/O エラー。 |
| EMFILE | 呼び出したプロセスにおいて、 既に最大数 (OPEN_MAX) のファイルがオープンされている。 |
| ENFILE | システム上で既に最大数のファイルがオープンされている。 |
| ENOMEM | group 構造体を割り当てるためのメモリが不十分。 |
| ERANGE | 与えられたバッファ空間が不十分である。 |
ファイル
| /etc/group | |
| ローカルのグループ・データベースファイル | |
準拠
SVr4, 4.3BSD, POSIX.1-2001
注意
上記の「返り値」以下の記述は POSIX.1-2001 に拠る。 この標準は「(エントリが) 見つからないこと」をエラーとしていないので、 そのような場合に errno がどのような値になるかを定めていない。 そのため、エラーを認識することは不可能である。 POSIX に準拠して、エントリが見つからない場合は errno を変更しないようにすべきである、と主張する人もいるかもしれない。 様々な Unix 系のシステムで試してみると、そのような場合には 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM といった様々な値が返される。 他の値が返されるかもしれない。
関連項目
endgrent(3), fgetgrent(3), getgrent(3), getpwnam(3), setgrent(3), group(5)
