HP-UX Reference (11i v1 00/12) - 3 Library Functions N-Z (vol 7)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/nan.3m
________________________________________________________________
___ ___
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 running. 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 sup-
plying 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 completed
(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 con-
tents. 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.
yp_master() Returns the host name of the master NIS server for a map.
Section 3−−1042 − 3 − HP-UX Release 11i: December 2000
___
___