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 May 4, 2019 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_maplist , 39.Nm yp_master , 40.Nm yp_match , 41.Nm yp_next , 42.Nm yp_order , 43.Nm yp_unbind , 44.Nm yperr_string , 45.Nm ypprot_err 46.Nd Interface to the YP subsystem 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In sys/types.h 51.In rpc/rpc.h 52.In rpcsvc/ypclnt.h 53.In 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_maplist "char *indomain" "struct ypmaplist **outmaplist" 64.Ft int 65.Fn yp_master "char *indomain" "char *inmap" "char **outname" 66.Ft int 67.Fn yp_match "char *indomain" "char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen" 68.Ft int 69.Fn yp_next "char *indomain" "char *inmap" "char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen" 70.Ft int 71.Fn yp_order "char *indomain" "char *inmap" "int *outorder" 72.Ft void 73.Fn yp_unbind "char *dom" 74.Ft char * 75.Fn yperr_string "int incode" 76.Ft int 77.Fn ypprot_err "unsigned int incode" 78.Sh DESCRIPTION 79The 80.Nm ypclnt 81suite provides an interface to the 82.Tn YP 83subsystem. 84For a general description of the 85.Tn YP 86subsystem, see 87.Xr yp 8 . 88.Pp 89For all functions, input values begin with 90.Li in 91and output values begin with 92.Li out . 93.Pp 94Any output values of type 95.Em char ** 96should be the addresses of uninitialized character pointers. 97These values will be reset to the null pointer (unless the address 98itself is the null pointer, in which case the error 99.Er YPERR_BADARGS 100will be returned). 101If necessary, 102memory will be allocated by the 103.Tn YP 104client routines using 105.Fn malloc , 106and the result will be stored in the appropriate output value. 107If the invocation of a 108.Tn YP 109client routine doesn't return an error, 110and an output value is not the null pointer, then this memory 111should be freed by the user when there is no additional need for 112the data stored there. 113For 114.Fa outkey 115and 116.Fa outval , 117two extra bytes of memory are allocated for a 118.Ql \en 119and 120.Ql \e0 , 121which are not 122reflected in the values of 123.Fa outkeylen 124or 125.Fa outvallen . 126.Pp 127All occurrences of 128.Fa indomain 129and 130.Fa inmap 131must be non-null, NUL-terminated strings. 132All input strings which also have 133a corresponding length parameter cannot be the null pointer unless the 134corresponding length value is zero. 135Such strings need not be NUL-terminated. 136.Pp 137All 138.Tn YP 139lookup calls (the functions 140.Fn yp_all , 141.Fn yp_first , 142.Fn yp_master , 143.Fn yp_match , 144.Fn yp_next , 145.Fn yp_order ) 146require a 147.Tn YP 148domain name and a 149.Tn YP 150map name. 151The default domain name may be obtained by calling 152.Fn yp_get_default_domain , 153and should thus be used before all other 154.Tn YP 155calls in a client program. 156The value it places 157.Fa domp 158is suitable for use as the 159.Fa indomain 160parameter to all subsequent 161.Tn YP 162calls. 163.Pp 164In order for 165.Tn YP 166lookup calls to succeed, the client process must be bound 167to a 168.Tn YP 169server process. 170The client process need not explicitly bind to 171the server, as it happens automatically whenever a lookup occurs. 172The function 173.Fn yp_bind 174is provided for a backup strategy, e.g. a local file, when a 175.Tn YP 176server process is not available. 177Each binding uses one socket descriptor on the client 178process, which may be explicitly freed using 179.Fn yp_unbind , 180which frees all per-process and per-node resources to bind the domain and 181marks the domain unbound. 182.Pp 183If, during a 184.Tn YP 185lookup, an RPC failure occurs, the domain used in the lookup 186is automatically marked unbound and the 187.Nm ypclnt 188layer retries the lookup as long as 189.Xr ypbind 8 190is running and either the client process cannot bind to a server for the domain 191specified in the lookup, or RPC requests to the 192.Tn YP 193server process fail. 194If an error is not RPC-related, one of the 195.Tn YP 196error codes described below 197is returned and control given back to the user code. 198.Pp 199The 200.Nm ypclnt 201suite provides the following functionality: 202.Bl -tag -width yp_match()xx 203.It Fn yp_match 204Provides the value associated with the given key. 205.It Fn yp_first 206Provides the first key-value pair from the given map in the named domain. 207.It Fn yp_next 208Provides the next key-value pair in the given map. 209To obtain the second pair, 210the 211.Fa inkey 212value should be the 213.Fa 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.Fa outkey 218value from the previous call to 219.Fn yp_next 220as the value for 221.Fa 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 order. 231The 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 until 236.Fn yp_next 237returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed 238exactly once, and if the entire procedure is repeated, the order will be 239the same. 240.Pp 241If the server is heavily loaded or the server fails for some reason, the 242domain being used may become unbound. 243If this happens, and the client process re-binds, the retrieval rules 244will break: some entries may be seen twice, and others not at all. 245For this reason, the function 246.Fn yp_all 247provides a better solution for reading all of the entries in a particular map. 248.It Fn yp_all 249This function provides a way to transfer an entire map from 250the server to the client process with a single request. 251This transfer uses TCP, unlike all other functions in the 252.Nm ypclnt 253suite, which use UDP. 254The entire transaction occurs in a single RPC request-response. 255The third argument to this function provides a way to supply 256the name of a function to process each key-value pair in the map. 257.Fn yp_all 258returns after the entire transaction is complete, or the 259.Fn foreach 260function decides that it does not want any more key-value pairs. 261The third argument to 262.Fn yp_all 263is: 264.Bd -literal -offset indent 265struct ypall_callback *incallback { 266 int (*foreach)(); 267 char *data; 268}; 269.Ed 270.Pp 271The 272.Em char *data 273argument is an opaque pointer for use by the callback function. 274The 275.Fn 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.Bd -literal -offset indent 281int foreach ( 282 int instatus, 283 unsigned long *inkey, 284 int inkeylen, 285 char *inval, 286 int invallen, 287 char *indata 288); 289.Ed 290.Pp 291Where: 292.Bl -tag -width "inkey, inval" 293.It Fa instatus 294Holds one of the return status values described in 295.In rpcsvc/yp_prot.h : 296see 297.Fn ypprot_err 298below for a function that will translate 299.Tn YP 300protocol errors into a 301.Nm ypclnt 302layer error code as described in 303.In rpcsvc/ypclnt.h . 304.It Fa inkey , inval 305The key and value arguments are somewhat different here than described 306above. 307In 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.Fn foreach 315function should do something useful with the contents of that memory during 316each iteration. 317If the key-value pairs are not terminated with either 318.Ql \en 319or 320.Ql \e0 321in the map, then they will not be terminated as such when given to the 322.Fn foreach 323function, either. 324.It Fa indata 325This is the contents of the 326.Fa incallback->data 327element of the callback structure. 328It is provided as a means to share state between the 329.Fn foreach 330function and the user code. 331Its use is completely optional: cast it to 332something useful or simply ignore it. 333.El 334.It Fn yp_order 335Returns the order number for a map. 336.It Fn yp_maplist 337Returns a singly-linked list of the names of all the maps available in the 338named domain. 339The second argument to 340.Fn yp_maplist 341is: 342.Bd -literal -offset indent 343struct ypmaplist { 344 char *map; 345 struct ypmaplist *next; 346}; 347.Ed 348.It Fn yp_master 349Returns the hostname for the machine on which the master 350.Tn YP 351server process for 352a map is running. 353.It Fn yperr_string 354Returns a pointer to a NUL-terminated error string that does not contain a 355.Ql \&. 356or 357.Ql \en . 358.It Fn ypprot_err 359Converts a 360.Tn YP 361protocol error code to a 362.Nm ypclnt 363error code suitable for 364.Fn yperr_string . 365.El 366.Sh RETURN VALUES 367All functions in the 368.Nm ypclnt 369suite which are of type 370.Em int 371return 0 upon success or one of the following error codes upon failure: 372.Bl -tag -width "YPERR_BADARGS " 373.It Bq Er YPERR_BADARGS 374The passed arguments to the function are invalid. 375.It Bq Er YPERR_BADDB 376The 377.Tn YP 378map that was polled is defective. 379.It Bq Er YPERR_DOMAIN 380Client process cannot bind to server on this 381.Tn YP 382domain. 383.It Bq Er YPERR_KEY 384The key passed does not exist. 385.It Bq Er YPERR_MAP 386There is no such map in the server's domain. 387.It Bq Er YPERR_DOM 388The local 389.Tn YP 390domain is not set. 391.It Bq Er YPERR_NOMORE 392There are no more records in the queried map. 393.It Bq Er YPERR_PMAP 394Cannot communicate with portmapper (see 395.Xr rpcbind 8 ) . 396.It Bq Er YPERR_RESRC 397A resource allocation failure occurred. 398.It Bq Er YPERR_RPC 399An RPC failure has occurred. 400The domain has been marked unbound. 401.It Bq Er YPERR_VERS 402Client/server version mismatch. 403If the server is running version 1 of the 404.Tn YP 405protocol, 406.Fn yp_all 407functionality does not exist. 408.It Bq Er YPERR_BIND 409Cannot communicate with 410.Xr ypbind 8 . 411.It Bq Er YPERR_YPERR 412An internal server or client error has occurred. 413.It Bq Er YPERR_YPSERV 414The client cannot communicate with the 415.Tn YP 416server process. 417.El 418.Sh SEE ALSO 419.Xr malloc 3 , 420.Xr yp 8 , 421.Xr ypbind 8 , 422.Xr ypserv 8 423.Sh AUTHORS 424.An Theo De Raadt 425