1.\" 2.\" Copyright (c) 1994 Jason R. Thorpe 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. All advertising materials mentioning features or use of this software 14.\" must display the following acknowledgement: 15.\" This product includes software developed by Jason Thorpe. 16.\" 4. Neither the name of the author nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $Id: ypclnt.3,v 1.1 1994/10/28 23:03:02 deraadt Exp $ 33.\" 34.Dd October 26, 1994 35.Dt YPCLNT 3 36.Os 37.Sh NAME 38.Nm yp_all , 39.Nm yp_bind , 40.Nm yp_first , 41.Nm yp_get_default_domain , 42.Nm yp_master , 43.Nm yp_match , 44.Nm yp_next , 45.Nm yp_order , 46.Nm yp_unbind , 47.Nm yperr_string , 48.Nm ypprot_err 49.Nd Interface to the YP subsystem 50.Sh SYNOPSIS 51.Fd #include <sys/types.h> 52.Fd #include <rpcsvc/ypclnt.h> 53.Fd #include <rpcsvc/yp_prot.h> 54.Ft int 55.Fn yp_all "char *indomain" "char *inmap" "struct ypall_callback *incallback" 56.Ft int 57.Fn yp_bind "char *dom" 58.Ft int 59.Fn yp_first "char *indomain" "char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen" 60.Ft int 61.Fn yp_get_default_domain "char **domp" 62.Ft int 63.Fn yp_master "char *indomain" "char *inmap" "char **outname" 64.Ft int 65.Fn yp_match "char *indomain" "char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen" 66.Ft int 67.Fn yp_next "char *indomain" "char *inmap" "char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen" 68.Ft int 69.Fn yp_order "char *indomain" "char *inmap" "char *outorder" 70.Ft void 71.Fn yp_unbind "char *dom" 72.Ft char * 73.Fn yperr_string "int incode" 74.Ft int 75.Fn ypprot_err "unsigned int incode" 76.Sh DESCRIPTION 77The 78.Nm ypclnt 79suite provides an interface to the YP subsystem. For a general description 80of the YP subsystem, see 81.Xr yp 8 . 82.Pp 83For all functions, input values begin with 84.Pa in 85and output values begin with 86.Pa out . 87Any ouput values of type 88.Em char ** 89should be the addresses of uninitialized character pointers. Memory will be 90allocated by the YP client routines using 91.Fn malloc . 92This memory can later be freed by the user if there is no additional need for 93the data stored there. For 94.Pa outkey 95and 96.Pa outval , 97two extra bytes of memory are allocated for a 98.Ql \en 99and 100.Ql \e0 , 101which are not 102reflected in the values of 103.Pa outkeylen 104or 105.Pa outvallen . 106All occurrences of 107.Pa indomain 108and 109.Pa inmap 110must be non-null, null-terminated strings. All input strings which also have 111a corresponding length parameter cannot be null unless the corresponding 112length value is zero. Such strings need not be null-terminated. 113.Pp 114All YP lookup calls (the functions 115.Fn yp_all , 116.Fn yp_first , 117.Fn yp_master , 118.Fn yp_match , 119.Fn yp_next , 120.Fn yp_order ) 121require a YP domain name and a YP map name. The default domain name may be 122obtained by calling 123.Fn yp_get_default_domain , 124and should thus be used before all other YP calls in a client program. 125The value it places 126.Pa outdomain 127is suitable for use as the 128.Pa indomain 129parameter to all subsequent YP calls. 130.Pp 131In order for YP lookup calls to succeed, the client process must be bound 132to a YP server process. The client process need not explicitly bind to 133the server, as it happens automatically whenever a lookup occurs. 134The function 135.Fn yp_bind 136is provided for a backup strategy, e.g. a local file, when a YP server process 137is not available. Each binding uses one socket descriptor on the client 138process, which may be explicitly freed using 139.Fn yp_unbind , 140which frees all per-process and per-node resources to bind the domain and 141marks the domain unbound. 142.Pp 143If, during a YP lookup, an RPC failure occurs, the domain used in the lookup 144is automatically marked unbound and the 145.Nm ypclnt 146layer retries the lookup as long as 147.Xr ypbind 8 148is running and either the client process cannot bind to a server for the domain 149specified in the lookup, or RPC requests to the YP server process fail. 150If an error is not RPC-related, one of the YP error codes described below 151is returned and control given back to the user code. 152.Pp 153The 154.Nm ypclnt 155suite provides the following functionality: 156.Bl -tag -width Fn yp_match 157.It Fn yp_match 158Provides the value associated with the given key. 159.It Fn yp_first 160Provides the first key-value pair from the given map in the named domain. 161.It Fn yp_next 162Provides the next key-value pair in the given map. To obtain the second pair, 163the 164.Pa inkey 165value should be the 166.Pa outkey 167value provided by the initial call to 168.Fn yp_first . 169In the general case, the next key-value pair may be obtained by using the 170.Pa outkey 171value from the previous call to 172.Fn yp_next 173as the value for 174.Pa inkey . 175.Pp 176Of course, the notions of ``first'' and ``next'' are particular to the 177type of YP map being accessed, and thus there is no guarantee of lexical 178order. The only guarantees provided with 179.Fn yp_first 180and 181.Fn yp_next , 182providing that the same map on the same server is polled repeatedly 183until 184.Fn yp_next 185returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed 186exactly once, and if the entire procedure is repeated, the order will be 187the same. 188.Pp 189If the server is heaviliy loaded or the server fails for some reason, the 190domain being used may become unbound. If this happens, and the client process 191re-binds, the retrieval rules will break: some entries may be seen twice, and 192others not at all. For this reason, the function 193.Fn yp_all 194provides a better solution for reading all of the entries in a particular 195map. 196.It Fn yp_all 197This function provides a way to transfer an entire an entire map from 198the server to the client process with a single request. This transfer 199uses TCP, unlike all other functions in the 200.Nm ypclnt 201suite, which use UDP. The entire transaction occurs in a single RPC 202request-response. The third argument to this function provides a way 203to supply the name of a function to process each key-value pair in the 204map. 205.Fn Yp_all 206returns after the entire transaction is complete, or the 207.Pa foreach 208function decides that it does not want any more key-value pairs. The third 209argument to 210.Fn yp_all 211is: 212.Bd -literal -offset indent 213struct ypall_callback *incallback { 214 int (*foreach)(); 215 char *data; 216}; 217.Ed 218.Pp 219The 220.Em char *data 221argument is an opaque pointer for use by the callback function. The 222.Pa foreach 223function should return non-zero when it no longer wishes to process 224key-value pairs, at which time 225.Fn yp_all 226returns a value of 0, and is called with the following arguments: 227.Pp 228.Bd -literal -offset indent 229int foreach ( 230 int instatus; 231 char *inkey; 232 int inkeylen; 233 char *inval; 234 int invallen; 235 char *indata; 236); 237.Ed 238.Pp 239Where: 240.Bl -tag -width "inkey, inval" 241.It Fa instatus 242Holds one of the return status values described in 243.Nm <rpcsvc/yp_prot.h> : 244see 245.Fn ypprot_err 246below for a function that will translate YP protocol errors into a 247.Nm ypclnt 248layer error code as described in 249.Nm <rpcsvc/ypclnt.h> . 250.It Fa inkey, inval 251The key and value arguments are somewhat different here than described 252above. In this case, the memory pointed to by 253.Fa inkey 254and 255.Fa inval 256is private to 257.Fn yp_all , 258and is overwritten with each subsequent key-value pair, thus the 259.Pa foreach 260function should do something useful with the contents of that memory during 261each iteration. If the key-value pairs are not terminated with either 262.Ql \en 263or 264.Ql \e0 265in the map, then they will not be terminated as such when given to the 266.Pa foreach 267function, either. 268.It Fa indata 269This is the contents of the 270.Pa incallback->data 271element of the callback structure. It is provided as a means to share 272state between the 273.Pa foreach 274function and the user code. Its use is completely optional: cast it to 275something useful or simply ignore it. 276.El 277.It Fn yp_order 278Returns the order number for a map. 279.It Fn yp_master 280Returns the hostname for the machine on which the master YP server process for 281a map is running. 282.It Fn yperr_string 283Returns a pointer to a null-terminated error string that does not contain a 284.Ql \&. 285or 286.Ql \en . 287.It Fn ypprot_err 288Converts a YP protocol error code to a 289.Nm ypclnt 290error code suitable for 291.Fn yperr_string . 292.El 293.Sh RETURN VALUES 294All functions in the 295.Nm ypclnt 296suite which are of type 297.Em int 298return 0 upon success or one of the following error codes upon failure: 299.Bl -tag -width "YPERR_BADARGS " 300.It Bq Er YPERR_BADARGS 301The passed arguments to the function are invalid 302.It Bq Er YPERR_BADDB 303The YP map that was polled is defective. 304.It Bq Er YPERR_DOMAIN 305Client process cannot bind to server on this YP domain. 306.It Bq Er YPERR_KEY 307The key passed does not exist. 308.It Bq Er YPERR_MAP 309There is no such map in the server's domain. 310.It Bq Er YPERR_DOM 311The local YP domain is not set. 312.It Bq Er YPERR_NOMORE 313There are no more records in the queried map. 314.It Bq Er YPERR_PMAP 315Cannot communicate with portmap. 316.It Bq Er YPERR_RESRC 317A resource allocation failure occurred. 318.It Bq Er YPERR_RPC 319An RPC failure has occurred. The domain has been marked unbound. 320.It Bq Er YPERR_VERS 321Client/server version mismatch. If the server is running version 1 322of the YP protocol, 323.Fn yp_all 324functionality does not exist. 325.It Bq Er YPERR_BIND 326Cannot communicate with 327.Xr ypbind 8 . 328.It Bq Er YPERR_YPERR 329An internal server or client error has occurred. 330.It Bq Er YPERR_YPSERV 331The client cannot communicate with the YP server process. 332.El 333.Sh SEE ALSO 334.Xr malloc 3 , 335.Xr ypbind 8 , 336.Xr yp 8 337.Sh AUTHOR 338Theo De Raadt 339