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