*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->NetBSD man pages -> yp_master (3)              
Title
Content
Arch
Section
 

YPCLNT(3)

Contents


NAME    [Toc]    [Back]

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

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

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

     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 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()    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 heaviliy 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 nonzero
 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 completely 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    [Toc]    [Back]

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

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

AUTHORS    [Toc]    [Back]

     Theo De Raadt

BSD                              May 21, 1997                              BSD
[ Back ]
 Similar pages
Name OS Title
diag0 HP-UX diagnostic interface to HP-PB I/O subsystem
diag1 HP-UX diagnostic interface to the PCI I/O subsystem
dxaudit Tru64 Motif Interface for the Audit Subsystem
auditconfig Tru64 Audit subsystem configuration graphical interface (Enhanced Security)
audit_setup Tru64 Audit subsystem configuration graphical interface (Enhanced Security)
scsi FreeBSD CAM SCSI subsystem
sys_attrs_ppp Tru64 ppp subsystem attributes
sys_attrs_psm Tru64 psm subsystem attributes
sys_attrs_pts Tru64 pts subsystem attributes
sys_attrs_rt Tru64 rt subsystem attributes
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service