xref: /titanic_51/usr/src/lib/libbc/inc/include/rpc/clnt.h (revision 37714ae43602c675f9dc59b070bfdf9fa702872c)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 #pragma ident	"%Z%%M%	%I%	%E% SMI"
23 
24 /*
25  * clnt.h - Client side remote procedure call interface.
26  *
27  * Copyright (C) 1984, Sun Microsystems, Inc.
28  */
29 
30 #ifndef _rpc_clnt_h
31 #define	_rpc_clnt_h
32 
33 /*
34  * Rpc calls return an enum clnt_stat.  This should be looked at more,
35  * since each implementation is required to live with this (implementation
36  * independent) list of errors.
37  */
38 enum clnt_stat {
39 	RPC_SUCCESS=0,			/* call succeeded */
40 	/*
41 	 * local errors
42 	 */
43 	RPC_CANTENCODEARGS=1,		/* can't encode arguments */
44 	RPC_CANTDECODERES=2,		/* can't decode results */
45 	RPC_CANTSEND=3,			/* failure in sending call */
46 	RPC_CANTRECV=4,			/* failure in receiving result */
47 	RPC_TIMEDOUT=5,			/* call timed out */
48 	RPC_INTR=18,			/* call interrupted */
49 	/*
50 	 * remote errors
51 	 */
52 	RPC_VERSMISMATCH=6,		/* rpc versions not compatible */
53 	RPC_AUTHERROR=7,		/* authentication error */
54 	RPC_PROGUNAVAIL=8,		/* program not available */
55 	RPC_PROGVERSMISMATCH=9,		/* program version mismatched */
56 	RPC_PROCUNAVAIL=10,		/* procedure unavailable */
57 	RPC_CANTDECODEARGS=11,		/* decode arguments error */
58 	RPC_SYSTEMERROR=12,		/* generic "other problem" */
59 
60 	/*
61 	 * callrpc & clnt_create errors
62 	 */
63 	RPC_UNKNOWNHOST=13,		/* unknown host name */
64 	RPC_UNKNOWNPROTO=17,		/* unkown protocol */
65 
66 	/*
67 	 * _ create errors
68 	 */
69 	RPC_PMAPFAILURE=14,		/* the pmapper failed in its call */
70 	RPC_PROGNOTREGISTERED=15,	/* remote program is not registered */
71 	/*
72 	 * unspecified error
73 	 */
74 	RPC_FAILED=16
75 };
76 
77 
78 /*
79  * Error info.
80  */
81 struct rpc_err {
82 	enum clnt_stat re_status;
83 	union {
84 		int RE_errno;		/* realated system error */
85 		enum auth_stat RE_why;	/* why the auth error occurred */
86 		struct {
87 			u_long low;	/* lowest verion supported */
88 			u_long high;	/* highest verion supported */
89 		} RE_vers;
90 		struct {		/* maybe meaningful if RPC_FAILED */
91 			long s1;
92 			long s2;
93 		} RE_lb;		/* life boot & debugging only */
94 	} ru;
95 #define	re_errno	ru.RE_errno
96 #define	re_why		ru.RE_why
97 #define	re_vers		ru.RE_vers
98 #define	re_lb		ru.RE_lb
99 };
100 
101 
102 /*
103  * Client rpc handle.
104  * Created by individual implementations, see e.g. rpc_udp.c.
105  * Client is responsible for initializing auth, see e.g. auth_none.c.
106  */
107 typedef struct {
108 	AUTH	*cl_auth;			/* authenticator */
109 	struct clnt_ops {
110 		enum clnt_stat	(*cl_call)();	/* call remote procedure */
111 		void		(*cl_abort)();	/* abort a call */
112 		void		(*cl_geterr)();	/* get specific error code */
113 		bool_t		(*cl_freeres)(); /* frees results */
114 		void		(*cl_destroy)(); /* destroy this structure */
115 		bool_t		(*cl_control)(); /* the ioctl() of rpc */
116 	} *cl_ops;
117 	caddr_t			cl_private;	/* private stuff */
118 } CLIENT;
119 
120 
121 /*
122  * client side rpc interface ops
123  *
124  * Parameter types are:
125  *
126  */
127 
128 /*
129  * enum clnt_stat
130  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
131  * 	CLIENT *rh;
132  *	u_long proc;
133  *	xdrproc_t xargs;
134  *	caddr_t argsp;
135  *	xdrproc_t xres;
136  *	caddr_t resp;
137  *	struct timeval timeout;
138  */
139 #define	CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)	\
140 	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
141 #define	clnt_call(rh, proc, xargs, argsp, xres, resp, secs)	\
142 	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
143 
144 /*
145  * void
146  * CLNT_ABORT(rh);
147  * 	CLIENT *rh;
148  */
149 #define	CLNT_ABORT(rh)	((*(rh)->cl_ops->cl_abort)(rh))
150 #define	clnt_abort(rh)	((*(rh)->cl_ops->cl_abort)(rh))
151 
152 /*
153  * struct rpc_err
154  * CLNT_GETERR(rh);
155  * 	CLIENT *rh;
156  */
157 #define	CLNT_GETERR(rh, errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
158 #define	clnt_geterr(rh, errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
159 
160 
161 /*
162  * bool_t
163  * CLNT_FREERES(rh, xres, resp);
164  * 	CLIENT *rh;
165  *	xdrproc_t xres;
166  *	caddr_t resp;
167  */
168 #define	CLNT_FREERES(rh, xres, resp) ((*(rh)->cl_ops->cl_freeres)\
169 	(rh, xres, resp))
170 #define	clnt_freeres(rh, xres, resp) ((*(rh)->cl_ops->cl_freeres)\
171 	(rh, xres, resp))
172 
173 /*
174  * bool_t
175  * CLNT_CONTROL(cl, request, info)
176  *	CLIENT *cl;
177  *	u_int request;
178  *	char *info;
179  */
180 #define	CLNT_CONTROL(cl, rq, in) ((*(cl)->cl_ops->cl_control)(cl, rq, in))
181 #define	clnt_control(cl, rq, in) ((*(cl)->cl_ops->cl_control)(cl, rq, in))
182 
183 /*
184  * control operations that apply to both udp and tcp transports
185  */
186 #define	CLSET_TIMEOUT		1   /* set timeout (timeval) */
187 #define	CLGET_TIMEOUT		2   /* get timeout (timeval) */
188 #define	CLGET_SERVER_ADDR	3   /* get server's address (sockaddr) */
189 #define	CLGET_FD		6   /* get connections file descriptor */
190 #define	CLSET_FD_CLOSE		8   /* close fd while clnt_destroy */
191 #define	CLSET_FD_NCLOSE		9   /* Do not close fd while clnt_destroy */
192 /*
193  * udp only control operations
194  */
195 #define	CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
196 #define	CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
197 
198 /*
199  * void
200  * CLNT_DESTROY(rh);
201  * 	CLIENT *rh;
202  */
203 #define	CLNT_DESTROY(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
204 #define	clnt_destroy(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
205 
206 
207 /*
208  * RPCTEST is a test program which is accessable on every rpc
209  * transport/port.  It is used for testing, performance evaluation,
210  * and network administration.
211  */
212 
213 #define	RPCTEST_PROGRAM		((u_long)1)
214 #define	RPCTEST_VERSION		((u_long)1)
215 #define	RPCTEST_NULL_PROC	((u_long)2)
216 #define	RPCTEST_NULL_BATCH_PROC	((u_long)3)
217 
218 /*
219  * By convention, procedure 0 takes null arguments and returns them
220  */
221 
222 #define	NULLPROC ((u_long)0)
223 
224 /*
225  * Below are the client handle creation routines for the various
226  * implementations of client side rpc.  They can return NULL if a
227  * creation failure occurs.
228  */
229 
230 #ifndef KERNEL
231 /*
232  * Memory based rpc (for speed check and testing)
233  * CLIENT *
234  * clntraw_create(prog, vers)
235  *	u_long prog;
236  *	u_long vers;
237  */
238 extern CLIENT *clntraw_create();
239 
240 
241 /*
242  * Generic client creation routine. Supported protocols are "udp" and "tcp"
243  */
244 extern CLIENT *
245 clnt_create(/*host, prog, vers, prot*/); /*
246 	char *host; 	-- hostname
247 	u_long prog;	-- program number
248 	u_long vers;	-- version number
249 	char *prot;	-- protocol
250 */
251 
252 /*
253  * Generic client creation routine. Supported protocols are "udp" and "tcp"
254  */
255 extern CLIENT *
256 clnt_create_vers(/*host, prog, vers_out, vers_low, vers_high, prot*/);
257 /*
258 	char *host; 	-- hostname
259 	u_long prog;	-- program number
260 	u_long *vers_out;	-- servers best  version number
261 	u_long vers_low;	-- low version number
262 	u_long vers_high;	-- high version number
263 	char *prot;	-- protocol
264 */
265 
266 
267 
268 /*
269  * TCP based rpc
270  * CLIENT *
271  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
272  *	struct sockaddr_in *raddr;
273  *	u_long prog;
274  *	u_long version;
275  *	register int *sockp;
276  *	u_int sendsz;
277  *	u_int recvsz;
278  */
279 extern CLIENT *clnttcp_create();
280 
281 /*
282  * UDP based rpc.
283  * CLIENT *
284  * clntudp_create(raddr, program, version, wait, sockp)
285  *	struct sockaddr_in *raddr;
286  *	u_long program;
287  *	u_long version;
288  *	struct timeval wait;
289  *	int *sockp;
290  *
291  * Same as above, but you specify max packet sizes.
292  * CLIENT *
293  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
294  *	struct sockaddr_in *raddr;
295  *	u_long program;
296  *	u_long version;
297  *	struct timeval wait;
298  *	int *sockp;
299  *	u_int sendsz;
300  *	u_int recvsz;
301  */
302 extern CLIENT *clntudp_create();
303 extern CLIENT *clntudp_bufcreate();
304 
305 /*
306  * Print why creation failed
307  */
308 void clnt_pcreateerror(/* char *msg */);	/* stderr */
309 char *clnt_spcreateerror(/* char *msg */);	/* string */
310 
311 /*
312  * Like clnt_perror(), but is more verbose in its output
313  */
314 void clnt_perrno(/* enum clnt_stat num */);	/* stderr */
315 
316 /*
317  * Print an English error message, given the client error code
318  */
319 void clnt_perror(/* CLIENT *clnt, char *msg */); 	/* stderr */
320 char *clnt_sperror(/* CLIENT *clnt, char *msg */);	/* string */
321 
322 /*
323  * If a creation fails, the following allows the user to figure out why.
324  */
325 struct rpc_createerr {
326 	enum clnt_stat cf_stat;
327 	struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
328 };
329 
330 extern struct rpc_createerr rpc_createerr;
331 
332 
333 #endif /* !KERNEL */
334 
335 /*
336  * Copy error message to buffer.
337  */
338 char *clnt_sperrno(/* enum clnt_stat num */);	/* string */
339 
340 
341 #ifdef KERNEL
342 /*
343  * Kernel udp based rpc
344  * CLIENT *
345  * clntkudp_create(addr, pgm, vers)
346  *	struct sockaddr_in *addr;
347  *	u_long pgm;
348  *	u_long vers;
349  */
350 extern CLIENT *clntkudp_create();
351 #endif
352 
353 /*
354  * Timers used for the pseudo-transport protocol when using datagrams
355  */
356 struct rpc_timers {
357 	u_short		rt_srtt;	/* smoothed round-trip time */
358 	u_short		rt_deviate;	/* estimated deviation */
359 	u_long		rt_rtxcur;	/* current (backed-off) rto */
360 };
361 
362 /*
363  * Feedback values used for possible congestion and rate control
364  */
365 #define	FEEDBACK_REXMIT1	1	/* first retransmit */
366 #define	FEEDBACK_OK		2	/* no retransmits */
367 
368 #define	UDPMSGSIZE	8800	/* rpc imposed limit on udp msg size */
369 #define	RPCSMALLMSGSIZE	400	/* a more reasonable packet size */
370 
371 #ifdef	KERNEL
372 /*
373  *	Alloc_xid presents an interface which kernel RPC clients
374  *	should use to allocate their XIDs.  Its implementation
375  *	may change over time (for example, to allow sharing of
376  *	XIDs between the kernel and user-level applications, so
377  *	all XID allocation should be done by calling alloc_xid().
378  */
379 extern u_long	clntxid;
380 #define	alloc_xid()	(clntxid++)
381 #endif
382 
383 #endif /*!_rpc_clnt_h*/
384