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.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" From: @(#)getgrent.3 8.2 (Berkeley) 4/19/94 29.\" $FreeBSD$ 30.\" 31.Dd April 16, 2003 32.Dt GETGRENT 3 33.Os 34.Sh NAME 35.Nm getgrent , 36.Nm getgrent_r , 37.Nm getgrnam , 38.Nm getgrnam_r , 39.Nm getgrgid , 40.Nm getgrgid_r , 41.Nm setgroupent , 42.Nm setgrent , 43.Nm endgrent 44.Nd group database operations 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In grp.h 49.Ft struct group * 50.Fn getgrent void 51.Ft int 52.Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 53.Ft struct group * 54.Fn getgrnam "const char *name" 55.Ft int 56.Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 57.Ft struct group * 58.Fn getgrgid "gid_t gid" 59.Ft int 60.Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 61.Ft int 62.Fn setgroupent "int stayopen" 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 gid_t 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. 96Identical group 97names or group gids may result in undefined behavior. 98.Pp 99The 100.Fn getgrent 101function 102sequentially reads the group database and is intended for programs 103that wish to step through the complete list of groups. 104.Pp 105The functions 106.Fn getgrent_r , 107.Fn getgrnam_r , 108and 109.Fn getgrgid_r 110are thread-safe versions of 111.Fn getgrent , 112.Fn getgrnam , 113and 114.Fn getgrgid , 115respectively. 116The caller must provide storage for the results of the search in 117the 118.Fa grp , 119.Fa buffer , 120.Fa bufsize , 121and 122.Fa result 123arguments. 124When these functions are successful, the 125.Fa grp 126argument will be filled-in, and a pointer to that argument will be 127stored in 128.Fa result . 129If an entry is not found or an error occurs, 130.Fa result 131will be set to 132.Dv NULL . 133.Pp 134These functions will open the group file for reading, if necessary. 135.Pp 136The 137.Fn setgroupent 138function 139opens the file, or rewinds it if it is already open. 140If 141.Fa stayopen 142is non-zero, file descriptors are left open, significantly speeding 143functions subsequent calls. 144This functionality is unnecessary for 145.Fn getgrent 146as it does not close its file descriptors by default. 147It should also 148be noted that it is dangerous for long-running programs to use this 149functionality as the group file may be updated. 150.Pp 151The 152.Fn setgrent 153function 154is identical to 155.Fn setgroupent 156with an argument of zero. 157.Pp 158The 159.Fn endgrent 160function 161closes any open files. 162.Sh RETURN VALUES 163The functions 164.Fn getgrent , 165.Fn getgrnam , 166and 167.Fn getgrgid , 168return a pointer to a group structure on success or 169.Dv NULL 170if the entry is not found or if an error occurs. 171If an error does occur, 172.Va errno 173will be set. 174Note that programs must explicitly set 175.Va errno 176to zero before calling any of these functions if they need to 177distinguish between a non-existent entry and an error. 178The functions 179.Fn getgrent_r , 180.Fn getgrnam_r , 181and 182.Fn getgrgid_r 183return 0 if no error occurred, or an error number to indicate failure. 184It is not an error if a matching entry is not found. 185(Thus, if 186.Fa result 187is set to 188.Dv NULL 189and the return value is 0, no matching entry exists.) 190.Pp 191The functions 192.Fn setgroupent 193and 194.Fn setgrent 195return the value 1 if successful, otherwise the value 1960 is returned. 197The functions 198.Fn endgrent 199and 200.Fn setgrfile 201have no return value. 202.Sh FILES 203.Bl -tag -width /etc/group -compact 204.It Pa /etc/group 205group database file 206.El 207.Sh COMPATIBILITY 208The historic function 209.Fn setgrfile , 210which allowed the specification of alternate password databases, has 211been deprecated and is no longer available. 212.Sh SEE ALSO 213.Xr getpwent 3 , 214.Xr group 5 , 215.Xr nsswitch.conf 5 , 216.Xr yp 8 217.Sh STANDARDS 218The 219.Fn getgrent , 220.Fn getgrnam , 221.Fn getgrnam_r , 222.Fn getgrgid , 223.Fn getgrgid_r 224and 225.Fn endgrent 226functions conform to 227.St -p1003.1-96 . 228The 229.Fn setgrent 230function differs from that standard in that its return type is 231.Vt int 232rather than 233.Vt void . 234.Sh HISTORY 235The functions 236.Fn endgrent , 237.Fn getgrent , 238.Fn getgrnam , 239.Fn getgrgid , 240and 241.Fn setgrent 242appeared in 243.At v7 . 244The functions 245.Fn setgrfile 246and 247.Fn setgroupent 248appeared in 249.Bx 4.3 Reno . 250The functions 251.Fn getgrent_r , 252.Fn getgrnam_r , 253and 254.Fn getgrgid_r 255appeared in 256.Fx 5.1 . 257.Sh BUGS 258The functions 259.Fn getgrent , 260.Fn getgrnam , 261.Fn getgrgid , 262.Fn setgroupent 263and 264.Fn setgrent 265leave their results in an internal static object and return 266a pointer to that object. 267Subsequent calls to 268the same function 269will modify the same object. 270.Pp 271The functions 272.Fn getgrent , 273.Fn getgrent_r , 274.Fn endgrent , 275.Fn setgroupent , 276and 277.Fn setgrent 278are fairly useless in a networked environment and should be 279avoided, if possible. 280The 281.Fn getgrent 282and 283.Fn getgrent_r 284functions 285make no attempt to suppress duplicate information if multiple 286sources are specified in 287.Xr nsswitch.conf 5 . 288