ns_lookup(3C)

NAME
     ns_lookup, ns_list, ns_close - lookup interface to name service daemon

SYNOPSIS
     #include <ns_api.h>

     int ns_lookup(ns_map_t *map, char *domain, char *table, const char *key, char *library, char *buf, size_t len);

     FILE *ns_list(ns_map_t *map, char *domain, char *table, char *library);

     void ns_close(ns_map_t *map);

     extern int _getXbyY_no_stat;

DESCRIPTION
     ns_lookup, ns_list and ns_close are part of the public interface to the
     UNS name service daemon, nsd(1M).  Ordinarily they are called through
     name service library routines such as getpwnam(3C) and gethostbyname(3N).

     When ns_lookup is called with a particular domain, table and key, it
     first will mmap in a global shared cache database corresponding to the
     table name and attempt to look up the key.  The mdbm database cache
     information is stored in the passed map structure.  If the lookup fails
     then the routine will open a file associated with the key, table and
     domain, and parse the data, in a similar way to flat configuration files.
     The file opened is generated on the fly by the cache miss daemon nsd(1M).

     The daemon will determine the resolve order for the request then call
     routines in shared libraries for each of the protocols supported to
     answer the request.  Once the data is found it is stored in the global
     shared cache database and a file is generated in memory using the format
     of the flat text file.  The value, if found is returned in buf.  Request
     result types can be found in ns_api.h.

     The map structure contains state for the cache file.  The structure is
     defined as:

     typedef struct {
          time_t         m_version;
          int       m_flags;
          MDBM      *m_map;
          int       m_stayopen;
     } ns_map_t;

     The m_version field contains a timestamp; any cache record older than
     this will be ignored.  The m_map field contains a pointer to the map file
     state and should be null on first call.  The m_stayopen field is unused
     by ns_lookup. The m_flags bit field contains state for ns_lookup and
     should be set to zero on first call, unless the dynamic creation of
     tables is desired.  In this case, the NS_MAP_DYNAMIC bit of the m_flags
     field should be set.  This will cause ns_lookup() or ns_list() to attempt
     to create the table if it does not exist.  The mapping may be removed by
     a call to ns_close, see below.

     ns_list will return a file handle to an NFS mounted file containing a
     list of all entries for a given domain and table.

     ns_close should be called to remove a cache mapping from memory.  The
     ns_lookup routine will open a cache file and map it into the process
     memory on first use, and it remains available for the life of the
     process.  The ns_close routine can be used to recover the virtual memory
     space or force a reopen of the cache.  This must be called before
     releasing the memory for the ns_map_t structure if dynamically allocated.

     Each of the name service API routines call stat(2) on the local files and
     ignore anything in the cache older than these files.  Since the stat call
     is quite expensive this may be skipped by setting the global integer
     _getXbyY_no_stat to a non-zero value.

DYNAMIC TABLES
     Tables that are not listed in nsswitch.conf(4) may be created by
     associating them with a parent table.  A parent table is one that is
     marked with the dynamic attribute.  Parent tables cannot support key
     lookup, but exist only to contain  and to provide protocol information to
     dynamically created tables.  See nsswitch.conf(4) for more information.
     To use dynamic tables, the m_flags field of the nsd_map_t passed to
     ns_lookup or ns_list must have the NS_MAP_DYNAMIC bit set and the table
     name must reference both the parent table and the new dynamic table.  The
     format of the dynamic table reference is the name of the parent table
     name followed by a colon followed by the name of the dynamic table name.
     For the parent table automount, the reference for the dynamic table
     auto_home would then be "automount:auto_home".

FILES
     /usr/include/ns_api.h

SEE ALSO
     nsd(1M), networks(4), nsswitch.conf(4)

DIAGNOSTICS
     The ns_lookup routine returns an integer result code which is one of:
     NS_SUCCESS, NS_NOTFOUND, NS_UNAVAIL, NS_TRYAGAIN, NS_BADREQ, NS_FATAL and
     NS_NOPERM. The ns_list routine will return a FILE pointer which is null
     on failure with errno set.