xref: /freebsd/include/rpc/clnt.h (revision 9336e0699bda8a301cd2bfa37106b6ec5e32012e)
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$
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 #include <netconfig.h>
65 #include <sys/un.h>
66 
67 /*
68  * Well-known IPV6 RPC broadcast address.
69  */
70 #define RPCB_MULTICAST_ADDR "ff02::202"
71 
72 /*
73  * the following errors are in general unrecoverable.  The caller
74  * should give up rather than retry.
75  */
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))
84 
85 /*
86  * Error info.
87  */
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
106 };
107 
108 
109 /*
110  * Client rpc handle.
111  * Created by individual implementations
112  * Client is responsible for initializing auth, see e.g. auth_none.c.
113  */
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;
139 
140 
141 /*
142  * Timers used for the pseudo-transport protocol when using datagrams
143  */
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 */
148 };
149 
150 /*
151  * Feedback values used for possible congestion and rate control
152  */
153 #define FEEDBACK_REXMIT1	1	/* first retransmit */
154 #define FEEDBACK_OK		2	/* no retransmits */
155 
156 /* Used to set version of portmapper used in broadcast */
157 
158 #define CLCR_SET_LOWVERS	3
159 #define CLCR_GET_LOWVERS	4
160 
161 #define RPCSMALLMSGSIZE 400	/* a more reasonable packet size */
162 
163 /*
164  * client side rpc interface ops
165  *
166  * Parameter types are:
167  *
168  */
169 
170 /*
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;
180  */
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))
187 
188 /*
189  * void
190  * CLNT_ABORT(rh);
191  * 	CLIENT *rh;
192  */
193 #define	CLNT_ABORT(rh)	((*(rh)->cl_ops->cl_abort)(rh))
194 #define	clnt_abort(rh)	((*(rh)->cl_ops->cl_abort)(rh))
195 
196 /*
197  * struct rpc_err
198  * CLNT_GETERR(rh);
199  * 	CLIENT *rh;
200  */
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))
203 
204 
205 /*
206  * bool_t
207  * CLNT_FREERES(rh, xres, resp);
208  * 	CLIENT *rh;
209  *	xdrproc_t xres;
210  *	void *resp;
211  */
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))
214 
215 /*
216  * bool_t
217  * CLNT_CONTROL(cl, request, info)
218  *      CLIENT *cl;
219  *      u_int request;
220  *      char *info;
221  */
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))
224 
225 /*
226  * control operations that apply to both udp and tcp transports
227  */
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 */
244 /*
245  * Connectionless only control operations
246  */
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) */
251 
252 /*
253  * void
254  * CLNT_DESTROY(rh);
255  * 	CLIENT *rh;
256  */
257 #define	CLNT_DESTROY(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
258 #define	clnt_destroy(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
259 
260 
261 /*
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.
265  */
266 
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)
271 
272 /*
273  * By convention, procedure 0 takes null arguments and returns them
274  */
275 
276 #define NULLPROC ((rpcproc_t)0)
277 
278 /*
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.
282  */
283 
284 /*
285  * Generic client creation routine. Supported protocols are those that
286  * belong to the nettype namespace (/etc/netconfig).
287  */
288 __BEGIN_DECLS
289 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
290 			   const char *);
291 /*
292  *
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
297  */
298 
299  /*
300  * Generic client creation routine. Just like clnt_create(), except
301  * it takes an additional timeout parameter.
302  */
303 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
304 	const rpcvers_t, const char *, const struct timeval *);
305 /*
306  *
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
312  */
313 
314 /*
315  * Generic client creation routine. Supported protocols are which belong
316  * to the nettype name space.
317  */
318 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
319 				const rpcvers_t, const rpcvers_t,
320 				const char *);
321 /*
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
328  */
329 
330 /*
331  * Generic client creation routine. Supported protocols are which belong
332  * to the nettype name space.
333  */
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 *);
337 /*
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
345  */
346 
347 /*
348  * Generic client creation routine. It takes a netconfig structure
349  * instead of nettype
350  */
351 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
352 			      const rpcvers_t, const struct netconfig *);
353 /*
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
358  */
359 
360 /*
361  * Generic client creation routine. Just like clnt_tp_create(), except
362  * it takes an additional timeout parameter.
363  */
364 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
365 	const rpcvers_t, const struct netconfig *, const struct timeval *);
366 /*
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
372  */
373 
374 /*
375  * Generic TLI create routine. Only provided for compatibility.
376  */
377 
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);
381 /*
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
389  */
390 
391 /*
392  * Low level clnt create routine for connectionful transports, e.g. tcp.
393  */
394 extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
395 			      const rpcprog_t, const rpcvers_t,
396 			      u_int, u_int);
397 /*
398  * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
399  */
400 extern CLIENT *clntunix_create(struct sockaddr_un *,
401 			       u_long, u_long, int *, u_int, u_int);
402 /*
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
409  */
410 
411 /*
412  * Low level clnt create routine for connectionless transports, e.g. udp.
413  */
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);
417 /*
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
424  */
425 
426 /*
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;
432  */
433 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
434 
435 __END_DECLS
436 
437 
438 /*
439  * Print why creation failed
440  */
441 __BEGIN_DECLS
442 extern void clnt_pcreateerror(const char *);			/* stderr */
443 extern char *clnt_spcreateerror(const char *);			/* string */
444 __END_DECLS
445 
446 /*
447  * Like clnt_perror(), but is more verbose in its output
448  */
449 __BEGIN_DECLS
450 extern void clnt_perrno(enum clnt_stat);		/* stderr */
451 extern char *clnt_sperrno(enum clnt_stat);		/* string */
452 __END_DECLS
453 
454 /*
455  * Print an English error message, given the client error code
456  */
457 __BEGIN_DECLS
458 extern void clnt_perror(CLIENT *, const char *);	 	/* stderr */
459 extern char *clnt_sperror(CLIENT *, const char *);		/* string */
460 __END_DECLS
461 
462 
463 /*
464  * If a creation fails, the following allows the user to figure out why.
465  */
466 struct rpc_createerr {
467 	enum clnt_stat cf_stat;
468 	struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
469 };
470 
471 __BEGIN_DECLS
472 extern struct rpc_createerr	*__rpc_createerr(void);
473 __END_DECLS
474 #define rpc_createerr		(*(__rpc_createerr()))
475 
476 /*
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;
488  */
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
495 
496 /*
497  * RPC broadcast interface
498  * The call is broadcasted to all locally connected nets.
499  *
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
512  *
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.
523  *
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
538  */
539 
540 typedef bool_t (*resultproc_t)(caddr_t, ...);
541 
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
553 
554 /* For backward compatibility */
555 #include <rpc/clnt_soc.h>
556 
557 #endif /* !_RPC_CLNT_H_ */
558