xref: /dragonfly/lib/libc/net/nsdispatch.3 (revision 0dace59e) 
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.Va dtab
61in the order given by
62.Xr nsswitch.conf 5
63for the database
64.Va database
65until a successful entry is found.
66.Pp
67.Va 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 \*(lp*nss_method\*(rp "void *retval" "void *mdata" "va_list *ap" ;
76.Pp
77.Va dtab
78is an array of
79.Va ns_dtab
80structures, which have the following format:
81.Bd -literal -offset indent
82typedef struct _ns_dtab {
83	const char	*src;
84	nss_method	 method;
85	void		*mdata;
86} ns_dtab;
87.Ed
88.Bd -ragged -offset indent
89The
90.Fa dtab
91array should consist of one entry for each source type that is
92implemented, with
93.Va src
94as the name of the source,
95.Va method
96as a function which handles that source, and
97.Va mdata
98as a handle on arbitrary data to be passed to the method.
99The last entry in
100.Va dtab
101should contain
102.Dv NULL
103values for
104.Va src ,
105.Va method ,
106and
107.Va mdata .
108.Ed
109.Pp
110Additionally, methods may be implemented in NSS modules, in
111which case they are selected using the
112.Fa database
113and
114.Fa method_name
115arguments along with the configured source.
116(The methods supplied via
117.Fa dtab
118take priority over those implemented in NSS modules in the event
119of a conflict.)
120.Pp
121.Va defaults
122contains a list of default sources to try if
123.Xr nsswitch.conf 5
124is missing or corrupted, or if there is no relevant entry for
125.Va database .
126It is an array of
127.Va ns_src
128structures, which have the following format:
129.Bd -literal -offset indent
130typedef struct _ns_src {
131	const char	*src;
132	u_int32_t	 flags;
133} ns_src;
134.Ed
135.Bd -ragged -offset indent
136The
137.Fa defaults
138array should consist of one entry for each source to be configured by
139default indicated by
140.Va src ,
141and
142.Va flags
143set to the criterion desired
144(usually
145.Dv NS_SUCCESS ;
146refer to
147.Sx Method return values
148for more information).
149The last entry in
150.Va defaults
151should have
152.Va src
153set to
154.Dv NULL
155and
156.Va flags
157set to 0.
158.Pp
159For convenience, a global variable defined as:
160.Dl extern const ns_src __nsdefaultsrc[];
161exists which contains a single default entry for the source
162.Sq files
163that may be used by callers which do not require complicated default
164rules.
165.Ed
166.Pp
167.Sq Va ...
168are optional extra arguments, which are passed to the appropriate method
169as a variable argument list of the type
170.Vt va_list .
171.Ss Valid source types
172While there is support for arbitrary sources, the following
173#defines for commonly implemented sources are available:
174.Bl -column NSSRC_COMPAT compat -offset indent
175.It Sy "#define	value"
176.It Dv NSSRC_FILES Ta """files""
177.It Dv NSSRC_DNS Ta """dns""
178.It Dv NSSRC_NIS Ta """nis""
179.It Dv NSSRC_COMPAT Ta """compat""
180.El
181.Pp
182Refer to
183.Xr nsswitch.conf 5
184for a complete description of what each source type is.
185.Ss Method return values
186The
187.Vt nss_method
188functions must return one of the following values depending upon status
189of the lookup:
190.Bl -column "Return value" "Status code"
191.It Sy "Return value	Status code"
192.It Dv NS_SUCCESS Ta success
193.It Dv NS_NOTFOUND Ta notfound
194.It Dv NS_UNAVAIL Ta unavail
195.It Dv NS_TRYAGAIN Ta tryagain
196.It Dv NS_RETURN Ta -none-
197.El
198.Pp
199Refer to
200.Xr nsswitch.conf 5
201for a complete description of each status code.
202.Pp
203The
204.Fn nsdispatch
205function returns the value of the method that caused the dispatcher to
206terminate, or
207.Dv NS_NOTFOUND
208otherwise.
209.Sh NOTES
210.Dx Ns 's
211.Lb libc
212provides stubs for compatibility with NSS modules
213written for the
214.Tn GNU
215C Library
216.Nm nsswitch
217interface.
218However, these stubs only support the use of the
219.Dq Li passwd
220and
221.Dq Li group
222databases.
223.Sh SEE ALSO
224.Xr hesiod 3 ,
225.Xr stdarg 3 ,
226.Xr nsswitch.conf 5 ,
227.Xr yp 8
228.Sh HISTORY
229The
230.Fn nsdispatch
231function first appeared in
232.Dx 2.1 .
233It was imported from the
234.Fx
235Project,
236where it appeared first in
237.Fx 5.0 .
238.Sh AUTHORS
239.An Luke Mewburn Aq Mt lukem@netbsd.org
240wrote this freely-distributable name-service switch implementation,
241using ideas from the
242.Tn ULTRIX
243svc.conf(5)
244and
245.Tn Solaris
246nsswitch.conf(4)
247manual pages.
248The
249.Fx
250Project
251added the support for threads and NSS modules, and normalized the uses
252of
253.Fn nsdispatch
254within the standard C library.
255