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