.\"	$NetBSD: nsdispatch.3,v 1.17 2004/07/27 14:35:56 wiz 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 July 18, 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 a successful entry is found.
.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
.Ft typedef int
.Fn \*(lp*nss_method\*(rp "void *retval" "void *cb_data" "va_list *ap" ;
.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
.Fa dtab
array should consist of one entry for each source type that is implemented,
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
.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.
.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;
	u_int32_t flags;
} ns_src;
.Ed
.Pp
.Bd -ragged -offset indent
The
.Fa defaults
array should consist of one entry foe each source to consult by default
indicated by
.Va 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
.Va src
set to
.Dv NULL
and
.Va flags
set to 0.
.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
.Ft ns_mtab *
.Fn nss_module_register "const char *source" "u_int *nelems" \
    "nss_module_unregister_fn *unreg" ;
.Pp
.Bl -tag -width source
.It Fa source
The name of the source that the module implements, as used by
.Fn nsdispatch
to construct the module's name.
.It Fa 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 Fa 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
.Ft typedef void
.Fn \*(lp*nss_module_unregister_fn\*(rp "ns_mtab *mtab" "u_int nelems" ;
.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
.Fa 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 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.