1.\" $NetBSD: ypclnt.3,v 1.20 2002/10/01 19:03:15 wiz 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. 88For a general description of 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. 136All input strings which also have 137a corresponding length parameter cannot be the null pointer unless the 138corresponding length value is zero. 139Such strings need not be NUL-terminated. 140.Pp 141All 142.Tn YP 143lookup calls (the functions 144.Fn yp_all , 145.Fn yp_first , 146.Fn yp_master , 147.Fn yp_match , 148.Fn yp_next , 149.Fn yp_order ) 150require a 151.Tn YP 152domain name and a 153.Tn YP 154map name. 155The default domain name may be obtained by calling 156.Fn yp_get_default_domain , 157and should thus be used before all other 158.Tn YP 159calls in a client program. 160The value it places 161.Pa outdomain 162is suitable for use as the 163.Pa indomain 164parameter to all subsequent 165.Tn YP 166calls. 167.Pp 168In order for 169.Tn YP 170lookup calls to succeed, the client process must be bound 171to a 172.Tn YP 173server process. 174The client process need not explicitly bind to 175the server, as it happens automatically whenever a lookup occurs. 176The function 177.Fn yp_bind 178is provided for a backup strategy, e.g. a local file, when a 179.Tn YP 180server process is not available. 181Each binding uses one socket descriptor on the client 182process, which may be explicitly freed using 183.Fn yp_unbind , 184which frees all per-process and per-node resources to bind the domain and 185marks the domain unbound. 186.Pp 187If, during a 188.Tn YP 189lookup, an RPC failure occurs, the domain used in the lookup 190is automatically marked unbound and the 191.Nm ypclnt 192layer retries the lookup as long as 193.Xr ypbind 8 194is running and either the client process cannot bind to a server for the domain 195specified in the lookup, or RPC requests to the 196.Tn YP 197server process fail. 198If an error is not RPC-related, one of the 199.Tn YP 200error codes described below 201is returned and control given back to the user code. 202.Pp 203The 204.Nm ypclnt 205suite provides the following functionality: 206.Bl -tag -width yp_match()xx 207.It Fn yp_match 208Provides the value associated with the given key. 209.It Fn yp_first 210Provides the first key-value pair from the given map in the named domain. 211.It Fn yp_next 212Provides the next key-value pair in the given map. 213To obtain the second pair, 214the 215.Pa inkey 216value should be the 217.Pa outkey 218value provided by the initial call to 219.Fn yp_first . 220In the general case, the next key-value pair may be obtained by using the 221.Pa outkey 222value from the previous call to 223.Fn yp_next 224as the value for 225.Pa inkey . 226.Pp 227Of course, the notions of 228.Dq first 229and 230.Dq next 231are particular to the 232type of 233.Tn YP 234map being accessed, and thus there is no guarantee of lexical order. 235The only guarantees provided with 236.Fn yp_first 237and 238.Fn yp_next , 239providing that the same map on the same server is polled repeatedly until 240.Fn yp_next 241returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed 242exactly once, and if the entire procedure is repeated, the order will be 243the same. 244.Pp 245If the server is heavily loaded or the server fails for some reason, the 246domain being used may become unbound. 247If this happens, and the client process re-binds, the retrieval rules 248will break: some entries may be seen twice, and others not at all. 249For this reason, the function 250.Fn yp_all 251provides a better solution for reading all of the entries in a particular map. 252.It Fn yp_all 253This function provides a way to transfer an entire map from 254the server to the client process with a single request. 255This transfer uses TCP, unlike all other functions in the 256.Nm ypclnt 257suite, which use UDP. 258The entire transaction occurs in a single RPC request-response. 259The third argument to this function provides a way to supply 260the name of a function to process each key-value pair in the map. 261.Fn yp_all 262returns after the entire transaction is complete, or the 263.Pa foreach 264function decides that it does not want any more key-value pairs. 265The third argument to 266.Fn yp_all 267is: 268.Bd -literal -offset indent 269struct ypall_callback *incallback { 270 int (*foreach)(); 271 char *data; 272}; 273.Ed 274.Pp 275The 276.Em char *data 277argument is an opaque pointer for use by the callback function. 278The 279.Pa foreach 280function should return non-zero when it no longer wishes to process 281key-value pairs, at which time 282.Fn yp_all 283returns a value of 0, and is called with the following arguments: 284.Pp 285.Bd -literal -offset indent 286int foreach ( 287 int instatus, 288 char *inkey, 289 int inkeylen, 290 char *inval, 291 int invallen, 292 char *indata 293); 294.Ed 295.Pp 296Where: 297.Bl -tag -width "inkey, inval" 298.It Fa instatus 299Holds one of the return status values described in 300.Nm \*[Lt]rpcsvc/yp_prot.h\*[Gt] : 301see 302.Fn ypprot_err 303below for a function that will translate 304.Tn YP 305protocol errors into a 306.Nm ypclnt 307layer error code as described in 308.Nm \*[Lt]rpcsvc/ypclnt.h\*[Gt] . 309.It Fa inkey, inval 310The key and value arguments are somewhat different here than described 311above. 312In this case, the memory pointed to by 313.Fa inkey 314and 315.Fa inval 316is private to 317.Fn yp_all , 318and is overwritten with each subsequent key-value pair, thus the 319.Pa foreach 320function should do something useful with the contents of that memory during 321each iteration. 322If the key-value pairs are not terminated with either 323.Ql \en 324or 325.Ql \e0 326in the map, then they will not be terminated as such when given to the 327.Pa foreach 328function, either. 329.It Fa indata 330This is the contents of the 331.Pa incallback-\*[Gt]data 332element of the callback structure. 333It is provided as a means to share state between the 334.Pa foreach 335function and the user code. 336Its use is completely optional: cast it to 337something useful or simply ignore it. 338.El 339.It Fn yp_order 340Returns the order number for a map. 341.It Fn yp_master 342Returns the hostname for the machine on which the master 343.Tn YP 344server process for 345a map is running. 346.It Fn yperr_string 347Returns a pointer to a NUL-terminated error string that does not contain a 348.Ql \&. 349or 350.Ql \en . 351.It Fn ypprot_err 352Converts a 353.Tn YP 354protocol error code to a 355.Nm ypclnt 356error code suitable for 357.Fn yperr_string . 358.El 359.Sh RETURN VALUES 360All functions in the 361.Nm ypclnt 362suite which are of type 363.Em int 364return 0 upon success or one of the following error codes upon failure: 365.Bl -tag -width "YPERR_BADARGS " 366.It Bq Er YPERR_BADARGS 367The passed arguments to the function are invalid 368.It Bq Er YPERR_BADDB 369The 370.Tn YP 371map that was polled is defective. 372.It Bq Er YPERR_DOMAIN 373Client process cannot bind to server on this 374.Tn YP 375domain. 376.It Bq Er YPERR_KEY 377The key passed does not exist. 378.It Bq Er YPERR_MAP 379There is no such map in the server's domain. 380.It Bq Er YPERR_DOM 381The local 382.Tn YP 383domain is not set. 384.It Bq Er YPERR_NOMORE 385There are no more records in the queried map. 386.It Bq Er YPERR_PMAP 387Cannot communicate with portmapper (see 388.Xr rpcbind 8 ) . 389.It Bq Er YPERR_RESRC 390A resource allocation failure occurred. 391.It Bq Er YPERR_RPC 392An RPC failure has occurred. 393The domain has been marked unbound. 394.It Bq Er YPERR_VERS 395Client/server version mismatch. 396If the server is running version 1 of the 397.Tn YP 398protocol, 399.Fn yp_all 400functionality does not exist. 401.It Bq Er YPERR_BIND 402Cannot communicate with 403.Xr ypbind 8 . 404.It Bq Er YPERR_YPERR 405An internal server or client error has occurred. 406.It Bq Er YPERR_YPSERV 407The client cannot communicate with the 408.Tn YP 409server process. 410.El 411.Sh SEE ALSO 412.Xr malloc 3 , 413.Xr yp 8 , 414.Xr ypbind 8 , 415.Xr ypserv 8 416.Sh AUTHORS 417.An Theo De Raadt 418