nis.subproj/ypclnt.3

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