man page from Jason Thorpe
This commit is contained in:
parent
429c7771d3
commit
ce0ad41a78
|
@ -0,0 +1,338 @@
|
|||
.\"
|
||||
.\" 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.
|
||||
.\"
|
||||
.\" $Id: ypclnt.3,v 1.1 1994/10/28 23:03:02 deraadt 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
|
Loading…
Reference in New Issue