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