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$ 34.\" 35.Dd April 16, 2003 36.Dt GETGRENT 3 37.Os 38.Sh NAME 39.Nm getgrent , 40.Nm getgrent_r , 41.Nm getgrnam , 42.Nm getgrnam_r , 43.Nm getgrgid , 44.Nm getgrgid_r , 45.Nm setgroupent , 46.Nm setgrent , 47.Nm endgrent 48.Nd group database operations 49.Sh LIBRARY 50.Lb libc 51.Sh SYNOPSIS 52.In grp.h 53.Ft struct group * 54.Fn getgrent void 55.Ft int 56.Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 57.Ft struct group * 58.Fn getgrnam "const char *name" 59.Ft int 60.Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 61.Ft struct group * 62.Fn getgrgid "gid_t gid" 63.Ft int 64.Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 65.Ft int 66.Fn setgroupent "int stayopen" 67.Ft int 68.Fn setgrent void 69.Ft void 70.Fn endgrent void 71.Sh DESCRIPTION 72These functions operate on the group database file 73.Pa /etc/group 74which is described 75in 76.Xr group 5 . 77Each line of the database is defined by the structure 78.Vt group 79found in the include 80file 81.In grp.h : 82.Bd -literal -offset indent 83struct group { 84 char *gr_name; /* group name */ 85 char *gr_passwd; /* group password */ 86 gid_t gr_gid; /* group id */ 87 char **gr_mem; /* group members */ 88}; 89.Ed 90.Pp 91The functions 92.Fn getgrnam 93and 94.Fn getgrgid 95search the group database for the given group name pointed to by 96.Fa name 97or the group id pointed to by 98.Fa gid , 99respectively, returning the first one encountered. 100Identical group 101names or group gids may result in undefined behavior. 102.Pp 103The 104.Fn getgrent 105function 106sequentially reads the group database and is intended for programs 107that wish to step through the complete list of groups. 108.Pp 109The functions 110.Fn getgrent_r , 111.Fn getgrnam_r , 112and 113.Fn getgrgid_r 114are thread-safe versions of 115.Fn getgrent , 116.Fn getgrnam , 117and 118.Fn getgrgid , 119respectively. 120The caller must provide storage for the results of the search in 121the 122.Fa grp , 123.Fa buffer , 124.Fa bufsize , 125and 126.Fa result 127arguments. 128When these functions are successful, the 129.Fa grp 130argument will be filled-in, and a pointer to that argument will be 131stored in 132.Fa result . 133If an entry is not found or an error occurs, 134.Fa result 135will be set to 136.Dv NULL . 137.Pp 138These functions will open the group file for reading, if necessary. 139.Pp 140The 141.Fn setgroupent 142function 143opens the file, or rewinds it if it is already open. 144If 145.Fa stayopen 146is non-zero, file descriptors are left open, significantly speeding 147functions subsequent calls. 148This functionality is unnecessary for 149.Fn getgrent 150as it does not close its file descriptors by default. 151It should also 152be noted that it is dangerous for long-running programs to use this 153functionality as the group file may be updated. 154.Pp 155The 156.Fn setgrent 157function 158is identical to 159.Fn setgroupent 160with an argument of zero. 161.Pp 162The 163.Fn endgrent 164function 165closes any open files. 166.Sh RETURN VALUES 167The functions 168.Fn getgrent , 169.Fn getgrnam , 170and 171.Fn getgrgid , 172return a pointer to a group structure on success or 173.Dv NULL 174if the entry is not found or if an error occurs. 175If an error does occur, 176.Va errno 177will be set. 178Note that programs must explicitly set 179.Va errno 180to zero before calling any of these functions if they need to 181distinguish between a non-existent entry and an error. 182The functions 183.Fn getgrent_r , 184.Fn getgrnam_r , 185and 186.Fn getgrgid_r 187return 0 if no error occurred, or an error number to indicate failure. 188It is not an error if a matching entry is not found. 189(Thus, if 190.Fa result 191is set to 192.Dv NULL 193and the return value is 0, no matching entry exists.) 194.Pp 195The functions 196.Fn setgroupent 197and 198.Fn setgrent 199return the value 1 if successful, otherwise the value 2000 is returned. 201The functions 202.Fn endgrent 203and 204.Fn setgrfile 205have no return value. 206.Sh FILES 207.Bl -tag -width /etc/group -compact 208.It Pa /etc/group 209group database file 210.El 211.Sh COMPATIBILITY 212The historic function 213.Fn setgrfile , 214which allowed the specification of alternate password databases, has 215been deprecated and is no longer available. 216.Sh SEE ALSO 217.Xr getpwent 3 , 218.Xr group 5 , 219.Xr nsswitch.conf 5 , 220.Xr yp 8 221.Sh STANDARDS 222The 223.Fn getgrent , 224.Fn getgrnam , 225.Fn getgrnam_r , 226.Fn getgrgid , 227.Fn getgrgid_r 228and 229.Fn endgrent 230functions conform to 231.St -p1003.1-96 . 232The 233.Fn setgrent 234function differs from that standard in that its return type is 235.Vt int 236rather than 237.Vt void . 238.Sh HISTORY 239The functions 240.Fn endgrent , 241.Fn getgrent , 242.Fn getgrnam , 243.Fn getgrgid , 244and 245.Fn setgrent 246appeared in 247.At v7 . 248The functions 249.Fn setgrfile 250and 251.Fn setgroupent 252appeared in 253.Bx 4.3 Reno . 254The functions 255.Fn getgrent_r , 256.Fn getgrnam_r , 257and 258.Fn getgrgid_r 259appeared in 260.Fx 5.1 . 261.Sh BUGS 262The functions 263.Fn getgrent , 264.Fn getgrnam , 265.Fn getgrgid , 266.Fn setgroupent 267and 268.Fn setgrent 269leave their results in an internal static object and return 270a pointer to that object. 271Subsequent calls to 272the same function 273will modify the same object. 274.Pp 275The functions 276.Fn getgrent , 277.Fn getgrent_r , 278.Fn endgrent , 279.Fn setgroupent , 280and 281.Fn setgrent 282are fairly useless in a networked environment and should be 283avoided, if possible. 284The 285.Fn getgrent 286and 287.Fn getgrent_r 288functions 289make no attempt to suppress duplicate information if multiple 290sources are specified in 291.Xr nsswitch.conf 5 . 292