ypclnt(3) CLIX ypclnt(3)
NAME
ypclnt: yp_get_default_domain, yp_bind, yp_unbind, yp_match, yp_first,
yp_next, yp_all, yp_order, yp_master, yperr_string, ypprot_err - Network
Information Service (NIS) client interface
LIBRARY
BSD Compatibility Library (libbsd.a)
SYNOPSIS
#include <rpcsvc/ypclnt.h>
int yp_bind(
char *indomain );
void yp_unbind(
char *indomain );
int yp_get_default_domain(
char **outdomain );
int yp_match(
char *indomain ,
char *inmap ,
char *inkey ,
int *inkeylen ,
char **outval ,
int *outvallen );
int yp_first(
char *indomain ,
char *inmap ,
char **outkey ,
int *outkeylen ,
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_all(
char *indomain ,
2/94 - Intergraph Corporation 1
ypclnt(3) CLIX ypclnt(3)
char *inmap ,
struct ypall_callback incallback );
int yp_order(
char *indomain ,
char *inmap ,
int *outorder );
int yp_master(
char
*indomain, ,
char *inmap, ,
char **outname );
char *yperr_string(
int incode );
int ypprot_err(
unsigned int incode );
PARAMETERS
indomain Specifies the name of a Network Information Service (NIS)
domain. Must be non-NULL and NULL-terminated.
inmap Specifies the name of an NIS map. Must be non-NULL and
NULL-terminated.
inkey Specifies a key within an NIS map; for example, a username
within the passwd.byname map.
inkeylen Specifies the length in bytes of an inkey parameter, not
including any terminating NULL.
incallback Specifies the function that yp_all() calls for each element
in a map, and a parameter to that function. See the
description of yp_all() in the DESCRIPTION section.
incode Specifies an error code.
outdomain Specifies an NIS domain name string return parameter.
outkey Specifies a key string return parameter.
outkeylen Specifies the length in bytes of a returned key, not
including the terminating NEWLINE or NULL.
outval Points to the value string for a specified inkey.
outvallen Specifies the length in bytes of a returned value string, not
including the terminating NEWLINE or NULL.
2 Intergraph Corporation - 2/94
ypclnt(3) CLIX ypclnt(3)
outorder Specifies the order number for a map.
outname Specifies a machine name.
DESCRIPTION
This package of functions provides an interface to the NIS network lookup
service. The package can be loaded from the standard library,
/usr/lib/libbsd.a. Refer to ypfiles(4) and ypserv(8) for an overview of
NIS, including the definitions of map and domain, and a description of the
various servers, databases, and commands.
All input parameter names begin with in. Output parameters begin with
out. Output parameters that are pointers to character pointers should be
addresses of uninitialized character pointers. Memory is allocated by the
NIS client package using malloc() and can be freed if the user code has no
continuing need for it. For each outkey and outval, two extra bytes of
memory are allocated at the end that contain NEWLINE and NULL,
respectively, but these two bytes are not reflected in outkeylen or
outvallen. The indomain and inmap strings must be non-NULL and NULL-
terminated. String parameters accompanied by a count parameter must not
be NULL but can point to NULL strings, with the count parameter indicating
this. Counted strings need not be NULL-terminated.
All functions that return integers return 0 if they succeed and a failure
code (YPERR_xxxx) otherwise. Failure codes are described in the RETURN
VALUES section.
The NIS lookup calls require a map name and a domain name, at minimum. It
is assumed that the client process knows the name of the map of interest.
Client processes should fetch the default domain of the node by calling
yp_get_default_domain() and use the returned outdomain as the indomain
parameter to successive NIS calls.
To use the NIS services, the client process must be ``bound'' to an NIS
server that serves the appropriate domain using yp_bind(). Binding need
not be explicitly set by user code; it is accomplished automatically when
an NIS lookup function is called. The yp_bind() function can be called
directly for processes that use a backup strategy (for example, a local
file) in cases when NIS services are not available.
Each binding allocates (uses up) one client process socket descriptor;
each bound domain costs one socket descriptor. However, multiple requests
to the same domain use that same descriptor. The yp_unbind() function is
available at the client interface for processes that explicitly manage
their socket descriptors while accessing multiple domains. The call to
yp_unbind() makes the domain unbound, and frees all per-process and per-
node resources used to bind it.
If a Remote Procedure Call (RPC) failure results when a binding is used,
that domain is unbound automatically. At that point, the ypclnt layer
2/94 - Intergraph Corporation 3
ypclnt(3) CLIX ypclnt(3)
retries indefinitely or until the operation succeeds, provided that ypbind
is running, and either of the following are true:
⊕ the client process cannot bind a server for the proper domain
⊕ 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 a success
code and any results.
The yp_match() function returns the value associated with a passed key.
This key must be exact; no pattern matching is available.
The yp_first() function returns the first key-value pair from the named
map in the named domain.
The yp_next() function returns the next key-value pair in a named map.
The inkey parameter should be the outkey returned from an initial call to
yp_first() (to get the second key-value pair) or the one returned from the
nth call to yp_next() (to get the nth + second key-value pair).
The concept of first (and next) is particular to the structure of the NIS
map being processed, the lexical order within any original (non-NIS)
database or any obvious numerical sorting order on the keys, values, or
key-value pairs do not relate to retrieval order. The only ordering
guarantee is that if the yp_first() function is called on a particular
map, and then the yp_next() function is repeatedly called on the same map
at the same server until the call fails with a reason of YPERR_NOMORE,
every entry in the database is seen exactly once. Further, if the same
sequence of operations is performed on the same map at the same server,
the entries will be seen in the same order.
When heavy server load or server failure occurs, it is possible for the
domain to become unbound, then bound once again (perhaps to a different
server) while a client is running. This can cause a break in one of the
enumeration rules; specific entries can 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. The next paragraph
describes a better solution to enumerating all entries in a map.
The yp_all() function provides a way to transfer an entire map from server
to client in a single request using Transmission Control Protocol (TCP)
(rather than User Datagram Protocol (UDP) as with other functions in this
package). The entire transaction occurs as a single RPC request and
response. The yp_all() function can be used like any other NIS procedure
by identifying the map in the normal manner and supplying the name of a
function that will be called to process each key-value pair within the
map. A return from the call to yp_all() only occurs when the transaction
is completed (successfully or unsuccessfully) or when the foreach()
4 Intergraph Corporation - 2/94
ypclnt(3) CLIX ypclnt(3)
function does not want to see any more key-value pairs.
The third parameter to yp_all() is as follows:
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 );
The instatus parameter will hold 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 an NIS protocol error
code to a ypclnt layer error code.)
The key and value parameters differ somewhat from those defined in the
synopsis section above. First, the memory pointed to by the inkey and
inval parameters is private to the yp_all() function and is overwritten
with the arrival of each new key-value pair. It is the responsibility of
the foreach() function to use the contents of that memory, but it does not
own the memory itself. Key and value objects presented to the foreach()
function look exactly as they do in the server map; if they were not
newline-terminated or NULL-terminated in the map, they are not so here
either.
The indata parameter is the contents of the incallback data element passed
to yp_all(). The data element of the callback structure can be used to
share state information between the foreach() function and the mainline
code. Its use is optional and no part of the NIS client package inspects
its contents.
The foreach() function returns 0 to indicate that it needs to be called
again for additional received key-value pairs, or nonzero to stop the flow
of key-value pairs. If foreach() returns a nonzero value, it is not
called again; the functional value of yp_all is then 0.
The yp_order() function returns the order number for a map.
The yp_master() function returns the machine name of the master NIS server
for a map.
The yperr_string() function returns a pointer to an error message string
2/94 - Intergraph Corporation 5
ypclnt(3) CLIX ypclnt(3)
that is NULL-terminated but contains no period or new line.
The ypprot_err() function has an NIS protocol error code as input and
returns a ypclnt layer error code, which can be used as input to
yperr_string().
EXAMPLES
1. To display the value for the key rita in the map passwd.byname for the
default domain:
char *default_domain;
char *value;
int value_len;
int return_val;
return_val = yp_get_default_domain(&default_domain);
if (return_val != 0) {
printf("yp_get_default_domain returned %d\n", return_val);
fprintf(stderr, "%s\n", yperr_string(return_val));
return(-1);
}
return_val = yp_match(default_domain, "passwd.byname", "rita",
strlen("rita"), &value, &value_len);
if (return_val != 0) {
printf("yp_match returned %d\n", return_val);
fprintf(stderr, "%s\n", yperr_string(return_val));
return(-1);
}
printf(value);
return(0);
}
2. To process all keys/value pairs in the group.byname map for a given
domain:
struct ypall_callback incallback;
int cbfun();
int return_val;
incallback.foreach = cbfun;
incallback.data = 0;
return_val = yp_all(domname, "group.byname", &incallback);
if (return_val != 0) {
fprintf(stderr, "%s\n", yperr_string(return_val));
return;
}
6 Intergraph Corporation - 2/94
ypclnt(3) CLIX ypclnt(3)
cbfun(stat, key, keylen, val, vallen, data)
int stat, keylen, vallen;
char *key, *val, *data;
{
if (stat == YP_NOMORE)
return(0);
if (stat != YP_TRUE) {
fprintf(stderr, "%s\n", yperr_string(ypprot_err(stat)));
return(0);
}
/* process the key and value */
RETURN VALUES
All integer functions return a value of 0 if the requested operation is
successful. If the operation fails, one of the following errors is
returned.
#define YPERR_BADARGS 1 /* args to function are bad */
#define YPERR_RPC 2 /* RPC failure - domain unbound */
#define YPERR_DOMAIN 3 /* can't bind to server on this domain */
#define YPERR_MAP 4 /* no such map in server's domain */
#define YPERR_KEY 5 /* no such key in map */
#define YPERR_YPERR 6 /* internal yp server or client error */
#define YPERR_RESRC 7 /* resource allocation failure */
#define YPERR_NOMORE 8 /* no more records in map database */
#define YPERR_PMAP 9 /* can't communicate with portmapper */
#define YPERR_YPBIND 10 /* can't communicate with ypbind */
#define YPERR_YPSERV 11 /* can't communicate with ypserv */
#define YPERR_NODOM 12 /* local domain name not set */
RELATED INFORMATION
Commands: ypserv(8)
Files: ypfiles(4)
CLIX Programming Guide.
2/94 - Intergraph Corporation 7