1.\" $OpenBSD: getgrent.3,v 1.10 2000/12/24 00:30:48 aaron 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd April 19, 1994 35.Dt GETGRENT 3 36.Os 37.Sh NAME 38.Nm getgrent , 39.Nm getgrnam , 40.Nm getgrnam_r , 41.Nm getgrgid , 42.Nm getgrgid_r , 43.Nm setgroupent , 44.\" .Nm setgrfile , 45.Nm setgrent , 46.Nm endgrent 47.Nd group database operations 48.Sh SYNOPSIS 49.Fd #include <sys/types.h> 50.Fd #include <grp.h> 51.Ft struct group * 52.Fn getgrent void 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 setgrfile "const char *name" 65.Ft void 66.Fn setgrent void 67.Ft void 68.Fn endgrent void 69.Sh DESCRIPTION 70These functions operate on the group database file 71.Pa /etc/group 72which is described 73in 74.Xr group 5 . 75Each line of the database is defined by the structure 76.Li struct group 77found in the include 78file 79.Aq Pa grp.h : 80.Bd -literal -offset indent 81struct group { 82 char *gr_name; /* group name */ 83 char *gr_passwd; /* group password */ 84 gid_t gr_gid; /* group id */ 85 char **gr_mem; /* group members */ 86}; 87.Ed 88.Pp 89The functions 90.Fn getgrnam 91and 92.Fn getgrgid 93search the group database for the given group name pointed to by 94.Fa name 95or the group ID pointed to by 96.Fa gid , 97respectively, returning the first one encountered. 98Identical group names or group GIDs may result in undefined behavior. 99.Pp 100.Fn getgrent 101sequentially reads the group database and is intended for programs 102that wish to step through the complete list of groups. 103.Pp 104All three routines will open the group file for reading, if necessary. 105.Pp 106.Fn setgroupent 107opens the file, or rewinds it if it is already open. 108If 109.Fa stayopen 110is non-zero, file descriptors are left open, significantly speeding 111subsequent function calls. 112This functionality is unnecessary for 113.Fn getgrent 114as it doesn't close its file descriptors by default. 115It should also 116be noted that it is dangerous for long-running programs to use this 117functionality as the group file may be updated. 118.Pp 119.Fn setgrent 120is equivalent to 121.Fn setgroupent 122with an argument of zero. 123.Pp 124The 125.Fn endgrent 126function closes any open files. 127.Pp 128The 129.Fn getgrgid_r 130and 131.Fn getgrnam_r 132functions both update the group structure pointed to by 133.Fa grp 134and store a pointer to that structure at the location pointed to by 135.Fa result . 136The structure is filled with an entry from the group database with a 137matching 138.Fa gid 139or 140.Fa name . 141Storage referenced by the group structure will be allocated from the memory 142provided with the 143.Fa buffer 144parameter, which is 145.Fa bufsiz 146characters in size. 147.\" The maximum size needed for this buffer can be determined with the 148.\" .Dv _SC_GETGR_R_SIZE_MAX 149.\" .Xr sysconf 2 150.\" parameter. 151.Sh RETURN VALUES 152The functions 153.Fn getgrent , 154.Fn getgrnam , 155and 156.Fn getgrgid 157return a pointer to the group entry if successful; if end-of-file 158is reached or an error occurs a null pointer is returned. 159The 160.Fn setgroupent 161function returns the value 1 if successful, otherwise 0. 162The 163.Fn endgrent 164and 165.Fn setgrent 166functions have no return value. 167The functions 168.Fn getgrgid_r 169and 170.Fn getgrnam_r 171store a null pointer at the location pointed to by 172.Fa result 173and return the error number 174if an error occurs, or the requested entry is not found. 175.Sh FILES 176.Bl -tag -width /etc/group -compact 177.It Pa /etc/group 178group database file 179.El 180.Sh SEE ALSO 181.Xr getpwent 3 , 182.Xr group 5 183.Sh HISTORY 184The functions 185.Fn endgrent , 186.Fn getgrent , 187.Fn getgrnam , 188.Fn getgrgid , 189and 190.Fn setgrent 191appeared in 192.At v7 . 193The functions 194.Fn setgrfile 195and 196.Fn setgroupent 197appeared in 198.Bx 4.3 Reno . 199.Sh COMPATIBILITY 200The historic function 201.Xr setgrfile 3 , 202which allowed the specification of alternate password databases, has 203been deprecated and is no longer available. 204.Sh BUGS 205The functions 206.Fn getgrent , 207.Fn getgrnam , 208.Fn getgrgid , 209.Fn setgroupent , 210and 211.Fn setgrent 212leave their results in an internal static object and return 213a pointer to that object. 214Subsequent calls to the same function will modify the same object. 215.Pp 216The functions 217.Fn getgrent , 218.Fn endgrent , 219.Fn setgroupent , 220and 221.Fn setgrent 222are fairly useless in a networked environment and should be 223avoided, if possible. 224