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
#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, 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);
The ypclnt suite provides an interface to the YP subsystem.
For a general
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 malloc(). 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 `0 and
` ', which are not reflected in the values of outkeylen or
outvallen.
All occurrences of indomain and inmap must be non-null, NULterminated
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 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 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 keyvalue
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 heavily loaded or the server fails for
some reason, the domain being used may become unbound.
If this happens, and the client process rebinds, 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 requestresponse. The
third argument to this function provides a
way to supply
the name of a function to process each keyvalue 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 keyvalue
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; therefore, 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 `0 or ` ' 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.
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 `0.
ypprot_err() Converts a YP protocol error code to a
ypclnt error code
suitable for yperr_string().
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 protocol,
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.
malloc(3), yp(8), ypbind(8), ypserv(8)
Theo De Raadt
OpenBSD 3.6 October 26, 1994
[ Back ] |
