yp_next Subroutine

Purpose

Returns each subsequent value it finds in the named Network Information Services (NIS) map until it reaches the end of the list.

Library

C Library (libc.a)

Syntax

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

yp_next (indomain, inmap, inkey, inkeylen, outkey, outkeylen, outval, outvallen)
char * indomain;
char * inmap;
char * inkey;
int  inkeylen;
char ** outkey;
int * outkeylen;
char ** outval;
int * outvallen;

Description

The yp_next subroutine returns each subsequent value it finds in the named NIS map until it reaches the end of the list.

The yp_next subroutine must be preceded by an initial yp_first subroutine. Use the outkey parameter value returned from the initial yp_first subroutine as the value of the inkey parameter for the yp_next subroutine. This will return the second key-value pair associated with the map. To show every entry in the NIS map, the yp_first subroutine is called with the yp_next subroutine called repeatedly. Each time the yp_next subroutine returns a key-value, use it as the inkey parameter for the next call.

The concepts of first and next depend on the structure of the NIS map being processed. The routines do not retrieve the information in a specific order, such as the lexical order from the original, non-NIS database information files or the numerical sorting order of the keys, values, or key-value pairs. If the yp_first subroutine is called on a specific map with the yp_next subroutine called repeatedly until the process returns a YPERR_NOMORE message, every entry in the NIS map is seen once. If the same sequence of operations is performed on the same map at the same server, the entries are seen in the same order.

Note: If a server operates under a heavy load or fails, the domain can become unbound and then bound again while a client is running. If it binds itself to a different server, entries may be seen twice or not at all. The domain rebinds itself to protect the enumeration process from being interrupted before it completes. Avoid this situation by returning all of the keys and values with the yp_all subroutine.

Parameters

Item Description
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.
inkey Points to the key that is used as input to the subroutine.
inkeylen Returns the length, in bytes, of the inkey parameter.
outkey Specifies the address of the uninitialized string pointer where the first key is returned. Memory is allocated by the NIS client using the malloc subroutine, and may be freed by the application.
outkeylen Returns the length, in bytes, of the outkey parameter.
outval Specifies the address of the uninitialized string pointer where the values associated with the key are returned. Memory is allocated by the NIS client using the malloc subroutine, and may be freed by the application.
outvallen Returns the length, in bytes, of the outval parameter.

Return Values

Upon successful completion, this routine returns a value of 0. If unsuccessful, it returns one of the error codes described in the rpcsvc/yp_prot.h file.