NAME

ypclnt yp_all yp_bind yp_first yp_get_default_domain yp_master yp_match yp_next yp_order yp_unbind yperr_string ypprot_err − Yellow Pages client interface

SYNOPSIS

#include <rpcsvc/ypclnt.h>
#include <sys/types.h>
#include <rpc/rpc.h>
#include <rpcsvc/yp_prot.h>
int yp_all(indomain, inmap, incallback);
char *indomain;
char *inmap;
struct ypall_callback *incallback;
int yp_bind(indomain);
char *indomain;
int yp_first(indomain, inmap, outkey, outkeylen, outval,
     outvallen)
char *indomain;
char *inmap;
char **outkey;
int *outkeylen;
char **outval;
int *outvallen;
int yp_get_default_domain(outdomain);
char **outdomain;
int yp_master(indomain, inmap, outmaster);
char *indomain;
char *inmap;
char **outmaster;
int yp_match(indomain, inmap, inkey, inkeylen, outval,
     outvallen)
char *indomain;
char *inmap;
char *inkey;
int inkeylen;
char **outval;
int *outvallen;
int yp_next(indomain, inmap, inkey, inkeylen, outkey,
    outkeylen, outval, outvallen);
char *indomain;
char *inmap;
char *inkey;
int inkeylen;
char **outkey;
int *outkeylen;
char **outval;
int *outvallen;
int yp_order(indomain, inmap, outorder);
char *indomain;
char *inmap;
unsigned long *outorder;
void yp_unbind(indomain)
char *indomain;
char *yperr_string(incode)
int incode;
int ypprot_err(incode)
unsigned int incode;

DESCRIPTION

These functions provide an interface to the Yellow Pages (YP) network lookup service.  The package can be loaded from the library /lib/libc.a. Refer to ypfiles(4) and ypserv(1M) for an overview of the YP, including the definitions of map and YP domain, and a description of the various servers, databases and commands comprising the YP.

Input parameter names begin with in; output parameter names begin with out.  Output parameters of type char ** should be the addresses of uninitialized character pointers.  Memory is allocated by the YP client package using malloc(3X) and may be freed if the user code has no continuing need for it. For each outkey and outval, two extra bytes of memory are allocated at the end that contain newline and null (in this order), but these two bytes are not reflected in outkeylen and outvallen. The indomain and inmap strings must be non-null and null-terminated.  String parameters which are accompanied by a length parameter cannot be null, but may point to null strings with a length parameter of zero.  Counted strings need not be null-terminated. 

The YP lookup calls require a map (database) name and a YP domain name.  The client process should know the name of the map of interest.  Client processes should obtain the host’s YP domain by calling yp_get_default_domain() and use the returned outdomain as the indomain parameter to subsequent YP calls. 

To use the YP services, the client process must be "bound" to a YP server that serves the appropriate YP domain using yp_bind(). Binding does not have to occur explicitly by user code, rather it occurs automatically whenever a YP lookup function is called. The yp_bind() function can be called directly for processes that use a backup strategy (e.g., a local file) when YP services are not available.

Each binding allocates (uses up) one client process socket descriptor; each bound YP domain costs one socket descriptor.  However, multiple requests to the same YP domain use that same descriptor.  The yp_unbind() function is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple YP domains.  The call to yp_unbind() makes the YP domain unbound and frees all per-process and per-node resources used to bind it. 

If an RPC failure results when using a binding, that YP domain will be unbound automatically.  The ypclnt layer then continues retrying until the operation succeeds, provided that ypbind(1M) is running and either

a)the client process cannot bind a server for the proper YP domain, or

b)RPC requests to the server fail. 

If an error is not RPC-related, ypbind(1M) is not running, or a bound ypserv(1M) process returns any answer (success or failure), the ypclnt layer returns control to the user code, either with an error code or a success code with any results.

The yp_match() function returns the value associated with a passed key.  This key must be exact; no pattern matching is available.

The yp_first() function returns the first key-value pair from the named map in the named YP domain.

The yp_next() function returns the next key-value pair in a named map. To obtain the second key-value pair, the inkey parameter should be the outkey returned from an initial call to yp_first(). To obtain the n + 1th key-value pair, the inkey value should be the outkey value from the nth call to yp_next().

The concepts of first and next are particular to the structure of the YP map being processed.  No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs.  The only ordering guarantee is that if the yp_first() function is called on a particular map and the yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order.

Under conditions of heavy server load or server failure, the YP domain may become unbound and bind again (perhaps to a different server) while a client is running.  This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all.  This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration.  The yp_all() function describes a better solution to enumerating all entries in a map.

The yp_all() function provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use yp_all() like any other YP procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map.  A return from the call to yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the foreach function decides it does not want any more key-value pairs. 

The third parameter to yp_all() is

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

The function foreach is called

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

The instatus parameter holds one of the return status values defined in <rpcsvc/yp_prot.h>: either YP_TRUE or an error code.  (See ypprot_err(), below, for a function that converts a YP protocol error code to a ypclnt layer error code, as defined in <rpcsvc/ypclnt.h>.)

The key and value parameters are somewhat different than defined in the above SYNOPSIS section.  First, the memory pointed to by the and inval parameters is private to the yp_all() function, and it is overwritten with the arrival of each new key-value pair. The foreach function should do something useful with the contents of that memory, but it does not own the memory.  Key and value objects presented to the foreach function look exactly as they do in the server’s map.  Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. 

The indata parameter is the contents of the incallback->data element passed to yp_all(). The data element of the callback structure can share state information between the foreach function and the mainline code.  Its use is optional, and no part of the YP client package inspects its contents; cast it to something useful or ignore it as needed. 

The foreach function is boolean.  It should return zero to indicate it should be called again for further received key-value pairs or non-zero to stop the flow of key-value pairs.  If foreach returns a non-zero value, it is not called again; the functional value of yp_all() is then 0.

The yp_order() function returns the order number for a map.

The yp_master() function returns the host name of the master YP server for a map.

The yperr_string() function returns a pointer to an error message string that is null-terminated, but contains no period or newline.

The ypprot_err() function takes a YP protocol error code as input and returns a ypclnt layer error code that can be used as input to yperr_string().

RETURN VALUE

All functions in this package of type int return 0 if the requested operation is successful or one of the following errors if the operation fails. 

YPERR_BADARGS   args to function are bad
YPERR_BADDB     YP map is defective
YPERR_DOMAIN    can’t bind to server on this YP domain
YPERR_KEY       no such key in map
YPERR_MAP       no such map in server’s YP domain
YPERR_NODOM     local YP domain name not set
YPERR_NOMORE    no more records in map
YPERR_PMAP      can’t communicate with portmap
YPERR_RESRC     resource allocation failure
YPERR_RPC       RPC failure - YP domain has been
                unbound
YPERR_VERS      YP client/server version mismatch:
                the YP server bound to uses Version 1
                protocol, so it does not provide
                yp_all() functionality
YPERR_YPBIND    can’t communicate with ypbind
YPERR_YPERR     internal YP server or client error
YPERR_YPSERV    can’t communicate with ypserv

AUTHOR

Sun Microsystems, Inc. 

SEE ALSO

domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). 

INTERNATIONAL SUPPORT

8-bit data, messages

Hewlett-Packard Company  —  May 11, 2021