xref: /netbsd-src/lib/libc/net/nsdispatch.3 (revision 23c8222edbfb0f0932d88a8351d3a0cf817dfb9e)
1.\"	$NetBSD: nsdispatch.3,v 1.22 2004/09/29 09:20:19 wiz Exp $
2.\"
3.\" Copyright (c) 1997, 1998, 1999, 2004 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; and by Jason R. Thorpe.
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.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.Dd September 28, 2004
38.Dt NSDISPATCH 3
39.Os
40.Sh NAME
41.Nm nsdispatch
42.Nd name-service switch dispatcher routine
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
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"
53.Fa "const ns_src defaults[]"
54.Fa "..."
55.Fc
56.Sh DESCRIPTION
57The
58.Fn nsdispatch
59function invokes the callback functions specified in
60.Va dtab
61in the order given in
62.Pa /etc/nsswitch.conf
63for the database
64.Va database
65until the action criteria for a source of that database is fulfilled.
66.Pp
67.Va retval
68is passed to each callback function to modify as necessary
69(to pass back to the caller of
70.Fn nsdispatch ) .
71.Pp
72Each callback has the function signature described by the typedef:
73.Pp
74.Bd -ragged -offset indent
75.Ft typedef int
76.Fn \*(lp*nss_method\*(rp "void *retval" "void *cb_data" "va_list ap" ;
77.Ed
78.Pp
79.Va dtab
80is an array of
81.Va ns_dtab
82structures, which have the following format:
83.Bd -literal -offset indent
84typedef struct {
85	const char *src;
86	nss_method cb;
87	void *cb_data;
88} ns_dtab;
89.Ed
90.Pp
91.Bd -ragged -offset indent
92The
93.Va dtab
94array should consist of one entry for each source type that has a
95static implementation,
96with
97.Va src
98as the name of the source,
99.Va cb
100as a function which handles that source, and
101.Va cb_data
102as a pointer to arbitrary data to be passed to the callback.
103The last entry in
104.Va dtab
105should contain
106.Dv NULL
107values for
108.Va src ,
109.Va cb ,
110and
111.Va cb_data .
112.Ed
113.Pp
114Callbacks may also be provided by dynamically-loaded modules, in which
115case they are selected using the
116.Va database
117and
118.Va method
119arguments in addition to the configured source.
120.Va method
121is usually the name of the function calling
122.Fn nsdispatch .
123Note that the callbacks provided by
124.Va dtab
125take priority over those implemented in dynamically-loaded modules in the
126event of a conflict.
127.Pp
128.Va defaults
129contains a list of default sources to try in the case of
130a missing or corrupt
131.Xr nsswitch.conf 5 ,
132or if there isn't a relevant entry for
133.Va database .
134It is an array of
135.Va ns_src
136structures, which have the following format:
137.Bd -literal -offset indent
138typedef struct {
139	const char *src;
140	u_int32_t flags;
141} ns_src;
142.Ed
143.Pp
144.Bd -ragged -offset indent
145The
146.Va defaults
147array should consist of one entry for each source to consult by default
148indicated by
149.Va src ,
150and
151.Va flags
152set to the desired behavior
153(usually
154.Dv NS_SUCCESS ;
155refer to
156.Sx Callback return values
157for more information).
158The last entry in
159.Va defaults
160should have
161.Va src
162set to
163.Dv NULL
164and
165.Va flags
166set to 0.
167.Pp
168Some invokers of
169.Fn nsdispatch
170(such as
171.Xr setgrent 3 )
172need to force all methods to be invoked,
173irrespective of the action criteria listed in
174.Xr nsswitch.conf 5 .
175This can be achieved by adding
176.Dv NS_FORCEALL
177to
178.Va defaults[0].flags
179before invoking
180.Fn nsdispatch .
181The return value of
182.Fn nsdispatch
183will be the result of the final callback method invoked.
184.Pp
185For convenience, a global variable defined as:
186.Dl extern const ns_src __nsdefaultsrc[];
187exists which contains a single default entry for
188.Sq files
189for use by callers which don't require complicated default rules.
190.Ed
191.Pp
192.Sq Va ...
193are optional extra arguments, which
194are passed to the appropriate callback function as a variable argument
195list of the type
196.Va va_list .
197.Ss Dynamically-loaded module interface
198The
199.Fn nsdispatch
200function loads callback modules from the run-time link-editor's search
201path using the following naming convention:
202.Bd -literal -offset indent
203nss_\*[Lt]source\*[Gt].so.\*[Lt]version\*[Gt]
204.Ed
205.Bl -tag -width XversionX -offset indent
206.It Aq source
207The source that the module implements.
208.It Aq version
209The
210.Nm nsdispatch
211module interface version, which is defined by the integer
212.Dv NSS_MODULE_INTERFACE_VERSION ,
213which has the value 0.
214.El
215.Pp
216When a module is loaded,
217.Fn nsdispatch
218looks for and calls the following function in the module:
219.Pp
220.Bd -ragged -offset indent
221.Ft ns_mtab *
222.Fn nss_module_register "const char *source" "u_int *nelems" \
223    "nss_module_unregister_fn *unreg" ;
224.Ed
225.Pp
226.Bl -tag -width source
227.It Va source
228The name of the source that the module implements, as used by
229.Fn nsdispatch
230to construct the module's name.
231.It Va nelems
232A pointer to an unsigned integer that
233.Fn nss_module_register
234should set to the number of elements in the
235.Va ns_mtab
236array returned by
237.Fn nss_module_register .
238.It Va unreg
239A pointer to a function pointer that
240.Fn nss_module_resgister
241can optionally set to a function to be invoked when the module is
242unloaded.
243.El
244.Pp
245The unregister function signature is described by the typedef:
246.Pp
247.Bd -ragged -offset indent
248.Ft typedef void
249.Fn \*(lp*nss_module_unregister_fn\*(rp "ns_mtab *mtab" "u_int nelems" ;
250.Ed
251.Pp
252.Fn nss_module_register
253returns an array of
254.Va ns_mtab
255structures, which have the following format:
256.Bd -literal -offset indent
257typedef struct {
258	const char *database;
259	const char *name;
260	nss_method method;
261	void *mdata;
262} ns_mtab;
263.Ed
264.Pp
265.Bd -ragged -offset indent
266The
267.Va mtab
268array should consist of one entry for each method that is implemented,
269with
270.Va database
271as the name of the database,
272.Va name
273as the name of the method,
274.Va method
275as the callback that implements the method, and
276.Va mdata
277as a pointer to arbitrary data to be passed to the callback.
278.Ed
279.Ss Valid source types
280While there is support for arbitrary sources, the following
281#defines for commonly implemented sources are provided:
282.Bl -column NSSRC_COMPAT COMPAT -offset indent
283.Sy #define	value
284.It NSSRC_FILES	"files"
285.It NSSRC_DNS	"dns"
286.It NSSRC_NIS	"nis"
287.It NSSRC_COMPAT	"compat"
288.El
289.Pp
290Refer to
291.Xr nsswitch.conf 5
292for a complete description of what each source type is.
293.Ss Valid database types
294While there is support for arbitrary databases, the following
295#defines for currently implemented system databases are provided:
296.Bl -column NSDB_NETGROUP NETGROUP -offset indent
297.Sy #define	value
298.It NSDB_HOSTS	"hosts"
299.It NSDB_GROUP	"group"
300.It NSDB_NETGROUP	"netgroup"
301.It NSDB_NETWORKS	"networks"
302.It NSDB_PASSWD	"passwd"
303.It NSDB_SHELLS	"shells"
304.El
305.Pp
306Refer to
307.Xr nsswitch.conf 5
308for a complete description of what each database is.
309.Ss Callback return values
310The callback functions should return one of the following values
311depending upon status of the lookup:
312.Bl -column NS_NOTFOUND -offset indent
313.Sy "Return value"	Status code
314.It NS_SUCCESS	success
315.It NS_NOTFOUND	notfound
316.It NS_UNAVAIL	unavail
317.It NS_TRYAGAIN	tryagain
318.El
319.Pp
320Refer to
321.Xr nsswitch.conf 5
322for a complete description of what each status code is.
323.Pp
324.Nm
325returns the value of the callback that caused the dispatcher to finish,
326or
327.Dv NS_NOTFOUND
328otherwise.
329.Sh SEE ALSO
330.Xr ld.elf_so 1 ,
331.Xr hesiod 3 ,
332.Xr stdarg 3 ,
333.Xr ypclnt 3 ,
334.Xr nsswitch.conf 5
335.Sh HISTORY
336The
337.Nm
338routines first appeared in
339.Nx 1.4 .
340Support for dynamically-loaded modules first appeared in
341.Nx 3.0 .
342.Sh AUTHORS
343Luke Mewburn
344.Aq lukem@NetBSD.org
345wrote this freely distributable name-service switch implementation,
346using ideas from the
347.Tn ULTRIX
348.Xr svc.conf 5
349and
350.Tn Solaris
351.Xr nsswitch.conf 4
352manual pages.
353Support for dynamically-loaded modules was added by Jason Thorpe
354.Aq thorpej@NetBSD.org ,
355based on code developed by the
356.Fx
357Project.
358