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