341 lines
10 KiB
Groff
341 lines
10 KiB
Groff
.\" $NetBSD: ypclnt.3,v 1.2 1995/02/27 13:00:48 cgd Exp $
|
|
.\"
|
|
.\"
|
|
.\" Copyright (c) 1994 Jason R. Thorpe
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by Jason Thorpe.
|
|
.\" 4. Neither the name of the author nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $NetBSD: ypclnt.3,v 1.2 1995/02/27 13:00:48 cgd Exp $
|
|
.\"
|
|
.Dd October 26, 1994
|
|
.Dt YPCLNT 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm yp_all ,
|
|
.Nm yp_bind ,
|
|
.Nm yp_first ,
|
|
.Nm yp_get_default_domain ,
|
|
.Nm yp_master ,
|
|
.Nm yp_match ,
|
|
.Nm yp_next ,
|
|
.Nm yp_order ,
|
|
.Nm yp_unbind ,
|
|
.Nm yperr_string ,
|
|
.Nm ypprot_err
|
|
.Nd Interface to the YP subsystem
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <rpcsvc/ypclnt.h>
|
|
.Fd #include <rpcsvc/yp_prot.h>
|
|
.Ft int
|
|
.Fn yp_all "char *indomain" "char *inmap" "struct ypall_callback *incallback"
|
|
.Ft int
|
|
.Fn yp_bind "char *dom"
|
|
.Ft int
|
|
.Fn yp_first "char *indomain" "char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
|
|
.Ft int
|
|
.Fn yp_get_default_domain "char **domp"
|
|
.Ft int
|
|
.Fn yp_master "char *indomain" "char *inmap" "char **outname"
|
|
.Ft int
|
|
.Fn yp_match "char *indomain" "char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen"
|
|
.Ft int
|
|
.Fn yp_next "char *indomain" "char *inmap" "char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
|
|
.Ft int
|
|
.Fn yp_order "char *indomain" "char *inmap" "char *outorder"
|
|
.Ft void
|
|
.Fn yp_unbind "char *dom"
|
|
.Ft char *
|
|
.Fn yperr_string "int incode"
|
|
.Ft int
|
|
.Fn ypprot_err "unsigned int incode"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm ypclnt
|
|
suite provides an interface to the YP subsystem. For a general description
|
|
of the YP subsystem, see
|
|
.Xr yp 8 .
|
|
.Pp
|
|
For all functions, input values begin with
|
|
.Pa in
|
|
and output values begin with
|
|
.Pa out .
|
|
Any ouput values of type
|
|
.Em char **
|
|
should be the addresses of uninitialized character pointers. Memory will be
|
|
allocated by the YP client routines using
|
|
.Fn malloc .
|
|
This memory can later be freed by the user if there is no additional need for
|
|
the data stored there. For
|
|
.Pa outkey
|
|
and
|
|
.Pa outval ,
|
|
two extra bytes of memory are allocated for a
|
|
.Ql \en
|
|
and
|
|
.Ql \e0 ,
|
|
which are not
|
|
reflected in the values of
|
|
.Pa outkeylen
|
|
or
|
|
.Pa outvallen .
|
|
All occurrences of
|
|
.Pa indomain
|
|
and
|
|
.Pa inmap
|
|
must be non-null, null-terminated strings. All input strings which also have
|
|
a corresponding length parameter cannot be null unless the corresponding
|
|
length value is zero. Such strings need not be null-terminated.
|
|
.Pp
|
|
All YP lookup calls (the functions
|
|
.Fn yp_all ,
|
|
.Fn yp_first ,
|
|
.Fn yp_master ,
|
|
.Fn yp_match ,
|
|
.Fn yp_next ,
|
|
.Fn yp_order )
|
|
require a YP domain name and a YP map name. The default domain name may be
|
|
obtained by calling
|
|
.Fn yp_get_default_domain ,
|
|
and should thus be used before all other YP calls in a client program.
|
|
The value it places
|
|
.Pa outdomain
|
|
is suitable for use as the
|
|
.Pa indomain
|
|
parameter to all subsequent YP calls.
|
|
.Pp
|
|
In order for YP lookup calls to succeed, the client process must be bound
|
|
to a YP server process. The client process need not explicitly bind to
|
|
the server, as it happens automatically whenever a lookup occurs.
|
|
The function
|
|
.Fn yp_bind
|
|
is provided for a backup strategy, e.g. a local file, when a YP server process
|
|
is not available. Each binding uses one socket descriptor on the client
|
|
process, which may be explicitly freed using
|
|
.Fn yp_unbind ,
|
|
which frees all per-process and per-node resources to bind the domain and
|
|
marks the domain unbound.
|
|
.Pp
|
|
If, during a YP lookup, an RPC failure occurs, the domain used in the lookup
|
|
is automatically marked unbound and the
|
|
.Nm ypclnt
|
|
layer retries the lookup as long as
|
|
.Xr ypbind 8
|
|
is running and either the client process cannot bind to a server for the domain
|
|
specified in the lookup, or RPC requests to the YP server process fail.
|
|
If an error is not RPC-related, one of the YP error codes described below
|
|
is returned and control given back to the user code.
|
|
.Pp
|
|
The
|
|
.Nm ypclnt
|
|
suite provides the following functionality:
|
|
.Bl -tag -width Fn yp_match
|
|
.It Fn yp_match
|
|
Provides the value associated with the given key.
|
|
.It Fn yp_first
|
|
Provides the first key-value pair from the given map in the named domain.
|
|
.It Fn yp_next
|
|
Provides the next key-value pair in the given map. To obtain the second pair,
|
|
the
|
|
.Pa inkey
|
|
value should be the
|
|
.Pa outkey
|
|
value provided by the initial call to
|
|
.Fn yp_first .
|
|
In the general case, the next key-value pair may be obtained by using the
|
|
.Pa outkey
|
|
value from the previous call to
|
|
.Fn yp_next
|
|
as the value for
|
|
.Pa inkey .
|
|
.Pp
|
|
Of course, the notions of ``first'' and ``next'' are particular to the
|
|
type of YP map being accessed, and thus there is no guarantee of lexical
|
|
order. The only guarantees provided with
|
|
.Fn yp_first
|
|
and
|
|
.Fn yp_next ,
|
|
providing that the same map on the same server is polled repeatedly
|
|
until
|
|
.Fn yp_next
|
|
returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed
|
|
exactly once, and if the entire procedure is repeated, the order will be
|
|
the same.
|
|
.Pp
|
|
If the server is heaviliy loaded or the server fails for some reason, the
|
|
domain being used may become unbound. If this happens, and the client process
|
|
re-binds, the retrieval rules will break: some entries may be seen twice, and
|
|
others not at all. For this reason, the function
|
|
.Fn yp_all
|
|
provides a better solution for reading all of the entries in a particular
|
|
map.
|
|
.It Fn yp_all
|
|
This function provides a way to transfer an entire an entire map from
|
|
the server to the client process with a single request. This transfer
|
|
uses TCP, unlike all other functions in the
|
|
.Nm ypclnt
|
|
suite, which use UDP. The entire transaction occurs in a single RPC
|
|
request-response. The third argument to this function provides a way
|
|
to supply the name of a function to process each key-value pair in the
|
|
map.
|
|
.Fn Yp_all
|
|
returns after the entire transaction is complete, or the
|
|
.Pa foreach
|
|
function decides that it does not want any more key-value pairs. The third
|
|
argument to
|
|
.Fn yp_all
|
|
is:
|
|
.Bd -literal -offset indent
|
|
struct ypall_callback *incallback {
|
|
int (*foreach)();
|
|
char *data;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Em char *data
|
|
argument is an opaque pointer for use by the callback function. The
|
|
.Pa foreach
|
|
function should return non-zero when it no longer wishes to process
|
|
key-value pairs, at which time
|
|
.Fn yp_all
|
|
returns a value of 0, and is called with the following arguments:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
int foreach (
|
|
int instatus;
|
|
char *inkey;
|
|
int inkeylen;
|
|
char *inval;
|
|
int invallen;
|
|
char *indata;
|
|
);
|
|
.Ed
|
|
.Pp
|
|
Where:
|
|
.Bl -tag -width "inkey, inval"
|
|
.It Fa instatus
|
|
Holds one of the return status values described in
|
|
.Nm <rpcsvc/yp_prot.h> :
|
|
see
|
|
.Fn ypprot_err
|
|
below for a function that will translate YP protocol errors into a
|
|
.Nm ypclnt
|
|
layer error code as described in
|
|
.Nm <rpcsvc/ypclnt.h> .
|
|
.It Fa inkey, inval
|
|
The key and value arguments are somewhat different here than described
|
|
above. In this case, the memory pointed to by
|
|
.Fa inkey
|
|
and
|
|
.Fa inval
|
|
is private to
|
|
.Fn yp_all ,
|
|
and is overwritten with each subsequent key-value pair, thus the
|
|
.Pa foreach
|
|
function should do something useful with the contents of that memory during
|
|
each iteration. If the key-value pairs are not terminated with either
|
|
.Ql \en
|
|
or
|
|
.Ql \e0
|
|
in the map, then they will not be terminated as such when given to the
|
|
.Pa foreach
|
|
function, either.
|
|
.It Fa indata
|
|
This is the contents of the
|
|
.Pa incallback->data
|
|
element of the callback structure. It is provided as a means to share
|
|
state between the
|
|
.Pa foreach
|
|
function and the user code. Its use is completely optional: cast it to
|
|
something useful or simply ignore it.
|
|
.El
|
|
.It Fn yp_order
|
|
Returns the order number for a map.
|
|
.It Fn yp_master
|
|
Returns the hostname for the machine on which the master YP server process for
|
|
a map is running.
|
|
.It Fn yperr_string
|
|
Returns a pointer to a null-terminated error string that does not contain a
|
|
.Ql \&.
|
|
or
|
|
.Ql \en .
|
|
.It Fn ypprot_err
|
|
Converts a YP protocol error code to a
|
|
.Nm ypclnt
|
|
error code suitable for
|
|
.Fn yperr_string .
|
|
.El
|
|
.Sh RETURN VALUES
|
|
All functions in the
|
|
.Nm ypclnt
|
|
suite which are of type
|
|
.Em int
|
|
return 0 upon success or one of the following error codes upon failure:
|
|
.Bl -tag -width "YPERR_BADARGS "
|
|
.It Bq Er YPERR_BADARGS
|
|
The passed arguments to the function are invalid
|
|
.It Bq Er YPERR_BADDB
|
|
The YP map that was polled is defective.
|
|
.It Bq Er YPERR_DOMAIN
|
|
Client process cannot bind to server on this YP domain.
|
|
.It Bq Er YPERR_KEY
|
|
The key passed does not exist.
|
|
.It Bq Er YPERR_MAP
|
|
There is no such map in the server's domain.
|
|
.It Bq Er YPERR_DOM
|
|
The local YP domain is not set.
|
|
.It Bq Er YPERR_NOMORE
|
|
There are no more records in the queried map.
|
|
.It Bq Er YPERR_PMAP
|
|
Cannot communicate with portmap.
|
|
.It Bq Er YPERR_RESRC
|
|
A resource allocation failure occurred.
|
|
.It Bq Er YPERR_RPC
|
|
An RPC failure has occurred. The domain has been marked unbound.
|
|
.It Bq Er YPERR_VERS
|
|
Client/server version mismatch. If the server is running version 1
|
|
of the YP protocol,
|
|
.Fn yp_all
|
|
functionality does not exist.
|
|
.It Bq Er YPERR_BIND
|
|
Cannot communicate with
|
|
.Xr ypbind 8 .
|
|
.It Bq Er YPERR_YPERR
|
|
An internal server or client error has occurred.
|
|
.It Bq Er YPERR_YPSERV
|
|
The client cannot communicate with the YP server process.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr malloc 3 ,
|
|
.Xr ypbind 8 ,
|
|
.Xr yp 8
|
|
.Sh AUTHOR
|
|
Theo De Raadt
|