xref: /dragonfly/lib/libc/gen/getgrent.3 (revision 984263bc) 
1.\" Copyright (c) 1989, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     From: @(#)getgrent.3	8.2 (Berkeley) 4/19/94
33.\" $FreeBSD: src/lib/libc/gen/getgrent.3,v 1.12.2.4 2003/03/15 15:11:05 trhodes Exp $
34.\"
35.Dd September 29, 1994
36.Dt GETGRENT 3
37.Os
38.Sh NAME
39.Nm getgrent ,
40.Nm getgrnam ,
41.Nm getgrgid ,
42.Nm setgroupent ,
43.\" .Nm setgrfile ,
44.Nm setgrent ,
45.Nm endgrent
46.Nd group database operations
47.Sh LIBRARY
48.Lb libc
49.Sh SYNOPSIS
50.In sys/types.h
51.In grp.h
52.Ft struct group *
53.Fn getgrent void
54.Ft struct group *
55.Fn getgrnam "const char *name"
56.Ft struct group *
57.Fn getgrgid "gid_t gid"
58.Ft int
59.Fn setgroupent "int stayopen"
60.\" .Ft void
61.\" .Fn setgrfile "const char *name"
62.Ft int
63.Fn setgrent void
64.Ft void
65.Fn endgrent void
66.Sh DESCRIPTION
67These functions operate on the group database file
68.Pa /etc/group
69which is described
70in
71.Xr group 5 .
72Each line of the database is defined by the structure
73.Vt group
74found in the include
75file
76.Aq Pa grp.h :
77.Bd -literal -offset indent
78struct group {
79	char	*gr_name;	/* group name */
80	char	*gr_passwd;	/* group password */
81	int	gr_gid;		/* group id */
82	char	**gr_mem;	/* group members */
83};
84.Ed
85.Pp
86The functions
87.Fn getgrnam
88and
89.Fn getgrgid
90search the group database for the given group name pointed to by
91.Fa name
92or the group id pointed to by
93.Fa gid ,
94respectively, returning the first one encountered.  Identical group
95names or group gids may result in undefined behavior.
96.Pp
97The
98.Fn getgrent
99function
100sequentially reads the group database and is intended for programs
101that wish to step through the complete list of groups.
102.Pp
103All three routines will open the group file for reading, if necessary.
104.Pp
105The
106.Fn setgroupent
107function
108opens the file, or rewinds it if it is already open.  If
109.Fa stayopen
110is non-zero, file descriptors are left open, significantly speeding
111functions subsequent calls.  This functionality is unnecessary for
112.Fn getgrent
113as it doesn't close its file descriptors by default.  It should also
114be noted that it is dangerous for long-running programs to use this
115functionality as the group file may be updated.
116.Pp
117The
118.Fn setgrent
119function
120is identical to
121.Fn setgroupent
122with an argument of zero.
123.Pp
124The
125.Fn endgrent
126function
127closes any open files.
128.Sh YP/NIS INTERACTION
129When the
130.Xr yp 8
131group database is enabled, the
132.Fn getgrnam
133and
134.Fn getgrgid
135functions use the YP maps
136.Dq Li group.byname
137and
138.Dq Li group.bygid ,
139respectively, if the requested group is not found in the local
140.Pa /etc/group
141file.  The
142.Fn getgrent
143function will step through the YP map
144.Dq Li group.byname
145if the entire map is enabled as described in
146.Xr group 5 .
147.Sh RETURN VALUES
148The functions
149.Fn getgrent ,
150.Fn getgrnam ,
151and
152.Fn getgrgid ,
153return a pointer to the group entry if successful; if end-of-file
154is reached or an error occurs a null pointer is returned.
155The functions
156.Fn setgroupent
157and
158.Fn setgrent
159return the value 1 if successful, otherwise the value
1600 is returned.
161The functions
162.Fn endgrent
163and
164.Fn setgrfile
165have no return value.
166.Sh FILES
167.Bl -tag -width /etc/group -compact
168.It Pa /etc/group
169group database file
170.El
171.Sh SEE ALSO
172.Xr getpwent 3 ,
173.Xr group 5 ,
174.Xr yp 8
175.Sh HISTORY
176The functions
177.Fn endgrent ,
178.Fn getgrent ,
179.Fn getgrnam ,
180.Fn getgrgid ,
181and
182.Fn setgrent
183appeared in
184.At v7 .
185The functions
186.Fn setgrfile
187and
188.Fn setgroupent
189appeared in
190.Bx 4.3 Reno .
191.Sh COMPATIBILITY
192The historic function
193.Fn setgrfile ,
194which allowed the specification of alternate password databases, has
195been deprecated and is no longer available.
196.Sh BUGS
197The functions
198.Fn getgrent ,
199.Fn getgrnam ,
200.Fn getgrgid ,
201.Fn setgroupent
202and
203.Fn setgrent
204leave their results in an internal static object and return
205a pointer to that object.
206Subsequent calls to
207the same function
208will modify the same object.
209