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