FreeBSD/Linux Kernel Cross Reference
sys/rpc/clnt.h
1 /* $NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $ */
2
3 /*
4 * The contents of this file are subject to the Sun Standards
5 * License Version 1.0 the (the "License";) You may not use
6 * this file except in compliance with the License. You may
7 * obtain a copy of the License at lib/libc/rpc/LICENSE
8 *
9 * Software distributed under the License is distributed on
10 * an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
11 * express or implied. See the License for the specific
12 * language governing rights and limitations under the License.
13 *
14 * The Original Code is Copyright 1998 by Sun Microsystems, Inc
15 *
16 * The Initial Developer of the Original Code is: Sun
17 * Microsystems, Inc.
18 *
19 * All Rights Reserved.
20 *
21 * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
22 * unrestricted use provided that this legend is included on all tape
23 * media and as a part of the software program in whole or part. Users
24 * may copy or modify Sun RPC without charge, but are not authorized
25 * to license or distribute it to anyone else except as part of a product or
26 * program developed by the user.
27 *
28 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
29 * WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
30 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
31 *
32 * Sun RPC is provided with no support and without any obligation on the
33 * part of Sun Microsystems, Inc. to assist in its use, correction,
34 * modification or enhancement.
35 *
36 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
37 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
38 * OR ANY PART THEREOF.
39 *
40 * In no event will Sun Microsystems, Inc. be liable for any lost revenue
41 * or profits or other special, indirect and consequential damages, even if
42 * Sun has been advised of the possibility of such damages.
43 *
44 * Sun Microsystems, Inc.
45 * 2550 Garcia Avenue
46 * Mountain View, California 94043
47 *
48 * from: @(#)clnt.h 1.31 94/04/29 SMI
49 * from: @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC
50 * $FreeBSD: releng/6.4/sys/rpc/clnt.h 178459 2008-04-24 10:46:25Z dfr $
51 */
52
53 /*
54 * clnt.h - Client side remote procedure call interface.
55 *
56 * Copyright (c) 1986-1991,1994-1999 by Sun Microsystems, Inc.
57 * All rights reserved.
58 */
59
60 #ifndef _RPC_CLNT_H_
61 #define _RPC_CLNT_H_
62 #include <rpc/clnt_stat.h>
63 #include <sys/cdefs.h>
64 #ifdef _KERNEL
65 #include <rpc/netconfig.h>
66 #else
67 #include <netconfig.h>
68 #endif
69 #include <sys/un.h>
70
71 /*
72 * Well-known IPV6 RPC broadcast address.
73 */
74 #define RPCB_MULTICAST_ADDR "ff02::202"
75
76 /*
77 * the following errors are in general unrecoverable. The caller
78 * should give up rather than retry.
79 */
80 #define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \
81 ((s) == RPC_CANTENCODEARGS) || \
82 ((s) == RPC_CANTDECODERES) || \
83 ((s) == RPC_VERSMISMATCH) || \
84 ((s) == RPC_PROCUNAVAIL) || \
85 ((s) == RPC_PROGUNAVAIL) || \
86 ((s) == RPC_PROGVERSMISMATCH) || \
87 ((s) == RPC_CANTDECODEARGS))
88
89 /*
90 * Error info.
91 */
92 struct rpc_err {
93 enum clnt_stat re_status;
94 union {
95 int RE_errno; /* related system error */
96 enum auth_stat RE_why; /* why the auth error occurred */
97 struct {
98 rpcvers_t low; /* lowest version supported */
99 rpcvers_t high; /* highest version supported */
100 } RE_vers;
101 struct { /* maybe meaningful if RPC_FAILED */
102 int32_t s1;
103 int32_t s2;
104 } RE_lb; /* life boot & debugging only */
105 } ru;
106 #define re_errno ru.RE_errno
107 #define re_why ru.RE_why
108 #define re_vers ru.RE_vers
109 #define re_lb ru.RE_lb
110 };
111
112
113 /*
114 * Client rpc handle.
115 * Created by individual implementations
116 * Client is responsible for initializing auth, see e.g. auth_none.c.
117 */
118 typedef struct __rpc_client {
119 AUTH *cl_auth; /* authenticator */
120 struct clnt_ops {
121 /* call remote procedure */
122 enum clnt_stat (*cl_call)(struct __rpc_client *,
123 rpcproc_t, xdrproc_t, void *, xdrproc_t,
124 void *, struct timeval);
125 /* abort a call */
126 void (*cl_abort)(struct __rpc_client *);
127 /* get specific error code */
128 void (*cl_geterr)(struct __rpc_client *,
129 struct rpc_err *);
130 /* frees results */
131 bool_t (*cl_freeres)(struct __rpc_client *,
132 xdrproc_t, void *);
133 /* destroy this structure */
134 void (*cl_destroy)(struct __rpc_client *);
135 /* the ioctl() of rpc */
136 bool_t (*cl_control)(struct __rpc_client *, u_int,
137 void *);
138 } *cl_ops;
139 void *cl_private; /* private stuff */
140 char *cl_netid; /* network token */
141 char *cl_tp; /* device name */
142 } CLIENT;
143
144
145 /*
146 * Timers used for the pseudo-transport protocol when using datagrams
147 */
148 struct rpc_timers {
149 u_short rt_srtt; /* smoothed round-trip time */
150 u_short rt_deviate; /* estimated deviation */
151 u_long rt_rtxcur; /* current (backed-off) rto */
152 };
153
154 /*
155 * Feedback values used for possible congestion and rate control
156 */
157 #define FEEDBACK_REXMIT1 1 /* first retransmit */
158 #define FEEDBACK_OK 2 /* no retransmits */
159
160 /* Used to set version of portmapper used in broadcast */
161
162 #define CLCR_SET_LOWVERS 3
163 #define CLCR_GET_LOWVERS 4
164
165 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */
166
167 /*
168 * client side rpc interface ops
169 *
170 * Parameter types are:
171 *
172 */
173
174 /*
175 * enum clnt_stat
176 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
177 * CLIENT *rh;
178 * rpcproc_t proc;
179 * xdrproc_t xargs;
180 * void *argsp;
181 * xdrproc_t xres;
182 * void *resp;
183 * struct timeval timeout;
184 */
185 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
186 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
187 argsp, xres, resp, secs))
188 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
189 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
190 argsp, xres, resp, secs))
191
192 /*
193 * void
194 * CLNT_ABORT(rh);
195 * CLIENT *rh;
196 */
197 #define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh))
198 #define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh))
199
200 /*
201 * struct rpc_err
202 * CLNT_GETERR(rh);
203 * CLIENT *rh;
204 */
205 #define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
206 #define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
207
208
209 /*
210 * bool_t
211 * CLNT_FREERES(rh, xres, resp);
212 * CLIENT *rh;
213 * xdrproc_t xres;
214 * void *resp;
215 */
216 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
217 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
218
219 /*
220 * bool_t
221 * CLNT_CONTROL(cl, request, info)
222 * CLIENT *cl;
223 * u_int request;
224 * char *info;
225 */
226 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
227 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
228
229 /*
230 * control operations that apply to both udp and tcp transports
231 */
232 #define CLSET_TIMEOUT 1 /* set timeout (timeval) */
233 #define CLGET_TIMEOUT 2 /* get timeout (timeval) */
234 #define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */
235 #define CLGET_FD 6 /* get connections file descriptor */
236 #define CLGET_SVC_ADDR 7 /* get server's address (netbuf) */
237 #define CLSET_FD_CLOSE 8 /* close fd while clnt_destroy */
238 #define CLSET_FD_NCLOSE 9 /* Do not close fd while clnt_destroy */
239 #define CLGET_XID 10 /* Get xid */
240 #define CLSET_XID 11 /* Set xid */
241 #define CLGET_VERS 12 /* Get version number */
242 #define CLSET_VERS 13 /* Set version number */
243 #define CLGET_PROG 14 /* Get program number */
244 #define CLSET_PROG 15 /* Set program number */
245 #define CLSET_SVC_ADDR 16 /* get server's address (netbuf) */
246 #define CLSET_PUSH_TIMOD 17 /* push timod if not already present */
247 #define CLSET_POP_TIMOD 18 /* pop timod */
248 /*
249 * Connectionless only control operations
250 */
251 #define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */
252 #define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */
253 #define CLSET_ASYNC 19
254 #define CLSET_CONNECT 20 /* Use connect() for UDP. (int) */
255
256 #ifdef _KERNEL
257 /*
258 * Kernel control operations. The default msleep string is "rpcrecv",
259 * and sleeps are non-interruptible by default.
260 */
261 #define CLSET_WAITCHAN 21 /* set string to use in msleep call */
262 #define CLGET_WAITCHAN 22 /* get string used in msleep call */
263 #define CLSET_INTERRUPTIBLE 23 /* set interruptible flag */
264 #define CLGET_INTERRUPTIBLE 24 /* set interruptible flag */
265 #endif
266
267
268 /*
269 * void
270 * CLNT_DESTROY(rh);
271 * CLIENT *rh;
272 */
273 #define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
274 #define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
275
276
277 /*
278 * RPCTEST is a test program which is accessible on every rpc
279 * transport/port. It is used for testing, performance evaluation,
280 * and network administration.
281 */
282
283 #define RPCTEST_PROGRAM ((rpcprog_t)1)
284 #define RPCTEST_VERSION ((rpcvers_t)1)
285 #define RPCTEST_NULL_PROC ((rpcproc_t)2)
286 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3)
287
288 /*
289 * By convention, procedure 0 takes null arguments and returns them
290 */
291
292 #define NULLPROC ((rpcproc_t)0)
293
294 /*
295 * Below are the client handle creation routines for the various
296 * implementations of client side rpc. They can return NULL if a
297 * creation failure occurs.
298 */
299
300 /*
301 * Generic client creation routine. Supported protocols are those that
302 * belong to the nettype namespace (/etc/netconfig).
303 */
304 __BEGIN_DECLS
305 #ifdef _KERNEL
306
307 /*
308 * struct socket *so; -- socket
309 * struct sockaddr *svcaddr; -- servers address
310 * rpcprog_t prog; -- program number
311 * rpcvers_t vers; -- version number
312 * size_t sendsz; -- buffer recv size
313 * size_t recvsz; -- buffer send size
314 */
315 extern CLIENT *clnt_dg_create(struct socket *so,
316 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version,
317 size_t sendsz, size_t recvsz);
318
319 /*
320 * struct socket *so; -- socket
321 * struct sockaddr *svcaddr; -- servers address
322 * rpcprog_t prog; -- program number
323 * rpcvers_t vers; -- version number
324 * size_t sendsz; -- buffer recv size
325 * size_t recvsz; -- buffer send size
326 */
327 extern CLIENT *clnt_vc_create(struct socket *so,
328 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version,
329 size_t sendsz, size_t recvsz);
330
331 /*
332 * struct netconfig *nconf; -- network type
333 * struct sockaddr *svcaddr; -- servers address
334 * rpcprog_t prog; -- program number
335 * rpcvers_t vers; -- version number
336 * size_t sendsz; -- buffer recv size
337 * size_t recvsz; -- buffer send size
338 */
339 extern CLIENT *clnt_reconnect_create(struct netconfig *nconf,
340 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version,
341 size_t sendsz, size_t recvsz);
342
343 #else
344
345 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
346 const char *);
347 /*
348 *
349 * const char *hostname; -- hostname
350 * const rpcprog_t prog; -- program number
351 * const rpcvers_t vers; -- version number
352 * const char *nettype; -- network type
353 */
354
355 /*
356 * Generic client creation routine. Just like clnt_create(), except
357 * it takes an additional timeout parameter.
358 */
359 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
360 const rpcvers_t, const char *, const struct timeval *);
361 /*
362 *
363 * const char *hostname; -- hostname
364 * const rpcprog_t prog; -- program number
365 * const rpcvers_t vers; -- version number
366 * const char *nettype; -- network type
367 * const struct timeval *tp; -- timeout
368 */
369
370 /*
371 * Generic client creation routine. Supported protocols are which belong
372 * to the nettype name space.
373 */
374 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
375 const rpcvers_t, const rpcvers_t,
376 const char *);
377 /*
378 * const char *host; -- hostname
379 * const rpcprog_t prog; -- program number
380 * rpcvers_t *vers_out; -- servers highest available version
381 * const rpcvers_t vers_low; -- low version number
382 * const rpcvers_t vers_high; -- high version number
383 * const char *nettype; -- network type
384 */
385
386 /*
387 * Generic client creation routine. Supported protocols are which belong
388 * to the nettype name space.
389 */
390 extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t,
391 rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *,
392 const struct timeval *);
393 /*
394 * const char *host; -- hostname
395 * const rpcprog_t prog; -- program number
396 * rpcvers_t *vers_out; -- servers highest available version
397 * const rpcvers_t vers_low; -- low version number
398 * const rpcvers_t vers_high; -- high version number
399 * const char *nettype; -- network type
400 * const struct timeval *tp -- timeout
401 */
402
403 /*
404 * Generic client creation routine. It takes a netconfig structure
405 * instead of nettype
406 */
407 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
408 const rpcvers_t, const struct netconfig *);
409 /*
410 * const char *hostname; -- hostname
411 * const rpcprog_t prog; -- program number
412 * const rpcvers_t vers; -- version number
413 * const struct netconfig *netconf; -- network config structure
414 */
415
416 /*
417 * Generic client creation routine. Just like clnt_tp_create(), except
418 * it takes an additional timeout parameter.
419 */
420 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
421 const rpcvers_t, const struct netconfig *, const struct timeval *);
422 /*
423 * const char *hostname; -- hostname
424 * const rpcprog_t prog; -- program number
425 * const rpcvers_t vers; -- version number
426 * const struct netconfig *netconf; -- network config structure
427 * const struct timeval *tp -- timeout
428 */
429
430 /*
431 * Generic TLI create routine. Only provided for compatibility.
432 */
433
434 extern CLIENT *clnt_tli_create(const int, const struct netconfig *,
435 struct netbuf *, const rpcprog_t,
436 const rpcvers_t, const u_int, const u_int);
437 /*
438 * const register int fd; -- fd
439 * const struct netconfig *nconf; -- netconfig structure
440 * struct netbuf *svcaddr; -- servers address
441 * const u_long prog; -- program number
442 * const u_long vers; -- version number
443 * const u_int sendsz; -- send size
444 * const u_int recvsz; -- recv size
445 */
446
447 /*
448 * Low level clnt create routine for connectionful transports, e.g. tcp.
449 */
450 extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
451 const rpcprog_t, const rpcvers_t,
452 u_int, u_int);
453 /*
454 * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
455 */
456 extern CLIENT *clntunix_create(struct sockaddr_un *,
457 u_long, u_long, int *, u_int, u_int);
458 /*
459 * const int fd; -- open file descriptor
460 * const struct netbuf *svcaddr; -- servers address
461 * const rpcprog_t prog; -- program number
462 * const rpcvers_t vers; -- version number
463 * const u_int sendsz; -- buffer recv size
464 * const u_int recvsz; -- buffer send size
465 */
466
467 /*
468 * Low level clnt create routine for connectionless transports, e.g. udp.
469 */
470 extern CLIENT *clnt_dg_create(const int, const struct netbuf *,
471 const rpcprog_t, const rpcvers_t,
472 const u_int, const u_int);
473 /*
474 * const int fd; -- open file descriptor
475 * const struct netbuf *svcaddr; -- servers address
476 * const rpcprog_t program; -- program number
477 * const rpcvers_t version; -- version number
478 * const u_int sendsz; -- buffer recv size
479 * const u_int recvsz; -- buffer send size
480 */
481
482 /*
483 * Memory based rpc (for speed check and testing)
484 * CLIENT *
485 * clnt_raw_create(prog, vers)
486 * u_long prog;
487 * u_long vers;
488 */
489 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
490 #endif
491
492 __END_DECLS
493
494
495 /*
496 * Print why creation failed
497 */
498 __BEGIN_DECLS
499 extern void clnt_pcreateerror(const char *); /* stderr */
500 extern char *clnt_spcreateerror(const char *); /* string */
501 __END_DECLS
502
503 /*
504 * Like clnt_perror(), but is more verbose in its output
505 */
506 __BEGIN_DECLS
507 extern void clnt_perrno(enum clnt_stat); /* stderr */
508 extern char *clnt_sperrno(enum clnt_stat); /* string */
509 __END_DECLS
510
511 /*
512 * Print an English error message, given the client error code
513 */
514 __BEGIN_DECLS
515 extern void clnt_perror(CLIENT *, const char *); /* stderr */
516 extern char *clnt_sperror(CLIENT *, const char *); /* string */
517 __END_DECLS
518
519
520 /*
521 * If a creation fails, the following allows the user to figure out why.
522 */
523 struct rpc_createerr {
524 enum clnt_stat cf_stat;
525 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
526 };
527
528 #ifdef _KERNEL
529 extern struct rpc_createerr rpc_createerr;
530 #else
531 __BEGIN_DECLS
532 extern struct rpc_createerr *__rpc_createerr(void);
533 __END_DECLS
534 #define rpc_createerr (*(__rpc_createerr()))
535 #endif
536
537 /*
538 * The simplified interface:
539 * enum clnt_stat
540 * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
541 * const char *host;
542 * const rpcprog_t prognum;
543 * const rpcvers_t versnum;
544 * const rpcproc_t procnum;
545 * const xdrproc_t inproc, outproc;
546 * const char *in;
547 * char *out;
548 * const char *nettype;
549 */
550 __BEGIN_DECLS
551 extern enum clnt_stat rpc_call(const char *, const rpcprog_t,
552 const rpcvers_t, const rpcproc_t,
553 const xdrproc_t, const char *,
554 const xdrproc_t, char *, const char *);
555 __END_DECLS
556
557 /*
558 * RPC broadcast interface
559 * The call is broadcasted to all locally connected nets.
560 *
561 * extern enum clnt_stat
562 * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
563 * eachresult, nettype)
564 * const rpcprog_t prog; -- program number
565 * const rpcvers_t vers; -- version number
566 * const rpcproc_t proc; -- procedure number
567 * const xdrproc_t xargs; -- xdr routine for args
568 * caddr_t argsp; -- pointer to args
569 * const xdrproc_t xresults; -- xdr routine for results
570 * caddr_t resultsp; -- pointer to results
571 * const resultproc_t eachresult; -- call with each result
572 * const char *nettype; -- Transport type
573 *
574 * For each valid response received, the procedure eachresult is called.
575 * Its form is:
576 * done = eachresult(resp, raddr, nconf)
577 * bool_t done;
578 * caddr_t resp;
579 * struct netbuf *raddr;
580 * struct netconfig *nconf;
581 * where resp points to the results of the call and raddr is the
582 * address if the responder to the broadcast. nconf is the transport
583 * on which the response was received.
584 *
585 * extern enum clnt_stat
586 * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp,
587 * eachresult, inittime, waittime, nettype)
588 * const rpcprog_t prog; -- program number
589 * const rpcvers_t vers; -- version number
590 * const rpcproc_t proc; -- procedure number
591 * const xdrproc_t xargs; -- xdr routine for args
592 * caddr_t argsp; -- pointer to args
593 * const xdrproc_t xresults; -- xdr routine for results
594 * caddr_t resultsp; -- pointer to results
595 * const resultproc_t eachresult; -- call with each result
596 * const int inittime; -- how long to wait initially
597 * const int waittime; -- maximum time to wait
598 * const char *nettype; -- Transport type
599 */
600
601 typedef bool_t (*resultproc_t)(caddr_t, ...);
602
603 __BEGIN_DECLS
604 extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t,
605 const rpcproc_t, const xdrproc_t,
606 caddr_t, const xdrproc_t, caddr_t,
607 const resultproc_t, const char *);
608 extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t,
609 const rpcproc_t, const xdrproc_t,
610 caddr_t, const xdrproc_t, caddr_t,
611 const resultproc_t, const int,
612 const int, const char *);
613 __END_DECLS
614
615 #ifndef _KERNEL
616 /* For backward compatibility */
617 #include <rpc/clnt_soc.h>
618 #endif
619
620 #endif /* !_RPC_CLNT_H_ */
Cache object: d6172a1201e37ab04750979069efa0cb
|