Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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

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

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

     int
     yp_bind(char *dom);

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

     int
     yp_get_default_domain(char **domp);

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

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

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

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

     void
     yp_unbind(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 sub-system, subsystem,
     system, 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.  Memory will be allocated by
     the YP client routines using malloc().  This memory can later be freed by the user if there is no addi-tional additional
     tional 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, null-terminated strings.  All input strings which also have a
     corresponding length parameter cannot be null unless the corresponding length value is zero.  Such
     strings need not be null-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 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 completely optional: cast it to
                                   something useful or simply ignore it.

     yp_order()      Returns the order number for a map.  The order number is updated whenever a map is
                     updated.  Clients may use the order number to check whether they are using the most
                     recent 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 null-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 portmap.

     [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 proto-col, protocol,
                       col, 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)

AUTHOR
     Theo De Raadt

BSD                            October 26, 1994                            BSD