NS_LOOKUP(3C)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
Page 1
NS_LOOKUP(3C)NS_LOOKUP(3C)
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 ALSOnsd(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.
Page 2
