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
)
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:
)
)
)
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 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.
)
)
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:
instatus
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
inkey
and
inval
is private to
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.
indata
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.
)
)
)
)
).
YPERR_BADARGS
]
YPERR_BADDB
]
YPERR_DOMAIN
]
YPERR_KEY
]
YPERR_MAP
]
YPERR_DOM
]
YPERR_NOMORE
]
YPERR_PMAP
]
YPERR_RESRC
]
YPERR_RPC
]
YPERR_VERS
]
)
functionality does not exist.
YPERR_BIND
]
YPERR_YPERR
]
YPERR_YPSERV
]