ypclnt(3C)ypclnt(3C)NAME
ypclnt: 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
SYNOPSIS
[flag]... file... [library]...
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 com‐
mands comprising the NIS.
Input parameter names begin with output parameter names begin with Out‐
put parameters of type should be the addresses of uninitialized charac‐
ter pointers. Memory is allocated by the NIS client package using 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 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.
Operational Behavior
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 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 Binding does
not have to occur explicitly by user code. Rather, it occurs
automatically whenever a NIS lookup function is called. 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 function, the process must also call the func‐
tion when it is finished using NIS in order to free up
resources.
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 descrip‐
tor. is available at the client interface for processes that
explicitly manage their socket descriptors while accessing mul‐
tiple NIS domains. The call to makes the NIS domain 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 layer then continues retrying
until the operation succeeds, provided 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 layer returns control to
the user code with either an error code or success code and the
results (see 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)
Returns the value associated with a passed key. This key must be
exact; no pattern matching is available. requires a full YP map name,
such as hosts.byname, instead of the nickname hosts.
Returns the first key-value pair from the named map
in the named NIS domain.
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 To obtain the
( n + 1 )th key-value pair, the inkey value should be the outkey
value from the nth call to
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, val‐
ues, or key-value pairs. The only ordering guarantee is that if
the function is called on a particular map and the function is
called repeatedly on the same map at the same server until the
call fails with an error of 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 oth‐
erwise be returned in the midst of the enumeration.
describes a better solution to enumerating all entries in a map.
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 trans‐
action occurs as a single RPC request and response. You can use
like any other NIS procedure by identifying the map in the nor‐
mal manner and supplying the name of a function called to
process each key-value pair within the map. A return from the
call to 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 is:
The function is called as follows:
Where:
instatus Holds one of the return status values defined in
either or an error code (see below, for a function
that converts a NIS protocol error code to a layer
error code, as defined in
inkey The key and value parameters are somewhat different
inval than defined in the section above. First, the memory
pointed to by inkey and inval is private to and is
overwritten with the arrival of each new key-value
pair. Therefore, should do something useful with the
contents of that memory, but it does not own the mem‐
ory. Key and value objects presented to the 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 The
data element of the callback structure can share state
information between 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 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 returns a
non-zero value, it is not called again and the functional value
of is then 0.
Returns the order number for a map.
This function is not supported if the ypbind process on the
client's system is bound to an NIS+ server running in "YP-com‐
patibility mode."
Returns the host name of the master NIS server for a map.
Returns a pointer to an error message string
that is null-terminated, but contains no period or newline.
Takes an NIS protocol error code as input
and returns a layer error code that can be used as input to
MULTITHREAD USAGE
Thread Safe: Yes
Cancel Safe: No
Fork Safe: No
Async-cancel Safe: No
Async-signal Safe: No
These functions cannot 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 and before These functions should not
be called by a multithreaded application that support asynchronous can‐
cellation or asynchronous signals.
WARNINGS
Starting with ONCplus version B.11.31.02, the NIS Version 1 protocol is
no longer available.
RETURN VALUE
All functions in this package of type return 0 if the requested opera‐
tion is successful or one of the following errors if the operation
fails.
database access violation
args to function are bad
NIS map is defective
database busy
cannot bind to server on this NIS domain
no such key in map
no such map in server's NIS domain
local NIS domain name not set
no more records in map
cannot communicate with portmap
resource allocation failure
RPC failure - NIS domain has been unbound
NIS client/server version mismatch: the NIS
server bound to uses Version 1 proto‐
col, so it does not provide functional‐
ity.
cannot communicate with
internal NIS server or client error
cannot communicate with
AUTHOR
was developed by Sun Microsystems, Inc.
SEE ALSOdomainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4).
ypclnt(3C)
