ypclnt(3N) ypclnt(3N)
NAME
yp_bind, yp_get_default_domain, yp_unbind, yp_match,
yp_first, ypclnt_first, yp_next, ypclnt_next - yellow pages
client interface
SYNOPSIS
#include <rpcsvc/ypclnt.h>
ypbind(indomain);
char *indomain;
ypgetdefaultdomain(outdomain);
char **outdomain;
void ypunbind(indomain)
char *indomain;
ypmatch(indomain, inmap, inkey, inkeylen, outval, outvallen)
char *indomain;
char *inmap;
char *inkey;
int inkeylen;
char **outval;
int *outvallen;
ypfirst(indomain, inmap, inkey, inkeylen, outval, outvallen)
ypclntfirst(indomain, inmap, inkey, inkeylen, outval, outvallen)
char *indomain;
char *inmap;
char *outkey;
int outkeylen;
char **outval;
int *outvallen;
ypnext(indomain, inmap, inkey, inkeylen, outkey, outkeylen, outval, outvallen);
ypclntnext(indomain, inmap, inkey, inkeylen, outkey, outkeylen, outval, outvallen);
char *indomain;
char *inmap;
char *inkey;
int inkeylen;
char **outkey;
int *outkeylen;
char **outval;
int *outvallen;
char *yperrstring(code)
int code;
DESCRIPTION
This package of functions is an interface to the yellow
pages (YP) network service. The package can be loaded from
Page 1 (last mod. 1/16/87)
ypclnt(3N) ypclnt(3N)
the standard library, /lib/libc.a. In the synopsis above,
all input parameters names begin with in, while output
parameters begin with out. Output parameters of type char
** should be addresses of uninitialized character pointers.
Memory is allocated by the YP client package using
malloc(3), and may be freed if the user code has no
continuing need for it.
For all outkeys and outvals, two extra bytes of memory are
allocated at the end, containing newline and NULL, but these
two bytes are not reflected in outkeylen.
Information is stored in the yellow pages system as sets of
key-value pairs, called entries, with no imposed or assumed
structure to the key or the value; both are counted binary
objects. A named set of key-value pairs is called a YP map,
and is implemented as a pair of dbm(3X) data base files.
maps are objects within named domains, which are implemented
by UNIX® directories. Although map names must be unique
within a domain, the same map name may appear in multiple
domains. As a map is a named set of key-value pairs, so is
a domain a named set of maps. Every map must be referenced
as an object in some domain. Both map names and domain
names are non-null printable ASCII strings. Null-length
domain and map names will be rejected by the YP client
interface, as will null pointers.
Network hosts, both servers and clients, have a default
domain, which is set at system startup by domainname(1).
The default domain may be fetched by calling
ypgetdefaultdomain(). In general, client processes
should make no assumption concerning the domain parameter
that is to be passed in the calls to ypmatch(), ypfirst(),
ypclntfirst(), ypnext(), and ypclntnext(), but should,
rather, use the domain name returned by
ypgetdefaultdomain().
All the functions in this package which are of type int,
return 0 if they succeed, and a failure code (YPERRxxxx)
otherwise. Failure codes are described below in the
DIAGNOSTICS section.
To use the YP services, the client process must be ``bound''
to a YP server that serves the appropriate domain. A client
is bound to a YP server when the client knows the internet
address of the server, the port on which the server is
listening for requests, and it has set up an RPC path to
that YP server. Binding doesn't need to be done explicitly
by user code; it will be done automatically when ypmatch(),
ypfirst(), ypclntfirst(), ypnext(), or ypclntnext() is
called for a domain that is not bound. The binding may,
however, be explicitly made by the client by a call to
Page 2 (last mod. 1/16/87)
ypclnt(3N) ypclnt(3N)
ypbind(). This is useful for processes that make use of a
backup strategy (e.g., a local file) in case YP services are
not available.
Binding allocates (uses up) one of the client process'
socket descriptors; each bound domain costs one socket
descriptor. If, however, ypmatch(), ypfirst(),
ypclntfirst(), ypnext(), or ypclntnext() is called naming
a domain which is already bound, no further binding needs to
be done. No new resource will be allocated on a per-call
basis.
If an RPC failure results upon use of a bound domain, that
domain will be unbound automatically by the YP client code,
and an indication of the RPC error will be returned. At
that point, the client process will retry forever until the
operation succeeds, provided that ypbind is running, and
either a) the client process can't bind to a server for the
proper domain, or b) RPC requests to the server fail.
ypunbind() is available at the client interface for
processes that need to explicitly manage their socket
descriptor resoures, and which need to access maps in
multiple domains. The call to ypunbind() will free the
socket allocated by the binding for the passed domain, and
will tear down the RPC path to the YP server process.
ypmatch returns the value associated with the passed key.
The key passed as the match value must be exact; no pattern
matching is available.
ypfirst returns the first key-value pair from the named map
in the named domain. The concept of first (and, for that
matter, of next) is particular to the structure of the YP
map data base processing: there is no relation in retrieval
order to either the lexical order within any original (non-
YP) data base, or to any obvious numerical sorting order on
the keys, the values, or the key-value pairs. The only
ordering guarantee made is that if the ypfirst() function
is called on a particular map, and then the ypnext()
function is repeatedly called on the same map until the call
fails with a reason of YPERRNOMORE, every entry in the data
base will be seen exactly once. Further, if the same
sequence of operations is performed on the same map, the
entries will be seen in the same order. ypfirst() will not
return any entry from a map whose key begins with the
sequence ``YP_''; such symbols are assumed to be private
symbols used by the YP system. In general, those entries
are of no interest to the client process. If the client
process needs to see them, ypclntfirst() will do no
filtering of YP private symbols.
Page 3 (last mod. 1/16/87)
ypclnt(3N) ypclnt(3N)
ypnext() returns the next key-value pair in a named map.
The input key should be one returned from a call to
ypfirst() (to get the second pair) or one returned from the
nth call to ypnext() (to get the nth + second pair). Any
valid key may be used, and is syntactically correct with
respect to the retrieval, but any key save the two mentioned
previously will yield a result which is semantically
meaningless. Again, if the client process needs to see all
of the entries in the map, including the YP private symbols,
ypclntnext() does no filtering to eliminate those entries.
yperrstring() returns a pointer to an error message string
that is null-terminated but contains no period or newline.
FILES
/usr/include/rpcsvc/ypclnt.h
/usr/include/rpcsvc/ypprot.h
SEE ALSO
yppasswd(1), dbm(3x), makedbm(1M), ypfiles(1M), ypinit(1M),
yppush(1M), ypserv(1M).
DIAGNOSTICS
All functions except ypunbind() return 0 if the requested
operation is successful, or one of the following errors if
the operation fails.
#define YPERR_BADARGS 1 /* args to function are bad */
#define YPERR_RPC 2 /* RPC failure - domain has been unbound */
#define YPERR_DOMAIN 3 /* can't bind to server on this domain */
#define YPERR_MAP 4 /* no such map in server's domain */
#define YPERR_KEY 5 /* no such key in map */
#define YPERR_YPERR 6 /* internal yp server or client error */
#define YPERR_RESRC 7 /* resource allocation failure */
#define YPERR_NOMORE 8 /* no more records in map database */
#define YPERR_PMAP 9 /* can't communicate with portmapper */
#define YPERR_YPBIND 10 /* can't communicate with ypbind */
#define YPERR_YPSERV 11 /* can't communicate with ypserv */
#define YPERR_NODOM 12 /* local domain name not set */
Page 4 (last mod. 1/16/87)