lib/libc/yp/ypclnt.3

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