ypclnt(3C)

Requires Optional NFS Services Software

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

#include <rpcsvc/ypclnt.h>

#include <sys/types.h>
#include <rpc/rpc.h>
#include <rpcsvc/yp_prot.h>

int yp_all(
char *indomain,
char *inmap,
struct ypall_callback incallback
);

int yp_bind(char *indomain);

int yp_first(
char *indomain,
char *inmap,
char **outkey,
int *outkeylen,
char **outval,
int *outvallen
);

int yp_master(
char *indomain,
char *inmap,
char **outmaster
);

int yp_match(
char *indomain,
char *inmap,
char *inkey,
int inkeylen,
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_order(
char *indomain,
char *inmap,
unsigned long *outorder
);

void yp_unbind(char *indomain);

char *yperr_string(int incode);

int ypprot_err(unsigned int incode);

DESCRIPTION

These functions provide an interface to the Network Information Service (NIS) network lookup service. The package can be loaded from the library /lib/libc.a. 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(3X) 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 (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.

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.

To use the NIS services, the client process must be "bound" to a 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 descriptors 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 will be unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided that ypbind(1M) is running and either:

a) the client process cannot bind a server for the proper NIS domain, or

b) RPC requests to the server fail.

If an error is not RPC-related, ypbind(1M) is not running, or a bound ypserv(1M) process returns any answer (success or failure), the ypclnt layer returns control to the user code, either with an error code or a success code with 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 NIS domain.

The yp_next() function 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 + 1th 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 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. The yp_all() function 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 TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use yp_all() 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 yp_all() 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 yp_all() is:

struct ypall_callback *incallback {
int (*foreach)();
char *data;
};

The function foreach is called

foreach(instatus, inkey, inkeylen, inval, invallen,
indata);
int instatus;
char *inkey;
int inkeylen;
char *inval;
int invallen;
char *indata;

The instatus parameter holds 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 a NIS protocol error code to a ypclnt layer error code, as defined in <rpcsvc/ypclnt.h>).

The key and value parameters are somewhat different than 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 it is overwritten with the arrival of each new key-value pair. The foreach function should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the foreach function 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.

The indata parameter is the contents of the incallback−>data element passed to yp_all() The data element of the callback structure can 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. Cast it to something useful or ignore it as needed.

The foreach function is Boolean. It should return zero to indicate it should be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If foreach returns a non-zero 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 host name of the master NIS server for a map.

The yperr_string() function returns a pointer to an error message string that is null-terminated, but contains no period or newline.

The ypprot_err() function takes a NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to yperr_string()

EXTERNAL INFLUENCES

International Code Set Support

Single-byte character codes sets are supported.

RETURN VALUE

All functions in this package of type int return 0 if the requested operation is successful or one of the following errors if the operation fails.

[YPERR_BADARGS] args to function are bad

[YPERR_BADDB] NIS map is defective

[YPERR_DOMAIN] can’t bind to server on this NIS domain

[YPERR_KEY] no such key in map

[YPERR_MAP] no such map in server’s NIS domain

[YPERR_NODOM] local NIS domain name not set

[YPERR_NOMORE] no more records in map

[YPERR_PMAP] can’t communicate with portmap

[YPERR_RESRC] resource allocation failure

[YPERR_RPC] RPC failure − NIS domain has been unbound

[YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide yp_all() functionality

[YPERR_YPBIND] can’t communicate with ypbind

[YPERR_YPERR] internal NIS server or client error

[YPERR_YPSERV] can’t communicate with ypserv

AUTHOR

ypclnt was developed by Sun Microsystems, Inc.

Museum

Related Articles