NS_LOOKUP(3C)							 NS_LOOKUP(3C)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

     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    [Toc]    [Back]

     /usr/include/ns_api.h

SEE ALSO    [Toc]    [Back]

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

DIAGNOSTICS    [Toc]    [Back]

     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.


									PPPPaaaaggggeeee 2222