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