NSDISPATCH(3) | Library Functions Manual | NSDISPATCH(3) |
nsdispatch
—
#include <nsswitch.h>
int
nsdispatch
(void *nsdrv,
const ns_dtab dtab[], const char
*database, const char *name,
const ns_src defaults[],
...);
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;
NULL
values for src, cb, and
cb_data.(*nss_method)
(void *cbrv,
void *cbdata, va_list ap);;
nsdispatch
() was invoked with.nsdispatch
().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;
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.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.extern const ns_src
__nsdefaultsrc[];
... 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.
nsdispatch
() function loads callback functions from
the run-time link-editor's search path using the following naming convention:
nss_<source>.so.<version>
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:
nss_module_register
(const char
*source, u_int *nelems,
nss_module_unregister_fn *unreg);;
nsdispatch
() to construct the module's name.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.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:
(*nss_module_unregister_fn)
(ns_mtab
*mtab, u_int nelems);;
nss_module_register
().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;
#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.
#define | Value | |
NSDB_HOSTS | hosts | |
NSDB_GROUP | group | |
NSDB_GROUP_COMPAT | group_compat | |
NSDB_NETGROUP | netgroup | |
NSDB_NETWORKS | networks | |
NSDB_PASSWD | passwd | |
NSDB_PASSWD_COMPAT | passwd_compat | |
NSDB_SHELLS | shells |
Refer to nsswitch.conf(5) for a complete description of what each database is.
Return value | Status code |
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. |
nss_method
() callback function for a standard method
in a standard database is:
For example, given the standard function getgrnam(3):
getgrnam
(const char *name)NOTE: Not all standard databases are using this calling convention yet; those that aren't are noted below. These will be changed in the future.
The callback function names and va_list organization for various standard database callback functions are:
Returns struct addrinfo * via void *cbrv.
Returns struct getnamaddr * via void *cbrv.
Returns struct getnamaddr * via void *cbrv.
The struct getnamaddr is defined internally in libc as:
struct getnamaddr { struct hostent *hp; char *buf; size_t buflen; int *he; };
All methods for all sources are invoked for this method name.
*retval should be set to a pointer to an
internal static struct group on success,
NULL
otherwise.
getgrent(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
*retval should be set to an appropriate errno(2) on failure.
getgrent_r(3)
returns 0 if nsdispatch
() returns
NS_SUCCESS
or
NS_NOTFOUND
, and *retval
otherwise.
*retval should be set to a pointer to an
internal static struct group on success,
NULL
otherwise.
getgrgid(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
*retval should be set to an appropriate errno(2) on failure.
getgrgid_r(3)
returns 0 if nsdispatch
() returns
NS_SUCCESS
or
NS_NOTFOUND
, and *retval
otherwise.
*retval should be set to a pointer to an
internal static struct group on success,
NULL
otherwise.
getgrnam(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
*retval should be set to an appropriate errno(2) on failure.
getgrnam_r(3)
returns 0 if nsdispatch
() returns
NS_SUCCESS
or
NS_NOTFOUND
, and *retval
otherwise.
retval is unused.
Lookups for group_compat are also stopped if
NS_SUCCESS
was returned to prevent multiple
“+:” compat entries from being expanded.
getgroupmembership(3) returns is -1 if *groupc is greater than to maxgrp, and 0 otherwise.
retval should be set to 0 on failure and 1 on success.
All methods for all sources are invoked for this method name.
All methods for all sources are invoked for this method name.
Find the given name and return its value
in line. bywhat is one of
_NG_KEYBYNAME
,
_NG_KEYBYUSER
, or
_NG_KEYBYHOST
.
*retval should be set to 0 for no more netgroup members and 1 otherwise.
getnetgrent(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, 0 otherwise.
*retval should be set to 1 for a successful match and 0 otherwise.
*retval should be set to a pointer to an
internal static struct netent on success,
NULL
otherwise.
getnetbyaddr(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
*retval should be set to a pointer to an
internal static struct netent on success,
NULL
otherwise.
getnetbyname(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
All methods for all sources are invoked for this method name.
*retval should be set to a pointer to an
internal static struct passwd on success,
NULL
otherwise.
getpwent(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
*retval should be set to an appropriate errno(2) on failure.
getpwent_r(3)
returns 0 if nsdispatch
() returns
NS_SUCCESS
or
NS_NOTFOUND
, and *retval
otherwise.
*retval should be set to a pointer to an
internal static struct passwd on success,
NULL
otherwise.
getpwnam(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
*retval should be set to an appropriate errno(2) on failure.
getpwnam_r(3)
returns 0 if nsdispatch
() returns
NS_SUCCESS
or
NS_NOTFOUND
, and *retval
otherwise.
*retval should be set to a pointer to an
internal static struct passwd on success,
NULL
otherwise.
getpwuid(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, NULL
otherwise.
*retval should be set to an appropriate errno(2) on failure.
getpwuid_r(3)
returns 0 if nsdispatch
() returns
NS_SUCCESS
or
NS_NOTFOUND
, and *retval
otherwise.
retval should be set to 0 on failure and 1 on success.
All methods for all sources are invoked for this method name.
All methods for all sources are invoked for this method name.
All methods for all sources are invoked for this method name.
getusershell(3)
returns *retval if
nsdispatch
() returns
NS_SUCCESS
, and 0 otherwise.
All methods for all sources are invoked for this method name.
nsdispatch
routines first appeared in
NetBSD 1.4. Support for dynamically-loaded modules
first appeared in NetBSD 3.0.
January 4, 2015 | NetBSD 9.2 |