EN JA
GETGRENT(3)
GETGRENT(3) FreeBSD Library Functions Manual GETGRENT(3)

名称

getgrent, getgrent_r, getgrnam, getgrnam_r, getgrgid, getgrgid_r, setgroupent, setgrent, endgrentグループデータベースの操作

ライブラリ

Standard C Library (libc, -lc)

書式

#include < grp.h>

struct group *
getgrent( void);

int
getgrent_r( struct group *grp, char *buffer, size_t bufsize, struct group **result);

struct group *
getgrnam( const char *name);

int
getgrnam_r( const char *name, struct group *grp, char *buffer, size_t bufsize, struct group **result);

struct group *
getgrgid( gid_t gid);

int
getgrgid_r( gid_t gid, struct group *grp, char *buffer, size_t bufsize, struct group **result);

int
setgroupent( int stayopen);

int
setgrent( void);

void
endgrent( void);

解説

これらの関数は、 group(5) に記述されたグループデータベースファイル /etc/group を操作します。データベースの各行は、次のインクルードファイル < grp.h> にある構造体 group によって定義されます:

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

関数 getgrnam() および getgrgid() は、 name で指される与えられたグループ名または gid で指されるグループ id を、グループデータベースでそれぞれ検索して、最初に遭遇するエントリを返します。同一グループ名または、同一グループ id は、未定義な動作結果となるかもしれません。

getgrent() 関数は、グループデータベースを順次読み込みます。完全なグループリストを通して処置するプログラム向きです。

関数 getgrent_r(), getgrnam_r() および getgrgid_r() はそれぞれ getgrent(), getgrnam() および getgrgid(), のスレッドセーフバージョンです。呼び出し側は、 grp, buffer, bufsize および result 引数で検索の結果のための領域を提供しなければなりません。これらの関数が成功するとき、 grp 引数は満たされ、そしてその引数へのポインタが result に収納されます。エントリが見つけられないか、またはエラーが発生すると、 resultNULL に設定されます。

必要ならば、これらの関数はグループファイルを読み込みのためにオープンします。

setgroupent() 関数はファイルをオープンします、または既にオープンしている場合はリワインドします。 stayopen が 0 でなければ、ファイル記述子はオープンしたままにされ、以後の関数呼び出しがきわめて高速化されます。 getgrent() は、デフォルトでファイル記述子をクローズしないので、この機能は不要です。また、グループファイルが更新される可能性があるので、長期間実行するプログラムでこの機能を使用するのは危険であることに注意すべきです。

setgrent() 関数は、0 の引数を持つ setgroupent() と同じです。

endgrent() 関数は、オープンされているファイルをクローズします。

戻り値

関数 getgrent(), getgrnam() および getgrgid() は成功すれば group 構造体へのポインタを返し、エントリが見つけられないか、またはエラーが発生すれば、 NULL を返します。エラーが発生すると、 errno は設定されます。存在しないエントリとエラーを区別する必要があるなら、プログラムはこれらの関数のいずれかを呼び出す前に明白に errno に 0 を設定しなければならないことに注意してください。関数 getgrent_r(), getgrnam_r() および getgrgid_r() はエラーが発生しなかったならは 0 を、または、失敗すを示すエラー番号を返します。一致エントリが見つけられないなら、それはエラーではありません。 (上に述べたように、 resultNULL に設定されて、リターン値が 0 となり、一致エントリは存在しません。)

関数 setgroupent() および setgrent() は、成功した場合は値 1 を返します。その他の場合は値 0 が返ります。関数 endgrent() および setgrfile() の戻り値はありません。

関連ファイル

/etc/group
グループデータベースファイル

互換性

代替パスワードデータベースの規格を許した歴史的な関数 setgrfile() は、これまで非難されてきましたが、もはや使用できません。

規格

getgrent(), getgrnam(), getgrnam_r(), getgrgid(), getgrgid_r() および endgrent() 関数は ISO/IEC 9945-1:1996 (“POSIX.1”) に適合しています。 setgrent() 関数はリターンタイプが void よりむしろ int であるという点において規格と異なっています。

歴史

関数 endgrent(), getgrent(), getgrnam(), getgrgid(), setgrent() は、 Version 7 AT&T UNIX で登場しました。関数 setgrfile() と setgroupent() は、 4.3BSD-Reno で登場しました。関数 getgrent_r(), getgrnam_r() と getgrgid_r() は、 FreeBSD 5.1 で登場しました。

バグ

関数 getgrent(), getgrnam(), getgrgid(), setgroupent(), setgrent() は、それらの結果を内部の静的オブジェクトに残し、そのオブジェクトのポインタを返します。後に続く同じ関数の呼び出しは、その同じオブジェクトを修正します。

関数 getgrent(), getgrent_r(), endgrent(), setgroupent() と setgrent() はネットワークでつながれた環境でほとんど役に立たなくなり、可能であれば、避けられるべきです。複数のソースが nsswitch.conf(5) で指定されるなら、 getgrent() と getgrent_r() 関数は二重化された情報を削除する試みを行ないません。

April 16, 2003 FreeBSD