ypclnt.3c (2010 09)

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 newline 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 parame-
ters 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.
Operational Behavior
yp_get_default_domain()
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.
yp_bind() 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. If a
process calls the yp_bind() function, the process must also call the
yp_unbind() function when it is finished using NIS in order to free up resources.
yp_unbind() 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 access-
ing 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.
Under the following circumstances, the
ypclnt layer returns control to the user
code with either an error code or success code and the results (see ypbind in
ypserv (1M)):
1. If an error is not RPC-related, or
2. If ypbind is not running, or
3. If rpbind is not running, or
4. If a bound ypserv process returns any answer
(success or failure)
yp_match() Returns the value associated with a passed key. This key must be exact; no pattern
matching is available. yp_match() requires a full YP map name, such as
hosts.byname , instead of the nickname hosts.
yp_first() Returns the first key-value pair from the named map in the named NIS domain.
2 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: September 2010