HAMMER - Formalize the maximum number of volumes (256).
[dragonfly.git] / include / rpc / clnt.h
bloba823d1ed32e17d7e0c422b0a6a57406b5cc08067
1 /*
2 * The contents of this file are subject to the Sun Standards
3 * License Version 1.0 the (the "License";) You may not use
4 * this file except in compliance with the License. You may
5 * obtain a copy of the License at lib/libc/rpc/LICENSE
7 * Software distributed under the License is distributed on
8 * an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
9 * express or implied. See the License for the specific
10 * language governing rights and limitations under the License.
12 * The Original Code is Copyright 1998 by Sun Microsystems, Inc
14 * The Initial Developer of the Original Code is: Sun
15 * Microsystems, Inc.
17 * All Rights Reserved.
19 * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
20 * unrestricted use provided that this legend is included on all tape
21 * media and as a part of the software program in whole or part. Users
22 * may copy or modify Sun RPC without charge, but are not authorized
23 * to license or distribute it to anyone else except as part of a product or
24 * program developed by the user.
26 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
27 * WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
30 * Sun RPC is provided with no support and without any obligation on the
31 * part of Sun Microsystems, Inc. to assist in its use, correction,
32 * modification or enhancement.
34 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
35 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
36 * OR ANY PART THEREOF.
38 * In no event will Sun Microsystems, Inc. be liable for any lost revenue
39 * or profits or other special, indirect and consequential damages, even if
40 * Sun has been advised of the possibility of such damages.
42 * Sun Microsystems, Inc.
43 * 2550 Garcia Avenue
44 * Mountain View, California 94043
46 * from: @(#)clnt.h 1.31 94/04/29 SMI
47 * from: @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC
48 * $NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $
49 * $FreeBSD: src/include/rpc/clnt.h,v 1.21 2003/01/24 01:47:55 fjoe Exp $
50 * $DragonFly: src/include/rpc/clnt.h,v 1.6 2005/11/13 12:27:04 swildner Exp $
54 * clnt.h - Client side remote procedure call interface.
56 * Copyright (c) 1986-1991,1994-1999 by Sun Microsystems, Inc.
57 * All rights reserved.
60 #ifndef _RPC_CLNT_H_
61 #define _RPC_CLNT_H_
62 #include <rpc/clnt_stat.h>
63 #include <sys/cdefs.h>
64 #include <netconfig.h>
65 #include <sys/un.h>
68 * Well-known IPV6 RPC broadcast address.
70 #define RPCB_MULTICAST_ADDR "ff02::202"
73 * the following errors are in general unrecoverable. The caller
74 * should give up rather than retry.
76 #define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \
77 ((s) == RPC_CANTENCODEARGS) || \
78 ((s) == RPC_CANTDECODERES) || \
79 ((s) == RPC_VERSMISMATCH) || \
80 ((s) == RPC_PROCUNAVAIL) || \
81 ((s) == RPC_PROGUNAVAIL) || \
82 ((s) == RPC_PROGVERSMISMATCH) || \
83 ((s) == RPC_CANTDECODEARGS))
86 * Error info.
88 struct rpc_err {
89 enum clnt_stat re_status;
90 union {
91 int RE_errno; /* related system error */
92 enum auth_stat RE_why; /* why the auth error occurred */
93 struct {
94 rpcvers_t low; /* lowest version supported */
95 rpcvers_t high; /* highest version supported */
96 } RE_vers;
97 struct { /* maybe meaningful if RPC_FAILED */
98 int32_t s1;
99 int32_t s2;
100 } RE_lb; /* life boot & debugging only */
101 } ru;
102 #define re_errno ru.RE_errno
103 #define re_why ru.RE_why
104 #define re_vers ru.RE_vers
105 #define re_lb ru.RE_lb
110 * Client rpc handle.
111 * Created by individual implementations
112 * Client is responsible for initializing auth, see e.g. auth_none.c.
114 typedef struct __rpc_client {
115 AUTH *cl_auth; /* authenticator */
116 struct clnt_ops {
117 /* call remote procedure */
118 enum clnt_stat (*cl_call)(struct __rpc_client *,
119 rpcproc_t, xdrproc_t, void *, xdrproc_t,
120 void *, struct timeval);
121 /* abort a call */
122 void (*cl_abort)(struct __rpc_client *);
123 /* get specific error code */
124 void (*cl_geterr)(struct __rpc_client *,
125 struct rpc_err *);
126 /* frees results */
127 bool_t (*cl_freeres)(struct __rpc_client *,
128 xdrproc_t, void *);
129 /* destroy this structure */
130 void (*cl_destroy)(struct __rpc_client *);
131 /* the ioctl() of rpc */
132 bool_t (*cl_control)(struct __rpc_client *, u_int,
133 void *);
134 } *cl_ops;
135 void *cl_private; /* private stuff */
136 char *cl_netid; /* network token */
137 char *cl_tp; /* device name */
138 } CLIENT;
142 * Timers used for the pseudo-transport protocol when using datagrams
144 struct rpc_timers {
145 u_short rt_srtt; /* smoothed round-trip time */
146 u_short rt_deviate; /* estimated deviation */
147 u_long rt_rtxcur; /* current (backed-off) rto */
151 * Feedback values used for possible congestion and rate control
153 #define FEEDBACK_REXMIT1 1 /* first retransmit */
154 #define FEEDBACK_OK 2 /* no retransmits */
156 /* Used to set version of portmapper used in broadcast */
158 #define CLCR_SET_LOWVERS 3
159 #define CLCR_GET_LOWVERS 4
161 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */
164 * client side rpc interface ops
166 * Parameter types are:
171 * enum clnt_stat
172 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
173 * CLIENT *rh;
174 * rpcproc_t proc;
175 * xdrproc_t xargs;
176 * void *argsp;
177 * xdrproc_t xres;
178 * void *resp;
179 * struct timeval timeout;
181 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
182 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
183 argsp, xres, resp, secs))
184 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
185 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
186 argsp, xres, resp, secs))
189 * void
190 * CLNT_ABORT(rh);
191 * CLIENT *rh;
193 #define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh))
194 #define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh))
197 * struct rpc_err
198 * CLNT_GETERR(rh);
199 * CLIENT *rh;
201 #define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
202 #define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
206 * bool_t
207 * CLNT_FREERES(rh, xres, resp);
208 * CLIENT *rh;
209 * xdrproc_t xres;
210 * void *resp;
212 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
213 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
216 * bool_t
217 * CLNT_CONTROL(cl, request, info)
218 * CLIENT *cl;
219 * u_int request;
220 * char *info;
222 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
223 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
226 * control operations that apply to both udp and tcp transports
228 #define CLSET_TIMEOUT 1 /* set timeout (timeval) */
229 #define CLGET_TIMEOUT 2 /* get timeout (timeval) */
230 #define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */
231 #define CLGET_FD 6 /* get connections file descriptor */
232 #define CLGET_SVC_ADDR 7 /* get server's address (netbuf) */
233 #define CLSET_FD_CLOSE 8 /* close fd while clnt_destroy */
234 #define CLSET_FD_NCLOSE 9 /* Do not close fd while clnt_destroy */
235 #define CLGET_XID 10 /* Get xid */
236 #define CLSET_XID 11 /* Set xid */
237 #define CLGET_VERS 12 /* Get version number */
238 #define CLSET_VERS 13 /* Set version number */
239 #define CLGET_PROG 14 /* Get program number */
240 #define CLSET_PROG 15 /* Set program number */
241 #define CLSET_SVC_ADDR 16 /* get server's address (netbuf) */
242 #define CLSET_PUSH_TIMOD 17 /* push timod if not already present */
243 #define CLSET_POP_TIMOD 18 /* pop timod */
245 * Connectionless only control operations
247 #define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */
248 #define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */
249 #define CLSET_ASYNC 19
250 #define CLSET_CONNECT 20 /* Use connect() for UDP. (int) */
253 * void
254 * CLNT_DESTROY(rh);
255 * CLIENT *rh;
257 #define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
258 #define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
262 * RPCTEST is a test program which is accessible on every rpc
263 * transport/port. It is used for testing, performance evaluation,
264 * and network administration.
267 #define RPCTEST_PROGRAM ((rpcprog_t)1)
268 #define RPCTEST_VERSION ((rpcvers_t)1)
269 #define RPCTEST_NULL_PROC ((rpcproc_t)2)
270 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3)
273 * By convention, procedure 0 takes null arguments and returns them
276 #define NULLPROC ((rpcproc_t)0)
279 * Below are the client handle creation routines for the various
280 * implementations of client side rpc. They can return NULL if a
281 * creation failure occurs.
285 * Generic client creation routine. Supported protocols are those that
286 * belong to the nettype namespace (/etc/netconfig).
288 __BEGIN_DECLS
289 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
290 const char *);
293 * const char *hostname; -- hostname
294 * const rpcprog_t prog; -- program number
295 * const rpcvers_t vers; -- version number
296 * const char *nettype; -- network type
300 * Generic client creation routine. Just like clnt_create(), except
301 * it takes an additional timeout parameter.
303 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
304 const rpcvers_t, const char *, const struct timeval *);
307 * const char *hostname; -- hostname
308 * const rpcprog_t prog; -- program number
309 * const rpcvers_t vers; -- version number
310 * const char *nettype; -- network type
311 * const struct timeval *tp; -- timeout
315 * Generic client creation routine. Supported protocols are which belong
316 * to the nettype name space.
318 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
319 const rpcvers_t, const rpcvers_t,
320 const char *);
322 * const char *host; -- hostname
323 * const rpcprog_t prog; -- program number
324 * rpcvers_t *vers_out; -- servers highest available version
325 * const rpcvers_t vers_low; -- low version number
326 * const rpcvers_t vers_high; -- high version number
327 * const char *nettype; -- network type
331 * Generic client creation routine. Supported protocols are which belong
332 * to the nettype name space.
334 extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t,
335 rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *,
336 const struct timeval *);
338 * const char *host; -- hostname
339 * const rpcprog_t prog; -- program number
340 * rpcvers_t *vers_out; -- servers highest available version
341 * const rpcvers_t vers_low; -- low version number
342 * const rpcvers_t vers_high; -- high version number
343 * const char *nettype; -- network type
344 * const struct timeval *tp -- timeout
348 * Generic client creation routine. It takes a netconfig structure
349 * instead of nettype
351 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
352 const rpcvers_t, const struct netconfig *);
354 * const char *hostname; -- hostname
355 * const rpcprog_t prog; -- program number
356 * const rpcvers_t vers; -- version number
357 * const struct netconfig *netconf; -- network config structure
361 * Generic client creation routine. Just like clnt_tp_create(), except
362 * it takes an additional timeout parameter.
364 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
365 const rpcvers_t, const struct netconfig *, const struct timeval *);
367 * const char *hostname; -- hostname
368 * const rpcprog_t prog; -- program number
369 * const rpcvers_t vers; -- version number
370 * const struct netconfig *netconf; -- network config structure
371 * const struct timeval *tp -- timeout
375 * Generic TLI create routine. Only provided for compatibility.
378 extern CLIENT *clnt_tli_create(const int, const struct netconfig *,
379 struct netbuf *, const rpcprog_t,
380 const rpcvers_t, const u_int, const u_int);
382 * const register int fd; -- fd
383 * const struct netconfig *nconf; -- netconfig structure
384 * struct netbuf *svcaddr; -- servers address
385 * const u_long prog; -- program number
386 * const u_long vers; -- version number
387 * const u_int sendsz; -- send size
388 * const u_int recvsz; -- recv size
392 * Low level clnt create routine for connectionful transports, e.g. tcp.
394 extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
395 const rpcprog_t, const rpcvers_t,
396 u_int, u_int);
398 * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
400 extern CLIENT *clntunix_create(struct sockaddr_un *,
401 u_long, u_long, int *, u_int, u_int);
403 * const int fd; -- open file descriptor
404 * const struct netbuf *svcaddr; -- servers address
405 * const rpcprog_t prog; -- program number
406 * const rpcvers_t vers; -- version number
407 * const u_int sendsz; -- buffer recv size
408 * const u_int recvsz; -- buffer send size
412 * Low level clnt create routine for connectionless transports, e.g. udp.
414 extern CLIENT *clnt_dg_create(const int, const struct netbuf *,
415 const rpcprog_t, const rpcvers_t,
416 const u_int, const u_int);
418 * const int fd; -- open file descriptor
419 * const struct netbuf *svcaddr; -- servers address
420 * const rpcprog_t program; -- program number
421 * const rpcvers_t version; -- version number
422 * const u_int sendsz; -- buffer recv size
423 * const u_int recvsz; -- buffer send size
427 * Memory based rpc (for speed check and testing)
428 * CLIENT *
429 * clnt_raw_create(prog, vers)
430 * u_long prog;
431 * u_long vers;
433 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
435 __END_DECLS
439 * Print why creation failed
441 __BEGIN_DECLS
442 extern void clnt_pcreateerror(const char *); /* stderr */
443 extern char *clnt_spcreateerror(const char *); /* string */
444 __END_DECLS
447 * Like clnt_perror(), but is more verbose in its output
449 __BEGIN_DECLS
450 extern void clnt_perrno(enum clnt_stat); /* stderr */
451 extern char *clnt_sperrno(enum clnt_stat); /* string */
452 __END_DECLS
455 * Print an English error message, given the client error code
457 __BEGIN_DECLS
458 extern void clnt_perror(CLIENT *, const char *); /* stderr */
459 extern char *clnt_sperror(CLIENT *, const char *); /* string */
460 __END_DECLS
464 * If a creation fails, the following allows the user to figure out why.
466 struct rpc_createerr {
467 enum clnt_stat cf_stat;
468 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
471 __BEGIN_DECLS
472 extern struct rpc_createerr *__rpc_createerr(void);
473 __END_DECLS
474 #define rpc_createerr (*(__rpc_createerr()))
477 * The simplified interface:
478 * enum clnt_stat
479 * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
480 * const char *host;
481 * const rpcprog_t prognum;
482 * const rpcvers_t versnum;
483 * const rpcproc_t procnum;
484 * const xdrproc_t inproc, outproc;
485 * const char *in;
486 * char *out;
487 * const char *nettype;
489 __BEGIN_DECLS
490 extern enum clnt_stat rpc_call(const char *, const rpcprog_t,
491 const rpcvers_t, const rpcproc_t,
492 const xdrproc_t, const char *,
493 const xdrproc_t, char *, const char *);
494 __END_DECLS
497 * RPC broadcast interface
498 * The call is broadcasted to all locally connected nets.
500 * extern enum clnt_stat
501 * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
502 * eachresult, nettype)
503 * const rpcprog_t prog; -- program number
504 * const rpcvers_t vers; -- version number
505 * const rpcproc_t proc; -- procedure number
506 * const xdrproc_t xargs; -- xdr routine for args
507 * caddr_t argsp; -- pointer to args
508 * const xdrproc_t xresults; -- xdr routine for results
509 * caddr_t resultsp; -- pointer to results
510 * const resultproc_t eachresult; -- call with each result
511 * const char *nettype; -- Transport type
513 * For each valid response received, the procedure eachresult is called.
514 * Its form is:
515 * done = eachresult(resp, raddr, nconf)
516 * bool_t done;
517 * caddr_t resp;
518 * struct netbuf *raddr;
519 * struct netconfig *nconf;
520 * where resp points to the results of the call and raddr is the
521 * address if the responder to the broadcast. nconf is the transport
522 * on which the response was received.
524 * extern enum clnt_stat
525 * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp,
526 * eachresult, inittime, waittime, nettype)
527 * const rpcprog_t prog; -- program number
528 * const rpcvers_t vers; -- version number
529 * const rpcproc_t proc; -- procedure number
530 * const xdrproc_t xargs; -- xdr routine for args
531 * caddr_t argsp; -- pointer to args
532 * const xdrproc_t xresults; -- xdr routine for results
533 * caddr_t resultsp; -- pointer to results
534 * const resultproc_t eachresult; -- call with each result
535 * const int inittime; -- how long to wait initially
536 * const int waittime; -- maximum time to wait
537 * const char *nettype; -- Transport type
540 typedef bool_t (*resultproc_t)(caddr_t, ...);
542 __BEGIN_DECLS
543 extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t,
544 const rpcproc_t, const xdrproc_t,
545 caddr_t, const xdrproc_t, caddr_t,
546 const resultproc_t, const char *);
547 extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t,
548 const rpcproc_t, const xdrproc_t,
549 caddr_t, const xdrproc_t, caddr_t,
550 const resultproc_t, const int,
551 const int, const char *);
552 __END_DECLS
554 /* For backward compatibility */
555 #include <rpc/clnt_soc.h>
557 #endif /* !_RPC_CLNT_H_ */