support/rpc/include/rpc/clnt.h

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