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