diff options
Diffstat (limited to 'lib/libypclnt')
| -rw-r--r-- | lib/libypclnt/ypclnt.3 | 362 |
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 |
