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.
nsdrv is passed to each callback function to use as necessary (to pass back to the caller of
nsdispatch()).
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 callback function which handles that source, and cb_data as a pointer to arbitrary data to be passed to the callback function. The last entry in dtab should contain NULL values for src, cb, and cb_data.
The callback function signature is described by the typedef:
typedef int (*nss_method)(
void *cbrv,
void *cbdata,
va_list ap);;
cbrv
The nsdrv that nsdispatch() was invoked with.
cbdata
The cb_data member of the array entry for the source that this callback function implements in the dtab argument of nsdispatch().
ap
The ... arguments to nsdispatch(), converted to a va_list.
database and
name are used to select methods from optional per-source dynamically-loaded modules.
name is usually the name of the function calling
nsdispatch(). Note that the callback functions 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 missing 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 function 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 callback functions 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 callback function 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
stdarg(3) variable argument list of the type
va_list.
nsdispatch returns the value of the callback function that caused the dispatcher to finish, or
NS_NOTFOUND otherwise.
Dynamically-loaded module interface
The
nsdispatch() function loads callback functions 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(), or 0 if there was a failure.
unreg
A pointer to a function pointer that nss_module_register() can optionally set to an unregister function to be invoked when the module is unloaded, or NULL if there isn't one.
The unregister function signature is described by the typedef:
typedef void (*nss_module_unregister_fn)(
ns_mtab *mtab,
u_int nelems);;
mtab
The array of ns_mtab structures returned by nss_module_register().
nelems
The *nelems value set by nss_module_register().
nss_module_register() returns an array of
ns_mtab structures (with
*nelems entries), or
NULL if there was a failure. The
ns_mtab structures 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 callback function (method) that is implemented, with database as the name of the database, name as the name of the callback function, method as the nss_method callback function that implements the method, and mdata as a pointer to arbitrary data to be passed to the callback function as its cbdata argument.
Valid source types
While there is support for arbitrary sources, the following #defines for commonly implemented sources are provided:
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:
NSDB_GROUP_COMPAT
group_compat
NSDB_PASSWD_COMPAT
passwd_compat
Refer to
nsswitch.conf(5) for a complete description of what each database is.
Callback function return values
The callback functions should return one of the following values depending upon status of the lookup:
NS_SUCCESS
The requested entry was found.
NS_NOTFOUND
The entry is not present at this source.
NS_TRYAGAIN
The source is busy, and may respond to retries.
NS_UNAVAIL
The source is not responding, or entry is corrupt.