 |
» |
|
|
|
NAMEypclnt(), yp_all(), yp_bind(), yp_first(), yp_get_default_domain(), yp_master(), yp_match(), yp_next(), yp_order(), yp_unbind(), yperr_string(), ypprot_err() — Network Information Service client interface SYNOPSIScc [flag...] file... -lnsl [library...]
#include <rpcsvc/ypclnt.h>
#include <sys/types.h>
#include <rpc/rpc.h>
#include <rpcsvc/yp_prot.h>
int yp_all(
char *indomain,
char *inmap,
struct ypall_callback *incallback
);
int yp_bind(char *indomain);
int yp_first(
char *indomain,
char *inmap,
char **outkey,
int *outkeylen,
char **outval,
int *outvallen
);
int yp_get_default_domain(char **outdomain);
int yp_master(
char *indomain,
char *inmap,
char **outmaster
);
int yp_match(
char *indomain,
char *inmap,
char *inkey,
int inkeylen,
char **outval,
int *outvallen
);
int yp_next(
char *indomain,
char *inmap,
char *inkey,
int inkeylen,
char **outkey,
int *outkeylen,
char **outval,
int *outvallen
);
int yp_order(
char *indomain,
char *inmap,
unsigned long *outorder
);
void yp_unbind(char *indomain);
char *yperr_string(int incode);
int ypprot_err(unsigned int incode); RemarksThe Network Information Service (NIS) was formerly known as Yellow Pages (yp).
Although the name has changed, the functionality of the
service remains the same. DESCRIPTIONThese functions provide an interface to the Network Information Service
(NIS) network-lookup service.
Refer to
ypfiles(4)
and
ypserv(1M)
for an overview of the NIS, including the definitions of
map
and NIS
domain,
and a description of the various servers, databases,
and commands comprising the NIS. Input parameter names begin with
in;
output parameter names begin with
out.
Output parameters of type
char**
should be the addresses of uninitialized character pointers.
Memory is allocated by the NIS client package using
malloc()
and can be freed after the last time the application accesses
the information returned (see
malloc(3C)).
For each
outkey
and
outval,
two extra bytes of memory are allocated at the end
that contain new-line and null (in that order),
but these two bytes are not reflected in
outkeylen
and
outvallen.
The
indomain
and
inmap
strings must be non-null and null-terminated.
String parameters that are accompanied by a length parameter
cannot be null, but can point
to null strings with a length parameter of zero.
Counted strings need not be null-terminated. The NIS lookup calls require a map (database) name and a NIS domain name.
The client process should know the name of the map of interest.
Client processes should obtain the host's NIS
domain by calling
yp_get_default_domain()
and use the returned
outdomain
as the
indomain
parameter to subsequent NIS calls. To use the NIS services, the client process must be ``bound'' to an NIS
server that serves the appropriate NIS
domain using
yp_bind().
Binding does not have to occur explicitly by user code.
Rather, it occurs automatically whenever a NIS lookup function is called.
yp_bind()
can be called directly for processes
that use a backup strategy (such as a local file) when NIS
services are not available. Each binding allocates (uses up) one client process socket descriptor.
Each bound NIS domain costs one socket descriptor.
However, multiple requests to the same NIS domain use that same descriptor.
yp_unbind()
is available at the client interface for processes
that explicitly manage their socket descriptors while accessing
multiple NIS domains.
The call to
yp_unbind()
makes the NIS domain
unbound
and frees all per-process and per-node resources used to bind it. If an RPC failure results when using a binding, that NIS
domain is unbound automatically.
The
ypclnt
layer then continues retrying until the operation succeeds,
provided
ypbind
is running (see
ypserv(1M))
and either:
- 1.
the client process cannot bind a server for the proper NIS
domain, or - 2.
RPC requests to the server fail.
If an error is not RPC-related, if
ypbind
is not running, or if a bound
ypserv
process returns any answer (success or failure),
the
ypclnt
layer returns control to the user code
with either an error code or with a success code and any results (see
ypbind
in
ypserv(1M)). Operational Behavior- yp_match()
Returns the value associated with a passed key.
This key must be exact; no pattern matching is available. - yp_first()
Returns the first key-value pair from the named map
in the named NIS domain. - 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 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 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 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
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. - yp_master()
Returns the host name of the master NIS server for a map. - yperr_string()
Returns a pointer to an error message string
that is null-terminated, but contains no period or newline. - ypprot_err()
Takes an NIS protocol error code as input
and returns a
ypclnt
layer error code
that can be used as input to
yperr_string()
MULTITHREAD USAGE- Thread Safe:
Yes - Cancel Safe:
Yes - Fork Safe:
No - Async-cancel Safe:
No - Async-signal Safe:
No
These functions can be called safely in a multithreaded environment. They
may be cancellation points in that they call functions that are cancel
points. In a multithreaded environment, these functions are
not safe to be called by a child process after
fork()
and before
exec().
These functions should not be called by a multithreaded application
that support asynchronous cancellation or asynchronous signals. WARNINGSThe NIS Version 1 protocol will not be available
in a future HP-UX release.
HP recommends that you use the next version of this protocol. RETURN VALUEAll functions in this package of type
int
return 0 if the requested operation is successful
or one of the following errors if the operation fails.
- [YPERR_ACCESS]
database access violation - [YPERR_BADARGS]
args to function are bad - [YPERR_BADDB]
NIS map is defective - [YPERR_BUSY]
database busy - [YPERR_DOMAIN]
cannot bind to server on this NIS domain - [YPERR_KEY]
no such key in map - [YPERR_MAP]
no such map in server's NIS domain - [YPERR_NODOM]
local NIS domain name not set - [YPERR_NOMORE]
no more records in map - [YPERR_PMAP]
cannot communicate with portmap - [YPERR_RESRC]
resource allocation failure - [YPERR_RPC]
RPC failure - NIS domain has been unbound - [YPERR_VERS]
NIS client/server version mismatch: the NIS
server bound to uses Version 1 protocol, so it does not provide
yp_all()
functionality.
- [YPERR_YPBIND]
cannot communicate with
ypbind - [YPERR_YPERR]
internal NIS server or client error - [YPERR_YPSERV]
cannot communicate with
ypserv
AUTHORypclnt()
was developed by Sun Microsystems, Inc. |
Printable version
