1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getgrent.3 8.2 (Berkeley) 04/19/94 7.\" 8.Dd 9.Dt GETGRENT 3 10.Os 11.Sh NAME 12.Nm getgrent , 13.Nm getgrnam , 14.Nm getgrgid , 15.Nm setgroupent , 16.\" .Nm setgrfile , 17.Nm setgrent , 18.Nm endgrent 19.Nd group database operations 20.Sh SYNOPSIS 21.Fd #include <grp.h> 22.Ft struct group * 23.Fn getgrent void 24.Ft struct group * 25.Fn getgrnam "const char *name" 26.Ft struct group * 27.Fn getgrgid "gid_t gid" 28.Ft struct group * 29.Fn setgroupent "int stayopen" 30.\" .Ft void 31.\" .Fn setgrfile "const char *name" 32.Ft int 33.Fn setgrent void 34.Ft void 35.Fn endgrent void 36.Sh DESCRIPTION 37These functions operate on the group database file 38.Pa /etc/group 39which is described 40in 41.Xr group 5 . 42Each line of the database is defined by the structure 43.Ar group 44found in the include 45file 46.Aq Pa grp.h : 47.Bd -literal -offset indent 48struct group { 49 char *gr_name; /* group name */ 50 char *gr_passwd; /* group password */ 51 gid_t gr_gid; /* group id */ 52 char **gr_mem; /* group members */ 53}; 54.Ed 55.Pp 56The functions 57.Fn getgrnam 58and 59.Fn getgrgid 60search the group database for the given group name pointed to by 61.Ar name 62or the group id pointed to by 63.Ar gid , 64respectively, returning the first one encountered. Identical group 65names or group gids may result in undefined behavior. 66.Pp 67The 68.Fn getgrent 69function 70sequentially reads the group database and is intended for programs 71that wish to step through the complete list of groups. 72.Pp 73All three routines will open the group file for reading, if necessary. 74.Pp 75The 76.Fn setgroupent 77function 78opens the file, or rewinds it if it is already open. If 79.Fa stayopen 80is non-zero, file descriptors are left open, significantly speeding 81functions subsequent calls. This functionality is unnecessary for 82.Fn getgrent 83as it doesn't close its file descriptors by default. It should also 84be noted that it is dangerous for long-running programs to use this 85functionality as the group file may be updated. 86.Pp 87The 88.Fn setgrent 89function 90is identical to 91.Fn setgroupent 92with an argument of zero. 93.Pp 94The 95.Fn endgrent 96function 97closes any open files. 98.Sh RETURN VALUES 99The functions 100.Fn getgrent , 101.Fn getgrnam , 102and 103.Fn getgrgid , 104return a pointer to the group entry if successful; if end-of-file 105is reached or an error occurs a null pointer is returned. 106The functions 107.Fn setgroupent 108and 109.Fn setgrent 110return the value 1 if successful, otherwise the value 1110 is returned. 112The functions 113.Fn endgrent 114and 115.Fn setgrfile 116have no return value. 117.Sh FILES 118.Bl -tag -width /etc/group -compact 119.It Pa /etc/group 120group database file 121.El 122.Sh SEE ALSO 123.Fn getpwent 3 , 124.Fn group 5 125.Sh HISTORY 126The functions 127.Fn endgrent , 128.Fn getgrent , 129.Fn getgrnam , 130.Fn getgrgid , 131and 132.Fn setgrent 133appeared in 134.At v7 . 135The functions 136.Fn setgrfile 137and 138.Fn setgroupent 139appeared in 140.Bx 4.3 Reno . 141.Sh COMPATIBILITY 142The historic function 143.Fn setgrfile , 144which allowed the specification of alternate password databases, has 145been deprecated and is no longer available. 146.Sh BUGS 147The functions 148.Fn getgrent , 149.Fn getgrnam , 150.Fn getgrgid , 151.Fn setgroupent 152and 153.Fn setgrent 154leave their results in an internal static object and return 155a pointer to that object. Subsequent calls to 156the same function 157will modify the same object. 158.Pp 159The functions 160.Fn getgrent , 161.Fn endgrent , 162.Fn setgroupent , 163and 164.Fn setgrent 165are fairly useless in a networked environment and should be 166avoided, if possible. 167