include/rpc/clnt.h

   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, MERCHANTABILITY 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  * $FreeBSD: src/include/rpc/clnt.h,v 1.11.2.1 2001/06/28 21:44:09 iedowse Exp $
  32  * $DragonFly: src/include/rpc/clnt.h,v 1.6 2005/11/13 12:27:04 swildner Exp $
  33  */
  34
  35 /*
  36  * clnt.h - Client side remote procedure call interface.
  37  *
  38  * Copyright (C) 1984, Sun Microsystems, Inc.
  39  */
  40
  41 #ifndef _RPC_CLNT_H_
  42 #define _RPC_CLNT_H_
  43 #include <sys/cdefs.h>
  44 #include <sys/un.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;           /* related 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) (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) (struct __rpc_client *);
 128                 /* get specific error code */
 129                 void            (*cl_geterr) (struct __rpc_client *,
 130                                         struct rpc_err *);
 131                 /* frees results */
 132                 bool_t          (*cl_freeres) (struct __rpc_client *,
 133                                         xdrproc_t, caddr_t);
 134                 /* destroy this structure */
 135                 void            (*cl_destroy) (struct __rpc_client *);
 136                 /* the ioctl() of rpc */
 137                 bool_t          (*cl_control) (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 udp, tcp and unix transports
 208  *
 209  * Note: options marked XXX are no-ops in this implementation of RPC.
 210  * The are present in TI-RPC but can't be implemented here since they
 211  * depend on the presence of STREAMS/TLI, which we don't have.
 212  *
 213  */
 214 #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
 215 #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
 216 #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
 217 #define CLGET_FD            6   /* get connections file descriptor */
 218 #define CLGET_SVC_ADDR      7   /* get server's address (netbuf)         XXX */
 219 #define CLSET_FD_CLOSE      8   /* close fd while clnt_destroy */
 220 #define CLSET_FD_NCLOSE     9   /* Do not close fd while clnt_destroy */
 221 #define CLGET_XID           10  /* Get xid */
 222 #define CLSET_XID           11  /* Set xid */
 223 #define CLGET_VERS          12  /* Get version number */
 224 #define CLSET_VERS          13  /* Set version number */
 225 #define CLGET_PROG          14  /* Get program number */
 226 #define CLSET_PROG          15  /* Set program number */
 227 #define CLSET_SVC_ADDR      16  /* get server's address (netbuf)         XXX */
 228 #define CLSET_PUSH_TIMOD    17  /* push timod if not already present     XXX */
 229 #define CLSET_POP_TIMOD     18  /* pop timod                             XXX */
 230
 231 /*
 232  * udp only control operations
 233  */
 234 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
 235 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
 236 #define CLSET_CONNECT           20      /* Use connect() for UDP. (int) */
 237
 238 /*
 239  * Operations which GSSAPI needs. (Bletch.)
 240  */
 241 #define CLGET_LOCAL_ADDR    19  /* get local addr (sockaddr) */
 242
 243
 244 /*
 245  * void
 246  * CLNT_DESTROY(rh);
 247  *      CLIENT *rh;
 248  */
 249 #define CLNT_DESTROY(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 250 #define clnt_destroy(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 251
 252
 253 /*
 254  * RPCTEST is a test program which is accessible on every rpc
 255  * transport/port.  It is used for testing, performance evaluation,
 256  * and network administration.
 257  */
 258
 259 #define RPCTEST_PROGRAM         ((u_long)1)
 260 #define RPCTEST_VERSION         ((u_long)1)
 261 #define RPCTEST_NULL_PROC       ((u_long)2)
 262 #define RPCTEST_NULL_BATCH_PROC ((u_long)3)
 263
 264 /*
 265  * By convention, procedure 0 takes null arguments and returns them
 266  */
 267
 268 #define NULLPROC ((u_long)0)
 269
 270 /*
 271  * Below are the client handle creation routines for the various
 272  * implementations of client side rpc.  They can return NULL if a
 273  * creation failure occurs.
 274  */
 275
 276 /*
 277  * Memory based rpc (for speed check and testing)
 278  * CLIENT *
 279  * clntraw_create(prog, vers)
 280  *      u_long prog;
 281  *      u_long vers;
 282  */
 283 __BEGIN_DECLS
 284 extern CLIENT *clntraw_create   (u_long, u_long);
 285 __END_DECLS
 286
 287
 288 /*
 289  * Generic client creation routine. Supported protocols are "udp", "tcp"
 290  * and "unix".
 291  * CLIENT *
 292  * clnt_create(host, prog, vers, prot);
 293  *      const char *host;       -- hostname
 294  *      u_long prog;    -- program number
 295  *      u_long vers;    -- version number
 296  *      const char *prot;       -- protocol
 297  */
 298 __BEGIN_DECLS
 299 CLIENT *        clnt_create(const char *, u_long, u_long, const char *);
 300 __END_DECLS
 301
 302
 303 /*
 304  * TCP based rpc
 305  * CLIENT *
 306  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
 307  *      struct sockaddr_in *raddr;
 308  *      u_long prog;
 309  *      u_long version;
 310  *      int *sockp;
 311  *      u_int sendsz;
 312  *      u_int recvsz;
 313  */
 314 __BEGIN_DECLS
 315 extern CLIENT *clnttcp_create   (struct sockaddr_in *,
 316                                      u_long,
 317                                      u_long,
 318                                      int *,
 319                                      u_int,
 320                                      u_int);
 321 __END_DECLS
 322
 323
 324 /*
 325  * UDP based rpc.
 326  * CLIENT *
 327  * clntudp_create(raddr, program, version, wait, sockp)
 328  *      struct sockaddr_in *raddr;
 329  *      u_long program;
 330  *      u_long version;
 331  *      struct timeval wait;
 332  *      int *sockp;
 333  *
 334  * Same as above, but you specify max packet sizes.
 335  * CLIENT *
 336  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
 337  *      struct sockaddr_in *raddr;
 338  *      u_long program;
 339  *      u_long version;
 340  *      struct timeval wait;
 341  *      int *sockp;
 342  *      u_int sendsz;
 343  *      u_int recvsz;
 344  */
 345 __BEGIN_DECLS
 346 extern CLIENT *clntudp_create   (struct sockaddr_in *,
 347                                      u_long,
 348                                      u_long,
 349                                      struct timeval,
 350                                      int *);
 351 extern CLIENT *clntudp_bufcreate (struct sockaddr_in *,
 352                                      u_long,
 353                                      u_long,
 354                                      struct timeval,
 355                                      int *,
 356                                      u_int,
 357                                      u_int);
 358 __END_DECLS
 359
 360
 361 /*
 362  * AF_UNIX based rpc
 363  * CLIENT *
 364  * clntunix_create(raddr, prog, vers, sockp, sendsz, recvsz)
 365  *      struct sockaddr_un *raddr;
 366  *      u_long prog;
 367  *      u_long version;
 368  *      int *sockp;
 369  *      u_int sendsz;
 370  *      u_int recvsz;
 371  */
 372 __BEGIN_DECLS
 373 extern CLIENT *clntunix_create  (struct sockaddr_un *,
 374                                      u_long,
 375                                      u_long,
 376                                      int *,
 377                                      u_int,
 378                                      u_int);
 379 __END_DECLS
 380
 381
 382 /*
 383  * Print why creation failed
 384  */
 385 __BEGIN_DECLS
 386 extern void     clnt_pcreateerror(const char *);                        /* stderr */
 387 extern char     *clnt_spcreateerror(const char *);                      /* string */
 388 __END_DECLS
 389
 390 /*
 391  * Like clnt_perror(), but is more verbose in its output
 392  */
 393 __BEGIN_DECLS
 394 extern void clnt_perrno         (enum clnt_stat);               /* stderr */
 395 extern char *clnt_sperrno       (enum clnt_stat);               /* string */
 396 __END_DECLS
 397
 398 /*
 399  * Print an English error message, given the client error code
 400  */
 401 __BEGIN_DECLS
 402 extern void      clnt_perror(CLIENT *, const char *);   /* stderr */
 403 extern char     *clnt_sperror(CLIENT *, const char *);  /* string */
 404 __END_DECLS
 405
 406
 407 /*
 408  * If a creation fails, the following allows the user to figure out why.
 409  */
 410 struct rpc_createerr {
 411         enum clnt_stat cf_stat;
 412         struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
 413 };
 414
 415 extern struct rpc_createerr rpc_createerr;
 416
 417
 418 #define UDPMSGSIZE      8800    /* rpc imposed limit on udp msg size */
 419 #define RPCSMALLMSGSIZE 400     /* a more reasonable packet size */
 420
 421 #endif /* !_RPC_CLNT_H */