1.\" $OpenBSD: getgrent.3,v 1.19 2014/03/12 11:36:06 schwarze 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: March 12 2014 $ 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 setgrfile , 41.Nm setgrent , 42.Nm endgrent 43.Nd group database operations 44.Sh SYNOPSIS 45.In sys/types.h 46.In grp.h 47.Ft struct group * 48.Fn getgrent void 49.Ft struct group * 50.Fn getgrnam "const char *name" 51.Ft int 52.Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 53.Ft struct group * 54.Fn getgrgid "gid_t gid" 55.Ft int 56.Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 57.Ft int 58.Fn setgroupent "int stayopen" 59.\" .Ft void 60.\" .Fn setgrfile "const char *name" 61.Ft void 62.Fn setgrent void 63.Ft void 64.Fn endgrent void 65.Sh DESCRIPTION 66These functions operate on the group database file 67.Pa /etc/group 68which is described 69in 70.Xr group 5 . 71Each line of the database is defined by the structure 72.Li struct group 73found in the include 74file 75.In grp.h : 76.Bd -literal -offset indent 77struct group { 78 char *gr_name; /* group name */ 79 char *gr_passwd; /* group password */ 80 gid_t gr_gid; /* group id */ 81 char **gr_mem; /* group members */ 82}; 83.Ed 84.Pp 85The functions 86.Fn getgrnam 87and 88.Fn getgrgid 89search the group database for the given group name pointed to by 90.Fa name 91or the group ID pointed to by 92.Fa gid , 93respectively, returning the first one encountered. 94Identical group names or group GIDs may result in undefined behavior. 95.Pp 96.Fn getgrent 97sequentially reads the group database and is intended for programs 98that wish to step through the complete list of groups. 99.Pp 100All three routines will open the group file for reading, if necessary. 101.Pp 102.Fn setgroupent 103opens the file, or rewinds it if it is already open. 104If 105.Fa stayopen 106is non-zero, file descriptors are left open, significantly speeding 107subsequent function calls. 108This functionality is unnecessary for 109.Fn getgrent 110as it doesn't close its file descriptors by default. 111It should also 112be noted that it is dangerous for long-running programs to use this 113functionality as the group file may be updated. 114.Pp 115.Fn setgrent 116is equivalent to 117.Fn setgroupent 118with an argument of zero. 119.Pp 120The 121.Fn endgrent 122function closes any open files. 123.Pp 124The 125.Fn getgrgid_r 126and 127.Fn getgrnam_r 128functions both update the group structure pointed to by 129.Fa grp 130and store a pointer to that structure at the location pointed to by 131.Fa result . 132The structure is filled with an entry from the group database with a 133matching 134.Fa gid 135or 136.Fa name . 137Storage referenced by the group structure will be allocated from the memory 138provided with the 139.Fa buffer 140parameter, which is 141.Fa bufsiz 142characters in size. 143.\" The maximum size needed for this buffer can be determined with the 144.\" .Dv _SC_GETGR_R_SIZE_MAX 145.\" .Xr sysconf 2 146.\" parameter. 147.Ss YP support 148If YP is active, the functions 149.Fn getgrent 150and 151.Fn getgrnam 152also use the 153.Pa group.byname 154YP map and the function 155.Fn getgrgid 156also uses the 157.Pa group.bygid 158YP map in addition to the group file, 159respecting the order of normal and YP entries in the group file. 160.Sh RETURN VALUES 161The functions 162.Fn getgrent , 163.Fn getgrnam , 164and 165.Fn getgrgid 166return a pointer to the group entry if successful; if end-of-file 167is reached or an error occurs a 168.Dv NULL 169pointer is returned. 170.Pp 171The 172.Fn setgroupent 173function returns the value 1 if successful, otherwise 0. 174.Pp 175The 176.Fn endgrent 177and 178.Fn setgrent 179functions have no return value. 180.Pp 181The functions 182.Fn getgrgid_r 183and 184.Fn getgrnam_r 185update 186.Ar result 187to point to 188.Ar grp 189if a match is found or set it to 190.Dv NULL 191if no match is found or an error occurs. 192They return 0 on success, even if no match is found, 193or an error number if an error occurs; see 194.Sx ERRORS . 195.Sh FILES 196.Bl -tag -width /etc/group -compact 197.It Pa /etc/group 198group database file 199.El 200.Sh ERRORS 201The 202.Fn getgruid_r 203and 204.Fn getgrnam_r 205functions may fail if: 206.Bl -tag -width Er 207.It Bq Er ERANGE 208The storage supplied via 209.Fa buffer 210and 211.Fa bufsize 212is too small and cannot contain all the strings to be returned in 213.Fa grp . 214.El 215.Pp 216The 217.Fn getgrent , 218.Fn getgrgid , 219.Fn getgrgid_r , 220.Fn getgrnam , 221and 222.Fn getgrnam_r 223functions may also fail for any of the errors specified for 224.Xr fgets 3 , 225.Xr getc 3 , 226and 227.Xr strtoul 3 . 228If YP is active, they may also fail due to errors caused by the YP subsystem. 229.Pp 230The 231.Fn setgroupent 232function may fail for any of the errors specified for 233.Xr fopen 3 . 234.Pp 235The 236.Fn endgrent , 237.Fn getgrgid_r , 238.Fn getgrnam_r , 239and 240.Fn setgrent 241functions do not set errno. 242.Sh SEE ALSO 243.Xr getpwent 3 , 244.Xr ypclnt 3 , 245.Xr group 5 , 246.Xr yp 8 247.Sh STANDARDS 248The functions 249.Fn getgrgid , 250.Fn getgrgid_r , 251.Fn getgrnam , 252and 253.Fn getgrnam_r 254are compliant with the 255.St -p1003.1-2008 256specification. 257.Pp 258The functions 259.Fn endgrent , 260.Fn getgrent , 261and 262.Fn setgrent 263are compliant with the X/Open System Interfaces option of the 264.St -p1003.1-2008 265specification. 266.Pp 267.Sx YP support 268and the 269.Fn setgroupent 270function are extensions to that specification. 271.Sh HISTORY 272The functions 273.Fn endgrent , 274.Fn getgrent , 275.Fn getgrnam , 276.Fn getgrgid , 277and 278.Fn setgrent 279appeared in 280.At v7 . 281The functions 282.Fn setgrfile 283and 284.Fn setgroupent 285appeared in 286.Bx 4.3 Reno . 287.Pp 288The historic function 289.Xr setgrfile 3 , 290which allowed the specification of alternate group databases, has 291been deprecated and is no longer available. 292.Sh BUGS 293The functions 294.Fn getgrent , 295.Fn getgrnam , 296.Fn getgrgid , 297.Fn setgroupent , 298and 299.Fn setgrent 300leave their results in an internal static object and return 301a pointer to that object. 302Subsequent calls to the same function will modify the same object. 303.Pp 304The functions 305.Fn getgrent , 306.Fn endgrent , 307.Fn setgroupent , 308and 309.Fn setgrent 310are fairly useless in a networked environment and should be 311avoided, if possible. 312