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