| 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.3 |