Annotation of src/lib/libc/yp/ypclnt.3, Revision 1.3
1.3 ! thorpej 1: .\" $NetBSD: ypclnt.3,v 1.2 1995/02/27 13:00:48 cgd Exp $
1.2 cgd 2: .\"
1.1 deraadt 3: .\"
4: .\" Copyright (c) 1994 Jason R. Thorpe
5: .\" All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
15: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by Jason Thorpe.
18: .\" 4. Neither the name of the author nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
1.3 ! thorpej 34: .\" $NetBSD: ypclnt.3,v 1.2 1995/02/27 13:00:48 cgd Exp $
1.1 deraadt 35: .\"
36: .Dd October 26, 1994
37: .Dt YPCLNT 3
38: .Os
39: .Sh NAME
40: .Nm yp_all ,
41: .Nm yp_bind ,
42: .Nm yp_first ,
43: .Nm yp_get_default_domain ,
44: .Nm yp_master ,
45: .Nm yp_match ,
46: .Nm yp_next ,
47: .Nm yp_order ,
48: .Nm yp_unbind ,
49: .Nm yperr_string ,
50: .Nm ypprot_err
51: .Nd Interface to the YP subsystem
52: .Sh SYNOPSIS
53: .Fd #include <sys/types.h>
54: .Fd #include <rpcsvc/ypclnt.h>
55: .Fd #include <rpcsvc/yp_prot.h>
56: .Ft int
57: .Fn yp_all "char *indomain" "char *inmap" "struct ypall_callback *incallback"
58: .Ft int
59: .Fn yp_bind "char *dom"
60: .Ft int
61: .Fn yp_first "char *indomain" "char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
62: .Ft int
63: .Fn yp_get_default_domain "char **domp"
64: .Ft int
65: .Fn yp_master "char *indomain" "char *inmap" "char **outname"
66: .Ft int
67: .Fn yp_match "char *indomain" "char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen"
68: .Ft int
69: .Fn yp_next "char *indomain" "char *inmap" "char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
70: .Ft int
71: .Fn yp_order "char *indomain" "char *inmap" "char *outorder"
72: .Ft void
73: .Fn yp_unbind "char *dom"
74: .Ft char *
75: .Fn yperr_string "int incode"
76: .Ft int
77: .Fn ypprot_err "unsigned int incode"
78: .Sh DESCRIPTION
79: The
80: .Nm ypclnt
81: suite provides an interface to the YP subsystem. For a general description
82: of the YP subsystem, see
83: .Xr yp 8 .
84: .Pp
85: For all functions, input values begin with
86: .Pa in
87: and output values begin with
88: .Pa out .
89: Any ouput values of type
90: .Em char **
91: should be the addresses of uninitialized character pointers. Memory will be
92: allocated by the YP client routines using
93: .Fn malloc .
94: This memory can later be freed by the user if there is no additional need for
95: the data stored there. For
96: .Pa outkey
97: and
98: .Pa outval ,
99: two extra bytes of memory are allocated for a
100: .Ql \en
101: and
102: .Ql \e0 ,
103: which are not
104: reflected in the values of
105: .Pa outkeylen
106: or
107: .Pa outvallen .
108: All occurrences of
109: .Pa indomain
110: and
111: .Pa inmap
112: must be non-null, null-terminated strings. All input strings which also have
113: a corresponding length parameter cannot be null unless the corresponding
114: length value is zero. Such strings need not be null-terminated.
115: .Pp
116: All YP lookup calls (the functions
117: .Fn yp_all ,
118: .Fn yp_first ,
119: .Fn yp_master ,
120: .Fn yp_match ,
121: .Fn yp_next ,
122: .Fn yp_order )
123: require a YP domain name and a YP map name. The default domain name may be
124: obtained by calling
125: .Fn yp_get_default_domain ,
126: and should thus be used before all other YP calls in a client program.
127: The value it places
128: .Pa outdomain
129: is suitable for use as the
130: .Pa indomain
131: parameter to all subsequent YP calls.
132: .Pp
133: In order for YP lookup calls to succeed, the client process must be bound
134: to a YP server process. The client process need not explicitly bind to
135: the server, as it happens automatically whenever a lookup occurs.
136: The function
137: .Fn yp_bind
138: is provided for a backup strategy, e.g. a local file, when a YP server process
139: is not available. Each binding uses one socket descriptor on the client
140: process, which may be explicitly freed using
141: .Fn yp_unbind ,
142: which frees all per-process and per-node resources to bind the domain and
143: marks the domain unbound.
144: .Pp
145: If, during a YP lookup, an RPC failure occurs, the domain used in the lookup
146: is automatically marked unbound and the
147: .Nm ypclnt
148: layer retries the lookup as long as
149: .Xr ypbind 8
150: is running and either the client process cannot bind to a server for the domain
151: specified in the lookup, or RPC requests to the YP server process fail.
152: If an error is not RPC-related, one of the YP error codes described below
153: is returned and control given back to the user code.
154: .Pp
155: The
156: .Nm ypclnt
157: suite provides the following functionality:
158: .Bl -tag -width Fn yp_match
159: .It Fn yp_match
160: Provides the value associated with the given key.
161: .It Fn yp_first
162: Provides the first key-value pair from the given map in the named domain.
163: .It Fn yp_next
164: Provides the next key-value pair in the given map. To obtain the second pair,
165: the
166: .Pa inkey
167: value should be the
168: .Pa outkey
169: value provided by the initial call to
170: .Fn yp_first .
171: In the general case, the next key-value pair may be obtained by using the
172: .Pa outkey
173: value from the previous call to
174: .Fn yp_next
175: as the value for
176: .Pa inkey .
177: .Pp
178: Of course, the notions of ``first'' and ``next'' are particular to the
179: type of YP map being accessed, and thus there is no guarantee of lexical
180: order. The only guarantees provided with
181: .Fn yp_first
182: and
183: .Fn yp_next ,
184: providing that the same map on the same server is polled repeatedly
185: until
186: .Fn yp_next
187: returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed
188: exactly once, and if the entire procedure is repeated, the order will be
189: the same.
190: .Pp
191: If the server is heaviliy loaded or the server fails for some reason, the
192: domain being used may become unbound. If this happens, and the client process
193: re-binds, the retrieval rules will break: some entries may be seen twice, and
194: others not at all. For this reason, the function
195: .Fn yp_all
196: provides a better solution for reading all of the entries in a particular
197: map.
198: .It Fn yp_all
199: This function provides a way to transfer an entire an entire map from
200: the server to the client process with a single request. This transfer
201: uses TCP, unlike all other functions in the
202: .Nm ypclnt
203: suite, which use UDP. The entire transaction occurs in a single RPC
204: request-response. The third argument to this function provides a way
205: to supply the name of a function to process each key-value pair in the
206: map.
207: .Fn Yp_all
208: returns after the entire transaction is complete, or the
209: .Pa foreach
210: function decides that it does not want any more key-value pairs. The third
211: argument to
212: .Fn yp_all
213: is:
214: .Bd -literal -offset indent
215: struct ypall_callback *incallback {
216: int (*foreach)();
217: char *data;
218: };
219: .Ed
220: .Pp
221: The
222: .Em char *data
223: argument is an opaque pointer for use by the callback function. The
224: .Pa foreach
225: function should return non-zero when it no longer wishes to process
226: key-value pairs, at which time
227: .Fn yp_all
228: returns a value of 0, and is called with the following arguments:
229: .Pp
230: .Bd -literal -offset indent
231: int foreach (
1.3 ! thorpej 232: int instatus,
! 233: char *inkey,
! 234: int inkeylen,
! 235: char *inval,
! 236: int invallen,
! 237: char *indata
1.1 deraadt 238: );
239: .Ed
240: .Pp
241: Where:
242: .Bl -tag -width "inkey, inval"
243: .It Fa instatus
244: Holds one of the return status values described in
245: .Nm <rpcsvc/yp_prot.h> :
246: see
247: .Fn ypprot_err
248: below for a function that will translate YP protocol errors into a
249: .Nm ypclnt
250: layer error code as described in
251: .Nm <rpcsvc/ypclnt.h> .
252: .It Fa inkey, inval
253: The key and value arguments are somewhat different here than described
254: above. In this case, the memory pointed to by
255: .Fa inkey
256: and
257: .Fa inval
258: is private to
259: .Fn yp_all ,
260: and is overwritten with each subsequent key-value pair, thus the
261: .Pa foreach
262: function should do something useful with the contents of that memory during
263: each iteration. If the key-value pairs are not terminated with either
264: .Ql \en
265: or
266: .Ql \e0
267: in the map, then they will not be terminated as such when given to the
268: .Pa foreach
269: function, either.
270: .It Fa indata
271: This is the contents of the
272: .Pa incallback->data
273: element of the callback structure. It is provided as a means to share
274: state between the
275: .Pa foreach
276: function and the user code. Its use is completely optional: cast it to
277: something useful or simply ignore it.
278: .El
279: .It Fn yp_order
280: Returns the order number for a map.
281: .It Fn yp_master
282: Returns the hostname for the machine on which the master YP server process for
283: a map is running.
284: .It Fn yperr_string
285: Returns a pointer to a null-terminated error string that does not contain a
286: .Ql \&.
287: or
288: .Ql \en .
289: .It Fn ypprot_err
290: Converts a YP protocol error code to a
291: .Nm ypclnt
292: error code suitable for
293: .Fn yperr_string .
294: .El
295: .Sh RETURN VALUES
296: All functions in the
297: .Nm ypclnt
298: suite which are of type
299: .Em int
300: return 0 upon success or one of the following error codes upon failure:
301: .Bl -tag -width "YPERR_BADARGS "
302: .It Bq Er YPERR_BADARGS
303: The passed arguments to the function are invalid
304: .It Bq Er YPERR_BADDB
305: The YP map that was polled is defective.
306: .It Bq Er YPERR_DOMAIN
307: Client process cannot bind to server on this YP domain.
308: .It Bq Er YPERR_KEY
309: The key passed does not exist.
310: .It Bq Er YPERR_MAP
311: There is no such map in the server's domain.
312: .It Bq Er YPERR_DOM
313: The local YP domain is not set.
314: .It Bq Er YPERR_NOMORE
315: There are no more records in the queried map.
316: .It Bq Er YPERR_PMAP
317: Cannot communicate with portmap.
318: .It Bq Er YPERR_RESRC
319: A resource allocation failure occurred.
320: .It Bq Er YPERR_RPC
321: An RPC failure has occurred. The domain has been marked unbound.
322: .It Bq Er YPERR_VERS
323: Client/server version mismatch. If the server is running version 1
324: of the YP protocol,
325: .Fn yp_all
326: functionality does not exist.
327: .It Bq Er YPERR_BIND
328: Cannot communicate with
329: .Xr ypbind 8 .
330: .It Bq Er YPERR_YPERR
331: An internal server or client error has occurred.
332: .It Bq Er YPERR_YPSERV
333: The client cannot communicate with the YP server process.
334: .El
335: .Sh SEE ALSO
336: .Xr malloc 3 ,
337: .Xr ypbind 8 ,
338: .Xr yp 8
339: .Sh AUTHOR
340: 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