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

y
ypclnt(3C) ypclnt(3C)
int ypprot_err(unsigned int incode);
Remarks
The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has
changed, the functionality of the service remains the same.
DESCRIPTION
These 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 informa-
tion 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 parame-
ter 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 subse-
quent 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 descrip-
tors 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 opera-
tions is performed on the same map at the same server, the entries are retrieved in
the same order.
HP-UX 11i Version 2: December 2007 Update − 2 − Hewlett-Packard Company 657