xref: /freebsd/lib/libc/gen/getgrent.3 (revision d056fa046c6a91b90cd98165face0e42a33a5173)
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$
34.\"
35.Dd April 16, 2003
36.Dt GETGRENT 3
37.Os
38.Sh NAME
39.Nm getgrent ,
40.Nm getgrent_r ,
41.Nm getgrnam ,
42.Nm getgrnam_r ,
43.Nm getgrgid ,
44.Nm getgrgid_r ,
45.Nm setgroupent ,
46.Nm setgrent ,
47.Nm endgrent
48.Nd group database operations
49.Sh LIBRARY
50.Lb libc
51.Sh SYNOPSIS
52.In grp.h
53.Ft struct group *
54.Fn getgrent void
55.Ft int
56.Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
57.Ft struct group *
58.Fn getgrnam "const char *name"
59.Ft int
60.Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
61.Ft struct group *
62.Fn getgrgid "gid_t gid"
63.Ft int
64.Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
65.Ft int
66.Fn setgroupent "int stayopen"
67.Ft int
68.Fn setgrent void
69.Ft void
70.Fn endgrent void
71.Sh DESCRIPTION
72These functions operate on the group database file
73.Pa /etc/group
74which is described
75in
76.Xr group 5 .
77Each line of the database is defined by the structure
78.Vt group
79found in the include
80file
81.In grp.h :
82.Bd -literal -offset indent
83struct group {
84	char	*gr_name;	/* group name */
85	char	*gr_passwd;	/* group password */
86	gid_t	gr_gid;		/* group id */
87	char	**gr_mem;	/* group members */
88};
89.Ed
90.Pp
91The functions
92.Fn getgrnam
93and
94.Fn getgrgid
95search the group database for the given group name pointed to by
96.Fa name
97or the group id pointed to by
98.Fa gid ,
99respectively, returning the first one encountered.
100Identical group
101names or group gids may result in undefined behavior.
102.Pp
103The
104.Fn getgrent
105function
106sequentially reads the group database and is intended for programs
107that wish to step through the complete list of groups.
108.Pp
109The functions
110.Fn getgrent_r ,
111.Fn getgrnam_r ,
112and
113.Fn getgrgid_r
114are thread-safe versions of
115.Fn getgrent ,
116.Fn getgrnam ,
117and
118.Fn getgrgid ,
119respectively.
120The caller must provide storage for the results of the search in
121the
122.Fa grp ,
123.Fa buffer ,
124.Fa bufsize ,
125and
126.Fa result
127arguments.
128When these functions are successful, the
129.Fa grp
130argument will be filled-in, and a pointer to that argument will be
131stored in
132.Fa result .
133If an entry is not found or an error occurs,
134.Fa result
135will be set to
136.Dv NULL .
137.Pp
138These functions will open the group file for reading, if necessary.
139.Pp
140The
141.Fn setgroupent
142function
143opens the file, or rewinds it if it is already open.
144If
145.Fa stayopen
146is non-zero, file descriptors are left open, significantly speeding
147functions subsequent calls.
148This functionality is unnecessary for
149.Fn getgrent
150as it does not close its file descriptors by default.
151It should also
152be noted that it is dangerous for long-running programs to use this
153functionality as the group file may be updated.
154.Pp
155The
156.Fn setgrent
157function
158is identical to
159.Fn setgroupent
160with an argument of zero.
161.Pp
162The
163.Fn endgrent
164function
165closes any open files.
166.Sh RETURN VALUES
167The functions
168.Fn getgrent ,
169.Fn getgrnam ,
170and
171.Fn getgrgid ,
172return a pointer to a group structure on success or
173.Dv NULL
174if the entry is not found or if an error occurs.
175If an error does occur,
176.Va errno
177will be set.
178Note that programs must explicitly set
179.Va errno
180to zero before calling any of these functions if they need to
181distinguish between a non-existent entry and an error.
182The functions
183.Fn getgrent_r ,
184.Fn getgrnam_r ,
185and
186.Fn getgrgid_r
187return 0 if no error occurred, or an error number to indicate failure.
188It is not an error if a matching entry is not found.
189(Thus, if
190.Fa result
191is set to
192.Dv NULL
193and the return value is 0, no matching entry exists.)
194.Pp
195The functions
196.Fn setgroupent
197and
198.Fn setgrent
199return the value 1 if successful, otherwise the value
2000 is returned.
201The functions
202.Fn endgrent
203and
204.Fn setgrfile
205have no return value.
206.Sh FILES
207.Bl -tag -width /etc/group -compact
208.It Pa /etc/group
209group database file
210.El
211.Sh COMPATIBILITY
212The historic function
213.Fn setgrfile ,
214which allowed the specification of alternate password databases, has
215been deprecated and is no longer available.
216.Sh SEE ALSO
217.Xr getpwent 3 ,
218.Xr group 5 ,
219.Xr nsswitch.conf 5 ,
220.Xr yp 8
221.Sh STANDARDS
222The
223.Fn getgrent ,
224.Fn getgrnam ,
225.Fn getgrnam_r ,
226.Fn getgrgid ,
227.Fn getgrgid_r
228and
229.Fn endgrent
230functions conform to
231.St -p1003.1-96 .
232The
233.Fn setgrent
234function differs from that standard in that its return type is
235.Vt int
236rather than
237.Vt void .
238.Sh HISTORY
239The functions
240.Fn endgrent ,
241.Fn getgrent ,
242.Fn getgrnam ,
243.Fn getgrgid ,
244and
245.Fn setgrent
246appeared in
247.At v7 .
248The functions
249.Fn setgrfile
250and
251.Fn setgroupent
252appeared in
253.Bx 4.3 Reno .
254The functions
255.Fn getgrent_r ,
256.Fn getgrnam_r ,
257and
258.Fn getgrgid_r
259appeared in
260.Fx 5.1 .
261.Sh BUGS
262The functions
263.Fn getgrent ,
264.Fn getgrnam ,
265.Fn getgrgid ,
266.Fn setgroupent
267and
268.Fn setgrent
269leave their results in an internal static object and return
270a pointer to that object.
271Subsequent calls to
272the same function
273will modify the same object.
274.Pp
275The functions
276.Fn getgrent ,
277.Fn getgrent_r ,
278.Fn endgrent ,
279.Fn setgroupent ,
280and
281.Fn setgrent
282are fairly useless in a networked environment and should be
283avoided, if possible.
284The
285.Fn getgrent
286and
287.Fn getgrent_r
288functions
289make no attempt to suppress duplicate information if multiple
290sources are specified in
291.Xr nsswitch.conf 5 .
292