.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     From: @(#)getgrent.3	8.2 (Berkeley) 4/19/94
.\"	$Id: getgrent.3,v 1.4 2002-05-18 07:12:54 horikawa Exp $
.\"
.\" $FreeBSD$
.Dd September 29, 1994
.Dt GETGRENT 3
.Os
.Sh 名称
.Nm getgrent ,
.Nm getgrnam ,
.Nm getgrgid ,
.Nm setgroupent ,
.\" .Nm setgrfile ,
.Nm setgrent ,
.Nm endgrent
.Nd グループデータベースの操作
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <grp.h>
.Ft struct group *
.Fn getgrent void
.Ft struct group *
.Fn getgrnam "const char *name"
.Ft struct group *
.Fn getgrgid "gid_t gid"
.Ft int
.Fn setgroupent "int stayopen"
.\" .Ft void
.\" .Fn setgrfile "const char *name"
.Ft int
.Fn setgrent void
.Ft void
.Fn endgrent void
.Sh 解説
これらの関数はいずれも、
.Xr group 5
に記述されたグループデータベースファイル
.Pa /etc/group
を操作します。データベースの各行は、インクルードファイル
.Aq Pa grp.h
にある構造体
.Ar group
によって定義されます。次のとおりです。
.Bd -literal -offset indent
struct group {
	char	*gr_name;	/* グループ名 */
	char	*gr_passwd;	/* グループパスワード */
	int	gr_gid;		/* グループ id */
	char	**gr_mem;	/* グループメンバ */
};
.Ed
.Pp
関数
.Fn getgrnam
および
.Fn getgrgid
は、
.Ar name
に示す与えられたグループ名または
.Ar gid
に示すグループ id を、グループデータベースで検索して、それぞれに最初の
適合エントリを返します。異なるエントリに同一グループ名または、同一グループ id
が与えられていると、未定義な不測の挙動をもたらすことがあります。
.Pp
.Fn getgrent
関数は、グループデータベースを順次読み込みます。完全な
グループリストを着実に生成するプログラム向きです。
.Pp
3 つのルーチンはいずれも、読み込みに必要ならば目的のグループファイルを
オープンします。
.Pp
.Fn setgroupent
関数は目的のファイルをオープン、またはすでにオープンされている
場合はリワインドします。
.Fa stayopen
が 0 でなければ、ファイル記述子はオープン
のままにされ、以後の関数呼び出しがきわめて高速化されます。ただし
.Fn getgrent
の場合は、デフォルトでファイル記述子をクローズしないので、この
機能は不要です。また、グループファイルが更新される可能性があるので、
長期間実行するプログラムでこの機能を使用するのは危険です。注意してください。
.Pp
.Fn setgrent
関数は、0 の引数を持つ
.Fn setgroupent
と同じです。
.Pp
.Fn endgrent
関数は、オープンされているファイルをクローズします。
.Sh YP/NIS の相互作用
.Xr yp 4
グループデータベースが使用可能な場合、要求されたグループがローカルの
.Pa /etc/groupfile
に見付からないと、
.Fn getgrnam
および
.Fn getgrgid
関数は、
YP マップ
.Dq group.byname
および
.Dq group.bygid
をそれぞれ使用します。
.Xr group 5
で記述されたとおりに全体マップが使用可能ならば、
.Fn getgrent
関数は YP マップ
.Dq group.byname
を通ります。
.Sh 戻り値
関数
.Fn getgrent ,
.Fn getgrnam ,
.Fn getgrgid
は、いずれも成功すると
グループエントリのポインタを返します。エンドオブファイルに到達するかエラー
が発生した場合は、ヌルポインタが返ります。関数
.Fn setgroupent
および
.Fn setgrent
は、処理が無事に完了した場合は値 1 を返します。
その他の場合は値 0 が返ります。
関数
.Fn endgrent
および
.Fn setgrfile
の戻り値はありません。
.Pp
.Sh 関連ファイル
.Bl -tag -width /etc/group -compact
.It Pa /etc/group
グループデータベースファイル
.El
.Sh 関連項目
.Xr getpwent 3 ,
.Xr yp 4 ,
.Xr group 5
.Sh 歴史
関数
.Fn endgrent ,
.Fn getgrent ,
.Fn getgrnam ,
.Fn getgrgid ,
.Fn setgrent
は、
.At v7
で最初に取り入れられました。関数
.Fn setgrfile
および
.Fn setgroupent
は、
.Bx 4.3 Reno
で最初に取り入れられました。
.Sh 互換性
代替パスワードデータベースの規格を許した歴史的な関数
.Fn setgrfile
は、これまで非難されてきましたが、もはや使用できません。
.Sh バグ
関数
.Fn getgrent ,
.Fn getgrnam ,
.Fn getgrgid ,
.Fn setgroupent ,
.Fn setgrent
は、それぞれの結果を内部の静的オブジェクトに残し、そのオブジェクトの
ポインタを返します。後に続く同じ関数の呼び出しは、その同じオブジェクトを
改変します。