diff --git a/lib/libypclnt/Makefile b/lib/libypclnt/Makefile index 857adf09003d..de237de07534 100644 --- a/lib/libypclnt/Makefile +++ b/lib/libypclnt/Makefile @@ -2,7 +2,6 @@ LIB= ypclnt SHLIB_MAJOR= 2 -MAN= ypclnt.3 SRCS= ypclnt_connect.c \ ypclnt_error.c \ ypclnt_free.c \ diff --git a/lib/libypclnt/ypclnt.3 b/lib/libypclnt/ypclnt.3 deleted file mode 100644 index 3241bfaf248c..000000000000 --- a/lib/libypclnt/ypclnt.3 +++ /dev/null @@ -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 -.Fd #include -.Fd #include -.Fd #include -.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