yp_all Subroutine

Purpose

Transfers all of the key-value pairs from the Network Information Services (NIS) server to the client as the entire map.

Library

C Library (libc.a)

Syntax

#include <rpcsvc/ypclnt.h>
#include <rpcsvc/yp_prot.h>

yp_all ( indomain,  inmap,  incallback)
char *indomain;
char *inmap;
struct ypall_CallBack *incallback {
int (* foreach) ();
char * data;
};

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

Description

The yp_all subroutine provides a way to transfer an entire map from the server to the client in a single request. The routine uses Transmission Control Protocol (TCP) rather than User Datagram Protocol (UDP) used by other NIS subroutines. This entire transaction takes place as a single Remote Procedure Call (RPC) request and response. The yp_all subroutine is used like any other NIS procedure, identifying a subroutine and map in the normal manner, and supplying a subroutine to process each key-value pair within the map.

The memory pointed to by the inkey and inval parameters is private to the yp_all subroutine. This memory is overwritten with each new key-value pair processed. The foreach function uses the contents of the memory but does not own the memory itself. Key and value objects presented to the foreach function look exactly as they do in the server's map. Objects not terminated by a new-line or null character in the server's map are not terminated by a new-line or null character in the client's map.

Note: The remote procedure call is returned to the yp_all subroutine only after the transaction is completed (successfully or unsuccessfully) or after the foreach function rejects any more key-value pairs.

Parameters

Item Description
data Specifies state information between the foreach function and the mainline code (see also the indata parameter).
indomain Points to the name of the domain used as input to the subroutine.
inmap Points to the name of the map used as input to the subroutine.
incallback Specifies the structure containing the user-defined foreach function, which is called for each key-value pair transferred.
instatus Specifies either a return status value of the form NIS_TRUE or an error code. The error codes are defined in the rpcsvc/yp_prot.h file.
inkey Points to the current key of the key-value pair as returned from the server's database.
inkeylen Returns the length, in bytes, of the inkey parameter.
inval Points to the current value of the key-value pair as returned from the server's database.
invallen Specifies the size of the value in bytes.
indata Specifies the contents of the incallback->data element passed to the yp_all subroutine. The data element shares state information between the foreach function and the mainline code. The indata parameter is optional because no part of the NIS client package inspects its contents.

Return Values

The foreach subroutine returns a value of 0 when it is ready to be called again for additional received key-value pairs. It returns a nonzero value to stop the flow of key-value pairs. If the foreach function returns a nonzero value, it is not called again, and the yp_all subroutine returns a value of 0.