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