nsdispatch(3) - NetBSD Manual Pages

NSDISPATCH(3)             NetBSD Programmer's Manual             NSDISPATCH(3)


NAME

     nsdispatch - name-service switch dispatcher routine


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <nsswitch.h>

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


DESCRIPTION

     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 dynami-
     cally loaded function.

     defaults contains a list of default sources to try in the case of a miss-
     ing 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
     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
     The callback functions should return one of the following values depend-
     ing 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

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


HISTORY

     The nsdispatch routines first appeared in NetBSD 1.4.


AUTHORS

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


BUGS

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

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

NetBSD 1.4                     January 19, 1999                              2