xref: /dragonfly/lib/libc/net/nsdispatch.3 (revision cfd1aba3) 
1.\"	$NetBSD: nsdispatch.3,v 1.8 1999/03/22 19:44:53 garbled Exp $
2.\"
3.\" Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Luke Mewburn.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 4. Neither the name of The NetBSD Foundation nor the names of its
18.\"    contributors may be used to endorse or promote products derived
19.\"    from this software without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
23.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
24.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
25.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31.\" POSSIBILITY OF SUCH DAMAGE.
32.\"
33.\" $FreeBSD: src/lib/libc/net/nsdispatch.3,v 1.14 2007/01/22 11:45:25 bms Exp $
34.\"
35.Dd January 22, 2007
36.Dt NSDISPATCH 3
37.Os
38.Sh NAME
39.Nm nsdispatch
40.Nd name-service switch dispatcher routine
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/types.h
45.In stdarg.h
46.In nsswitch.h
47.Ft int
48.Fo nsdispatch
49.Fa "void *retval"
50.Fa "const ns_dtab dtab[]"
51.Fa "const char *database"
52.Fa "const char *method_name"
53.Fa "const ns_src defaults[]"
54.Fa "..."
55.Fc
56.Sh DESCRIPTION
57The
58.Fn nsdispatch
59function invokes the methods specified in
60.Fa dtab
61in the order given by
62.Xr nsswitch.conf 5
63for the database
64.Fa database
65until a successful entry is found.
66.Pp
67.Fa retval
68is passed to each method to modify as necessary, to pass back results to
69the caller of
70.Fn nsdispatch .
71.Pp
72Each method has the function signature described by the typedef:
73.Pp
74.Ft typedef int
75.Fn (*nss_method) "void *retval" "void *mdata" "va_list *ap" ;
76.Bl -item
77.It
78.Fa dtab
79is an array of
80.Vt ns_dtab
81structures, which have the following format:
82.Bl -item -offset indent
83.It
84.Bd -literal
85typedef struct _ns_dtab {
86	const char	*src;
87	nss_method	 method;
88	void		*mdata;
89} ns_dtab;
90.Ed
91.It
92The
93.Fa dtab
94array should consist of one entry for each source type that is
95implemented, with
96.Fa src
97as the name of the source,
98.Fa method
99as a function which handles that source, and
100.Fa mdata
101as a handle on arbitrary data to be passed to the method.
102The last entry in
103.Fa dtab
104should contain
105.Dv NULL
106values for
107.Fa src ,
108.Fa method ,
109and
110.Fa mdata .
111.El
112.Pp
113Additionally, methods may be implemented in NSS modules, in
114which case they are selected using the
115.Fa database
116and
117.Fa method_name
118arguments along with the configured source.
119(The methods supplied via
120.Fa dtab
121take priority over those implemented in NSS modules in the event
122of a conflict.)
123.It
124.Fa defaults
125contains a list of default sources to try if
126.Xr nsswitch.conf 5
127is missing or corrupted, or if there is no relevant entry for
128.Fa database .
129It is an array of
130.Vt ns_src
131structures, which have the following format:
132.Bl -item -offset indent
133.It
134.Bd -literal
135typedef struct _ns_src {
136	const char	*src;
137	u_int32_t	 flags;
138} ns_src;
139.Ed
140.It
141The
142.Fa defaults
143array should consist of one entry for each source to be configured by
144default indicated by
145.Fa src ,
146and
147.Fa flags
148set to the criterion desired
149(usually
150.Dv NS_SUCCESS ;
151refer to
152.Sx Method return values
153for more information).
154The last entry in
155.Fa defaults
156should have
157.Fa src
158set to
159.Dv NULL
160and
161.Fa flags
162set to 0.
163.It
164For convenience, a global variable defined as:
165.Dl extern const ns_src __nsdefaultsrc[];
166exists which contains a single default entry for the source
167.Sq files
168that may be used by callers which do not require complicated default
169rules.
170.El
171.It
172.Sq Fa ...
173are optional extra arguments, which are passed to the appropriate method
174as a variable argument list of the type
175.Vt va_list .
176.El
177.Ss Valid source types
178While there is support for arbitrary sources, the following
179#defines for commonly implemented sources are available:
180.Bl -column NSSRC_COMPAT compat -offset indent
181.It Sy "#define	value"
182.It Dv NSSRC_FILES Ta \&"files"
183.It Dv NSSRC_DNS Ta \&"dns"
184.It Dv NSSRC_NIS Ta \&"nis"
185.It Dv NSSRC_COMPAT Ta \&"compat"
186.El
187.Pp
188Refer to
189.Xr nsswitch.conf 5
190for a complete description of what each source type is.
191.Ss Method return values
192The
193.Vt nss_method
194functions must return one of the following values depending upon status
195of the lookup:
196.Bl -column "Return value" "Status code"
197.It Sy "Return value	Status code"
198.It Dv NS_SUCCESS Ta success
199.It Dv NS_NOTFOUND Ta notfound
200.It Dv NS_UNAVAIL Ta unavail
201.It Dv NS_TRYAGAIN Ta tryagain
202.It Dv NS_RETURN Ta -none-
203.El
204.Pp
205Refer to
206.Xr nsswitch.conf 5
207for a complete description of each status code.
208.Pp
209The
210.Fn nsdispatch
211function returns the value of the method that caused the dispatcher to
212terminate, or
213.Dv NS_NOTFOUND
214otherwise.
215.Sh NOTES
216.Dx Ns 's
217.Lb libc
218provides stubs for compatibility with NSS modules
219written for the
220.Tn GNU
221C Library
222.Nm nsswitch
223interface.
224However, these stubs only support the use of the
225.Dq Li passwd
226and
227.Dq Li group
228databases.
229.Sh SEE ALSO
230.Xr hesiod 3 ,
231.Xr stdarg 3 ,
232.Xr nsswitch.conf 5 ,
233.Xr yp 8
234.Sh HISTORY
235The
236.Fn nsdispatch
237function first appeared in
238.Dx 2.1 .
239It was imported from the
240.Fx
241Project,
242where it appeared first in
243.Fx 5.0 .
244.Sh AUTHORS
245.An Luke Mewburn Aq Mt lukem@netbsd.org
246wrote this freely-distributable name-service switch implementation,
247using ideas from the
248.Tn ULTRIX
249svc.conf(5)
250and
251.Tn Solaris
252nsswitch.conf(4)
253manual pages.
254The
255.Fx
256Project
257added the support for threads and NSS modules, and normalized the uses
258of
259.Fn nsdispatch
260within the standard C library.
261