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