include/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 _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_*/