HP-UX Reference (11i v2 04/09) - 3 Library Functions N-Z (vol 7)

y
ypclnt(3C) ypclnt(3C)
Under conditions of heavy server load or server failure, the NIS domain may
become unbound and bind again (perhaps to a different server) while a client is run-
ning. 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.
yp_all() describes a better solution to enumerating all entries in a map.
yp_all() 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 NIS 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 com-
pleted (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 as follows:
foreach(
int instatus;
char *inkey;
int inkeylen;
char *inval;
int invallen;
char *indata;
);
Where:
instatus 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 NIS protocol
error code to a ypclnt layer error code, as defined in
<rpcsvc/ypclnt.h>
).
inkey
inval
The key and value parameters are somewhat different than defined
in the SYNOPSIS section above. First, the memory pointed to by
inkey and inval is private to
yp_all(), and is overwritten with
the arrival of each new key-value pair. Therefore, foreach()
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() 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.
indata Is the contents of the incallback −>data element passed to
yp_all() The data element of the callback structure can share
state information between foreach() and the mainline code. Its
use is optional, and no part of the NIS client package inspects its
contents. Cast it to something useful or ignore it as appropriate.
The
foreach() function is Boolean. It should return zero to indicate it needs to
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 and
the functional value of yp_all() is then 0.
yp_order() Returns the order number for a map.
Section 3−−1188 Hewlett-Packard Company − 3 − HP-UX 11i Version 2: September 2004