| blob | d3fe5859892331facc7ebb24dba2df99d7077922 |
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
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