| YPCLNT(3) | Library Functions Manual | YPCLNT(3) | 
yp_all, yp_bind,
  yp_first,
  yp_get_default_domain,
  yp_master, yp_match,
  yp_next, yp_order,
  yp_unbind, yperr_string,
  ypprot_err, yp_setbindtries
  —
#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);
int
  
  yp_setbindtries(int
    ntries);
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 pointers. 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
    values 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 automatically 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 automatically 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()yp_first()yp_next()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()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:
<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>.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.yp_order()yp_master()yperr_string().’ or
      ‘\n’.ypprot_err()ypclnt
      error code suitable for yperr_string().yp_setbindtries()0 which means wait
      forever if no ypserver is not found of if the RPC communication with the
      yp server fails. If the number passed is negative, the current number of
      tries is not modified.
    This function is an extension to the client library that allows an application to catch communication problems with the ypserver without blocking forever.
ypclnt suite which are of type
  int return 0 upon success or one of the following error
  codes upon failure:
YPERR_BADARGS]YPERR_BADDB]YPERR_BIND]YPERR_DOM]YPERR_DOMAIN]YPERR_KEY]YPERR_MAP]YPERR_NOMORE]YPERR_PMAP]YPERR_RESRC]YPERR_RPC]YPERR_VERS]yp_all() functionality does not
      exist.YPERR_YPERR]YPERR_YPSERV]| February 7, 2018 | NetBSD 10.0 |