Annotation of src/lib/libc/yp/ypclnt.3, Revision 1.23
1.23 ! martin 1: .\" $NetBSD: ypclnt.3,v 1.22 2003/05/10 12:14:27 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: .\"
1.5 thorpej 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
1.10 jtc 21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
1.9 jtc 22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1.5 thorpej 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.
1.1 deraadt 29: .\"
1.6 lukem 30: .Dd May 21, 1997
1.1 deraadt 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
1.12 perry 46: .Sh LIBRARY
47: .Lb libc
1.1 deraadt 48: .Sh SYNOPSIS
1.21 wiz 49: .In sys/types.h
50: .In rpc/rpc.h
51: .In rpcsvc/ypclnt.h
52: .In rpcsvc/yp_prot.h
1.1 deraadt 53: .Ft int
1.6 lukem 54: .Fn yp_all "const char *indomain" "const char *inmap" "struct ypall_callback *incallback"
1.1 deraadt 55: .Ft int
1.6 lukem 56: .Fn yp_bind "const char *dom"
1.1 deraadt 57: .Ft int
1.6 lukem 58: .Fn yp_first "const char *indomain" "const char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
1.1 deraadt 59: .Ft int
1.8 lukem 60: .Fn yp_get_default_domain "char **outdomain"
1.1 deraadt 61: .Ft int
1.6 lukem 62: .Fn yp_master "const char *indomain" "const char *inmap" "char **outname"
1.1 deraadt 63: .Ft int
1.6 lukem 64: .Fn yp_match "const char *indomain" "const char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen"
1.1 deraadt 65: .Ft int
1.6 lukem 66: .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 67: .Ft int
1.6 lukem 68: .Fn yp_order "const char *indomain" "const char *inmap" "int *outorder"
1.1 deraadt 69: .Ft void
1.6 lukem 70: .Fn yp_unbind "const char *dom"
1.1 deraadt 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
1.11 lukem 78: suite provides an interface to the
79: .Tn YP
1.20 wiz 80: subsystem.
81: For a general description of the
1.11 lukem 82: .Tn YP
83: subsystem, see
1.1 deraadt 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 .
1.6 lukem 90: .Pp
1.4 thorpej 91: Any output values of type
1.1 deraadt 92: .Em char **
1.6 lukem 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,
1.11 lukem 99: memory will be allocated by the
100: .Tn YP
101: client routines using
1.6 lukem 102: .Fn malloc ,
103: and the result will be stored in the appropriate output value.
1.11 lukem 104: If the invocation of a
105: .Tn YP
106: client routine doesn't return an error,
1.7 lukem 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.
1.6 lukem 110: For
1.1 deraadt 111: .Pa outkey
112: and
113: .Pa 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: .Pa outkeylen
121: or
122: .Pa outvallen .
1.6 lukem 123: .Pp
1.1 deraadt 124: All occurrences of
125: .Pa indomain
126: and
127: .Pa inmap
1.20 wiz 128: must be non-null, NUL-terminated strings.
129: All input strings which also have
1.6 lukem 130: a corresponding length parameter cannot be the null pointer unless the
1.20 wiz 131: corresponding length value is zero.
132: Such strings need not be NUL-terminated.
1.1 deraadt 133: .Pp
1.11 lukem 134: All
135: .Tn YP
136: lookup calls (the functions
1.1 deraadt 137: .Fn yp_all ,
138: .Fn yp_first ,
139: .Fn yp_master ,
140: .Fn yp_match ,
141: .Fn yp_next ,
142: .Fn yp_order )
1.11 lukem 143: require a
144: .Tn YP
145: domain name and a
146: .Tn YP
1.20 wiz 147: map name.
148: The default domain name may be obtained by calling
1.1 deraadt 149: .Fn yp_get_default_domain ,
1.11 lukem 150: and should thus be used before all other
151: .Tn YP
152: calls in a client program.
1.1 deraadt 153: The value it places
154: .Pa outdomain
155: is suitable for use as the
156: .Pa indomain
1.11 lukem 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
1.20 wiz 166: server process.
167: The client process need not explicitly bind to
1.1 deraadt 168: the server, as it happens automatically whenever a lookup occurs.
169: The function
170: .Fn yp_bind
1.11 lukem 171: is provided for a backup strategy, e.g. a local file, when a
172: .Tn YP
1.20 wiz 173: server process is not available.
174: Each binding uses one socket descriptor on the client
1.1 deraadt 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
1.11 lukem 180: If, during a
181: .Tn YP
182: lookup, an RPC failure occurs, the domain used in the lookup
1.1 deraadt 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
1.11 lukem 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
1.1 deraadt 194: is returned and control given back to the user code.
195: .Pp
196: The
197: .Nm ypclnt
198: suite provides the following functionality:
1.17 ross 199: .Bl -tag -width yp_match()xx
1.1 deraadt 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
1.20 wiz 205: Provides the next key-value pair in the given map.
206: To obtain the second pair,
1.1 deraadt 207: the
208: .Pa inkey
209: value should be the
210: .Pa 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: .Pa outkey
215: value from the previous call to
216: .Fn yp_next
217: as the value for
218: .Pa inkey .
219: .Pp
1.6 lukem 220: Of course, the notions of
221: .Dq first
222: and
223: .Dq next
224: are particular to the
1.11 lukem 225: type of
226: .Tn YP
1.20 wiz 227: map being accessed, and thus there is no guarantee of lexical order.
228: The only guarantees provided with
1.1 deraadt 229: .Fn yp_first
230: and
231: .Fn yp_next ,
1.20 wiz 232: providing that the same map on the same server is polled repeatedly until
1.1 deraadt 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
1.19 wiz 238: If the server is heavily loaded or the server fails for some reason, the
1.20 wiz 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
1.1 deraadt 243: .Fn yp_all
1.20 wiz 244: provides a better solution for reading all of the entries in a particular map.
1.1 deraadt 245: .It Fn yp_all
1.6 lukem 246: This function provides a way to transfer an entire map from
1.20 wiz 247: the server to the client process with a single request.
248: This transfer uses TCP, unlike all other functions in the
1.1 deraadt 249: .Nm ypclnt
1.20 wiz 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.
1.6 lukem 254: .Fn yp_all
1.1 deraadt 255: returns after the entire transaction is complete, or the
256: .Pa foreach
1.20 wiz 257: function decides that it does not want any more key-value pairs.
258: The third argument to
1.1 deraadt 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
1.20 wiz 270: argument is an opaque pointer for use by the callback function.
271: The
1.1 deraadt 272: .Pa 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: .Pp
278: .Bd -literal -offset indent
279: int foreach (
1.3 thorpej 280: int instatus,
281: char *inkey,
282: int inkeylen,
283: char *inval,
284: int invallen,
285: char *indata
1.1 deraadt 286: );
287: .Ed
288: .Pp
289: Where:
290: .Bl -tag -width "inkey, inval"
291: .It Fa instatus
292: Holds one of the return status values described in
1.22 wiz 293: .Aq Pa rpcsvc/yp_prot.h :
1.1 deraadt 294: see
295: .Fn ypprot_err
1.11 lukem 296: below for a function that will translate
297: .Tn YP
298: protocol errors into a
1.1 deraadt 299: .Nm ypclnt
300: layer error code as described in
1.22 wiz 301: .Aq Pa rpcsvc/ypclnt.h .
1.1 deraadt 302: .It Fa inkey, inval
303: The key and value arguments are somewhat different here than described
1.20 wiz 304: above.
305: In this case, the memory pointed to by
1.1 deraadt 306: .Fa inkey
307: and
308: .Fa inval
309: is private to
310: .Fn yp_all ,
311: and is overwritten with each subsequent key-value pair, thus the
312: .Pa foreach
313: function should do something useful with the contents of that memory during
1.20 wiz 314: each iteration.
315: If the key-value pairs are not terminated with either
1.1 deraadt 316: .Ql \en
317: or
318: .Ql \e0
319: in the map, then they will not be terminated as such when given to the
320: .Pa foreach
321: function, either.
322: .It Fa indata
323: This is the contents of the
1.18 ross 324: .Pa incallback-\*[Gt]data
1.20 wiz 325: element of the callback structure.
326: It is provided as a means to share state between the
1.1 deraadt 327: .Pa foreach
1.20 wiz 328: function and the user code.
329: Its use is completely optional: cast it to
1.1 deraadt 330: something useful or simply ignore it.
331: .El
332: .It Fn yp_order
333: Returns the order number for a map.
334: .It Fn yp_master
1.11 lukem 335: Returns the hostname for the machine on which the master
336: .Tn YP
337: server process for
1.1 deraadt 338: a map is running.
339: .It Fn yperr_string
1.6 lukem 340: Returns a pointer to a NUL-terminated error string that does not contain a
1.1 deraadt 341: .Ql \&.
342: or
343: .Ql \en .
344: .It Fn ypprot_err
1.11 lukem 345: Converts a
346: .Tn YP
347: protocol error code to a
1.1 deraadt 348: .Nm ypclnt
349: error code suitable for
350: .Fn yperr_string .
351: .El
352: .Sh RETURN VALUES
353: All functions in the
354: .Nm ypclnt
355: suite which are of type
356: .Em int
357: return 0 upon success or one of the following error codes upon failure:
358: .Bl -tag -width "YPERR_BADARGS "
359: .It Bq Er YPERR_BADARGS
1.22 wiz 360: The passed arguments to the function are invalid.
1.1 deraadt 361: .It Bq Er YPERR_BADDB
1.15 wiz 362: The
1.11 lukem 363: .Tn YP
364: map that was polled is defective.
1.1 deraadt 365: .It Bq Er YPERR_DOMAIN
1.15 wiz 366: Client process cannot bind to server on this
1.11 lukem 367: .Tn YP
368: domain.
1.1 deraadt 369: .It Bq Er YPERR_KEY
370: The key passed does not exist.
371: .It Bq Er YPERR_MAP
372: There is no such map in the server's domain.
373: .It Bq Er YPERR_DOM
1.15 wiz 374: The local
1.11 lukem 375: .Tn YP
376: domain is not set.
1.1 deraadt 377: .It Bq Er YPERR_NOMORE
378: There are no more records in the queried map.
379: .It Bq Er YPERR_PMAP
1.14 enami 380: Cannot communicate with portmapper (see
1.15 wiz 381: .Xr rpcbind 8 ) .
1.1 deraadt 382: .It Bq Er YPERR_RESRC
383: A resource allocation failure occurred.
384: .It Bq Er YPERR_RPC
1.20 wiz 385: An RPC failure has occurred.
386: The domain has been marked unbound.
1.1 deraadt 387: .It Bq Er YPERR_VERS
1.20 wiz 388: Client/server version mismatch.
389: If the server is running version 1 of the
1.11 lukem 390: .Tn YP
391: protocol,
1.1 deraadt 392: .Fn yp_all
393: functionality does not exist.
394: .It Bq Er YPERR_BIND
395: Cannot communicate with
396: .Xr ypbind 8 .
397: .It Bq Er YPERR_YPERR
398: An internal server or client error has occurred.
399: .It Bq Er YPERR_YPSERV
1.15 wiz 400: The client cannot communicate with the
1.11 lukem 401: .Tn YP
402: server process.
1.1 deraadt 403: .El
404: .Sh SEE ALSO
405: .Xr malloc 3 ,
1.16 wiz 406: .Xr yp 8 ,
1.1 deraadt 407: .Xr ypbind 8 ,
1.6 lukem 408: .Xr ypserv 8
1.16 wiz 409: .Sh AUTHORS
410: .An Theo De Raadt
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to ypclnt.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / yp