'\"macro stdmacro
.if n .pH g3n.ypclnt @(#)ypclnt	40.3 of 1/29/90
.\" Copyright 1989 AT&T
.\" @(#)ypclnt.3n 1.10 89/09/28 SMI;
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.nr X
.if \nX=0 .ds x} ypclnt 3N "" "\&"
.if \nX=1 .ds x} ypclnt 3N ""
.if \nX=2 .ds x} ypclnt 3N "" "\&"
.if \nX=3 .ds x} ypclnt "" "" "\&"
.TH \*(x}
.SH NAME
\f4ypclnt, yp_get_default_domain, yp_bind, yp_unbind, yp_match, yp_first, yp_next, yp_all, yp_order, yp_master, yperr_string, ypprot_err\fP \- YP client interface
.SH SYNOPSIS
.P
.ft 4
.nf
#include <rpcsvc/ypclnt.h>
#include <rpcsvc/yp_prot.h>
.fi
.ft R
.SH DESCRIPTION
.P
This package of functions provides an interface to the
\s-1YP\s0
network lookup service.
The package can be loaded from the standard library,
\f4/usr/lib/libnsl.{so,a}\fR.
Refer to
\f4ypfiles\fR(4)
and
\f4ypserv\fR(1M)
for an overview of the YP name
services, including the definitions of
\f2map\fR
and
\f2domain\fR,
and a description of the various servers, databases,
and commands that comprise the
\s-1YP\s0 name service.
.P
All input parameters names begin with
\f2in\fR.
Output parameters begin with
\f2out\fR.
Output parameters of type
\f4char **\fR
should be addresses of uninitialized character pointers.
Memory is allocated by the
\s-1YP\s0
client package using
\f4malloc\fR(3),
and may be freed if the user code has no continuing need for it.
For each
\f2outkey\fR
and
\f2outval\fR,
two extra bytes of memory are allocated at the end that contain
\s-1NEWLINE\s0
and
\s-1NULL\s0,
respectively, but these two bytes are not reflected in
\f2outkeylen\fR
or
\f2outvallen\fR.
\f2indomain\fR
and
\f2inmap\fR
strings must be non-\s-1NULL\s0 and
\s-1NULL\s0-terminated.
String parameters which are accompanied by a count parameter may
not be
\s-1NULL\s0,
but may point to
\s-1NULL\s0
strings, with the count parameter indicating this.
Counted strings need not be
\s-1NULL\s0-terminated.
.P
All functions in this package of type
\f2int\fR
return 0 if they succeed, and a failure code
(\f4\s-1YPERR\s0_\f2xxxx\fR)\fR
otherwise.
Failure codes are described under
\s-1DIAGNOSTICS\s0
below.
.SS Routines
.P
.ft 4
.nf
.sp .5
yp_bind (indomain);
char *indomain;
.fi
.ft R
.IP
To use the
\s-1YP\s0
name services, the client process must be \*(lqbound\*(rq to a
\s-1YP\s0
server that serves the appropriate domain using
\f4yp_bind(\|)\fR.
Binding need not be done explicitly by user code; this
is done automatically whenever a
\s-1YP\s0
lookup function is called.
\f4yp_bind(\|)\fR
can be called directly for processes
that make use of a backup strategy (for example,
a local file) in cases when
\s-1YP\s0
services are not available.
.P
.ft 4
.nf
.sp .5
void
yp_unbind (indomain)
char *indomain;
.fi
.ft R
.IP
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.
\f4yp_unbind(\|)\fR
is available at the client interface for processes that
explicitly manage their socket descriptors while accessing
multiple domains.
The call to
\f4yp_unbind(\|)\fR
make the domain
\f2unbound\fR,
and free all per-process and per-node resources used to bind
it.
.IP
If an
\s-1RPC\s0
failure results upon use of a binding, that domain will be
unbound automatically.  At that point, the
\f4ypclnt(\|)\fR
layer will retry
forever or until the operation succeeds, provided that
\f4ypbind\fR
is running, and either
.RS
.TP
\(bu
the client process cannot bind a server for the proper domain,
or
.TP
\(bu
\s-1RPC\s0
requests to the server fail.
.RE
.IP
If an error is not
\s-1RPC\s0-related,
or if
\f4ypbind\fR
is not running, or if a bound
\f4ypserv\fR
process returns any answer (success or failure),
the
\f4ypclnt\fR
layer will return control to the user code,
either with an error code,
or a success code and any results.
.br
.if t .ne 9
.P
.ft 4
.nf
.sp .5
yp_get_default_domain (outdomain);
char **outdomain;
.fi
.ft R
.IP
The
\s-1YP\s0
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 node's default domain by calling
\f4yp_get_default_domain(\|)\fR,
and use the returned
\f2outdomain\fR
as the
\f2indomain\fR
parameter to successive
\s-1YP\s0
name service calls.
.P
.ft 4
.nf
.sp .5
yp_match(indomain, inmap, inkey, inkeylen, outval, outvallen)
char *indomain;
char *inmap;
char *inkey;
int inkeylen;
char **outval;
int *outvallen;
.fi
.ft R
.IP
\f4yp_match(\|)\fR
returns the value associated with a passed key.  This key
must be exact; no pattern matching is available.
.P
.ft 4
.nf
.sp .5
yp_first(indomain, inmap, outkey, outkeylen, outval, outvallen)
char *indomain;
char *inmap;
char **outkey;
int *outkeylen;
char **outval;
int *outvallen;
.fi
.ft R
.IP
\f4yp_first(\|)\fR
returns the first key-value pair from the named map
in the named domain.
.P
.ft 4
.nf
.sp .5
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;
.fi
.ft R
.IP
\f4yp_next(\|)\fR
returns the next key-value pair in a named map.  The
\f2inkey\fR
parameter should be the
\f2outkey\fR
returned from an initial call to
\f4yp_first(\|)\fR
(to get the second key-value pair) or the one returned from the
\f2n\fRth
call to
\f4yp_next(\|)\fR
(to get the
\f2n\fRth
+ second key-value pair).
.IP
The concept of first (and, for that matter, of next) is particular
to the structure of the
\s-1YP\s0
map being processing; there is no relation in
retrieval order to either the lexical order within
any original (non-\s-1YP\s0 name service)
data base, or to any obvious numerical sorting order on the keys,
values, or key-value pairs.  The only ordering guarantee made is
that if the
\f4yp_first(\|)\fR
function is called on a particular map, and then the
\f4yp_next(\|)\fR
function is repeatedly called on the same map at the same server
until the call fails with a reason of
\f4\s-1YPERR_NOMORE\s0\fR,
every entry in the data base will be 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.
.br
.if t .ne 7
.IP
Under conditions of heavy server load or server failure, 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 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 next paragraph describes a better solution to enumerating all
entries in a map.
.P
.ft 4
.nf
.sp .5
yp_all(indomain, inmap, incallback);
char *indomain;
char *inmap;
struct ypall_callback *incallback;
.fi
.ft R
.IP
\f4yp_all(\|)\fR
provides a way to transfer an entire map
from server to client in a single request using
\s-1TCP\s0
(rather than
\s-1UDP\s0
as with other functions in this package).
The entire transaction take place as a single
\s-1RPC\s0
request and response. 
\f4yp_all(\|)\fR
can be used just like any other
\s-1YP\s0
name service procedure,
identify the map in the normal manner, and supply the name of a
function which will be called to process each key-value pair
within the map.  The call to
\f4yp_all(\|)\fR
returns only when the transaction is completed
(successfully or unsuccessfully), or the
\f4foreach\fR
function decides that it does not want to see
any more key-value pairs.
.IP
The third parameter to
\f4yp_all(\|)\fR
is
.RS 1i
.ft 4
.nf
struct ypall_callback *incallback {
int (*foreach)(\|);
char *data;
};
.fi
.ft R
.RE
The function
\f4foreach\fR
is called
.RS 1i
.ft 4
.nf
foreach(instatus, inkey, inkeylen, inval, invallen, indata);
int instatus;
char *inkey;
int inkeylen;
char *inval;
int invallen;
char *indata;
.fi
.ft R
.RE
.IP
The
\f2instatus\fR
parameter will hold one of the return status values defined in
\f4<rpcsvc/yp_prot.h\fR
\(em either
\f4\s-1YP_TRUE\s0\fR
or an error code. (See
\f4ypprot_err(\|)\fR,
below, for a function which converts a
\s-1YP\s0
name service
protocol error code to a
\f4ypclnt\fR
layer error code.)
.IP
The key and value parameters are somewhat different
than defined in the
synopsis section above. First, the memory pointed to by the
\f2inkey\fR
and
\f2inval\fR
parameters is private to the
\f4yp_all(\|)\fR
function, and is overwritten with the arrival
of each new key-value pair.
It is the responsibility of the
\f4foreach\fR
function to do something useful with the contents
of that memory, but it
does not own the memory itself.  Key and value objects
presented to the
\f4foreach\fR
function look exactly as they do in the server's map \(em if they
were not
\s-1NEWLINE\s0-terminated
or
\s-1NULL\s0-terminated
in the map, they will not be here either.
.IP
The
\f2indata\fR
parameter is the contents of the
\f4incallback->data\fR
element passed to
\f4yp_all(\|)\fR.
The
\f4data\fR
element of the callback structure may be used to share
state information between the
\f4foreach\fR
function and the mainline code.  Its use is optional,
and no part of the
\s-1YP\s0
client package inspects its contents \(em
cast it to something useful, or ignore it.
.IP
The
\f4foreach\fR
function is a Boolean.
It should return zero to
indicate that it wants to be called again for
further received key-value pairs, or non-zero to stop
the flow of key-value pairs. 
If
\f4foreach\fR
returns a non-zero value, it is not called again; the functional
value of
\f4yp_all(\|)\fR
is then 0.
.br
.if t .ne 8
.P
.ft 4
.nf
.sp .5
yp_order(indomain, inmap, outorder);
char *indomain;
char *inmap;
int *outorder;
.fi
.ft R
.IP
\f4yp_order(\|)\fR
returns the order number for a map.
.br
.if t .ne 7
.P
.ft 4
.nf
.sp .5
yp_master(indomain, inmap, outname);
char *indomain;
char *inmap;
char **outname;
.fi
.ft R
.IP
\f4yp_master(\|)\fR
returns the machine name of the master
\s-1YP\s0
server for a map.
.P
.ft 4
.nf
.sp .5
char *yperr_string(incode)
int incode;
.fi
.ft R
.IP
\f4yperr_string(\|)\fR
returns a pointer to an error message string that is
\s-1NULL\s0-terminated
but contains no period or
\s-1NEWLINE\s0.
.P
.ft 4
.nf
.sp .5
ypprot_err (incode)
unsigned int incode;
.fi
.ft R
.IP
\f4ypprot_err(\|)\fR
takes a
\s-1YP\s0
name service
protocol error code as input, and returns a ypclnt layer error
code, which may be used in turn as an input to
\f4yperr_string(\|)\fR.
.SH FILES
.PD 0
.TP 20
\f4/usr/lib/libyp.a\fR
.PD
.SH "SEE ALSO"
\f4ypserv\fR(1M),
\f4malloc\fR(3),
\f4ypupdate\fR(3N),
\f4ypfiles\fR(4)
.SH DIAGNOSTICS
.P
All integer functions return 0 if the
requested operation is successful,
or one of the following errors if the operation fails.
.RS
.TP 8
\f4#define \s-1YPERR_BADARGS\s0\fR
\f4"1	/* args to function are bad */"\fR
.TP
\f4#define \s-1YPERR_RPC\s0\fR
\f4"2	/* RPC failure \- domain has been unbound */"\fR
.TP
\f4#define \s-1YPERR_DOMAIN\s0\fR
\f4"3	/* can't bind to server on this domain */"\fR
.TP
\f4#define \s-1YPERR_MAP\s0\fR
\f4"4	/* no such map in server's domain */"\fR
.TP
\f4#define \s-1YPERR_KEY\s0\fR
\f4"5	/* no such key in map */"\fR
.TP
\f4#define \s-1YPERR_YPERR\s0\fR
\f4"6	/* internal yp server or client error */"\fR
.TP
\f4#define \s-1YPERR_RESRC\s0\fR
\f4"7	/* resource allocation failure */"\fR
.br
.ne 5
.TP
\f4#define \s-1YPERR_NOMORE\s0\fR
\f4"8	/* no more records in map database */"\fR
.TP
\f4#define \s-1YPERR_PMAP\s0\fR
\f4"9	/* can't communicate with rpcbinder */"\fR
.br
.ne 3
.TP
\f4#define \s-1YPERR_YPBIND\s0\fR
\f4"10	/* can't communicate with ypbind */"\fR
.br
.ne 3
.TP
\f4#define \s-1YPERR_YPSERV\s0\fR
\f4"11	/* can't communicate with ypserv */"\fR
.TP
\f4#define \s-1YPERR_NODOM\s0\fR
\f4"12	/* local domain name not set */"\fR
.TP
\f4#define	\s-1YPERR_BADDB\s0fR\fR
\f4"13	/* yp database is bad */"\fR
.TP
\f4#define	\s-1YPERR_VERS\s0fR\fR
\f4"14	/* yp version mismatch */"\fR
.TP
\f4#define	\s-1YPERR_ACCESS\s0\fR
\f4"15	/* access violation */"\fR
.TP
\f4#define	\s-1YPERR_BUSY\s0\fR
\f4"16	/* database busy */"\fR
.RE
