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