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.\" 4. 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 int 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 functions 193.Fn setgroupent 194and 195.Fn setgrent 196return the value 1 if successful, otherwise the value 1970 is returned. 198The 199.Fn endgrent 200function has 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 256and 257.Dx 2.1 . 258.Sh BUGS 259The functions 260.Fn getgrent , 261.Fn getgrnam , 262.Fn getgrgid , 263.Fn setgroupent 264and 265.Fn setgrent 266leave their results in an internal static object and return 267a pointer to that object. 268Subsequent calls to 269the same function 270will modify the same object. 271.Pp 272The functions 273.Fn getgrent , 274.Fn getgrent_r , 275.Fn endgrent , 276.Fn setgroupent , 277and 278.Fn setgrent 279are fairly useless in a networked environment and should be 280avoided, if possible. 281The 282.Fn getgrent 283and 284.Fn getgrent_r 285functions 286make no attempt to suppress duplicate information if multiple 287sources are specified in 288.Xr nsswitch.conf 5 . 289