Unix/Linux Go Back    


NetBSD 6.1.5 - man page for yp_next (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


YPCLNT(3)			   BSD Library Functions Manual 			YPCLNT(3)

NAME
     yp_all, yp_bind, yp_first, yp_get_default_domain, yp_master, yp_match, yp_next, yp_order,
     yp_unbind, yperr_string, ypprot_err -- Interface to the YP subsystem

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/types.h>
     #include <rpc/rpc.h>
     #include <rpcsvc/ypclnt.h>
     #include <rpcsvc/yp_prot.h>

     int
     yp_all(const char *indomain, const char *inmap, struct ypall_callback *incallback);

     int
     yp_bind(const char *dom);

     int
     yp_first(const char *indomain, const char *inmap, char **outkey, int *outkeylen,
	 char **outval, int *outvallen);

     int
     yp_get_default_domain(char **outdomain);

     int
     yp_master(const char *indomain, const char *inmap, char **outname);

     int
     yp_match(const char *indomain, const char *inmap, const char *inkey, int inkeylen,
	 char **outval, int *outvallen);

     int
     yp_next(const char *indomain, const char *inmap, const char *inkey, int inkeylen,
	 char **outkey, int *outkeylen, char **outval, int *outvallen);

     int
     yp_order(const char *indomain, const char *inmap, int *outorder);

     void
     yp_unbind(const char *dom);

     char *
     yperr_string(int incode);

     int
     ypprot_err(unsigned int incode);

DESCRIPTION
     The ypclnt suite provides an interface to the YP subsystem.  For a general description of
     the YP subsystem, see yp(8).

     For all functions, input values begin with in and output values begin with out.

     Any output values of type char ** should be the addresses of uninitialized character point-
     ers.  These values will be reset to the null pointer (unless the address itself is the null
     pointer, in which case the error YPERR_BADARGS will be returned).	If necessary, memory will
     be allocated by the YP client routines using malloc(), and the result will be stored in the
     appropriate output value.	If the invocation of a YP client routine doesn't return an error,
     and an output value is not the null pointer, then this memory should be freed by the user
     when there is no additional need for the data stored there.  For outkey and outval, two
     extra bytes of memory are allocated for a '\n' and '\0', which are not reflected in the val-
     ues of outkeylen or outvallen.

     All occurrences of indomain and inmap must be non-null, NUL-terminated strings.  All input
     strings which also have a corresponding length parameter cannot be the null pointer unless
     the corresponding length value is zero.  Such strings need not be NUL-terminated.

     All YP lookup calls (the functions yp_all(), yp_first(), yp_master(), yp_match(), yp_next(),
     yp_order()) require a YP domain name and a YP map name.  The default domain name may be
     obtained by calling yp_get_default_domain(), and should thus be used before all other YP
     calls in a client program.  The value it places outdomain is suitable for use as the
     indomain parameter to all subsequent YP calls.

     In order for YP lookup calls to succeed, the client process must be bound to a YP server
     process.  The client process need not explicitly bind to the server, as it happens automati-
     cally whenever a lookup occurs.  The function yp_bind() is provided for a backup strategy,
     e.g. a local file, when a YP server process is not available.  Each binding uses one socket
     descriptor on the client process, which may be explicitly freed using yp_unbind(), which
     frees all per-process and per-node resources to bind the domain and marks the domain
     unbound.

     If, during a YP lookup, an RPC failure occurs, the domain used in the lookup is automati-
     cally marked unbound and the ypclnt layer retries the lookup as long as ypbind(8) is running
     and either the client process cannot bind to a server for the domain specified in the
     lookup, or RPC requests to the YP server process fail.  If an error is not RPC-related, one
     of the YP error codes described below is returned and control given back to the user code.

     The ypclnt suite provides the following functionality:

     yp_match()    Provides the value associated with the given key.

     yp_first()    Provides the first key-value pair from the given map in the named domain.

     yp_next()	   Provides the next key-value pair in the given map.  To obtain the second pair,
		   the inkey value should be the outkey value provided by the initial call to
		   yp_first().	In the general case, the next key-value pair may be obtained by
		   using the outkey value from the previous call to yp_next() as the value for
		   inkey.

		   Of course, the notions of ``first'' and ``next'' are particular to the type of
		   YP map being accessed, and thus there is no guarantee of lexical order.  The
		   only guarantees provided with yp_first() and yp_next(), providing that the
		   same map on the same server is polled repeatedly until yp_next() returns
		   YPERR_NOMORE, are that all key-value pairs in that map will be accessed
		   exactly once, and if the entire procedure is repeated, the order will be the
		   same.

		   If the server is heavily loaded or the server fails for some reason, the
		   domain being used may become unbound.  If this happens, and the client process
		   re-binds, the retrieval rules will break: some entries may be seen twice, and
		   others not at all.  For this reason, the function yp_all() provides a better
		   solution for reading all of the entries in a particular map.

     yp_all()	   This function provides a way to transfer an entire map from the server to the
		   client process with a single request.  This transfer uses TCP, unlike all
		   other functions in the ypclnt suite, which use UDP.	The entire transaction
		   occurs in a single RPC request-response.  The third argument to this function
		   provides a way to supply the name of a function to process each key-value pair
		   in the map.	yp_all() returns after the entire transaction is complete, or the
		   foreach function decides that it does not want any more key-value pairs.  The
		   third argument to yp_all() is:

			 struct ypall_callback *incallback {
				 int (*foreach)();
				 char *data;
			 };

		   The char *data argument is an opaque pointer for use by the callback function.
		   The foreach function should return non-zero when it no longer wishes to
		   process key-value pairs, at which time yp_all() returns a value of 0, and is
		   called with the following arguments:

			 int foreach (
				 int instatus,
				 char *inkey,
				 int inkeylen,
				 char *inval,
				 int invallen,
				 char *indata
			 );

		   Where:

		   instatus	 Holds one of the return status values described in
				 <rpcsvc/yp_prot.h>: see ypprot_err() below for a function that
				 will translate YP protocol errors into a ypclnt layer error code
				 as described in <rpcsvc/ypclnt.h>.

		   inkey, inval  The key and value arguments are somewhat different here than
				 described above.  In this case, the memory pointed to by inkey
				 and inval is private to yp_all(), and is overwritten with each
				 subsequent key-value pair, thus the foreach function should do
				 something useful with the contents of that memory during each
				 iteration.  If the key-value pairs are not terminated with
				 either '\n' or '\0' in the map, then they will not be terminated
				 as such when given to the foreach function, either.

		   indata	 This is the contents of the incallback->data element of the
				 callback structure.  It is provided as a means to share state
				 between the foreach function and the user code.  Its use is com-
				 pletely optional: cast it to something useful or simply ignore
				 it.

     yp_order()    Returns the order number for a map.

     yp_master()   Returns the hostname for the machine on which the master YP server process for
		   a map is running.

     yperr_string()
		   Returns a pointer to a NUL-terminated error string that does not contain a '.'
		   or '\n'.

     ypprot_err()  Converts a YP protocol error code to a ypclnt error code suitable for
		   yperr_string().

RETURN VALUES
     All functions in the ypclnt suite which are of type int return 0 upon success or one of the
     following error codes upon failure:

     [YPERR_BADARGS]   The passed arguments to the function are invalid.

     [YPERR_BADDB]     The YP map that was polled is defective.

     [YPERR_DOMAIN]    Client process cannot bind to server on this YP domain.

     [YPERR_KEY]       The key passed does not exist.

     [YPERR_MAP]       There is no such map in the server's domain.

     [YPERR_DOM]       The local YP domain is not set.

     [YPERR_NOMORE]    There are no more records in the queried map.

     [YPERR_PMAP]      Cannot communicate with portmapper (see rpcbind(8)).

     [YPERR_RESRC]     A resource allocation failure occurred.

     [YPERR_RPC]       An RPC failure has occurred.  The domain has been marked unbound.

     [YPERR_VERS]      Client/server version mismatch.	If the server is running version 1 of the
		       YP protocol, yp_all() functionality does not exist.

     [YPERR_BIND]      Cannot communicate with ypbind(8).

     [YPERR_YPERR]     An internal server or client error has occurred.

     [YPERR_YPSERV]    The client cannot communicate with the YP server process.

SEE ALSO
     malloc(3), yp(8), ypbind(8), ypserv(8)

AUTHORS
     Theo De Raadt

BSD					   May 21, 1997 				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:00 AM.