xref: /freebsd/include/rpc/clnt.h (revision 5e3190f700637fcfc1a52daeaa4a031fdd2557c7)
1 /*	$NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $	*/
2 
3 /*-
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  * Copyright (c) 2010, Oracle America, Inc.
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions are met:
11  * - Redistributions of source code must retain the above copyright notice,
12  *   this list of conditions and the following disclaimer.
13  * - Redistributions in binary form must reproduce the above copyright notice,
14  *   this list of conditions and the following disclaimer in the documentation
15  *   and/or other materials provided with the distribution.
16  * - Neither the name of the "Oracle America, Inc." nor the names of its
17  *   contributors may be used to endorse or promote products derived
18  *   from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
24  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  *
32  *	from: @(#)clnt.h 1.31 94/04/29 SMI
33  *	from: @(#)clnt.h	2.1 88/07/29 4.0 RPCSRC
34  */
35 
36 /*
37  * clnt.h - Client side remote procedure call interface.
38  */
39 
40 #ifndef _RPC_CLNT_H_
41 #define _RPC_CLNT_H_
42 #include <rpc/clnt_stat.h>
43 #include <sys/cdefs.h>
44 #include <netconfig.h>
45 #include <sys/un.h>
46 
47 /*
48  * Well-known IPV6 RPC broadcast address.
49  */
50 #define RPCB_MULTICAST_ADDR "ff02::202"
51 
52 /*
53  * the following errors are in general unrecoverable.  The caller
54  * should give up rather than retry.
55  */
56 #define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \
57 	((s) == RPC_CANTENCODEARGS) || \
58 	((s) == RPC_CANTDECODERES) || \
59 	((s) == RPC_VERSMISMATCH) || \
60 	((s) == RPC_PROCUNAVAIL) || \
61 	((s) == RPC_PROGUNAVAIL) || \
62 	((s) == RPC_PROGVERSMISMATCH) || \
63 	((s) == RPC_CANTDECODEARGS))
64 
65 /*
66  * Error info.
67  */
68 struct rpc_err {
69 	enum clnt_stat re_status;
70 	union {
71 		int RE_errno;		/* related system error */
72 		enum auth_stat RE_why;	/* why the auth error occurred */
73 		struct {
74 			rpcvers_t low;	/* lowest version supported */
75 			rpcvers_t high;	/* highest version supported */
76 		} RE_vers;
77 		struct {		/* maybe meaningful if RPC_FAILED */
78 			int32_t s1;
79 			int32_t s2;
80 		} RE_lb;		/* life boot & debugging only */
81 	} ru;
82 #define	re_errno	ru.RE_errno
83 #define	re_why		ru.RE_why
84 #define	re_vers		ru.RE_vers
85 #define	re_lb		ru.RE_lb
86 };
87 
88 
89 /*
90  * Client rpc handle.
91  * Created by individual implementations
92  * Client is responsible for initializing auth, see e.g. auth_none.c.
93  */
94 typedef struct __rpc_client {
95 	AUTH	*cl_auth;			/* authenticator */
96 	struct clnt_ops {
97 		/* call remote procedure */
98 		enum clnt_stat	(*cl_call)(struct __rpc_client *,
99 				    rpcproc_t, xdrproc_t, void *, xdrproc_t,
100 				        void *, struct timeval);
101 		/* abort a call */
102 		void		(*cl_abort)(struct __rpc_client *);
103 		/* get specific error code */
104 		void		(*cl_geterr)(struct __rpc_client *,
105 					struct rpc_err *);
106 		/* frees results */
107 		bool_t		(*cl_freeres)(struct __rpc_client *,
108 					xdrproc_t, void *);
109 		/* destroy this structure */
110 		void		(*cl_destroy)(struct __rpc_client *);
111 		/* the ioctl() of rpc */
112 		bool_t          (*cl_control)(struct __rpc_client *, u_int,
113 				    void *);
114 	} *cl_ops;
115 	void 			*cl_private;	/* private stuff */
116 	char			*cl_netid;	/* network token */
117 	char			*cl_tp;		/* device name */
118 } CLIENT;
119 
120 
121 /*
122  * Timers used for the pseudo-transport protocol when using datagrams
123  */
124 struct rpc_timers {
125 	u_short		rt_srtt;	/* smoothed round-trip time */
126 	u_short		rt_deviate;	/* estimated deviation */
127 	u_long		rt_rtxcur;	/* current (backed-off) rto */
128 };
129 
130 /*
131  * Feedback values used for possible congestion and rate control
132  */
133 #define FEEDBACK_REXMIT1	1	/* first retransmit */
134 #define FEEDBACK_OK		2	/* no retransmits */
135 
136 /* Used to set version of portmapper used in broadcast */
137 
138 #define CLCR_SET_LOWVERS	3
139 #define CLCR_GET_LOWVERS	4
140 
141 #define RPCSMALLMSGSIZE 400	/* a more reasonable packet size */
142 
143 /*
144  * client side rpc interface ops
145  *
146  * Parameter types are:
147  *
148  */
149 
150 /*
151  * enum clnt_stat
152  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
153  * 	CLIENT *rh;
154  *	rpcproc_t proc;
155  *	xdrproc_t xargs;
156  *	void *argsp;
157  *	xdrproc_t xres;
158  *	void *resp;
159  *	struct timeval timeout;
160  */
161 #define	CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
162 	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
163 		argsp, xres, resp, secs))
164 #define	clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
165 	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
166 		argsp, xres, resp, secs))
167 
168 /*
169  * void
170  * CLNT_ABORT(rh);
171  * 	CLIENT *rh;
172  */
173 #define	CLNT_ABORT(rh)	((*(rh)->cl_ops->cl_abort)(rh))
174 #define	clnt_abort(rh)	((*(rh)->cl_ops->cl_abort)(rh))
175 
176 /*
177  * struct rpc_err
178  * CLNT_GETERR(rh);
179  * 	CLIENT *rh;
180  */
181 #define	CLNT_GETERR(rh,errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
182 #define	clnt_geterr(rh,errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
183 
184 
185 /*
186  * bool_t
187  * CLNT_FREERES(rh, xres, resp);
188  * 	CLIENT *rh;
189  *	xdrproc_t xres;
190  *	void *resp;
191  */
192 #define	CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
193 #define	clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
194 
195 /*
196  * bool_t
197  * CLNT_CONTROL(cl, request, info)
198  *      CLIENT *cl;
199  *      u_int request;
200  *      char *info;
201  */
202 #define	CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
203 #define	clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
204 
205 /*
206  * control operations that apply to both udp and tcp transports
207  */
208 #define CLSET_TIMEOUT		1	/* set timeout (timeval) */
209 #define CLGET_TIMEOUT		2	/* get timeout (timeval) */
210 #define CLGET_SERVER_ADDR	3	/* get server's address (sockaddr) */
211 #define CLGET_FD		6	/* get connections file descriptor */
212 #define CLGET_SVC_ADDR		7	/* get server's address (netbuf) */
213 #define CLSET_FD_CLOSE		8	/* close fd while clnt_destroy */
214 #define CLSET_FD_NCLOSE		9	/* Do not close fd while clnt_destroy */
215 #define CLGET_XID 		10	/* Get xid */
216 #define CLSET_XID		11	/* Set xid */
217 #define CLGET_VERS		12	/* Get version number */
218 #define CLSET_VERS		13	/* Set version number */
219 #define CLGET_PROG		14	/* Get program number */
220 #define CLSET_PROG		15	/* Set program number */
221 #define CLSET_SVC_ADDR		16	/* get server's address (netbuf) */
222 #define CLSET_PUSH_TIMOD	17	/* push timod if not already present */
223 #define CLSET_POP_TIMOD		18	/* pop timod */
224 /*
225  * Connectionless only control operations
226  */
227 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
228 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
229 #define CLSET_ASYNC		19
230 #define CLSET_CONNECT		20	/* Use connect() for UDP. (int) */
231 
232 /*
233  * void
234  * CLNT_DESTROY(rh);
235  * 	CLIENT *rh;
236  */
237 #define	CLNT_DESTROY(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
238 #define	clnt_destroy(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
239 
240 
241 /*
242  * RPCTEST is a test program which is accessible on every rpc
243  * transport/port.  It is used for testing, performance evaluation,
244  * and network administration.
245  */
246 
247 #define RPCTEST_PROGRAM		((rpcprog_t)1)
248 #define RPCTEST_VERSION		((rpcvers_t)1)
249 #define RPCTEST_NULL_PROC	((rpcproc_t)2)
250 #define RPCTEST_NULL_BATCH_PROC	((rpcproc_t)3)
251 
252 /*
253  * By convention, procedure 0 takes null arguments and returns them
254  */
255 
256 #define NULLPROC ((rpcproc_t)0)
257 
258 /*
259  * Below are the client handle creation routines for the various
260  * implementations of client side rpc.  They can return NULL if a
261  * creation failure occurs.
262  */
263 
264 /*
265  * Generic client creation routine. Supported protocols are those that
266  * belong to the nettype namespace (/etc/netconfig).
267  */
268 __BEGIN_DECLS
269 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
270 			   const char *);
271 /*
272  *
273  * 	const char *hostname;			-- hostname
274  *	const rpcprog_t prog;			-- program number
275  *	const rpcvers_t vers;			-- version number
276  *	const char *nettype;			-- network type
277  */
278 
279  /*
280  * Generic client creation routine. Just like clnt_create(), except
281  * it takes an additional timeout parameter.
282  */
283 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
284 	const rpcvers_t, const char *, const struct timeval *);
285 /*
286  *
287  *	const char *hostname;			-- hostname
288  *	const rpcprog_t prog;			-- program number
289  *	const rpcvers_t vers;			-- version number
290  *	const char *nettype;			-- network type
291  *	const struct timeval *tp;		-- timeout
292  */
293 
294 /*
295  * Generic client creation routine. Supported protocols are which belong
296  * to the nettype name space.
297  */
298 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
299 				const rpcvers_t, const rpcvers_t,
300 				const char *);
301 /*
302  *	const char *host;		-- hostname
303  *	const rpcprog_t prog;		-- program number
304  *	rpcvers_t *vers_out;		-- servers highest available version
305  *	const rpcvers_t vers_low;	-- low version number
306  *	const rpcvers_t vers_high;	-- high version number
307  *	const char *nettype;		-- network type
308  */
309 
310 /*
311  * Generic client creation routine. Supported protocols are which belong
312  * to the nettype name space.
313  */
314 extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t,
315 	rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *,
316 	const struct timeval *);
317 /*
318  *	const char *host;		-- hostname
319  *	const rpcprog_t prog;		-- program number
320  *	rpcvers_t *vers_out;		-- servers highest available version
321  *	const rpcvers_t vers_low;	-- low version number
322  *	const rpcvers_t vers_high;	-- high version number
323  *	const char *nettype;		-- network type
324  *	const struct timeval *tp	-- timeout
325  */
326 
327 /*
328  * Generic client creation routine. It takes a netconfig structure
329  * instead of nettype
330  */
331 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
332 			      const rpcvers_t, const struct netconfig *);
333 /*
334  *	const char *hostname;			-- hostname
335  *	const rpcprog_t prog;			-- program number
336  *	const rpcvers_t vers;			-- version number
337  *	const struct netconfig *netconf; 	-- network config structure
338  */
339 
340 /*
341  * Generic client creation routine. Just like clnt_tp_create(), except
342  * it takes an additional timeout parameter.
343  */
344 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
345 	const rpcvers_t, const struct netconfig *, const struct timeval *);
346 /*
347  *	const char *hostname;			-- hostname
348  *	const rpcprog_t prog;			-- program number
349  *	const rpcvers_t vers;			-- version number
350  *	const struct netconfig *netconf; 	-- network config structure
351  *	const struct timeval *tp		-- timeout
352  */
353 
354 /*
355  * Generic TLI create routine. Only provided for compatibility.
356  */
357 
358 extern CLIENT *clnt_tli_create(const int, const struct netconfig *,
359 			       struct netbuf *, const rpcprog_t,
360 			       const rpcvers_t, const u_int, const u_int);
361 /*
362  *	const register int fd;		-- fd
363  *	const struct netconfig *nconf;	-- netconfig structure
364  *	struct netbuf *svcaddr;		-- servers address
365  *	const u_long prog;			-- program number
366  *	const u_long vers;			-- version number
367  *	const u_int sendsz;			-- send size
368  *	const u_int recvsz;			-- recv size
369  */
370 
371 /*
372  * Low level clnt create routine for connectionful transports, e.g. tcp.
373  */
374 extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
375 			      const rpcprog_t, const rpcvers_t,
376 			      u_int, u_int);
377 /*
378  * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
379  */
380 extern CLIENT *clntunix_create(struct sockaddr_un *,
381 			       u_long, u_long, int *, u_int, u_int);
382 /*
383  *	const int fd;				-- open file descriptor
384  *	const struct netbuf *svcaddr;		-- servers address
385  *	const rpcprog_t prog;			-- program number
386  *	const rpcvers_t vers;			-- version number
387  *	const u_int sendsz;			-- buffer recv size
388  *	const u_int recvsz;			-- buffer send size
389  */
390 
391 /*
392  * Low level clnt create routine for connectionless transports, e.g. udp.
393  */
394 extern CLIENT *clnt_dg_create(const int, const struct netbuf *,
395 			      const rpcprog_t, const rpcvers_t,
396 			      const u_int, const u_int);
397 /*
398  *	const int fd;				-- open file descriptor
399  *	const struct netbuf *svcaddr;		-- servers address
400  *	const rpcprog_t program;		-- program number
401  *	const rpcvers_t version;		-- version number
402  *	const u_int sendsz;			-- buffer recv size
403  *	const u_int recvsz;			-- buffer send size
404  */
405 
406 /*
407  * Memory based rpc (for speed check and testing)
408  * CLIENT *
409  * clnt_raw_create(prog, vers)
410  *	u_long prog;
411  *	u_long vers;
412  */
413 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
414 
415 __END_DECLS
416 
417 
418 /*
419  * Print why creation failed
420  */
421 __BEGIN_DECLS
422 extern void clnt_pcreateerror(const char *);			/* stderr */
423 extern char *clnt_spcreateerror(const char *);			/* string */
424 __END_DECLS
425 
426 /*
427  * Like clnt_perror(), but is more verbose in its output
428  */
429 __BEGIN_DECLS
430 extern void clnt_perrno(enum clnt_stat);		/* stderr */
431 extern char *clnt_sperrno(enum clnt_stat);		/* string */
432 __END_DECLS
433 
434 /*
435  * Print an English error message, given the client error code
436  */
437 __BEGIN_DECLS
438 extern void clnt_perror(CLIENT *, const char *);	 	/* stderr */
439 extern char *clnt_sperror(CLIENT *, const char *);		/* string */
440 __END_DECLS
441 
442 
443 /*
444  * If a creation fails, the following allows the user to figure out why.
445  */
446 struct rpc_createerr {
447 	enum clnt_stat cf_stat;
448 	struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
449 };
450 
451 __BEGIN_DECLS
452 extern struct rpc_createerr	*__rpc_createerr(void);
453 __END_DECLS
454 #define rpc_createerr		(*(__rpc_createerr()))
455 
456 /*
457  * The simplified interface:
458  * enum clnt_stat
459  * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
460  *	const char *host;
461  *	const rpcprog_t prognum;
462  *	const rpcvers_t versnum;
463  *	const rpcproc_t procnum;
464  *	const xdrproc_t inproc, outproc;
465  *	const char *in;
466  *	char *out;
467  *	const char *nettype;
468  */
469 __BEGIN_DECLS
470 extern enum clnt_stat rpc_call(const char *, const rpcprog_t,
471 			       const rpcvers_t, const rpcproc_t,
472 			       const xdrproc_t, const char *,
473 			       const xdrproc_t, char *, const char *);
474 __END_DECLS
475 
476 /*
477  * RPC broadcast interface
478  * The call is broadcasted to all locally connected nets.
479  *
480  * extern enum clnt_stat
481  * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
482  *			eachresult, nettype)
483  *	const rpcprog_t		prog;		-- program number
484  *	const rpcvers_t		vers;		-- version number
485  *	const rpcproc_t		proc;		-- procedure number
486  *	const xdrproc_t	xargs;		-- xdr routine for args
487  *	caddr_t		argsp;		-- pointer to args
488  *	const xdrproc_t	xresults;	-- xdr routine for results
489  *	caddr_t		resultsp;	-- pointer to results
490  *	const resultproc_t	eachresult;	-- call with each result
491  *	const char		*nettype;	-- Transport type
492  *
493  * For each valid response received, the procedure eachresult is called.
494  * Its form is:
495  *		done = eachresult(resp, raddr, nconf)
496  *			bool_t done;
497  *			caddr_t resp;
498  *			struct netbuf *raddr;
499  *			struct netconfig *nconf;
500  * where resp points to the results of the call and raddr is the
501  * address if the responder to the broadcast.  nconf is the transport
502  * on which the response was received.
503  *
504  * extern enum clnt_stat
505  * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp,
506  *			eachresult, inittime, waittime, nettype)
507  *	const rpcprog_t		prog;		-- program number
508  *	const rpcvers_t		vers;		-- version number
509  *	const rpcproc_t		proc;		-- procedure number
510  *	const xdrproc_t	xargs;		-- xdr routine for args
511  *	caddr_t		argsp;		-- pointer to args
512  *	const xdrproc_t	xresults;	-- xdr routine for results
513  *	caddr_t		resultsp;	-- pointer to results
514  *	const resultproc_t	eachresult;	-- call with each result
515  *	const int 		inittime;	-- how long to wait initially
516  *	const int 		waittime;	-- maximum time to wait
517  *	const char		*nettype;	-- Transport type
518  */
519 
520 typedef bool_t (*resultproc_t)(caddr_t, ...);
521 
522 __BEGIN_DECLS
523 extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t,
524 				    const rpcproc_t, const xdrproc_t,
525 				    caddr_t, const xdrproc_t, caddr_t,
526 				    const resultproc_t, const char *);
527 extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t,
528 					const rpcproc_t, const xdrproc_t,
529 					caddr_t, const xdrproc_t, caddr_t,
530 					const resultproc_t, const int,
531 					const int, const char *);
532 __END_DECLS
533 
534 /* For backward compatibility */
535 #include <rpc/clnt_soc.h>
536 
537 #endif /* !_RPC_CLNT_H_ */
538