Add nsswitch support.
[dragonfly.git] / lib / libc / gen / getgrent.3
CommitLineData
984263bc
MD
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.
984263bc
MD
12.\" 4. Neither the name of the University nor the names of its contributors
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" From: @(#)getgrent.3 8.2 (Berkeley) 4/19/94
ed5d5720 29.\" $FreeBSD: src/lib/libc/gen/getgrent.3,v 1.28 2007/01/09 00:27:53 imp Exp $
34622406 30.\" $DragonFly: src/lib/libc/gen/getgrent.3,v 1.5 2008/04/19 10:08:05 swildner Exp $
984263bc 31.\"
34622406 32.Dd April 19, 2008
984263bc
MD
33.Dt GETGRENT 3
34.Os
35.Sh NAME
36.Nm getgrent ,
ed5d5720 37.Nm getgrent_r ,
984263bc 38.Nm getgrnam ,
ed5d5720 39.Nm getgrnam_r ,
984263bc 40.Nm getgrgid ,
ed5d5720 41.Nm getgrgid_r ,
984263bc 42.Nm setgroupent ,
984263bc
MD
43.Nm setgrent ,
44.Nm endgrent
45.Nd group database operations
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
984263bc
MD
49.In grp.h
50.Ft struct group *
51.Fn getgrent void
ed5d5720
PA
52.Ft int
53.Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
984263bc
MD
54.Ft struct group *
55.Fn getgrnam "const char *name"
ed5d5720
PA
56.Ft int
57.Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
984263bc
MD
58.Ft struct group *
59.Fn getgrgid "gid_t gid"
60.Ft int
ed5d5720
PA
61.Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
62.Ft int
984263bc 63.Fn setgroupent "int stayopen"
984263bc
MD
64.Ft int
65.Fn setgrent void
66.Ft void
67.Fn endgrent void
68.Sh DESCRIPTION
69These functions operate on the group database file
70.Pa /etc/group
71which is described
72in
73.Xr group 5 .
74Each line of the database is defined by the structure
75.Vt group
76found in the include
77file
44cb301e 78.In grp.h :
984263bc
MD
79.Bd -literal -offset indent
80struct group {
81 char *gr_name; /* group name */
82 char *gr_passwd; /* group password */
ed5d5720 83 gid_t gr_gid; /* group id */
984263bc
MD
84 char **gr_mem; /* group members */
85};
86.Ed
87.Pp
88The functions
89.Fn getgrnam
90and
91.Fn getgrgid
92search the group database for the given group name pointed to by
93.Fa name
94or the group id pointed to by
95.Fa gid ,
ed5d5720
PA
96respectively, returning the first one encountered.
97Identical group
984263bc
MD
98names or group gids may result in undefined behavior.
99.Pp
100The
101.Fn getgrent
102function
103sequentially reads the group database and is intended for programs
104that wish to step through the complete list of groups.
105.Pp
ed5d5720
PA
106The functions
107.Fn getgrent_r ,
108.Fn getgrnam_r ,
109and
110.Fn getgrgid_r
111are thread-safe versions of
112.Fn getgrent ,
113.Fn getgrnam ,
114and
115.Fn getgrgid ,
116respectively.
117The caller must provide storage for the results of the search in
118the
119.Fa grp ,
120.Fa buffer ,
121.Fa bufsize ,
122and
123.Fa result
124arguments.
125When these functions are successful, the
126.Fa grp
127argument will be filled-in, and a pointer to that argument will be
128stored in
129.Fa result .
130If an entry is not found or an error occurs,
131.Fa result
132will be set to
133.Dv NULL .
134.Pp
135These functions will open the group file for reading, if necessary.
984263bc
MD
136.Pp
137The
138.Fn setgroupent
139function
ed5d5720
PA
140opens the file, or rewinds it if it is already open.
141If
984263bc
MD
142.Fa stayopen
143is non-zero, file descriptors are left open, significantly speeding
ed5d5720
PA
144functions subsequent calls.
145This functionality is unnecessary for
984263bc 146.Fn getgrent
ed5d5720
PA
147as it does not close its file descriptors by default.
148It should also
984263bc
MD
149be noted that it is dangerous for long-running programs to use this
150functionality as the group file may be updated.
151.Pp
152The
153.Fn setgrent
154function
155is identical to
156.Fn setgroupent
157with an argument of zero.
158.Pp
159The
160.Fn endgrent
161function
162closes any open files.
984263bc
MD
163.Sh RETURN VALUES
164The functions
165.Fn getgrent ,
166.Fn getgrnam ,
167and
168.Fn getgrgid ,
ed5d5720
PA
169return a pointer to a group structure on success or
170.Dv NULL
171if the entry is not found or if an error occurs.
172If an error does occur,
173.Va errno
174will be set.
175Note that programs must explicitly set
176.Va errno
177to zero before calling any of these functions if they need to
178distinguish between a non-existent entry and an error.
179The functions
180.Fn getgrent_r ,
181.Fn getgrnam_r ,
182and
183.Fn getgrgid_r
184return 0 if no error occurred, or an error number to indicate failure.
185It is not an error if a matching entry is not found.
186(Thus, if
187.Fa result
188is set to
189.Dv NULL
190and the return value is 0, no matching entry exists.)
191.Pp
984263bc
MD
192The functions
193.Fn setgroupent
194and
195.Fn setgrent
196return the value 1 if successful, otherwise the value
1970 is returned.
34622406 198The
984263bc 199.Fn endgrent
34622406 200function has no return value.
984263bc
MD
201.Sh FILES
202.Bl -tag -width /etc/group -compact
203.It Pa /etc/group
204group database file
205.El
0b84df5c
SW
206.Sh COMPATIBILITY
207The historic function
208.Fn setgrfile ,
209which allowed the specification of alternate password databases, has
210been deprecated and is no longer available.
984263bc
MD
211.Sh SEE ALSO
212.Xr getpwent 3 ,
213.Xr group 5 ,
ed5d5720 214.Xr nsswitch.conf 5 ,
984263bc 215.Xr yp 8
ed5d5720
PA
216.Sh STANDARDS
217The
218.Fn getgrent ,
219.Fn getgrnam ,
220.Fn getgrnam_r ,
221.Fn getgrgid ,
222.Fn getgrgid_r
223and
224.Fn endgrent
225functions conform to
226.St -p1003.1-96 .
227The
228.Fn setgrent
229function differs from that standard in that its return type is
230.Vt int
231rather than
232.Vt void .
984263bc
MD
233.Sh HISTORY
234The functions
235.Fn endgrent ,
236.Fn getgrent ,
237.Fn getgrnam ,
238.Fn getgrgid ,
239and
240.Fn setgrent
241appeared in
242.At v7 .
243The functions
244.Fn setgrfile
245and
246.Fn setgroupent
247appeared in
248.Bx 4.3 Reno .
ed5d5720
PA
249The functions
250.Fn getgrent_r ,
251.Fn getgrnam_r ,
252and
253.Fn getgrgid_r
254appeared in
255.Fx 5.1
256and
257.Dx 2.1 .
984263bc
MD
258.Sh BUGS
259The functions
260.Fn getgrent ,
261.Fn getgrnam ,
262.Fn getgrgid ,
263.Fn setgroupent
264and
265.Fn setgrent
266leave their results in an internal static object and return
267a pointer to that object.
268Subsequent calls to
269the same function
270will modify the same object.
ed5d5720
PA
271.Pp
272The functions
273.Fn getgrent ,
274.Fn getgrent_r ,
275.Fn endgrent ,
276.Fn setgroupent ,
277and
278.Fn setgrent
279are fairly useless in a networked environment and should be
280avoided, if possible.
281The
282.Fn getgrent
283and
284.Fn getgrent_r
285functions
286make no attempt to suppress duplicate information if multiple
287sources are specified in
288.Xr nsswitch.conf 5 .