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 Output parameters of type should be the addresses of uninitialized char-
acter pointers. Memory is allocated by the NIS client package using 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 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 auto-
matically 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 function 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 descriptor. is
available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple 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, values, 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 otherwise 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 transac-
tion occurs as a single RPC request and response. You can use 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 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 than defined in the section above. First, the memory pointed to by
inval inkey and inval is private to and is overwritten with the arrival of each new key-value pair. Therefore, should do some-
thing useful with the contents of that memory, but it does not own the memory. 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-compatibility
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 cancellation 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 operation 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 protocol, so it does not provide functionality.
cannot communicate with
internal NIS server or client error
cannot communicate with
AUTHOR
was developed by Sun Microsystems, Inc.
SEE ALSO
domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4).
ypclnt(3C)