Copyright (c) 1997, 1998, 1999, 2004, 2005, 2008
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 April 7, 2008 .Dt NSDISPATCH 3 .Os .Sh NAME .Nm nsdispatch .Nd name-service switch dispatcher routine .Sh LIBRARY .Lb libc .Sh SYNOPSIS n 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 .Fa dtab in the order given in
a /etc/nsswitch.conf for the database .Fa database until the action criteria for a source of that database is fulfilled.
p .Fa retval is passed to each callback function to modify as necessary (to pass back to the caller of .Fn nsdispatch ) .
p .Fa dtab is an array of .Fa ns_dtab structures, which have the following format: d -ragged -offset indent d -literal typedef struct { const char *src; nss_method cb; void *cb_data; } ns_dtab; .Ed
p The .Fa dtab array should consist of one entry for each source type that has a static implementation, with .Fa src as the name of the source, .Fa cb as a function which handles that source, and .Fa cb_data as a pointer to arbitrary data to be passed to the callback. The last entry in .Fa dtab should contain .Dv NULL values for .Fa src , .Fa cb , and .Fa cb_data . .Ed
p Each callback has the function signature described by the typedef:
p d -ragged -offset indent .Ft typedef int .Fn \*(lp*nss_method\*(rp "void *cbrv" "void *cbdata" "va_list ap" ;
p l -tag -width cbdata t Fa cbrv The .Fa retval that .Fn nsdispatch was invoked with. t Fa cbdata The .Fa cb_data member of the array entry for the source that this callback implements in the .Fa dtab argument of .Fn nsdispatch . t Fa ap The .Sq Fa "..." arguments to .Fn nsdispatch , converted to a .Ft va_list . .El .Ed
p Callbacks may also be provided by dynamically-loaded modules, in which case they are selected using the .Fa database and .Fa method arguments in addition to the configured source. .Fa method is usually the name of the function calling .Fn nsdispatch . Note that the callbacks provided by .Fa dtab take priority over those implemented in dynamically-loaded modules in the event of a conflict.
p .Fa 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 .Fa database . It is an array of .Fa ns_src structures, which have the following format: d -ragged -offset indent d -literal typedef struct { const char *src; uint32_t flags; } ns_src; .Ed
p The .Fa defaults array should consist of one entry for each source to consult by default indicated by .Fa src , and .Fa flags set to the desired behavior (usually .Dv NS_SUCCESS ; refer to .Sx Callback return values for more information). The last entry in .Fa defaults should have .Fa src set to .Dv NULL and .Fa flags set to 0.
p 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 .Fa defaults[0].flags before invoking .Fn nsdispatch . The return value of .Fn nsdispatch will be the result of the final callback method invoked.
p 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
p
.Sq Fa ...
are optional extra arguments, which
are passed to the appropriate callback function as a variable argument
list of the type
.Fa 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:
d -ragged -offset indent d -literal nss_\*[Lt]source\*[Gt].so.\*[Lt]version\*[Gt]
.Ed
l -tag -width XversionX t Aq source The source that the module implements.
t 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
.Ed
p When a module is loaded, .Fn nsdispatch looks for and calls the following function in the module:
p d -ragged -offset indent .Ft ns_mtab * .Fo nss_module_register .Fa "const char *source" .Fa "u_int *nelems" .Fa "nss_module_unregister_fn *unreg" .Fc
p l -tag -width source t Fa source The name of the source that the module implements, as used by .Fn nsdispatch to construct the module's name. t Fa nelems A pointer to an unsigned integer that .Fn nss_module_register should set to the number of elements in the .Ft ns_mtab array returned by .Fn nss_module_register , or .Dv 0 if there was a failure. t Fa unreg A pointer to a function pointer that .Fn nss_module_register can optionally set to a function to be invoked when the module is unloaded, or .Dv NULL if there isn't one. .El .Ed
p The unregister function signature is described by the typedef:
p d -ragged -offset indent .Ft typedef void .Fo \*(lp*nss_module_unregister_fn\*(rp .Fa "ns_mtab *mtab" .Fa "u_int nelems" .Fc
p l -tag -width nelems t Fa mtab The array of .Ft ns_mtab structures returned by .Fn nss_module_register . t Fa nelems The .Fa nelems value set by .Fn nss_module_register . .El .Ed
p .Fn nss_module_register returns .Dv NULL on failure, or an array of .Ft ns_mtab structures, which have the following format: d -ragged -offset indent d -literal typedef struct { const char *database; const char *name; nss_method method; void *mdata; } ns_mtab; .Ed
p
The
.Fa mtab
array should consist of one entry for each method that is implemented,
with
.Fa database
as the name of the database,
.Fa name
as the name of the method,
.Fa method
as the
.Ft nss_method
callback that implements the method, and
.Fa mdata
as a pointer to arbitrary data to be passed to the callback as its
.Fa cbdata
argument.
.Ed
.Ss Valid source types
While there is support for arbitrary sources, the following
#defines for commonly implemented sources are provided:
l -column NSSRC_COMPAT COMPAT -offset indent .Sy #define value
t NSSRC_FILES "files" t NSSRC_DNS "dns" t NSSRC_NIS "nis" t NSSRC_COMPAT "compat" .El
p
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:
l -column NSDB_NETGROUP NETGROUP -offset indent .Sy #define value
t NSDB_HOSTS "hosts" t NSDB_GROUP "group" t NSDB_NETGROUP "netgroup" t NSDB_NETWORKS "networks" t NSDB_PASSWD "passwd" t NSDB_SHELLS "shells" .El
p 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: l -column NS_NOTFOUND -offset indent .Sy "Return value" Status code t NS_SUCCESS success t NS_NOTFOUND notfound t NS_UNAVAIL unavail t NS_TRYAGAIN tryagain .El
p Refer to .Xr nsswitch.conf 5 for a complete description of what each status code is.
p
.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.