YPCLNT(3) | Library Functions Manual | YPCLNT(3) |
yp_all
, yp_bind
,
yp_first
,
yp_get_default_domain
,
yp_master
, yp_match
,
yp_next
, yp_order
,
yp_unbind
, yperr_string
,
ypprot_err
, yp_setbindtries
—
#include <sys/types.h>
#include <rpc/rpc.h>
#include <rpcsvc/ypclnt.h>
#include <rpcsvc/yp_prot.h>
int
yp_all
(const
char *indomain, const
char *inmap, struct
ypall_callback *incallback);
int
yp_bind
(const
char *dom);
int
yp_first
(const
char *indomain, const
char *inmap, char
**outkey, int
*outkeylen, char
**outval, int
*outvallen);
int
yp_get_default_domain
(char
**outdomain);
int
yp_master
(const
char *indomain, const
char *inmap, char
**outname);
int
yp_match
(const
char *indomain, const
char *inmap, const char
*inkey, int
inkeylen, char
**outval, int
*outvallen);
int
yp_next
(const
char *indomain, const
char *inmap, const char
*inkey, int
inkeylen, char
**outkey, int
*outkeylen, char
**outval, int
*outvallen);
int
yp_order
(const
char *indomain, const
char *inmap, int
*outorder);
void
yp_unbind
(const
char *dom);
char *
yperr_string
(int
incode);
int
ypprot_err
(unsigned
int incode);
int
yp_setbindtries
(int
ntries);
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. 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 routine 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 parameter 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 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
()yp_first
()yp_next
()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 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 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
()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
function 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:
<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>
.yp_all
(), 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.yp_order
()yp_master
()yperr_string
().
’ or
‘\n
’.ypprot_err
()ypclnt
error code suitable for yperr_string
().yp_setbindtries
()0
which means wait
forever if no ypserver is not found of if the RPC communication with the
yp server fails. If the number passed is negative, the current number of
tries is not modified.
This function is an extension to the client library that allows an application to catch communication problems with the ypserver without blocking forever.
ypclnt
suite which are of type
int return 0 upon success or one of the following error
codes upon failure:
YPERR_BADARGS
]YPERR_BADDB
]YPERR_BIND
]YPERR_DOM
]YPERR_DOMAIN
]YPERR_KEY
]YPERR_MAP
]YPERR_NOMORE
]YPERR_PMAP
]YPERR_RESRC
]YPERR_RPC
]YPERR_VERS
]yp_all
() functionality does not
exist.YPERR_YPERR
]YPERR_YPSERV
]February 7, 2018 | NetBSD 9.2 |