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