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

NAME
     yyppaallll, yyppbbiinndd, yyppffiirrsstt, yyppggeettddeeffaauullttddoommaaiinn, yyppmmaasstteerr, yyppmmaattcchh,
     yyppnneexxtt, yyppoorrddeerr, yyppuunnbbiinndd, yyppeerrrrssttrriinngg, yypppprrootteerrrr - Interface to
     the YP subsystem

SYNOPSIS
     ##iinncclluuddee <>
     ##iinncclluuddee <>
     ##iinncclluuddee <>

     int
     yyppaallll(char *indomain, char *inmap, struct ypallcallback *incallback);

     int
     yyppbbiinndd(char *dom);

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

     int
     yyppggeettddeeffaauullttddoommaaiinn(char **domp);

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

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

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

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

     void
     yyppuunnbbiinndd(char *dom);

     char *
     yyppeerrrrssttrriinngg(int incode);

     int
     yypppprrootteerrrr(unsigned int incode);

DESCRIPTION
     The yyppccllnntt suite provides an interface to the YP subsystem.  For a gen-
     eral 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.  Memory will be allocated by the YP
     client routines using mmaalllloocc().  This memory can later be freed by the
     user if 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, null-terminated
     strings.  All input strings which also have a corresponding length param-
     eter cannot be null unless the corresponding length value is zero.  Such
     strings need not be null-terminated.

     All YP lookup calls (the functions yyppaallll(), yyppffiirrsstt(), yyppmmaasstteerr(),
     yyppmmaattcchh(), yyppnneexxtt(), yyppoorrddeerr()) require a YP domain name and a YP map
     name.  The default domain name may be obtained by calling
     yyppggeettddeeffaauullttddoommaaiinn(), 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 yyppbbiinndd() 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
     yyppuunnbbiinndd(), 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 yyppccllnntt layer retries the
     lookup as long as ypbind(8) is running and either the client process can-
     not 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 yyppccllnntt suite provides the following functionality:

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

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

     yyppnneexxtt()       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 yyppffiirrsstt().
                     In the general case, the next key-value pair may be
                     obtained by using the outkey value from the previous call
                     to yyppnneexxtt() as the value for inkey.

                     Of course, the notions of ``first'' and ``next'' are par-
                     ticular to the type of YP map being accessed, and thus
                     there is no guarantee of lexical order.  The only guaran-
                     tees provided with yyppffiirrsstt() and yyppnneexxtt(), providing
                     that the same map on the same server is polled repeatedly
                     until yyppnneexxtt() returns YPERRNOMORE, 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 func-
                     tion yyppaallll() provides a better solution for reading all
                     of the entries in a particular map.

     yyppaallll()        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 func-
                     tions in the yyppccllnntt 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.  YYppaallll() 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
                     yyppaallll() is:

                           struct ypallcallback *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 yyppaallll() 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 <>: see
                                   yypppprrootteerrrr() below for a function that will
                                   translate YP protocol errors into a yyppccllnntt
                                   layer error code as described in
                                   <>.

                     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 yyppaallll(), 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.

     yyppoorrddeerr()      Returns the order number for a map.

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

     yyppeerrrrssttrriinngg()  Returns a pointer to a null-terminated error string that
                     does not contain a `.' or `\n'.

     yypppprrootteerrrr()    Converts a YP protocol error code to a yyppccllnntt error code
                     suitable for yyppeerrrrssttrriinngg().

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

     [YPERRBADARGS]   The passed arguments to the function are invalid

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

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

     [YPERRKEY]       The key passed does not exist.

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

     [YPERRDOM]       The local YP domain is not set.

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

     [YPERRPMAP]      Cannot communicate with portmap.

     [YPERRRESRC]     A resource allocation failure occurred.

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

     [YPERRVERS]      Client/server version mismatch.  If the server is run-
                       ning version 1 of the YP protocol, yyppaallll() functional-
                       ity does not exist.

     [YPERRBIND]      Cannot communicate with ypbind(8).

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

     [YPERRYPSERV]    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