1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)getgrent.3 8.2 (Berkeley) 4/19/94 33.\" $FreeBSD: src/lib/libc/gen/getgrent.3,v 1.12.2.4 2003/03/15 15:11:05 trhodes Exp $ 34.\" $DragonFly: src/lib/libc/gen/getgrent.3,v 1.4 2006/05/26 19:39:36 swildner Exp $ 35.\" 36.Dd September 29, 1994 37.Dt GETGRENT 3 38.Os 39.Sh NAME 40.Nm getgrent , 41.Nm getgrnam , 42.Nm getgrgid , 43.Nm setgroupent , 44.\" .Nm setgrfile , 45.Nm setgrent , 46.Nm endgrent 47.Nd group database operations 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In sys/types.h 52.In grp.h 53.Ft struct group * 54.Fn getgrent void 55.Ft struct group * 56.Fn getgrnam "const char *name" 57.Ft struct group * 58.Fn getgrgid "gid_t gid" 59.Ft int 60.Fn setgroupent "int stayopen" 61.\" .Ft void 62.\" .Fn setgrfile "const char *name" 63.Ft int 64.Fn setgrent void 65.Ft void 66.Fn endgrent void 67.Sh DESCRIPTION 68These functions operate on the group database file 69.Pa /etc/group 70which is described 71in 72.Xr group 5 . 73Each line of the database is defined by the structure 74.Vt group 75found in the include 76file 77.In grp.h : 78.Bd -literal -offset indent 79struct group { 80 char *gr_name; /* group name */ 81 char *gr_passwd; /* group password */ 82 int gr_gid; /* group id */ 83 char **gr_mem; /* group members */ 84}; 85.Ed 86.Pp 87The functions 88.Fn getgrnam 89and 90.Fn getgrgid 91search the group database for the given group name pointed to by 92.Fa name 93or the group id pointed to by 94.Fa gid , 95respectively, returning the first one encountered. Identical group 96names or group gids may result in undefined behavior. 97.Pp 98The 99.Fn getgrent 100function 101sequentially reads the group database and is intended for programs 102that wish to step through the complete list of groups. 103.Pp 104All three routines will open the group file for reading, if necessary. 105.Pp 106The 107.Fn setgroupent 108function 109opens the file, or rewinds it if it is already open. If 110.Fa stayopen 111is non-zero, file descriptors are left open, significantly speeding 112functions subsequent calls. This functionality is unnecessary for 113.Fn getgrent 114as it doesn't close its file descriptors by default. It should also 115be noted that it is dangerous for long-running programs to use this 116functionality as the group file may be updated. 117.Pp 118The 119.Fn setgrent 120function 121is identical to 122.Fn setgroupent 123with an argument of zero. 124.Pp 125The 126.Fn endgrent 127function 128closes any open files. 129.Sh YP/NIS INTERACTION 130When the 131.Xr yp 8 132group database is enabled, the 133.Fn getgrnam 134and 135.Fn getgrgid 136functions use the YP maps 137.Dq Li group.byname 138and 139.Dq Li group.bygid , 140respectively, if the requested group is not found in the local 141.Pa /etc/group 142file. The 143.Fn getgrent 144function will step through the YP map 145.Dq Li group.byname 146if the entire map is enabled as described in 147.Xr group 5 . 148.Sh RETURN VALUES 149The functions 150.Fn getgrent , 151.Fn getgrnam , 152and 153.Fn getgrgid , 154return a pointer to the group entry if successful; if end-of-file 155is reached or an error occurs a null pointer is returned. 156The functions 157.Fn setgroupent 158and 159.Fn setgrent 160return the value 1 if successful, otherwise the value 1610 is returned. 162The functions 163.Fn endgrent 164and 165.Fn setgrfile 166have no return value. 167.Sh FILES 168.Bl -tag -width /etc/group -compact 169.It Pa /etc/group 170group database file 171.El 172.Sh COMPATIBILITY 173The historic function 174.Fn setgrfile , 175which allowed the specification of alternate password databases, has 176been deprecated and is no longer available. 177.Sh SEE ALSO 178.Xr getpwent 3 , 179.Xr group 5 , 180.Xr yp 8 181.Sh HISTORY 182The functions 183.Fn endgrent , 184.Fn getgrent , 185.Fn getgrnam , 186.Fn getgrgid , 187and 188.Fn setgrent 189appeared in 190.At v7 . 191The functions 192.Fn setgrfile 193and 194.Fn setgroupent 195appeared in 196.Bx 4.3 Reno . 197.Sh BUGS 198The functions 199.Fn getgrent , 200.Fn getgrnam , 201.Fn getgrgid , 202.Fn setgroupent 203and 204.Fn setgrent 205leave their results in an internal static object and return 206a pointer to that object. 207Subsequent calls to 208the same function 209will modify the same object. 210