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
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/types.h>
#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, size_t *outkeylen,
char **outval, size_t *outvallen);
int
yp_get_default_domain(char **domp);
int
yp_master(char *indomain, char *inmap, **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, size_t inkeylen,
char **outkey, int *outkeylen, char **outval, size_t *outvallen);
int
yp_order(char *indomain, char *inmap, int *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 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 uninitial‐
ized 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 rou‐
tine 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 param‐
eter 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 domp 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 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 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 proce‐
dure is repeated, the order will be the same.
If the server is heavily 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 func‐
tion 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 dif‐
ferent here than described above. In this
case, the memory pointed to by inkey and
inval is private to yp_all(), and is over‐
written with each subsequent key-value pair,
thus the foreach() function should do some‐
thing 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 termi‐
nated 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
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 run‐
ning version 1 of the YP protocol, yp_all() functional‐
ity 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 ALSOmalloc(3), yp(8), ypbind(8), ypserv(8)AUTHORS
Theo De Raadt
BSD April 23, 2009 BSD
