1.\" Copyright (c) 1989, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getgrent.3 6.7 (Berkeley) 04/19/91 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 getgrname "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 necesssary. 74.Pp 75The 76.Fn setgrfile 77function 78changes the default group file to 79.Fa file , 80thus allowing the use of alternate group files. 81.Pp 82The 83.Fn setgroupent 84function 85opens the file, or rewinds it if it is already open. If 86.Fa stayopen 87is non-zero, file descriptors are left open, significantly speeding 88functions subsequent calls. This functionality is unnecessary for 89.Fn getgrent 90as it doesn't close its file descriptors by default. It should also 91be noted that it is dangerous for long-running programs to use this 92functionality as the group file may be updated. 93.Pp 94The 95.Fn setgrent 96function 97is identical to 98.Fn setgroupent 99with an argument of zero. 100.Pp 101The 102.Fn endgrent 103function 104closes any open files. 105.Sh RETURN VALUES 106The functions 107.Fn getgrent , 108.Fn getgrnam , 109and 110.Fn getgrgid , 111return a pointer to the group entry if successful; if end-of-file 112is reached or an error occurs a null pointer is returned. 113The functions 114.Fn setgroupent 115and 116.Fn setgrent 117return the value 1 if successful, otherwise the value 1180 is returned. 119The functions 120.Fn endgrent 121and 122.Fn setgrfile 123have no return value. 124.Sh FILES 125.Bl -tag -width /etc/group -compact 126.It Pa /etc/group 127group database file 128.El 129.Sh SEE ALSO 130.Fn getpwent 3 , 131.Fn group 5 132.Sh HISTORY 133The functions 134.Fn endgrent , 135.Fn getgrent , 136.Fn getgrnam , 137.Fn getgrgid , 138and 139.Fn setgrent 140appeared in 141.At v7 . 142The functions 143.Fn setgrfile 144and 145.Fn setgroupent 146appeared in 147.Bx 4.3 Reno . 148.Sh BUGS 149The functions 150.Fn getgrent , 151.Fn getgrnam , 152.Fn getgrgid , 153.Fn setgroupent 154and 155.Fn setgrent 156leave their results in an internal static object and return 157a pointer to that object. Subsequent calls to 158the same function 159will modify the same object. 160.Pp 161The functions 162.Fn getgrent , 163.Fn endgrent , 164.Fn setgroupent , 165and 166.Fn setgrent 167are fairly useless in a networked environment and should be 168avoided, if possible. 169