2e1ff26314ac497d3cfb4838b3a4ff0c0b2ae6cc
[kopensolaris-gnu/glibc.git] / sunrpc / rpc / clnt.h
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 _RPC_CLNT_H
38
39 #define _RPC_CLNT_H     1
40 #include <features.h>
41
42 __BEGIN_DECLS
43
44 /*
45  * Rpc calls return an enum clnt_stat.  This should be looked at more,
46  * since each implementation is required to live with this (implementation
47  * independent) list of errors.
48  */
49 enum clnt_stat {
50         RPC_SUCCESS=0,                  /* call succeeded */
51         /*
52          * local errors
53          */
54         RPC_CANTENCODEARGS=1,           /* can't encode arguments */
55         RPC_CANTDECODERES=2,            /* can't decode results */
56         RPC_CANTSEND=3,                 /* failure in sending call */
57         RPC_CANTRECV=4,                 /* failure in receiving result */
58         RPC_TIMEDOUT=5,                 /* call timed out */
59         /*
60          * remote errors
61          */
62         RPC_VERSMISMATCH=6,             /* rpc versions not compatible */
63         RPC_AUTHERROR=7,                /* authentication error */
64         RPC_PROGUNAVAIL=8,              /* program not available */
65         RPC_PROGVERSMISMATCH=9,         /* program version mismatched */
66         RPC_PROCUNAVAIL=10,             /* procedure unavailable */
67         RPC_CANTDECODEARGS=11,          /* decode arguments error */
68         RPC_SYSTEMERROR=12,             /* generic "other problem" */
69
70         /*
71          * callrpc & clnt_create errors
72          */
73         RPC_UNKNOWNHOST=13,             /* unknown host name */
74         RPC_UNKNOWNPROTO=17,            /* unkown protocol */
75
76         /*
77          * _ create errors
78          */
79         RPC_PMAPFAILURE=14,             /* the pmapper failed in its call */
80         RPC_PROGNOTREGISTERED=15,       /* remote program is not registered */
81         /*
82          * unspecified error
83          */
84         RPC_FAILED=16
85 };
86
87
88 /*
89  * Error info.
90  */
91 struct rpc_err {
92         enum clnt_stat re_status;
93         union {
94                 int RE_errno;           /* realated system error */
95                 enum auth_stat RE_why;  /* why the auth error occurred */
96                 struct {
97                         u_long low;     /* lowest verion supported */
98                         u_long high;    /* highest verion supported */
99                 } RE_vers;
100                 struct {                /* maybe meaningful if RPC_FAILED */
101                         long s1;
102                         long s2;
103                 } RE_lb;                /* life boot & debugging only */
104         } ru;
105 #define re_errno        ru.RE_errno
106 #define re_why          ru.RE_why
107 #define re_vers         ru.RE_vers
108 #define re_lb           ru.RE_lb
109 };
110
111
112 /*
113  * Client rpc handle.
114  * Created by individual implementations, see e.g. rpc_udp.c.
115  * Client is responsible for initializing auth, see e.g. auth_none.c.
116  */
117 typedef struct {
118         AUTH    *cl_auth;                       /* authenticator */
119         struct clnt_ops {
120                 enum clnt_stat  (*cl_call)();   /* call remote procedure */
121                 void            (*cl_abort)();  /* abort a call */
122                 void            (*cl_geterr)(); /* get specific error code */
123                 bool_t          (*cl_freeres)(); /* frees results */
124                 void            (*cl_destroy)();/* destroy this structure */
125                 bool_t          (*cl_control)();/* the ioctl() of rpc */
126         } *cl_ops;
127         caddr_t                 cl_private;     /* private stuff */
128 } CLIENT;
129
130
131 /*
132  * client side rpc interface ops
133  *
134  * Parameter types are:
135  *
136  */
137
138 /*
139  * enum clnt_stat
140  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
141  *      CLIENT *rh;
142  *      u_long proc;
143  *      xdrproc_t xargs;
144  *      caddr_t argsp;
145  *      xdrproc_t xres;
146  *      caddr_t resp;
147  *      struct timeval timeout;
148  */
149 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)     \
150         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
151 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs)     \
152         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
153
154 /*
155  * void
156  * CLNT_ABORT(rh);
157  *      CLIENT *rh;
158  */
159 #define CLNT_ABORT(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
160 #define clnt_abort(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
161
162 /*
163  * struct rpc_err
164  * CLNT_GETERR(rh);
165  *      CLIENT *rh;
166  */
167 #define CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
168 #define clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
169
170
171 /*
172  * bool_t
173  * CLNT_FREERES(rh, xres, resp);
174  *      CLIENT *rh;
175  *      xdrproc_t xres;
176  *      caddr_t resp;
177  */
178 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
179 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
180
181 /*
182  * bool_t
183  * CLNT_CONTROL(cl, request, info)
184  *      CLIENT *cl;
185  *      u_int request;
186  *      char *info;
187  */
188 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
189 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
190
191 /*
192  * control operations that apply to both udp and tcp transports
193  */
194 #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
195 #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
196 #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
197 /*
198  * udp only control operations
199  */
200 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
201 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
202
203 /*
204  * void
205  * CLNT_DESTROY(rh);
206  *      CLIENT *rh;
207  */
208 #define CLNT_DESTROY(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
209 #define clnt_destroy(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
210
211
212 /*
213  * RPCTEST is a test program which is accessable on every rpc
214  * transport/port.  It is used for testing, performance evaluation,
215  * and network administration.
216  */
217
218 #define RPCTEST_PROGRAM         ((u_long)1)
219 #define RPCTEST_VERSION         ((u_long)1)
220 #define RPCTEST_NULL_PROC       ((u_long)2)
221 #define RPCTEST_NULL_BATCH_PROC ((u_long)3)
222
223 /*
224  * By convention, procedure 0 takes null arguments and returns them
225  */
226
227 #define NULLPROC ((u_long)0)
228
229 /*
230  * Below are the client handle creation routines for the various
231  * implementations of client side rpc.  They can return NULL if a
232  * creation failure occurs.
233  */
234
235 /*
236  * Memory based rpc (for speed check and testing)
237  * CLIENT *
238  * clntraw_create(prog, vers)
239  *      u_long prog;
240  *      u_long vers;
241  */
242 extern CLIENT *clntraw_create __P ((u_long __prog, u_long __vers));
243
244
245 /*
246  * Generic client creation routine. Supported protocols are "udp" and "tcp"
247  * CLIENT *
248  * clnt_create(host, prog, vers, prot)
249  *      char *host;     -- hostname
250  *      u_int prog;     -- program number
251  *      u_int vers;     -- version number
252  *      char *prot;     -- protocol
253  */
254 extern CLIENT *clnt_create __P ((char *__host, u_int __prog, u_int __vers,
255                                  char *__prot));
256
257
258 /*
259  * TCP based rpc
260  * CLIENT *
261  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
262  *      struct sockaddr_in *raddr;
263  *      u_long prog;
264  *      u_long version;
265  *      register int *sockp;
266  *      u_int sendsz;
267  *      u_int recvsz;
268  */
269 extern CLIENT *clnttcp_create __P ((struct sockaddr_in *__raddr,
270                                     u_long __prog, u_long __version,
271                                     int *__sockp, u_int __sendsz,
272                                     u_int __recvsz));
273
274 /*
275  * UDP based rpc.
276  * CLIENT *
277  * clntudp_create(raddr, program, version, wait, sockp)
278  *      struct sockaddr_in *raddr;
279  *      u_long program;
280  *      u_long version;
281  *      struct timeval wait_resend;
282  *      int *sockp;
283  *
284  * Same as above, but you specify max packet sizes.
285  * CLIENT *
286  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
287  *      struct sockaddr_in *raddr;
288  *      u_long program;
289  *      u_long version;
290  *      struct timeval wait_resend;
291  *      int *sockp;
292  *      u_int sendsz;
293  *      u_int recvsz;
294  */
295 extern CLIENT *clntudp_create __P ((struct sockaddr_in *__raddr,
296                                     u_long __program, u_long __version,
297                                     struct timeval __wait_resend,
298                                     int *__sockp));
299 extern CLIENT *clntudp_bufcreate __P ((struct sockaddr_in *__raddr,
300                                        u_long __program, u_long __version,
301                                        struct timeval __wait_resend,
302                                        int *__sockp, u_int __sendsz,
303                                        u_int __recvsz));
304
305 /*
306  * Print why creation failed
307  */
308 extern void clnt_pcreateerror __P ((char *__msg));      /* stderr */
309 extern char *clnt_spcreateerror __P ((char *__msg));    /* string */
310
311 /*
312  * Like clnt_perror(), but is more verbose in its output
313  */
314 extern void clnt_perrno __P ((enum clnt_stat __num));   /* stderr */
315
316 /*
317  * Print an English error message, given the client error code
318  */
319 extern void clnt_perror __P ((CLIENT *__clnt, char *__msg));    /* stderr */
320 extern char *clnt_sperror __P ((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
334 /*
335  * Copy error message to buffer.
336  */
337 extern char *clnt_sperrno __P ((enum clnt_stat __num)); /* string */
338
339
340
341 #define UDPMSGSIZE      8800    /* rpc imposed limit on udp msg size */
342 #define RPCSMALLMSGSIZE 400     /* a more reasonable packet size */
343
344 __END_DECLS
345
346 #endif /* rpc/clnt.h */