1.\" $OpenBSD: getgrent.3,v 1.24 2019/08/30 23:35:40 jmc Exp $ 2.\" 3.\" Copyright (c) 1989, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: August 30 2019 $ 31.Dt GETGRENT 3 32.Os 33.Sh NAME 34.Nm getgrent , 35.Nm getgrnam , 36.Nm getgrnam_r , 37.Nm getgrgid , 38.Nm getgrgid_r , 39.Nm setgroupent , 40.Nm setgrent , 41.Nm endgrent 42.Nd group database operations 43.Sh SYNOPSIS 44.In grp.h 45.Ft struct group * 46.Fn getgrent void 47.Ft struct group * 48.Fn getgrnam "const char *name" 49.Ft int 50.Fn getgrnam_r "const char *name" "struct group *grp" "char *buf" "size_t bufsize" "struct group **result" 51.Ft struct group * 52.Fn getgrgid "gid_t gid" 53.Ft int 54.Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buf" "size_t bufsize" "struct group **result" 55.Ft int 56.Fn setgroupent "int stayopen" 57.Ft void 58.Fn setgrent void 59.Ft void 60.Fn endgrent void 61.Sh DESCRIPTION 62These functions operate on the group database file 63.Pa /etc/group 64which is described 65in 66.Xr group 5 . 67Each line of the database is defined by the structure 68.Li struct group 69found in the include 70file 71.In grp.h : 72.Bd -literal -offset indent 73struct group { 74 char *gr_name; /* group name */ 75 char *gr_passwd; /* group password */ 76 gid_t gr_gid; /* group id */ 77 char **gr_mem; /* group members */ 78}; 79.Ed 80.Pp 81The functions 82.Fn getgrnam 83and 84.Fn getgrgid 85search the group database for the given group name pointed to by 86.Fa name 87or the group ID pointed to by 88.Fa gid , 89respectively, returning the first one encountered. 90Identical group names or group GIDs may result in undefined behavior. 91.Pp 92.Fn getgrent 93sequentially reads the group database and is intended for programs 94that wish to step through the complete list of groups. 95.Pp 96All three routines will open the group file for reading, if necessary. 97.Pp 98.Fn setgroupent 99opens the file, or rewinds it if it is already open. 100If 101.Fa stayopen 102is non-zero, file descriptors are left open, significantly speeding 103subsequent function calls. 104This functionality is unnecessary for 105.Fn getgrent 106as it doesn't close its file descriptors by default. 107It should also 108be noted that it is dangerous for long-running programs to use this 109functionality as the group file may be updated. 110.Pp 111.Fn setgrent 112is equivalent to 113.Fn setgroupent 114with an argument of zero. 115.Pp 116The 117.Fn endgrent 118function closes any open files. 119.Pp 120The 121.Fn getgrgid_r 122and 123.Fn getgrnam_r 124functions both update the group structure pointed to by 125.Fa grp 126and store a pointer to that structure at the location pointed to by 127.Fa result . 128The structure is filled with an entry from the group database with a 129matching 130.Fa gid 131or 132.Fa name . 133Storage referenced by the group structure will be allocated from the memory 134provided with the 135.Fa buf 136parameter, which is 137.Fa bufsiz 138characters in size. 139The maximum size needed for this buffer can be determined with 140.Fn sysconf _SC_GETGR_R_SIZE_MAX . 141.Ss YP support 142If YP is active, the functions 143.Fn getgrent 144and 145.Fn getgrnam 146also use the 147.Pa group.byname 148YP map and the function 149.Fn getgrgid 150also uses the 151.Pa group.bygid 152YP map in addition to the group file, 153respecting the order of normal and YP entries in the group file. 154.Sh RETURN VALUES 155The functions 156.Fn getgrent , 157.Fn getgrnam , 158and 159.Fn getgrgid 160return a pointer to the group entry if successful; if end-of-file 161is reached or an error occurs a 162.Dv NULL 163pointer is returned. 164.Pp 165The 166.Fn setgroupent 167function returns the value 1 if successful, otherwise 0. 168.Pp 169The 170.Fn endgrent 171and 172.Fn setgrent 173functions have no return value. 174.Pp 175The functions 176.Fn getgrgid_r 177and 178.Fn getgrnam_r 179update 180.Ar result 181to point to 182.Ar grp 183if a match is found or set it to 184.Dv NULL 185if no match is found or an error occurs. 186They return 0 on success, even if no match is found, 187or an error number if an error occurs; see 188.Sx ERRORS . 189.Sh FILES 190.Bl -tag -width /etc/group -compact 191.It Pa /etc/group 192group database file 193.El 194.Sh ERRORS 195The 196.Fn getgrgid_r 197and 198.Fn getgrnam_r 199functions may fail if: 200.Bl -tag -width Er 201.It Bq Er ERANGE 202The storage supplied via 203.Fa buf 204and 205.Fa bufsize 206is too small and cannot contain all the strings to be returned in 207.Fa grp . 208.El 209.Pp 210The 211.Fn getgrent , 212.Fn getgrgid , 213.Fn getgrgid_r , 214.Fn getgrnam , 215and 216.Fn getgrnam_r 217functions may also fail for any of the errors specified for 218.Xr fgets 3 , 219.Xr getc 3 , 220and 221.Xr strtoul 3 . 222If YP is active, they may also fail due to errors caused by the YP subsystem. 223.Pp 224The 225.Fn setgroupent 226function may fail for any of the errors specified for 227.Xr fopen 3 . 228.Pp 229The 230.Fn endgrent , 231.Fn getgrgid_r , 232.Fn getgrnam_r , 233and 234.Fn setgrent 235functions do not set errno. 236.Sh SEE ALSO 237.Xr getpwent 3 , 238.Xr sysconf 3 , 239.Xr yp_bind 3 , 240.Xr group 5 , 241.Xr yp 8 242.Sh STANDARDS 243The functions 244.Fn getgrgid , 245.Fn getgrgid_r , 246.Fn getgrnam , 247and 248.Fn getgrnam_r 249are compliant with the 250.St -p1003.1-2008 251specification. 252.Pp 253The functions 254.Fn endgrent , 255.Fn getgrent , 256and 257.Fn setgrent 258are compliant with the X/Open System Interfaces option of the 259.St -p1003.1-2008 260specification. 261.Pp 262.Sx YP support 263and the 264.Fn setgroupent 265function are extensions to that specification. 266.Sh HISTORY 267The functions 268.Fn endgrent , 269.Fn getgrent , 270.Fn getgrnam , 271.Fn getgrgid , 272and 273.Fn setgrent 274appeared in 275.At v7 . 276The 277.Fn setgroupent 278function appeared in 279.Bx 4.3 Reno . 280.Pp 281The historic function 282.Fn setgrfile , 283which allowed the specification of alternate group databases, has 284been deprecated and is no longer available. 285.Sh BUGS 286The functions 287.Fn getgrent , 288.Fn getgrnam , 289.Fn getgrgid , 290.Fn setgroupent , 291and 292.Fn setgrent 293leave their results in an internal static object and return 294a pointer to that object. 295Subsequent calls to the same function will modify the same object. 296.Pp 297The functions 298.Fn getgrent , 299.Fn endgrent , 300.Fn setgroupent , 301and 302.Fn setgrent 303are fairly useless in a networked environment and should be 304avoided, if possible. 305