Add a ypclnt.3 manual page referenced by various other YP based manual pages.

PR:		108980
Obtained from:	OpenBSD (minimal changes for mdoc(7) style)

1 files changed, 362 insertions, 0 deletions

diff --git a/lib/libypclnt/ypclnt.3 b/lib/libypclnt/ypclnt.3
new file mode 100644
index 0000000..3241bfa
--- /dev/null
+++ b/lib/libypclnt/ypclnt.3
@@ -0,0 +1,362 @@
+.\"	$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