ypclnt.3c (2010 09)

y
ypclnt(3C) ypclnt(3C)
yp_next() Returns the next key-value pair in a named map. To obtain the second key-value
pair, the inkey parameter should be the outkey returned from an initial call to
yp_first(). To obtain the ( n + 1 )th key-value pair, the inkey value should be
the outkey value from the nth call to
yp_next().
The concepts of first and next are particular to the structure of the NIS map being
processed. No relation in retrieval order exists to either the lexical order within
any original ASCII file or to any obvious numerical sorting order on the keys,
values, or key-value pairs. The only ordering guarantee is that if the
yp_first()
function is called on a particular map and the
yp_next() function is called
repeatedly on the same map at the same server until the call fails with an error of
[YPERR_NOMORE], every entry in the database is retrieved exactly once. If the
same sequence of operations is performed on the same map at the same server, the
entries are retrieved in the same order.
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.
HP-UX 11i Version 3: September 2010 − 3 − Hewlett-Packard Company 3