1 /* $NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $ */
4 * Copyright (c) 2010, Oracle America, Inc.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met:
9 * - Redistributions of source code must retain the above copyright notice,
10 * this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright notice,
12 * this list of conditions and the following disclaimer in the documentation
13 * and/or other materials provided with the distribution.
14 * - Neither the name of the "Oracle America, Inc." nor the names of its
15 * contributors may be used to endorse or promote products derived
16 * from this software without specific prior written permission.
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 * POSSIBILITY OF SUCH DAMAGE.
30 * from: @(#)clnt.h 1.31 94/04/29 SMI
31 * from: @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC
36 * clnt.h - Client side remote procedure call interface.
41 #include <rpc/clnt_stat.h>
42 #include <sys/cdefs.h>
43 #include <netconfig.h>
47 * Well-known IPV6 RPC broadcast address.
49 #define RPCB_MULTICAST_ADDR "ff02::202"
52 * the following errors are in general unrecoverable. The caller
53 * should give up rather than retry.
55 #define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \
56 ((s) == RPC_CANTENCODEARGS) || \
57 ((s) == RPC_CANTDECODERES) || \
58 ((s) == RPC_VERSMISMATCH) || \
59 ((s) == RPC_PROCUNAVAIL) || \
60 ((s) == RPC_PROGUNAVAIL) || \
61 ((s) == RPC_PROGVERSMISMATCH) || \
62 ((s) == RPC_CANTDECODEARGS))
68 enum clnt_stat re_status;
70 int RE_errno; /* related system error */
71 enum auth_stat RE_why; /* why the auth error occurred */
73 rpcvers_t low; /* lowest version supported */
74 rpcvers_t high; /* highest version supported */
76 struct { /* maybe meaningful if RPC_FAILED */
79 } RE_lb; /* life boot & debugging only */
81 #define re_errno ru.RE_errno
82 #define re_why ru.RE_why
83 #define re_vers ru.RE_vers
84 #define re_lb ru.RE_lb
90 * Created by individual implementations
91 * Client is responsible for initializing auth, see e.g. auth_none.c.
93 typedef struct __rpc_client {
94 AUTH *cl_auth; /* authenticator */
96 /* call remote procedure */
97 enum clnt_stat (*cl_call)(struct __rpc_client *,
98 rpcproc_t, xdrproc_t, void *, xdrproc_t,
99 void *, struct timeval);
101 void (*cl_abort)(struct __rpc_client *);
102 /* get specific error code */
103 void (*cl_geterr)(struct __rpc_client *,
106 bool_t (*cl_freeres)(struct __rpc_client *,
108 /* destroy this structure */
109 void (*cl_destroy)(struct __rpc_client *);
110 /* the ioctl() of rpc */
111 bool_t (*cl_control)(struct __rpc_client *, u_int,
114 void *cl_private; /* private stuff */
115 char *cl_netid; /* network token */
116 char *cl_tp; /* device name */
121 * Timers used for the pseudo-transport protocol when using datagrams
124 u_short rt_srtt; /* smoothed round-trip time */
125 u_short rt_deviate; /* estimated deviation */
126 u_long rt_rtxcur; /* current (backed-off) rto */
130 * Feedback values used for possible congestion and rate control
132 #define FEEDBACK_REXMIT1 1 /* first retransmit */
133 #define FEEDBACK_OK 2 /* no retransmits */
135 /* Used to set version of portmapper used in broadcast */
137 #define CLCR_SET_LOWVERS 3
138 #define CLCR_GET_LOWVERS 4
140 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */
143 * client side rpc interface ops
145 * Parameter types are:
151 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
158 * struct timeval timeout;
160 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
161 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
162 argsp, xres, resp, secs))
163 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
164 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
165 argsp, xres, resp, secs))
172 #define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh))
173 #define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh))
180 #define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
181 #define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
186 * CLNT_FREERES(rh, xres, resp);
191 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
192 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
196 * CLNT_CONTROL(cl, request, info)
201 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
202 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
205 * control operations that apply to both udp and tcp transports
207 #define CLSET_TIMEOUT 1 /* set timeout (timeval) */
208 #define CLGET_TIMEOUT 2 /* get timeout (timeval) */
209 #define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */
210 #define CLGET_FD 6 /* get connections file descriptor */
211 #define CLGET_SVC_ADDR 7 /* get server's address (netbuf) */
212 #define CLSET_FD_CLOSE 8 /* close fd while clnt_destroy */
213 #define CLSET_FD_NCLOSE 9 /* Do not close fd while clnt_destroy */
214 #define CLGET_XID 10 /* Get xid */
215 #define CLSET_XID 11 /* Set xid */
216 #define CLGET_VERS 12 /* Get version number */
217 #define CLSET_VERS 13 /* Set version number */
218 #define CLGET_PROG 14 /* Get program number */
219 #define CLSET_PROG 15 /* Set program number */
220 #define CLSET_SVC_ADDR 16 /* get server's address (netbuf) */
221 #define CLSET_PUSH_TIMOD 17 /* push timod if not already present */
222 #define CLSET_POP_TIMOD 18 /* pop timod */
224 * Connectionless only control operations
226 #define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */
227 #define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */
228 #define CLSET_ASYNC 19
229 #define CLSET_CONNECT 20 /* Use connect() for UDP. (int) */
236 #define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
237 #define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
241 * RPCTEST is a test program which is accessible on every rpc
242 * transport/port. It is used for testing, performance evaluation,
243 * and network administration.
246 #define RPCTEST_PROGRAM ((rpcprog_t)1)
247 #define RPCTEST_VERSION ((rpcvers_t)1)
248 #define RPCTEST_NULL_PROC ((rpcproc_t)2)
249 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3)
252 * By convention, procedure 0 takes null arguments and returns them
255 #define NULLPROC ((rpcproc_t)0)
258 * Below are the client handle creation routines for the various
259 * implementations of client side rpc. They can return NULL if a
260 * creation failure occurs.
264 * Generic client creation routine. Supported protocols are those that
265 * belong to the nettype namespace (/etc/netconfig).
268 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
272 * const char *hostname; -- hostname
273 * const rpcprog_t prog; -- program number
274 * const rpcvers_t vers; -- version number
275 * const char *nettype; -- network type
279 * Generic client creation routine. Just like clnt_create(), except
280 * it takes an additional timeout parameter.
282 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
283 const rpcvers_t, const char *, const struct timeval *);
286 * const char *hostname; -- hostname
287 * const rpcprog_t prog; -- program number
288 * const rpcvers_t vers; -- version number
289 * const char *nettype; -- network type
290 * const struct timeval *tp; -- timeout
294 * Generic client creation routine. Supported protocols are which belong
295 * to the nettype name space.
297 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
298 const rpcvers_t, const rpcvers_t,
301 * const char *host; -- hostname
302 * const rpcprog_t prog; -- program number
303 * rpcvers_t *vers_out; -- servers highest available version
304 * const rpcvers_t vers_low; -- low version number
305 * const rpcvers_t vers_high; -- high version number
306 * const char *nettype; -- network type
310 * Generic client creation routine. Supported protocols are which belong
311 * to the nettype name space.
313 extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t,
314 rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *,
315 const struct timeval *);
317 * const char *host; -- hostname
318 * const rpcprog_t prog; -- program number
319 * rpcvers_t *vers_out; -- servers highest available version
320 * const rpcvers_t vers_low; -- low version number
321 * const rpcvers_t vers_high; -- high version number
322 * const char *nettype; -- network type
323 * const struct timeval *tp -- timeout
327 * Generic client creation routine. It takes a netconfig structure
330 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
331 const rpcvers_t, const struct netconfig *);
333 * const char *hostname; -- hostname
334 * const rpcprog_t prog; -- program number
335 * const rpcvers_t vers; -- version number
336 * const struct netconfig *netconf; -- network config structure
340 * Generic client creation routine. Just like clnt_tp_create(), except
341 * it takes an additional timeout parameter.
343 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
344 const rpcvers_t, const struct netconfig *, const struct timeval *);
346 * const char *hostname; -- hostname
347 * const rpcprog_t prog; -- program number
348 * const rpcvers_t vers; -- version number
349 * const struct netconfig *netconf; -- network config structure
350 * const struct timeval *tp -- timeout
354 * Generic TLI create routine. Only provided for compatibility.
357 extern CLIENT *clnt_tli_create(const int, const struct netconfig *,
358 struct netbuf *, const rpcprog_t,
359 const rpcvers_t, const u_int, const u_int);
361 * const register int fd; -- fd
362 * const struct netconfig *nconf; -- netconfig structure
363 * struct netbuf *svcaddr; -- servers address
364 * const u_long prog; -- program number
365 * const u_long vers; -- version number
366 * const u_int sendsz; -- send size
367 * const u_int recvsz; -- recv size
371 * Low level clnt create routine for connectionful transports, e.g. tcp.
373 extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
374 const rpcprog_t, const rpcvers_t,
377 * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
379 extern CLIENT *clntunix_create(struct sockaddr_un *,
380 u_long, u_long, int *, u_int, u_int);
382 * const int fd; -- open file descriptor
383 * const struct netbuf *svcaddr; -- servers address
384 * const rpcprog_t prog; -- program number
385 * const rpcvers_t vers; -- version number
386 * const u_int sendsz; -- buffer recv size
387 * const u_int recvsz; -- buffer send size
391 * Low level clnt create routine for connectionless transports, e.g. udp.
393 extern CLIENT *clnt_dg_create(const int, const struct netbuf *,
394 const rpcprog_t, const rpcvers_t,
395 const u_int, const u_int);
397 * const int fd; -- open file descriptor
398 * const struct netbuf *svcaddr; -- servers address
399 * const rpcprog_t program; -- program number
400 * const rpcvers_t version; -- version number
401 * const u_int sendsz; -- buffer recv size
402 * const u_int recvsz; -- buffer send size
406 * Memory based rpc (for speed check and testing)
408 * clnt_raw_create(prog, vers)
412 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
418 * Print why creation failed
421 extern void clnt_pcreateerror(const char *); /* stderr */
422 extern char *clnt_spcreateerror(const char *); /* string */
426 * Like clnt_perror(), but is more verbose in its output
429 extern void clnt_perrno(enum clnt_stat); /* stderr */
430 extern char *clnt_sperrno(enum clnt_stat); /* string */
434 * Print an English error message, given the client error code
437 extern void clnt_perror(CLIENT *, const char *); /* stderr */
438 extern char *clnt_sperror(CLIENT *, const char *); /* string */
443 * If a creation fails, the following allows the user to figure out why.
445 struct rpc_createerr {
446 enum clnt_stat cf_stat;
447 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
451 extern struct rpc_createerr *__rpc_createerr(void);
453 #define rpc_createerr (*(__rpc_createerr()))
456 * The simplified interface:
458 * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
460 * const rpcprog_t prognum;
461 * const rpcvers_t versnum;
462 * const rpcproc_t procnum;
463 * const xdrproc_t inproc, outproc;
466 * const char *nettype;
469 extern enum clnt_stat rpc_call(const char *, const rpcprog_t,
470 const rpcvers_t, const rpcproc_t,
471 const xdrproc_t, const char *,
472 const xdrproc_t, char *, const char *);
476 * RPC broadcast interface
477 * The call is broadcasted to all locally connected nets.
479 * extern enum clnt_stat
480 * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
481 * eachresult, nettype)
482 * const rpcprog_t prog; -- program number
483 * const rpcvers_t vers; -- version number
484 * const rpcproc_t proc; -- procedure number
485 * const xdrproc_t xargs; -- xdr routine for args
486 * caddr_t argsp; -- pointer to args
487 * const xdrproc_t xresults; -- xdr routine for results
488 * caddr_t resultsp; -- pointer to results
489 * const resultproc_t eachresult; -- call with each result
490 * const char *nettype; -- Transport type
492 * For each valid response received, the procedure eachresult is called.
494 * done = eachresult(resp, raddr, nconf)
497 * struct netbuf *raddr;
498 * struct netconfig *nconf;
499 * where resp points to the results of the call and raddr is the
500 * address if the responder to the broadcast. nconf is the transport
501 * on which the response was received.
503 * extern enum clnt_stat
504 * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp,
505 * eachresult, inittime, waittime, nettype)
506 * const rpcprog_t prog; -- program number
507 * const rpcvers_t vers; -- version number
508 * const rpcproc_t proc; -- procedure number
509 * const xdrproc_t xargs; -- xdr routine for args
510 * caddr_t argsp; -- pointer to args
511 * const xdrproc_t xresults; -- xdr routine for results
512 * caddr_t resultsp; -- pointer to results
513 * const resultproc_t eachresult; -- call with each result
514 * const int inittime; -- how long to wait initially
515 * const int waittime; -- maximum time to wait
516 * const char *nettype; -- Transport type
519 typedef bool_t (*resultproc_t)(caddr_t, ...);
522 extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t,
523 const rpcproc_t, const xdrproc_t,
524 caddr_t, const xdrproc_t, caddr_t,
525 const resultproc_t, const char *);
526 extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t,
527 const rpcproc_t, const xdrproc_t,
528 caddr_t, const xdrproc_t, caddr_t,
529 const resultproc_t, const int,
530 const int, const char *);
533 /* For backward compatibility */
534 #include <rpc/clnt_soc.h>
536 #endif /* !_RPC_CLNT_H_ */