xref: /original-bsd/lib/librpc/rpc/clnt.h (revision 16fe368f)
1 /* @(#)clnt.h	2.1 88/07/29 4.0 RPCSRC; from 1.31 88/02/08 SMI*/
2 /*
3  * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
4  * unrestricted use provided that this legend is included on all tape
5  * media and as a part of the software program in whole or part.  Users
6  * may copy or modify Sun RPC without charge, but are not authorized
7  * to license or distribute it to anyone else except as part of a product or
8  * program developed by the user.
9  *
10  * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
11  * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
12  * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
13  *
14  * Sun RPC is provided with no support and without any obligation on the
15  * part of Sun Microsystems, Inc. to assist in its use, correction,
16  * modification or enhancement.
17  *
18  * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
19  * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
20  * OR ANY PART THEREOF.
21  *
22  * In no event will Sun Microsystems, Inc. be liable for any lost revenue
23  * or profits or other special, indirect and consequential damages, even if
24  * Sun has been advised of the possibility of such damages.
25  *
26  * Sun Microsystems, Inc.
27  * 2550 Garcia Avenue
28  * Mountain View, California  94043
29  */
30 
31 /*
32  * clnt.h - Client side remote procedure call interface.
33  *
34  * Copyright (C) 1984, Sun Microsystems, Inc.
35  */
36 
37 #ifndef _CLNT_
38 #define _CLNT_
39 
40 /*
41  * Rpc calls return an enum clnt_stat.  This should be looked at more,
42  * since each implementation is required to live with this (implementation
43  * independent) list of errors.
44  */
45 enum clnt_stat {
46 	RPC_SUCCESS=0,			/* call succeeded */
47 	/*
48 	 * local errors
49 	 */
50 	RPC_CANTENCODEARGS=1,		/* can't encode arguments */
51 	RPC_CANTDECODERES=2,		/* can't decode results */
52 	RPC_CANTSEND=3,			/* failure in sending call */
53 	RPC_CANTRECV=4,			/* failure in receiving result */
54 	RPC_TIMEDOUT=5,			/* call timed out */
55 	/*
56 	 * remote errors
57 	 */
58 	RPC_VERSMISMATCH=6,		/* rpc versions not compatible */
59 	RPC_AUTHERROR=7,		/* authentication error */
60 	RPC_PROGUNAVAIL=8,		/* program not available */
61 	RPC_PROGVERSMISMATCH=9,		/* program version mismatched */
62 	RPC_PROCUNAVAIL=10,		/* procedure unavailable */
63 	RPC_CANTDECODEARGS=11,		/* decode arguments error */
64 	RPC_SYSTEMERROR=12,		/* generic "other problem" */
65 
66 	/*
67 	 * callrpc & clnt_create errors
68 	 */
69 	RPC_UNKNOWNHOST=13,		/* unknown host name */
70 	RPC_UNKNOWNPROTO=17,		/* unkown protocol */
71 
72 	/*
73 	 * _ create errors
74 	 */
75 	RPC_PMAPFAILURE=14,		/* the pmapper failed in its call */
76 	RPC_PROGNOTREGISTERED=15,	/* remote program is not registered */
77 	/*
78 	 * unspecified error
79 	 */
80 	RPC_FAILED=16
81 };
82 
83 
84 /*
85  * Error info.
86  */
87 struct rpc_err {
88 	enum clnt_stat re_status;
89 	union {
90 		int RE_errno;		/* realated system error */
91 		enum auth_stat RE_why;	/* why the auth error occurred */
92 		struct {
93 			u_long low;	/* lowest verion supported */
94 			u_long high;	/* highest verion supported */
95 		} RE_vers;
96 		struct {		/* maybe meaningful if RPC_FAILED */
97 			long s1;
98 			long s2;
99 		} RE_lb;		/* life boot & debugging only */
100 	} ru;
101 #define	re_errno	ru.RE_errno
102 #define	re_why		ru.RE_why
103 #define	re_vers		ru.RE_vers
104 #define	re_lb		ru.RE_lb
105 };
106 
107 
108 /*
109  * Client rpc handle.
110  * Created by individual implementations, see e.g. rpc_udp.c.
111  * Client is responsible for initializing auth, see e.g. auth_none.c.
112  */
113 typedef struct {
114 	AUTH	*cl_auth;			/* authenticator */
115 	struct clnt_ops {
116 		enum clnt_stat	(*cl_call)();	/* call remote procedure */
117 		void		(*cl_abort)();	/* abort a call */
118 		void		(*cl_geterr)();	/* get specific error code */
119 		bool_t		(*cl_freeres)(); /* frees results */
120 		void		(*cl_destroy)();/* destroy this structure */
121 		bool_t          (*cl_control)();/* the ioctl() of rpc */
122 	} *cl_ops;
123 	caddr_t			cl_private;	/* private stuff */
124 } CLIENT;
125 
126 
127 /*
128  * client side rpc interface ops
129  *
130  * Parameter types are:
131  *
132  */
133 
134 /*
135  * enum clnt_stat
136  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
137  * 	CLIENT *rh;
138  *	u_long proc;
139  *	xdrproc_t xargs;
140  *	caddr_t argsp;
141  *	xdrproc_t xres;
142  *	caddr_t resp;
143  *	struct timeval timeout;
144  */
145 #define	CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)	\
146 	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
147 #define	clnt_call(rh, proc, xargs, argsp, xres, resp, secs)	\
148 	((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
149 
150 /*
151  * void
152  * CLNT_ABORT(rh);
153  * 	CLIENT *rh;
154  */
155 #define	CLNT_ABORT(rh)	((*(rh)->cl_ops->cl_abort)(rh))
156 #define	clnt_abort(rh)	((*(rh)->cl_ops->cl_abort)(rh))
157 
158 /*
159  * struct rpc_err
160  * CLNT_GETERR(rh);
161  * 	CLIENT *rh;
162  */
163 #define	CLNT_GETERR(rh,errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
164 #define	clnt_geterr(rh,errp)	((*(rh)->cl_ops->cl_geterr)(rh, errp))
165 
166 
167 /*
168  * bool_t
169  * CLNT_FREERES(rh, xres, resp);
170  * 	CLIENT *rh;
171  *	xdrproc_t xres;
172  *	caddr_t resp;
173  */
174 #define	CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
175 #define	clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
176 
177 /*
178  * bool_t
179  * CLNT_CONTROL(cl, request, info)
180  *      CLIENT *cl;
181  *      u_int request;
182  *      char *info;
183  */
184 #define	CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
185 #define	clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
186 
187 /*
188  * control operations that apply to both udp and tcp transports
189  */
190 #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
191 #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
192 #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
193 /*
194  * udp only control operations
195  */
196 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
197 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
198 
199 /*
200  * void
201  * CLNT_DESTROY(rh);
202  * 	CLIENT *rh;
203  */
204 #define	CLNT_DESTROY(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
205 #define	clnt_destroy(rh)	((*(rh)->cl_ops->cl_destroy)(rh))
206 
207 
208 /*
209  * RPCTEST is a test program which is accessable on every rpc
210  * transport/port.  It is used for testing, performance evaluation,
211  * and network administration.
212  */
213 
214 #define RPCTEST_PROGRAM		((u_long)1)
215 #define RPCTEST_VERSION		((u_long)1)
216 #define RPCTEST_NULL_PROC	((u_long)2)
217 #define RPCTEST_NULL_BATCH_PROC	((u_long)3)
218 
219 /*
220  * By convention, procedure 0 takes null arguments and returns them
221  */
222 
223 #define NULLPROC ((u_long)0)
224 
225 /*
226  * Below are the client handle creation routines for the various
227  * implementations of client side rpc.  They can return NULL if a
228  * creation failure occurs.
229  */
230 
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 
254 
255 /*
256  * TCP based rpc
257  * CLIENT *
258  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
259  *	struct sockaddr_in *raddr;
260  *	u_long prog;
261  *	u_long version;
262  *	register int *sockp;
263  *	u_int sendsz;
264  *	u_int recvsz;
265  */
266 extern CLIENT *clnttcp_create();
267 
268 /*
269  * UDP based rpc.
270  * CLIENT *
271  * clntudp_create(raddr, program, version, wait, sockp)
272  *	struct sockaddr_in *raddr;
273  *	u_long program;
274  *	u_long version;
275  *	struct timeval wait;
276  *	int *sockp;
277  *
278  * Same as above, but you specify max packet sizes.
279  * CLIENT *
280  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
281  *	struct sockaddr_in *raddr;
282  *	u_long program;
283  *	u_long version;
284  *	struct timeval wait;
285  *	int *sockp;
286  *	u_int sendsz;
287  *	u_int recvsz;
288  */
289 extern CLIENT *clntudp_create();
290 extern CLIENT *clntudp_bufcreate();
291 
292 /*
293  * Print why creation failed
294  */
295 void clnt_pcreateerror(/* char *msg */);	/* stderr */
296 char *clnt_spcreateerror(/* char *msg */);	/* string */
297 
298 /*
299  * Like clnt_perror(), but is more verbose in its output
300  */
301 void clnt_perrno(/* enum clnt_stat num */);	/* stderr */
302 
303 /*
304  * Print an English error message, given the client error code
305  */
306 void clnt_perror(/* CLIENT *clnt, char *msg */); 	/* stderr */
307 char *clnt_sperror(/* CLIENT *clnt, char *msg */);	/* string */
308 
309 /*
310  * If a creation fails, the following allows the user to figure out why.
311  */
312 struct rpc_createerr {
313 	enum clnt_stat cf_stat;
314 	struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
315 };
316 
317 extern struct rpc_createerr rpc_createerr;
318 
319 
320 
321 /*
322  * Copy error message to buffer.
323  */
324 char *clnt_sperrno(/* enum clnt_stat num */);	/* string */
325 
326 
327 
328 #define UDPMSGSIZE	8800	/* rpc imposed limit on udp msg size */
329 #define RPCSMALLMSGSIZE	400	/* a more reasonable packet size */
330 
331 #endif /*!_CLNT_*/
332