mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-03 09:00:21 +00:00
Back out my previous commit to this area, there are differences between
our implementation and OpenBSD's. Requested by: des
This commit is contained in:
Tom Rhodes
parent
a6c4457396
commit
98cea79298
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=168040
@ -2,7 +2,6 @@
|
||||
|
||||
LIB= ypclnt
|
||||
SHLIB_MAJOR= 2
|
||||
MAN= ypclnt.3
|
||||
SRCS= ypclnt_connect.c \
|
||||
ypclnt_error.c \
|
||||
ypclnt_free.c \
|
||||
|
||||
@ -1,362 +0,0 @@
|
||||
.\" $OpenBSD: ypclnt.3,v 1.16 2003/07/07 15:46:37 jmc Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" This code is derived from software contributed to The NetBSD Foundation
|
||||
.\" by Jason R. Thorpe.
|
||||
.\"
|
||||
.\" 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 the NetBSD
|
||||
.\" Foundation, Inc. and its contributors.
|
||||
.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
||||
.\" ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.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 <rpc/rpc.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" "int *outorder"
|
||||
.Ft void
|
||||
.Fn yp_unbind "char *dom"
|
||||
.Ft const 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
|
||||
.Ar in
|
||||
and output values begin with
|
||||
.Ar out .
|
||||
Any output values of type
|
||||
.Ar 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
|
||||
.Ar outkey
|
||||
and
|
||||
.Ar outval ,
|
||||
two extra bytes of memory are allocated for a
|
||||
.Ql \en
|
||||
and
|
||||
.Ql \e0 ,
|
||||
which are not
|
||||
reflected in the values of
|
||||
.Ar outkeylen
|
||||
or
|
||||
.Ar outvallen .
|
||||
All occurrences of
|
||||
.Ar indomain
|
||||
and
|
||||
.Ar inmap
|
||||
must be non-null, NUL-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 NUL-terminated.
|
||||
.Pp
|
||||
All YP lookup calls (the functions
|
||||
.Fn yp_all ,
|
||||
.Fn yp_first ,
|
||||
.Fn yp_master ,
|
||||
.Fn yp_match ,
|
||||
.Fn yp_next ,
|
||||
and
|
||||
.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
|
||||
.Ar outdomain
|
||||
is suitable for use as the
|
||||
.Ar 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 "yperr_string()"
|
||||
.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
|
||||
.Ar 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
|
||||
.Ar outkey
|
||||
value from the previous call to
|
||||
.Fn yp_next
|
||||
as the value for
|
||||
.Ar inkey .
|
||||
.Pp
|
||||
Of course, the notions of
|
||||
.Dq first
|
||||
and
|
||||
.Dq 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 heavily 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 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
|
||||
.Fn 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
|
||||
.Fn 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:
|
||||
.Bd -literal -offset indent
|
||||
int foreach (
|
||||
int instatus,
|
||||
char *inkey,
|
||||
int inkeylen,
|
||||
char *inval,
|
||||
int invallen,
|
||||
char *indata
|
||||
);
|
||||
.Ed
|
||||
.Pp
|
||||
Where:
|
||||
.Bl -tag -width "It Ar inkey, inval"
|
||||
.It Fa instatus
|
||||
Holds one of the return status values described in
|
||||
.Aq Pa 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
|
||||
.Aq Pa rpcsvc/ypclnt.h .
|
||||
.It Ar inkey, inval
|
||||
The key and value arguments are somewhat different here than described
|
||||
above.
|
||||
In this case, the memory pointed to by
|
||||
.Ar inkey
|
||||
and
|
||||
.Ar inval
|
||||
is private to
|
||||
.Fn yp_all ,
|
||||
and is overwritten with each subsequent key-value pair; therefore, the
|
||||
.Fn 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
|
||||
.Fn foreach
|
||||
function, either.
|
||||
.It Ar 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
|
||||
.Fn 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 NUL-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 yp 8 ,
|
||||
.Xr ypbind 8 ,
|
||||
.Xr ypserv 8
|
||||
.Sh AUTHORS
|
||||
Theo De Raadt
|
||||
Loading…
Reference in New Issue
Block a user