nsdispatch(3)
- NetBSD Manual Pages
NSDISPATCH(3) NetBSD Library Functions Manual NSDISPATCH(3)
NAME
nsdispatch -- name-service switch dispatcher routine
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <nsswitch.h>
int
nsdispatch(void *retval, const ns_dtab dtab[], const char *database,
const char *method, const ns_src defaults[], ...);
DESCRIPTION
The nsdispatch() function invokes the callback functions specified in
dtab in the order given in /etc/nsswitch.conf for the database database
until the action criteria for a source of that database is fulfilled.
retval is passed to each callback function to modify as necessary (to
pass back to the caller of nsdispatch()).
Each callback has the function signature described by the typedef:
typedef int (*nss_method)(void *retval, void *cb_data, va_list ap);
dtab is an array of ns_dtab structures, which have the following format:
typedef struct {
const char *src;
nss_method cb;
void *cb_data;
} ns_dtab;
The dtab array should consist of one entry for each source type
that has a static implementation, with src as the name of the
source, cb as a function which handles that source, and cb_data as
a pointer to arbitrary data to be passed to the callback. The last
entry in dtab should contain NULL values for src, cb, and cb_data.
Callbacks may also be provided by dynamically-loaded modules, in which
case they are selected using the database and method arguments in addi-
tion to the configured source. method is usually the name of the func-
tion calling nsdispatch(). Note that the callbacks provided by dtab take
priority over those implemented in dynamically-loaded modules in the
event of a conflict.
defaults contains a list of default sources to try in the case of a miss-
ing or corrupt nsswitch.conf(5), or if there isn't a relevant entry for
database. It is an array of ns_src structures, which have the following
format:
typedef struct {
const char *src;
uint32_t flags;
} ns_src;
The defaults array should consist of one entry for each source to
consult by default indicated by src, and flags set to the desired
behavior (usually NS_SUCCESS; refer to Callback return values for
more information). The last entry in defaults should have src set
to NULL and flags set to 0.
Some invokers of nsdispatch() (such as setgrent(3)) need to force
all methods to be invoked, irrespective of the action criteria
listed in nsswitch.conf(5). This can be achieved by adding
NS_FORCEALL to defaults[0].flags before invoking nsdispatch(). The
return value of nsdispatch() will be the result of the final call-
back method invoked.
For convenience, a global variable defined as:
extern const ns_src __nsdefaultsrc[];
exists which contains a single default entry for `files' for use by
callers which don't require complicated default rules.
`...' are optional extra arguments, which are passed to the appropriate
callback function as a variable argument list of the type va_list.
Dynamically-loaded module interface
The nsdispatch() function loads callback modules from the run-time link-
editor's search path using the following naming convention:
nss_<source>.so.<version>
<source> The source that the module implements.
<version> The nsdispatch module interface version, which is
defined by the integer NSS_MODULE_INTERFACE_VERSION,
which has the value 0.
When a module is loaded, nsdispatch() looks for and calls the following
function in the module:
ns_mtab * nss_module_register(const char *source, u_int *nelems,
nss_module_unregister_fn *unreg);
source The name of the source that the module implements, as used by
nsdispatch() to construct the module's name.
nelems A pointer to an unsigned integer that nss_module_register()
should set to the number of elements in the ns_mtab array
returned by nss_module_register().
unreg A pointer to a function pointer that nss_module_resgister() can
optionally set to a function to be invoked when the module is
unloaded.
The unregister function signature is described by the typedef:
typedef void (*nss_module_unregister_fn)(ns_mtab *mtab, u_int
nelems);
nss_module_register() returns an array of ns_mtab structures, which have
the following format:
typedef struct {
const char *database;
const char *name;
nss_method method;
void *mdata;
} ns_mtab;
The mtab array should consist of one entry for each method that is
implemented, with database as the name of the database, name as the
name of the method, method as the callback that implements the
method, and mdata as a pointer to arbitrary data to be passed to
the callback.
Valid source types
While there is support for arbitrary sources, the following #defines for
commonly implemented sources are provided:
#define value
NSSRC_FILES "files"
NSSRC_DNS "dns"
NSSRC_NIS "nis"
NSSRC_COMPAT "compat"
Refer to nsswitch.conf(5) for a complete description of what each source
type is.
Valid database types
While there is support for arbitrary databases, the following #defines
for currently implemented system databases are provided:
#define value
NSDB_HOSTS "hosts"
NSDB_GROUP "group"
NSDB_NETGROUP "netgroup"
NSDB_NETWORKS "networks"
NSDB_PASSWD "passwd"
NSDB_SHELLS "shells"
Refer to nsswitch.conf(5) for a complete description of what each data-
base is.
Callback return values
The callback functions should return one of the following values depend-
ing upon status of the lookup:
Return value Status code
NS_SUCCESS success
NS_NOTFOUND notfound
NS_UNAVAIL unavail
NS_TRYAGAIN tryagain
Refer to nsswitch.conf(5) for a complete description of what each status
code is.
nsdispatch returns the value of the callback that caused the dispatcher
to finish, or NS_NOTFOUND otherwise.
SEE ALSO
ld.elf_so(1), hesiod(3), stdarg(3), ypclnt(3), nsswitch.conf(5)
HISTORY
The nsdispatch routines first appeared in NetBSD 1.4. Support for dynam-
ically-loaded modules first appeared in NetBSD 3.0.
AUTHORS
Luke Mewburn <lukem@NetBSD.org> wrote this freely distributable name-ser-
vice switch implementation, using ideas from the ULTRIX svc.conf(5) and
Solaris nsswitch.conf(4) manual pages. Support for dynamically-loaded
modules was added by Jason Thorpe <thorpej@NetBSD.org>, based on code
developed by the FreeBSD Project.
NetBSD 4.0 September 28, 2004 NetBSD 4.0
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.