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