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 CLIENT CLIENT;
 121 struct CLIENT {
 122   AUTH  *cl_auth;                /* authenticator */
 123   struct clnt_ops {
 124     enum clnt_stat (*cl_call) __P ((CLIENT *, u_long, xdrproc_t,
 125                                     caddr_t, xdrproc_t,
 126                                     caddr_t, struct timeval));
 127                                 /* call remote procedure */
 128     void (*cl_abort) __P ((void));  /* abort a call */
 129     void (*cl_geterr) __P ((CLIENT *, struct rpc_err *));
 130                                 /* get specific error code */
 131     bool_t (*cl_freeres) __P ((CLIENT *, xdrproc_t, caddr_t));
 132                                 /* frees results */
 133     void (*cl_destroy) __P ((CLIENT *)); /* destroy this structure */
 134     bool_t (*cl_control) __P ((CLIENT *, int, char *));
 135                                 /* the ioctl() of rpc */
 136   } *cl_ops;
 137   caddr_t cl_private;           /* private stuff */
 138 };
 139
 140
 141 /*
 142  * client side rpc interface ops
 143  *
 144  * Parameter types are:
 145  *
 146  */
 147
 148 /*
 149  * enum clnt_stat
 150  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
 151  *      CLIENT *rh;
 152  *      u_long proc;
 153  *      xdrproc_t xargs;
 154  *      caddr_t argsp;
 155  *      xdrproc_t xres;
 156  *      caddr_t resp;
 157  *      struct timeval timeout;
 158  */
 159 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)     \
 160         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 161 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs)     \
 162         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 163
 164 /*
 165  * void
 166  * CLNT_ABORT(rh);
 167  *      CLIENT *rh;
 168  */
 169 #define CLNT_ABORT(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 170 #define clnt_abort(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 171
 172 /*
 173  * struct rpc_err
 174  * CLNT_GETERR(rh);
 175  *      CLIENT *rh;
 176  */
 177 #define CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 178 #define clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 179
 180
 181 /*
 182  * bool_t
 183  * CLNT_FREERES(rh, xres, resp);
 184  *      CLIENT *rh;
 185  *      xdrproc_t xres;
 186  *      caddr_t resp;
 187  */
 188 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
 189 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
 190
 191 /*
 192  * bool_t
 193  * CLNT_CONTROL(cl, request, info)
 194  *      CLIENT *cl;
 195  *      u_int request;
 196  *      char *info;
 197  */
 198 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
 199 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
 200
 201 /*
 202  * control operations that apply to both udp and tcp transports
 203  */
 204 #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
 205 #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
 206 #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
 207 /*
 208  * udp only control operations
 209  */
 210 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
 211 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
 212
 213 /*
 214  * void
 215  * CLNT_DESTROY(rh);
 216  *      CLIENT *rh;
 217  */
 218 #define CLNT_DESTROY(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 219 #define clnt_destroy(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 220
 221
 222 /*
 223  * RPCTEST is a test program which is accessible on every rpc
 224  * transport/port.  It is used for testing, performance evaluation,
 225  * and network administration.
 226  */
 227
 228 #define RPCTEST_PROGRAM         ((u_long)1)
 229 #define RPCTEST_VERSION         ((u_long)1)
 230 #define RPCTEST_NULL_PROC       ((u_long)2)
 231 #define RPCTEST_NULL_BATCH_PROC ((u_long)3)
 232
 233 /*
 234  * By convention, procedure 0 takes null arguments and returns them
 235  */
 236
 237 #define NULLPROC ((u_long)0)
 238
 239 /*
 240  * Below are the client handle creation routines for the various
 241  * implementations of client side rpc.  They can return NULL if a
 242  * creation failure occurs.
 243  */
 244
 245 /*
 246  * Memory based rpc (for speed check and testing)
 247  * CLIENT *
 248  * clntraw_create(prog, vers)
 249  *      u_long prog;
 250  *      u_long vers;
 251  */
 252 extern CLIENT *clntraw_create __P ((u_long __prog, u_long __vers));
 253
 254
 255 /*
 256  * Generic client creation routine. Supported protocols are "udp" and "tcp"
 257  * CLIENT *
 258  * clnt_create(host, prog, vers, prot)
 259  *      char *host;     -- hostname
 260  *      u_int prog;     -- program number
 261  *      u_int vers;     -- version number
 262  *      char *prot;     -- protocol
 263  */
 264 extern CLIENT *clnt_create __P ((char *__host, u_int __prog, u_int __vers,
 265                                  char *__prot));
 266
 267
 268 /*
 269  * TCP based rpc
 270  * CLIENT *
 271  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
 272  *      struct sockaddr_in *raddr;
 273  *      u_long prog;
 274  *      u_long version;
 275  *      register int *sockp;
 276  *      u_int sendsz;
 277  *      u_int recvsz;
 278  */
 279 extern CLIENT *clnttcp_create __P ((struct sockaddr_in *__raddr,
 280                                     u_long __prog, u_long __version,
 281                                     int *__sockp, u_int __sendsz,
 282                                     u_int __recvsz));
 283
 284 /*
 285  * UDP based rpc.
 286  * CLIENT *
 287  * clntudp_create(raddr, program, version, wait, sockp)
 288  *      struct sockaddr_in *raddr;
 289  *      u_long program;
 290  *      u_long version;
 291  *      struct timeval wait_resend;
 292  *      int *sockp;
 293  *
 294  * Same as above, but you specify max packet sizes.
 295  * CLIENT *
 296  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
 297  *      struct sockaddr_in *raddr;
 298  *      u_long program;
 299  *      u_long version;
 300  *      struct timeval wait_resend;
 301  *      int *sockp;
 302  *      u_int sendsz;
 303  *      u_int recvsz;
 304  */
 305 extern CLIENT *clntudp_create __P ((struct sockaddr_in *__raddr,
 306                                     u_long __program, u_long __version,
 307                                     struct timeval __wait_resend,
 308                                     int *__sockp));
 309 extern CLIENT *clntudp_bufcreate __P ((struct sockaddr_in *__raddr,
 310                                        u_long __program, u_long __version,
 311                                        struct timeval __wait_resend,
 312                                        int *__sockp, u_int __sendsz,
 313                                        u_int __recvsz));
 314
 315 /*
 316  * Print why creation failed
 317  */
 318 extern void clnt_pcreateerror __P ((char *__msg));      /* stderr */
 319 extern char *clnt_spcreateerror __P ((char *__msg));    /* string */
 320
 321 /*
 322  * Like clnt_perror(), but is more verbose in its output
 323  */
 324 extern void clnt_perrno __P ((enum clnt_stat __num));   /* stderr */
 325
 326 /*
 327  * Print an English error message, given the client error code
 328  */
 329 extern void clnt_perror __P ((CLIENT *__clnt, __const char *__msg));
 330                                                                 /* stderr */
 331 extern char *clnt_sperror __P ((CLIENT *__clnt, __const char *__msg));
 332                                                                 /* string */
 333
 334 /*
 335  * If a creation fails, the following allows the user to figure out why.
 336  */
 337 struct rpc_createerr {
 338         enum clnt_stat cf_stat;
 339         struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
 340 };
 341
 342 extern struct rpc_createerr rpc_createerr;
 343
 344
 345
 346 /*
 347  * Copy error message to buffer.
 348  */
 349 extern char *clnt_sperrno __P ((enum clnt_stat __num)); /* string */
 350
 351
 352 /*
 353  * get the local host's IP address without consulting
 354  * name service library functions
 355  */
 356 extern void get_myaddress __P ((struct sockaddr_in *));
 357
 358
 359 #define UDPMSGSIZE      8800    /* rpc imposed limit on udp msg size */
 360 #define RPCSMALLMSGSIZE 400     /* a more reasonable packet size */
 361
 362 __END_DECLS
 363
 364 #endif /* rpc/clnt.h */