1 /* $NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $ */
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
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.
14 * The Original Code is Copyright 1998 by Sun Microsystems, Inc
16 * The Initial Developer of the Original Code is: Sun
19 * All Rights Reserved.
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.
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.
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.
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.
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.
44 * Sun Microsystems, Inc.
46 * Mountain View, California 94043
48 * from: @(#)clnt.h 1.31 94/04/29 SMI
49 * from: @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC
54 * clnt.h - Client side remote procedure call interface.
56 * Copyright (c) 1986-1991,1994-1999 by Sun Microsystems, Inc.
57 * All rights reserved.
62 #include <rpc/clnt_stat.h>
63 #include <sys/cdefs.h>
65 #include <sys/refcount.h>
66 #include <rpc/netconfig.h>
68 #include <netconfig.h>
73 * Well-known IPV6 RPC broadcast address.
75 #define RPCB_MULTICAST_ADDR "ff02::202"
78 * the following errors are in general unrecoverable. The caller
79 * should give up rather than retry.
81 #define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \
82 ((s) == RPC_CANTENCODEARGS) || \
83 ((s) == RPC_CANTDECODERES) || \
84 ((s) == RPC_VERSMISMATCH) || \
85 ((s) == RPC_PROCUNAVAIL) || \
86 ((s) == RPC_PROGUNAVAIL) || \
87 ((s) == RPC_PROGVERSMISMATCH) || \
88 ((s) == RPC_CANTDECODEARGS))
94 enum clnt_stat re_status;
96 int RE_errno; /* related system error */
97 enum auth_stat RE_why; /* why the auth error occurred */
99 rpcvers_t low; /* lowest version supported */
100 rpcvers_t high; /* highest version supported */
102 struct { /* maybe meaningful if RPC_FAILED */
105 } RE_lb; /* life boot & debugging only */
107 #define re_errno ru.RE_errno
108 #define re_why ru.RE_why
109 #define re_vers ru.RE_vers
110 #define re_lb ru.RE_lb
115 * Functions of this type may be used to receive notification when RPC
116 * calls have to be re-transmitted etc.
118 typedef void rpc_feedback(int cmd, int procnum, void *);
121 * A structure used with CLNT_CALL_EXT to pass extra information used
122 * while processing an RPC call.
124 struct rpc_callextra {
125 AUTH *rc_auth; /* auth handle to use for this call */
126 rpc_feedback *rc_feedback; /* callback for retransmits etc. */
127 void *rc_feedback_arg; /* argument for callback */
133 * Created by individual implementations
134 * Client is responsible for initializing auth, see e.g. auth_none.c.
136 typedef struct __rpc_client {
138 volatile u_int cl_refs; /* reference count */
139 AUTH *cl_auth; /* authenticator */
141 /* call remote procedure */
142 enum clnt_stat (*cl_call)(struct __rpc_client *,
143 struct rpc_callextra *, rpcproc_t, xdrproc_t, void *,
144 xdrproc_t, void *, struct timeval);
146 void (*cl_abort)(struct __rpc_client *);
147 /* get specific error code */
148 void (*cl_geterr)(struct __rpc_client *,
151 bool_t (*cl_freeres)(struct __rpc_client *,
153 /* destroy this structure */
154 void (*cl_destroy)(struct __rpc_client *);
155 /* the ioctl() of rpc */
156 bool_t (*cl_control)(struct __rpc_client *, u_int,
160 AUTH *cl_auth; /* authenticator */
162 /* call remote procedure */
163 enum clnt_stat (*cl_call)(struct __rpc_client *,
164 rpcproc_t, xdrproc_t, void *, xdrproc_t,
165 void *, struct timeval);
167 void (*cl_abort)(struct __rpc_client *);
168 /* get specific error code */
169 void (*cl_geterr)(struct __rpc_client *,
172 bool_t (*cl_freeres)(struct __rpc_client *,
174 /* destroy this structure */
175 void (*cl_destroy)(struct __rpc_client *);
176 /* the ioctl() of rpc */
177 bool_t (*cl_control)(struct __rpc_client *, u_int,
181 void *cl_private; /* private stuff */
182 char *cl_netid; /* network token */
183 char *cl_tp; /* device name */
187 * Timers used for the pseudo-transport protocol when using datagrams
190 u_short rt_srtt; /* smoothed round-trip time */
191 u_short rt_deviate; /* estimated deviation */
192 u_long rt_rtxcur; /* current (backed-off) rto */
196 * Feedback values used for possible congestion and rate control
198 #define FEEDBACK_OK 1 /* no retransmits */
199 #define FEEDBACK_REXMIT1 2 /* first retransmit */
200 #define FEEDBACK_REXMIT2 3 /* second and subsequent retransmit */
201 #define FEEDBACK_RECONNECT 4 /* client reconnect */
203 /* Used to set version of portmapper used in broadcast */
205 #define CLCR_SET_LOWVERS 3
206 #define CLCR_GET_LOWVERS 4
208 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */
211 * client side rpc interface ops
213 * Parameter types are:
218 #define CLNT_ACQUIRE(rh) \
219 refcount_acquire(&(rh)->cl_refs)
220 #define CLNT_RELEASE(rh) \
221 if (refcount_release(&(rh)->cl_refs)) \
226 * CLNT_CALL_EXT(rh, ext, proc, xargs, argsp, xres, resp, timeout)
228 * struct rpc_callextra *ext;
234 * struct timeval timeout;
236 #define CLNT_CALL_EXT(rh, ext, proc, xargs, argsp, xres, resp, secs) \
237 ((*(rh)->cl_ops->cl_call)(rh, ext, proc, xargs, \
238 argsp, xres, resp, secs))
243 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
250 * struct timeval timeout;
253 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
254 ((*(rh)->cl_ops->cl_call)(rh, NULL, proc, xargs, \
255 argsp, xres, resp, secs))
256 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
257 ((*(rh)->cl_ops->cl_call)(rh, NULL, proc, xargs, \
258 argsp, xres, resp, secs))
260 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
261 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
262 argsp, xres, resp, secs))
263 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
264 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
265 argsp, xres, resp, secs))
273 #define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh))
274 #define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh))
281 #define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
282 #define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
287 * CLNT_FREERES(rh, xres, resp);
292 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
293 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
297 * CLNT_CONTROL(cl, request, info)
302 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
303 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
306 * control operations that apply to both udp and tcp transports
308 #define CLSET_TIMEOUT 1 /* set timeout (timeval) */
309 #define CLGET_TIMEOUT 2 /* get timeout (timeval) */
310 #define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */
311 #define CLGET_FD 6 /* get connections file descriptor */
312 #define CLGET_SVC_ADDR 7 /* get server's address (netbuf) */
313 #define CLSET_FD_CLOSE 8 /* close fd while clnt_destroy */
314 #define CLSET_FD_NCLOSE 9 /* Do not close fd while clnt_destroy */
315 #define CLGET_XID 10 /* Get xid */
316 #define CLSET_XID 11 /* Set xid */
317 #define CLGET_VERS 12 /* Get version number */
318 #define CLSET_VERS 13 /* Set version number */
319 #define CLGET_PROG 14 /* Get program number */
320 #define CLSET_PROG 15 /* Set program number */
321 #define CLSET_SVC_ADDR 16 /* get server's address (netbuf) */
322 #define CLSET_PUSH_TIMOD 17 /* push timod if not already present */
323 #define CLSET_POP_TIMOD 18 /* pop timod */
325 * Connectionless only control operations
327 #define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */
328 #define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */
329 #define CLSET_ASYNC 19
330 #define CLSET_CONNECT 20 /* Use connect() for UDP. (int) */
334 * Kernel control operations. The default msleep string is "rpcrecv",
335 * and sleeps are non-interruptible by default.
337 #define CLSET_WAITCHAN 21 /* set string to use in msleep call */
338 #define CLGET_WAITCHAN 22 /* get string used in msleep call */
339 #define CLSET_INTERRUPTIBLE 23 /* set interruptible flag */
340 #define CLGET_INTERRUPTIBLE 24 /* set interruptible flag */
341 #define CLSET_RETRIES 25 /* set retry count for reconnect */
342 #define CLGET_RETRIES 26 /* get retry count for reconnect */
351 #define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
352 #define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
356 * RPCTEST is a test program which is accessible on every rpc
357 * transport/port. It is used for testing, performance evaluation,
358 * and network administration.
361 #define RPCTEST_PROGRAM ((rpcprog_t)1)
362 #define RPCTEST_VERSION ((rpcvers_t)1)
363 #define RPCTEST_NULL_PROC ((rpcproc_t)2)
364 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3)
367 * By convention, procedure 0 takes null arguments and returns them
370 #define NULLPROC ((rpcproc_t)0)
373 * Below are the client handle creation routines for the various
374 * implementations of client side rpc. They can return NULL if a
375 * creation failure occurs.
379 * Generic client creation routine. Supported protocols are those that
380 * belong to the nettype namespace (/etc/netconfig).
386 * struct socket *so; -- socket
387 * struct sockaddr *svcaddr; -- servers address
388 * rpcprog_t prog; -- program number
389 * rpcvers_t vers; -- version number
390 * size_t sendsz; -- buffer recv size
391 * size_t recvsz; -- buffer send size
393 extern CLIENT *clnt_dg_create(struct socket *so,
394 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version,
395 size_t sendsz, size_t recvsz);
398 * struct socket *so; -- socket
399 * struct sockaddr *svcaddr; -- servers address
400 * rpcprog_t prog; -- program number
401 * rpcvers_t vers; -- version number
402 * size_t sendsz; -- buffer recv size
403 * size_t recvsz; -- buffer send size
405 extern CLIENT *clnt_vc_create(struct socket *so,
406 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version,
407 size_t sendsz, size_t recvsz);
410 * struct netconfig *nconf; -- network type
411 * struct sockaddr *svcaddr; -- servers address
412 * rpcprog_t prog; -- program number
413 * rpcvers_t vers; -- version number
414 * size_t sendsz; -- buffer recv size
415 * size_t recvsz; -- buffer send size
417 extern CLIENT *clnt_reconnect_create(struct netconfig *nconf,
418 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version,
419 size_t sendsz, size_t recvsz);
423 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
427 * const char *hostname; -- hostname
428 * const rpcprog_t prog; -- program number
429 * const rpcvers_t vers; -- version number
430 * const char *nettype; -- network type
434 * Generic client creation routine. Just like clnt_create(), except
435 * it takes an additional timeout parameter.
437 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
438 const rpcvers_t, const char *, const struct timeval *);
441 * const char *hostname; -- hostname
442 * const rpcprog_t prog; -- program number
443 * const rpcvers_t vers; -- version number
444 * const char *nettype; -- network type
445 * const struct timeval *tp; -- timeout
449 * Generic client creation routine. Supported protocols are which belong
450 * to the nettype name space.
452 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
453 const rpcvers_t, const rpcvers_t,
456 * const char *host; -- hostname
457 * const rpcprog_t prog; -- program number
458 * rpcvers_t *vers_out; -- servers highest available version
459 * const rpcvers_t vers_low; -- low version number
460 * const rpcvers_t vers_high; -- high version number
461 * const char *nettype; -- network type
465 * Generic client creation routine. Supported protocols are which belong
466 * to the nettype name space.
468 extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t,
469 rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *,
470 const struct timeval *);
472 * const char *host; -- hostname
473 * const rpcprog_t prog; -- program number
474 * rpcvers_t *vers_out; -- servers highest available version
475 * const rpcvers_t vers_low; -- low version number
476 * const rpcvers_t vers_high; -- high version number
477 * const char *nettype; -- network type
478 * const struct timeval *tp -- timeout
482 * Generic client creation routine. It takes a netconfig structure
485 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
486 const rpcvers_t, const struct netconfig *);
488 * const char *hostname; -- hostname
489 * const rpcprog_t prog; -- program number
490 * const rpcvers_t vers; -- version number
491 * const struct netconfig *netconf; -- network config structure
495 * Generic client creation routine. Just like clnt_tp_create(), except
496 * it takes an additional timeout parameter.
498 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
499 const rpcvers_t, const struct netconfig *, const struct timeval *);
501 * const char *hostname; -- hostname
502 * const rpcprog_t prog; -- program number
503 * const rpcvers_t vers; -- version number
504 * const struct netconfig *netconf; -- network config structure
505 * const struct timeval *tp -- timeout
509 * Generic TLI create routine. Only provided for compatibility.
512 extern CLIENT *clnt_tli_create(const int, const struct netconfig *,
513 struct netbuf *, const rpcprog_t,
514 const rpcvers_t, const u_int, const u_int);
516 * const register int fd; -- fd
517 * const struct netconfig *nconf; -- netconfig structure
518 * struct netbuf *svcaddr; -- servers address
519 * const u_long prog; -- program number
520 * const u_long vers; -- version number
521 * const u_int sendsz; -- send size
522 * const u_int recvsz; -- recv size
526 * Low level clnt create routine for connectionful transports, e.g. tcp.
528 extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
529 const rpcprog_t, const rpcvers_t,
532 * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
534 extern CLIENT *clntunix_create(struct sockaddr_un *,
535 u_long, u_long, int *, u_int, u_int);
537 * const int fd; -- open file descriptor
538 * const struct netbuf *svcaddr; -- servers address
539 * const rpcprog_t prog; -- program number
540 * const rpcvers_t vers; -- version number
541 * const u_int sendsz; -- buffer recv size
542 * const u_int recvsz; -- buffer send size
546 * Low level clnt create routine for connectionless transports, e.g. udp.
548 extern CLIENT *clnt_dg_create(const int, const struct netbuf *,
549 const rpcprog_t, const rpcvers_t,
550 const u_int, const u_int);
552 * const int fd; -- open file descriptor
553 * const struct netbuf *svcaddr; -- servers address
554 * const rpcprog_t program; -- program number
555 * const rpcvers_t version; -- version number
556 * const u_int sendsz; -- buffer recv size
557 * const u_int recvsz; -- buffer send size
561 * Memory based rpc (for speed check and testing)
563 * clnt_raw_create(prog, vers)
567 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
574 * Print why creation failed
577 extern void clnt_pcreateerror(const char *); /* stderr */
578 extern char *clnt_spcreateerror(const char *); /* string */
582 * Like clnt_perror(), but is more verbose in its output
585 extern void clnt_perrno(enum clnt_stat); /* stderr */
586 extern char *clnt_sperrno(enum clnt_stat); /* string */
590 * Print an English error message, given the client error code
593 extern void clnt_perror(CLIENT *, const char *); /* stderr */
594 extern char *clnt_sperror(CLIENT *, const char *); /* string */
599 * If a creation fails, the following allows the user to figure out why.
601 struct rpc_createerr {
602 enum clnt_stat cf_stat;
603 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
607 extern struct rpc_createerr rpc_createerr;
610 extern struct rpc_createerr *__rpc_createerr(void);
612 #define rpc_createerr (*(__rpc_createerr()))
617 * The simplified interface:
619 * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
621 * const rpcprog_t prognum;
622 * const rpcvers_t versnum;
623 * const rpcproc_t procnum;
624 * const xdrproc_t inproc, outproc;
627 * const char *nettype;
630 extern enum clnt_stat rpc_call(const char *, const rpcprog_t,
631 const rpcvers_t, const rpcproc_t,
632 const xdrproc_t, const char *,
633 const xdrproc_t, char *, const char *);
637 * RPC broadcast interface
638 * The call is broadcasted to all locally connected nets.
640 * extern enum clnt_stat
641 * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
642 * eachresult, nettype)
643 * const rpcprog_t prog; -- program number
644 * const rpcvers_t vers; -- version number
645 * const rpcproc_t proc; -- procedure number
646 * const xdrproc_t xargs; -- xdr routine for args
647 * caddr_t argsp; -- pointer to args
648 * const xdrproc_t xresults; -- xdr routine for results
649 * caddr_t resultsp; -- pointer to results
650 * const resultproc_t eachresult; -- call with each result
651 * const char *nettype; -- Transport type
653 * For each valid response received, the procedure eachresult is called.
655 * done = eachresult(resp, raddr, nconf)
658 * struct netbuf *raddr;
659 * struct netconfig *nconf;
660 * where resp points to the results of the call and raddr is the
661 * address if the responder to the broadcast. nconf is the transport
662 * on which the response was received.
664 * extern enum clnt_stat
665 * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp,
666 * eachresult, inittime, waittime, nettype)
667 * const rpcprog_t prog; -- program number
668 * const rpcvers_t vers; -- version number
669 * const rpcproc_t proc; -- procedure number
670 * const xdrproc_t xargs; -- xdr routine for args
671 * caddr_t argsp; -- pointer to args
672 * const xdrproc_t xresults; -- xdr routine for results
673 * caddr_t resultsp; -- pointer to results
674 * const resultproc_t eachresult; -- call with each result
675 * const int inittime; -- how long to wait initially
676 * const int waittime; -- maximum time to wait
677 * const char *nettype; -- Transport type
680 typedef bool_t (*resultproc_t)(caddr_t, ...);
683 extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t,
684 const rpcproc_t, const xdrproc_t,
685 caddr_t, const xdrproc_t, caddr_t,
686 const resultproc_t, const char *);
687 extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t,
688 const rpcproc_t, const xdrproc_t,
689 caddr_t, const xdrproc_t, caddr_t,
690 const resultproc_t, const int,
691 const int, const char *);
694 /* For backward compatibility */
695 #include <rpc/clnt_soc.h>
698 #endif /* !_RPC_CLNT_H_ */