clnt.h revision 8858
1/* 2 * Sun RPC is a product of Sun Microsystems, Inc. and is provided for 3 * unrestricted use provided that this legend is included on all tape 4 * media and as a part of the software program in whole or part. Users 5 * may copy or modify Sun RPC without charge, but are not authorized 6 * to license or distribute it to anyone else except as part of a product or 7 * program developed by the user. 8 * 9 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE 10 * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR 11 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. 12 * 13 * Sun RPC is provided with no support and without any obligation on the 14 * part of Sun Microsystems, Inc. to assist in its use, correction, 15 * modification or enhancement. 16 * 17 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE 18 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC 19 * OR ANY PART THEREOF. 20 * 21 * In no event will Sun Microsystems, Inc. be liable for any lost revenue 22 * or profits or other special, indirect and consequential damages, even if 23 * Sun has been advised of the possibility of such damages. 24 * 25 * Sun Microsystems, Inc. 26 * 2550 Garcia Avenue 27 * Mountain View, California 94043 28 * 29 * from: @(#)clnt.h 1.31 88/02/08 SMI 30 * from: @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC 31 * $Id: clnt.h,v 1.2 1994/08/07 18:40:55 wollman Exp $ 32 */ 33 34/* 35 * clnt.h - Client side remote procedure call interface. 36 * 37 * Copyright (C) 1984, Sun Microsystems, Inc. 38 */ 39 40#ifndef _RPC_CLNT_H_ 41#define _RPC_CLNT_H_ 42#include <sys/cdefs.h> 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 */ 49enum 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 */ 91struct 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 */ 117typedef 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__BEGIN_DECLS 243extern CLIENT *clntraw_create __P((u_long, u_long)); 244__END_DECLS 245 246 247/* 248 * Generic client creation routine. Supported protocols are "udp" and "tcp" 249 * CLIENT * 250 * clnt_create(host, prog, vers, prot); 251 * char *host; -- hostname 252 * u_long prog; -- program number 253 * u_long vers; -- version number 254 * char *prot; -- protocol 255 */ 256__BEGIN_DECLS 257extern CLIENT *clnt_create __P((char *, u_long, u_long, char *)); 258__END_DECLS 259 260 261/* 262 * TCP based rpc 263 * CLIENT * 264 * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz) 265 * struct sockaddr_in *raddr; 266 * u_long prog; 267 * u_long version; 268 * register int *sockp; 269 * u_int sendsz; 270 * u_int recvsz; 271 */ 272__BEGIN_DECLS 273extern CLIENT *clnttcp_create __P((struct sockaddr_in *, 274 u_long, 275 u_long, 276 int *, 277 u_int, 278 u_int)); 279__END_DECLS 280 281 282/* 283 * UDP based rpc. 284 * CLIENT * 285 * clntudp_create(raddr, program, version, wait, sockp) 286 * struct sockaddr_in *raddr; 287 * u_long program; 288 * u_long version; 289 * struct timeval wait; 290 * int *sockp; 291 * 292 * Same as above, but you specify max packet sizes. 293 * CLIENT * 294 * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz) 295 * struct sockaddr_in *raddr; 296 * u_long program; 297 * u_long version; 298 * struct timeval wait; 299 * int *sockp; 300 * u_int sendsz; 301 * u_int recvsz; 302 */ 303__BEGIN_DECLS 304extern CLIENT *clntudp_create __P((struct sockaddr_in *, 305 u_long, 306 u_long, 307 struct timeval, 308 int *)); 309extern CLIENT *clntudp_bufcreate __P((struct sockaddr_in *, 310 u_long, 311 u_long, 312 struct timeval, 313 int *, 314 u_int, 315 u_int)); 316__END_DECLS 317 318 319/* 320 * Print why creation failed 321 */ 322__BEGIN_DECLS 323extern void clnt_pcreateerror __P((char *)); /* stderr */ 324extern char *clnt_spcreateerror __P((char *)); /* string */ 325__END_DECLS 326 327/* 328 * Like clnt_perror(), but is more verbose in its output 329 */ 330__BEGIN_DECLS 331extern void clnt_perrno __P((enum clnt_stat)); /* stderr */ 332extern char *clnt_sperrno __P((enum clnt_stat)); /* string */ 333__END_DECLS 334 335/* 336 * Print an English error message, given the client error code 337 */ 338__BEGIN_DECLS 339extern void clnt_perror __P((CLIENT *, char *)); /* stderr */ 340extern char *clnt_sperror __P((CLIENT *, char *)); /* string */ 341__END_DECLS 342 343 344/* 345 * If a creation fails, the following allows the user to figure out why. 346 */ 347struct rpc_createerr { 348 enum clnt_stat cf_stat; 349 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */ 350}; 351 352extern struct rpc_createerr rpc_createerr; 353 354 355#define UDPMSGSIZE 8800 /* rpc imposed limit on udp msg size */ 356#define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */ 357 358#endif /* !_RPC_CLNT_H */ 359