nsdispatch(3C)

NAME

nsdispatch - NSS central routing

Synopsis

   #include <nsswitch.h>

   int nsdispatch(void rv, const ns_dtab dtab, const char dbname,
   	const char methname, const ns_src src, ...);

Description

The Name Service Switch (NSS) feature provides the means by which add-on modules can be used to implement ``classic UNIX system'' simple database lookup operations such as getpwnam and getgrgid. The central manager of this switching is the nsdispatch routine.

For convenience, this interface deliberately matches the FreeBSD nsdispatch function, although this implementation is done from scratch.

The nsdispatch function, following the system's NSS configuration, see nsswitch.conf(5), calls potentially a sequence of routines (or ``methods'') matching the requested operation, methname, on the specified database, dbname. Although case is ignored in matching the database name, case is significant for the method name.

When a method makes an acceptable return, nsdispatch finishes, returning the return-value of that method. These methods are provided by NSS ``modules'', the standard modules being files, which operates solely on the system's classic database files like /etc/passwd, nis, pure Network Information Services or ``yellow pages'' operations, and compat, which provides methods matching the historic behavior of the system.

Each method called by nsdispatch has a shape matching the type pointed to by nss_method, as defined in the nsswitch.h header:

       typedef int (nss_method)(void rv, void mdata, va_list ap);

The first argument is the same rv passed as the first argument to nsdispatch, the second argument is the method-specific data corresponding to this method (see below) and ap provides a ready-to-use handle on the variable arguments, if any, passed to nsdispatch after its fifth argument. The method is expected to return one of these values defined in the nsswitch.h header:

       NS_SUCCESS
       NS_UNAVAIL
       NS_NOTFOUND
       NS_TRYAGAIN

which correspond with the status keywords in the NSS configuration file or NS_RETURN which typically means to stop searching.

The dtab argument to nsdispatch is either a null pointer or the address of the initial element of an array of ns_dtab structures, terminated by an all-zero-valued element, specifying a collection of overriding methods. The type ns_dtab is defined in the nsswitch.h header as

       typedef struct {
           const char src;    // overrides this module
           nss_method method;  // call this routine ...
           void       mdata;  // ... passing this data
       } ns_dtab;

The system APIs associated with the databases iaf, group, passwd, and shadow all call nsdispatch to implement their operations, but do so passing a nonnull dtab argument, specifying overriding built-in methods to use for the files, nis, and compat modules. See nsswitch.conf(5) for their method argument passing conventions.

The src argument to nsdispatch is either a null pointer or the address of the initial element of an array of ns_src structures, terminated by an all-zero-valued element, specifying the default handling to use when processing. The type ns_src is defined in the nsswitch.h header as

       typedef struct {
           const char   name;  // module, e.g., "files"
           unsigned int flags;  // NS_* status/action bits
       } ns_src;

where the flags value is the bitwise OR of the status/action bit values listed above, where the presence of one of these tells nsdispatch that it should accept that return value as ending its sequence of method calls. If no modules are found for the requested dbname, the list of module and method acceptance criteria pairs pointed to by src will be used. If src is a null pointer, the fallback default of

       {{"compat", NS_SUCCESS|NS_RETURN}, {0, 0}}

will be used.

Modules

The NSS modules are dynamic shared libraries found in the /usr/lib/nss/ directory with the name module.so.1. They must have an exported function called nss_method_register with shape matching the type pointed to by nss_module_register_fn as defined in the nsswitch.h header:

       typedef struct {
           const char database;  // e.g., "passwd"
           const char name;      // e.g., "getpwnam"
           nss_method method;     // call this routine ...
           void       mdata;     // ... passing this data
       } ns_mtab;
       typedef void (nss_module_unregister_fn)(ns_mtab mtab, unsigned int len);
       typedef ns_mtab (nss_module_register_fn)(const char modname,
   			unsigned int plen, nss_module_unregister_fn fptr);

The nss_module_register function is expected to return a pointer to the start of an array of ns_mtab structures whose length is stored in the integer pointed to by plen. The pointer pointed-to by fptr should be set to null if no clean-up action is needed when this module is to be disconnected; otherwise it should be set to the address of an appropriate unregister function, which will be passed the address of the start of the ns_mtab array and its length as returned by the module's register function.

The returned array of ns_mtab structures lists the database/method pairs provided by this module. Note that this array's contents are expected to be modifiable, as nsdispatch sorts the array for quicker lookups.

The nsdispatch function returns the value returned by the last-called method, or NS_NOTFOUND if no method was called.

Any problems with the configuration file are reported via syslog(3C).

Files

/etc/nsswitch.conf: NSS configuration file
/usr/lib/nss/.so.1: NSS runtime modules

References

getgrent(3C), getpwent(3C), getspent(3C), ia_uinfo(3iac), syslog(3C), nsswitch.conf(5), stdarg(5)