NAME    [Toc]    [Back]

     nsdispatch - name-service switch dispatcher routine

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <nsswitch.h>

     int
     nsdispatch(void *retval, const ns_dtab dtab[], const char *database,
             const char *method, const ns_src defaults[], ...);

DESCRIPTION    [Toc]    [Back]

     The nsdispatch() function invokes the callback functions specified in
     dtab in the order given in /etc/nsswitch.conf for the database database
     until a successful entry is found.

     retval is passed to each callback function to modify 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;
                   int (*cb)(void *retval, void *cb_data, va_list ap);
                   void *cb_data;
           } ns_dtab;

           For each source type that is implemented, an entry with src set to
           the name of the source, cb defined as a function which handles that
           source, and cb_data is used to pass arbritrary data to the callback
           function.  The last entry in dtab should contain NULL values for
           src, cb, and cb_data.

     method is usually the name of the function calling nsdispatch().  When
     dynamic loading is supported, a symbol constructed from database, the
     current source, and method will be used as the name to invoke the dynamically
 loaded function.

     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;
                   u_int32_t flags;
           } ns_src;

           For each default source type, an entry with src set to the name of
           the source, and flags set to the relevant flags (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.

           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.

   Valid source types    [Toc]    [Back]
     Whilst there is support for arbitrary sources, the following #defines for
     commonly implementated sources are available:

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

   Callback return values    [Toc]    [Back]
     The callback functions should return one of the following values depending
 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    [Toc]    [Back]

     hesiod(3), stdarg(3), ypclnt(3), nsswitch.conf(5)

HISTORY    [Toc]    [Back]

     The nsdispatch routines first appeared in NetBSD 1.4.

AUTHORS    [Toc]    [Back]

     Luke Mewburn <lukem@netbsd.org> wrote this freely distributable name-service
 switch implementation, using ideas from the ULTRIX svc.conf(5) and
     Solaris nsswitch.conf(4) manual pages.

BUGS    [Toc]    [Back]

     The nsdispatch routines are not thread safe.  This will be rectified in
     the future.

     Currently there is no support for dynamically loadable dispatcher callback
 functions.  It is anticipated that this will be added in the future
     in the back-end without requiring changes to code that invokes
     nsdispatch().

BSD                            January 19, 1999                            BSD