xref: /freebsd/lib/libc/gen/getnetgrent.3 (revision 6e5dcc6113da649a79e5bc2c3ea9329bcd1d85d5)
1.\" Copyright (c) 1992, 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. 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.\"     @(#)getnetgrent.3	8.1 (Berkeley) 6/4/93
29.\"
30.Dd June 5, 2016
31.Dt GETNETGRENT 3
32.Os
33.Sh NAME
34.Nm getnetgrent ,
35.Nm innetgr ,
36.Nm setnetgrent ,
37.Nm endnetgrent
38.Nd netgroup database operations
39.Sh LIBRARY
40.Lb libc
41.Sh SYNOPSIS
42.In netdb.h
43.Ft int
44.Fn getnetgrent "char **host" "char **user" "char **domain"
45.Ft int
46.Fn getnetgrent_r "char **host" "char **user" "char **domain" "char *buf" "size_t bufsize"
47.Ft int
48.Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain"
49.Ft void
50.Fn setnetgrent "const char *netgroup"
51.Ft void
52.Fn endnetgrent void
53.Sh DESCRIPTION
54These functions operate on the netgroup database file
55.Pa /etc/netgroup
56which is described
57in
58.Xr netgroup 5 .
59The database defines a set of netgroups, each made up of one or more triples:
60.Bd -literal -offset indent
61(host, user, domain)
62.Ed
63that defines a combination of host, user and domain.
64Any of the three fields may be specified as ``wildcards'' that match any
65string.
66.Pp
67The function
68.Fn getnetgrent
69sets the three pointer arguments to the strings of the next member of the
70current netgroup.
71If any of the string pointers are
72.Dv NULL
73that field is considered a wildcard.
74.Pp
75The functions
76.Fn setnetgrent
77and
78.Fn endnetgrent
79set the current netgroup and terminate the current netgroup respectively.
80If
81.Fn setnetgrent
82is called with a different netgroup than the previous call, an implicit
83.Fn endnetgrent
84is implied.
85The
86.Fn setnetgrent
87function
88also sets the offset to the first member of the netgroup.
89.Pp
90The function
91.Fn innetgr
92searches for a match of all fields within the specified group.
93If any of the
94.Sy host ,
95.Sy user ,
96or
97.Sy domain
98arguments are
99.Dv NULL
100those fields will match any string value in the netgroup member.
101.Sh RETURN VALUES
102The function
103.Fn getnetgrent
104returns 0 for ``no more netgroup members'' and 1 otherwise.
105The function
106.Fn innetgr
107returns 1 for a successful match and 0 otherwise.
108The functions
109.Fn setnetgrent
110and
111.Fn endnetgrent
112have no return value.
113.Sh FILES
114.Bl -tag -width /etc/netgroup -compact
115.It Pa /etc/netgroup
116netgroup database file
117.El
118.Sh COMPATIBILITY
119The netgroup members have three string fields to maintain compatibility
120with other vendor implementations, however it is not obvious what use the
121.Sy domain
122string has within
123.Bx .
124.Sh SEE ALSO
125.Xr netgroup 5
126.Sh BUGS
127The function
128.Fn getnetgrent
129returns pointers to dynamically allocated data areas that are freed when
130the function
131.Fn endnetgrent
132is called.
133