ssdi(3C)

NAME
     ssdi_get_config_and_load - consult configuration file and load DSO
     corresponding to the source for a given system database

SYNOPSIS
     #include <ssdi.h>
     int ssdi_get_config_and_load(char *dbname, struct ssdiconfiginfo *cfinfo,
          struct ssdisrcinfo *srcinfo);

DESCRIPTION
     The ssdi_get_config_and_load function provides the means for an
     application to load the dynamic shared object (DSO) corresponding to a
     source for a given system database. A database is a collection of
     information related to users, groups, networks, etc. that the operating
     system expects to be maintained by user-level libraries.  For example,
     information relating to users is encapsulated by the passwd database.
     Each such has a definite interface. For example, the getpwent(3C)
     routines define the interface for the passwd database.  The information
     contained in a given database  may be stored in multiple sources. Almost
     all standard databases come with sources that are compiled-in with the
     interface. The files source for the passwd database which maintains
     relevant information in files is one such.  A Dynamic source for a
     database is one whose implementation is not fixed at the time of
     compilation of interface for the database.  Thus, a dynamic source allows
     for custom implementations of database repositories.

     The file /etc/ssdi.conf (see ssdi(4)) is used to add a dynamic source for
     a database.  Each application can cache configuration information for a
     given database using a variable of type struct ssdiconfiginfo, which
     includes the following members:

     int  ssdi_ci_got_config          If non-zero, the rest of the fields
                                      contain configuration information.

     char *ssdi_ci_dsrcs[_SSDI_MAXSRCS]
                                      Names of dynamic sources for the given
                                      database.

     char **ssdi_ci_currdsrc          Next dynamic source to load. Pointer to
                                      the name in the above array.

     Initially, the variable used to cache configuration information should be
     set to _SSDI_InitConfigInfo.

     Each dynamic source should be implemented as a DSO, and should reside in
     a standard directory as defined by _SSDI_STD_SRC_DIR. The DSO should
     export a variable which represents a vector of functions. This vector
     contains addresses of functions which implement corresponding
     functionality of the database interface. The correspondence between the
     vector and the routines of the database interface is defined in a
     database specific header file, <di_{database-name}.h>.  For example, the
     file <di_group.h> defines the correspondence for the group database. If a
     source does not implement a particular routine then the corresponding
     element in the vector should be set to NULL.

     On its very first invocation, ssdi_get_config_and_load function gathers
     information for the database dbname from the configuration file, and
     caches it in the variable pointed to by cfinfo.  Then, it loads (using
     dlopen(3)) the DSO corresponding to the first source listed in the
     configuration.  Information concerning the loaded source is returned in
     srcinfo, which is of type struct ssdisrcinfo, and has the following
     fields:

     char ssdi_si_name[_SSDI_MAXSRCNAME]
                                      The name of the source that was loaded.

     _SSDI_VOIDFUNC  *ssdi_si_funcs   A pointer to the vector of routines
                                      implemented by the source; resolved
                                      using dlsym(3) from the DSO
                                      corresponding to the source.

     On subsequent invocations (with the same arguments),
     ssdi_get_config_and_load loads the next source in the cached
     configuration information; srcinfo is overwritten with data from this new
     source.  Since  ssdi_get_config_and_load maintains state between
     invocations in cfinfo, it should not be manipulated by the caller, except
     for proper initialization before the first invocation.

SEE ALSO
     ssdi(4), dlopen(3), dlsym(3), getpwent(3C), getgrent(3C)

DIAGNOSTICS
     If a source was successfully loaded, ssdi_get_config_and_load returns
     zero. Otherwise, a non-zero value is returned.