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$ 30.\" 31.Dd July 31, 2016 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 void 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 function 192.Fn setgroupent 193returns the value 1 if successful, otherwise the value 1940 is returned. 195The functions 196.Fn endgrent , 197.Fn setgrent 198and 199.Fn setgrfile 200have no return value. 201.Sh FILES 202.Bl -tag -width /etc/group -compact 203.It Pa /etc/group 204group database file 205.El 206.Sh COMPATIBILITY 207The historic function 208.Fn setgrfile , 209which allowed the specification of alternate password databases, has 210been deprecated and is no longer available. 211.Sh SEE ALSO 212.Xr getpwent 3 , 213.Xr group 5 , 214.Xr nsswitch.conf 5 , 215.Xr yp 8 216.Sh STANDARDS 217The 218.Fn getgrent , 219.Fn getgrnam , 220.Fn getgrnam_r , 221.Fn getgrgid , 222.Fn getgrgid_r 223and 224.Fn endgrent 225functions conform to 226.St -p1003.1-96 . 227The 228.Fn setgrent 229function differs from that standard in that its return type is 230.Vt int 231rather than 232.Vt void . 233.Sh HISTORY 234The functions 235.Fn endgrent , 236.Fn getgrent , 237.Fn getgrnam , 238.Fn getgrgid , 239and 240.Fn setgrent 241appeared in 242.At v7 . 243The functions 244.Fn setgrfile 245and 246.Fn setgroupent 247appeared in 248.Bx 4.3 Reno . 249The functions 250.Fn getgrent_r , 251.Fn getgrnam_r , 252and 253.Fn getgrgid_r 254appeared in 255.Fx 5.1 . 256.Sh BUGS 257The functions 258.Fn getgrent , 259.Fn getgrnam , 260.Fn getgrgid , 261.Fn setgroupent 262and 263.Fn setgrent 264leave their results in an internal static object and return 265a pointer to that object. 266Subsequent calls to 267the same function 268will modify the same object. 269.Pp 270The functions 271.Fn getgrent , 272.Fn getgrent_r , 273.Fn endgrent , 274.Fn setgroupent , 275and 276.Fn setgrent 277are fairly useless in a networked environment and should be 278avoided, if possible. 279The 280.Fn getgrent 281and 282.Fn getgrent_r 283functions 284make no attempt to suppress duplicate information if multiple 285sources are specified in 286.Xr nsswitch.conf 5 . 287