Annotation of src/lib/libc/yp/ypclnt.3, Revision 1.18
1.18 ! ross 1: .\" $NetBSD: ypclnt.3,v 1.17 2002/02/06 12:49:05 ross 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.18 ! ross 56: .Fd #include \*[Lt]sys/types.h\*[Gt]
! 57: .Fd #include \*[Lt]rpc/rpc.h\*[Gt]
! 58: .Fd #include \*[Lt]rpcsvc/ypclnt.h\*[Gt]
! 59: .Fd #include \*[Lt]rpcsvc/yp_prot.h\*[Gt]
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
87: subsystem. For a general description
88: of the
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.6 lukem 135: must be non-null, NUL-terminated strings. All input strings which also have
136: a corresponding length parameter cannot be the null pointer unless the
137: corresponding length value is zero. Such strings need not be NUL-terminated.
1.1 deraadt 138: .Pp
1.11 lukem 139: All
140: .Tn YP
141: lookup calls (the functions
1.1 deraadt 142: .Fn yp_all ,
143: .Fn yp_first ,
144: .Fn yp_master ,
145: .Fn yp_match ,
146: .Fn yp_next ,
147: .Fn yp_order )
1.11 lukem 148: require a
149: .Tn YP
150: domain name and a
151: .Tn YP
1.15 wiz 152: map name. The default domain name may be
1.1 deraadt 153: obtained by calling
154: .Fn yp_get_default_domain ,
1.11 lukem 155: and should thus be used before all other
156: .Tn YP
157: calls in a client program.
1.1 deraadt 158: The value it places
159: .Pa outdomain
160: is suitable for use as the
161: .Pa indomain
1.11 lukem 162: parameter to all subsequent
163: .Tn YP
164: calls.
165: .Pp
166: In order for
167: .Tn YP
168: lookup calls to succeed, the client process must be bound
169: to a
170: .Tn YP
171: server process. The client process need not explicitly bind to
1.1 deraadt 172: the server, as it happens automatically whenever a lookup occurs.
173: The function
174: .Fn yp_bind
1.11 lukem 175: is provided for a backup strategy, e.g. a local file, when a
176: .Tn YP
177: server process
1.1 deraadt 178: is not available. Each binding uses one socket descriptor on the client
179: process, which may be explicitly freed using
180: .Fn yp_unbind ,
181: which frees all per-process and per-node resources to bind the domain and
182: marks the domain unbound.
183: .Pp
1.11 lukem 184: If, during a
185: .Tn YP
186: lookup, an RPC failure occurs, the domain used in the lookup
1.1 deraadt 187: is automatically marked unbound and the
188: .Nm ypclnt
189: layer retries the lookup as long as
190: .Xr ypbind 8
191: is running and either the client process cannot bind to a server for the domain
1.11 lukem 192: specified in the lookup, or RPC requests to the
193: .Tn YP
194: server process fail.
195: If an error is not RPC-related, one of the
196: .Tn YP
197: error codes described below
1.1 deraadt 198: is returned and control given back to the user code.
199: .Pp
200: The
201: .Nm ypclnt
202: suite provides the following functionality:
1.17 ross 203: .Bl -tag -width yp_match()xx
1.1 deraadt 204: .It Fn yp_match
205: Provides the value associated with the given key.
206: .It Fn yp_first
207: Provides the first key-value pair from the given map in the named domain.
208: .It Fn yp_next
209: Provides the next key-value pair in the given map. 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
1.6 lukem 223: Of course, the notions of
224: .Dq first
225: and
226: .Dq next
227: are particular to the
1.11 lukem 228: type of
229: .Tn YP
230: map being accessed, and thus there is no guarantee of lexical
1.1 deraadt 231: order. 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
236: until
237: .Fn yp_next
238: returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed
239: exactly once, and if the entire procedure is repeated, the order will be
240: the same.
241: .Pp
242: If the server is heaviliy loaded or the server fails for some reason, the
243: domain being used may become unbound. If this happens, and the client process
244: re-binds, the retrieval rules will break: some entries may be seen twice, and
245: others not at all. For this reason, the function
246: .Fn yp_all
247: provides a better solution for reading all of the entries in a particular
248: map.
249: .It Fn yp_all
1.6 lukem 250: This function provides a way to transfer an entire map from
1.1 deraadt 251: the server to the client process with a single request. This transfer
252: uses TCP, unlike all other functions in the
253: .Nm ypclnt
254: suite, which use UDP. The entire transaction occurs in a single RPC
255: request-response. The third argument to this function provides a way
256: to supply the name of a function to process each key-value pair in the
257: map.
1.6 lukem 258: .Fn yp_all
1.1 deraadt 259: returns after the entire transaction is complete, or the
260: .Pa foreach
261: function decides that it does not want any more key-value pairs. The third
262: argument to
263: .Fn yp_all
264: is:
265: .Bd -literal -offset indent
266: struct ypall_callback *incallback {
267: int (*foreach)();
268: char *data;
269: };
270: .Ed
271: .Pp
272: The
273: .Em char *data
274: argument is an opaque pointer for use by the callback function. 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 (
1.3 thorpej 283: int instatus,
284: char *inkey,
285: int inkeylen,
286: char *inval,
287: int invallen,
288: char *indata
1.1 deraadt 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
1.18 ! ross 296: .Nm \*[Lt]rpcsvc/yp_prot.h\*[Gt] :
1.1 deraadt 297: see
298: .Fn ypprot_err
1.11 lukem 299: below for a function that will translate
300: .Tn YP
301: protocol errors into a
1.1 deraadt 302: .Nm ypclnt
303: layer error code as described in
1.18 ! ross 304: .Nm \*[Lt]rpcsvc/ypclnt.h\*[Gt] .
1.1 deraadt 305: .It Fa inkey, inval
306: The key and value arguments are somewhat different here than described
307: above. In this case, the memory pointed to by
308: .Fa inkey
309: and
310: .Fa inval
311: is private to
312: .Fn yp_all ,
313: and is overwritten with each subsequent key-value pair, thus the
314: .Pa foreach
315: function should do something useful with the contents of that memory during
316: each iteration. If the key-value pairs are not terminated with either
317: .Ql \en
318: or
319: .Ql \e0
320: in the map, then they will not be terminated as such when given to the
321: .Pa foreach
322: function, either.
323: .It Fa indata
324: This is the contents of the
1.18 ! ross 325: .Pa incallback-\*[Gt]data
1.1 deraadt 326: element of the callback structure. It is provided as a means to share
327: state between the
328: .Pa foreach
329: function and the user code. Its use is completely optional: cast it to
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
360: The passed arguments to the function are invalid
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
385: An RPC failure has occurred. The domain has been marked unbound.
386: .It Bq Er YPERR_VERS
387: Client/server version mismatch. If the server is running version 1
1.15 wiz 388: of the
1.11 lukem 389: .Tn YP
390: protocol,
1.1 deraadt 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
1.15 wiz 399: The client cannot communicate with the
1.11 lukem 400: .Tn YP
401: server process.
1.1 deraadt 402: .El
403: .Sh SEE ALSO
404: .Xr malloc 3 ,
1.16 wiz 405: .Xr yp 8 ,
1.1 deraadt 406: .Xr ypbind 8 ,
1.6 lukem 407: .Xr ypserv 8
1.16 wiz 408: .Sh AUTHORS
409: .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