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 #define _RPC_CLNT_H     1
  39
  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         RPC_NOBROADCAST = 21,           /* Broadcasting not supported */
  73         /*
  74          * callrpc & clnt_create errors
  75          */
  76         RPC_UNKNOWNHOST=13,             /* unknown host name */
  77         RPC_UNKNOWNPROTO=17,            /* unknown protocol */
  78         RPC_UNKNOWNADDR = 19,           /* Remote address unknown */
  79
  80         /*
  81          * rpcbind errors
  82          */
  83         RPC_RPCBFAILURE=14,             /* portmapper failed in its call */
  84 #define RPC_PMAPFAILURE RPC_RPCBFAILURE
  85         RPC_PROGNOTREGISTERED=15,       /* remote program is not registered */
  86         RPC_N2AXLATEFAILURE = 22,       /* Name to addr translation failed */
  87         /*
  88          * unspecified error
  89          */
  90         RPC_FAILED=16,
  91         RPC_INTR=18,
  92         RPC_TLIERROR=20,
  93         RPC_UDERROR=23,
  94         /*
  95          * asynchronous errors
  96          */
  97         RPC_INPROGRESS = 24,
  98         RPC_STALERACHANDLE = 25
  99 };
 100
 101
 102 /*
 103  * Error info.
 104  */
 105 struct rpc_err {
 106   enum clnt_stat re_status;
 107   union {
 108     int RE_errno;               /* related system error */
 109     enum auth_stat RE_why;      /* why the auth error occurred */
 110     struct {
 111       u_long low;               /* lowest verion supported */
 112       u_long high;              /* highest verion supported */
 113     } RE_vers;
 114     struct {                    /* maybe meaningful if RPC_FAILED */
 115       long s1;
 116       long s2;
 117     } RE_lb;                    /* life boot & debugging only */
 118   } ru;
 119 #define re_errno        ru.RE_errno
 120 #define re_why          ru.RE_why
 121 #define re_vers         ru.RE_vers
 122 #define re_lb           ru.RE_lb
 123 };
 124
 125
 126 /*
 127  * Client rpc handle.
 128  * Created by individual implementations, see e.g. rpc_udp.c.
 129  * Client is responsible for initializing auth, see e.g. auth_none.c.
 130  */
 131 typedef struct CLIENT CLIENT;
 132 struct CLIENT {
 133   AUTH  *cl_auth;                /* authenticator */
 134   struct clnt_ops {
 135     enum clnt_stat (*cl_call) __P ((CLIENT *, u_long, xdrproc_t,
 136                                     caddr_t, xdrproc_t,
 137                                     caddr_t, struct timeval));
 138                                 /* call remote procedure */
 139     void (*cl_abort) __P ((void));  /* abort a call */
 140     void (*cl_geterr) __P ((CLIENT *, struct rpc_err *));
 141                                 /* get specific error code */
 142     bool_t (*cl_freeres) __P ((CLIENT *, xdrproc_t, caddr_t));
 143                                 /* frees results */
 144     void (*cl_destroy) __P ((CLIENT *)); /* destroy this structure */
 145     bool_t (*cl_control) __P ((CLIENT *, int, char *));
 146                                 /* the ioctl() of rpc */
 147   } *cl_ops;
 148   caddr_t cl_private;           /* private stuff */
 149 };
 150
 151
 152 /*
 153  * client side rpc interface ops
 154  *
 155  * Parameter types are:
 156  *
 157  */
 158
 159 /*
 160  * enum clnt_stat
 161  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
 162  *      CLIENT *rh;
 163  *      u_long proc;
 164  *      xdrproc_t xargs;
 165  *      caddr_t argsp;
 166  *      xdrproc_t xres;
 167  *      caddr_t resp;
 168  *      struct timeval timeout;
 169  */
 170 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)     \
 171         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 172 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs)     \
 173         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 174
 175 /*
 176  * void
 177  * CLNT_ABORT(rh);
 178  *      CLIENT *rh;
 179  */
 180 #define CLNT_ABORT(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 181 #define clnt_abort(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 182
 183 /*
 184  * struct rpc_err
 185  * CLNT_GETERR(rh);
 186  *      CLIENT *rh;
 187  */
 188 #define CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 189 #define clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 190
 191
 192 /*
 193  * bool_t
 194  * CLNT_FREERES(rh, xres, resp);
 195  *      CLIENT *rh;
 196  *      xdrproc_t xres;
 197  *      caddr_t resp;
 198  */
 199 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
 200 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
 201
 202 /*
 203  * bool_t
 204  * CLNT_CONTROL(cl, request, info)
 205  *      CLIENT *cl;
 206  *      u_int request;
 207  *      char *info;
 208  */
 209 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
 210 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
 211
 212 /*
 213  * control operations that apply to all transports
 214  *
 215  * Note: options marked XXX are no-ops in this implementation of RPC.
 216  * The are present in TI-RPC but can't be implemented here since they
 217  * depend on the presence of STREAMS/TLI, which we don't have.
 218  */
 219 #define CLSET_TIMEOUT        1    /* set timeout (timeval) */
 220 #define CLGET_TIMEOUT        2    /* get timeout (timeval) */
 221 #define CLGET_SERVER_ADDR    3    /* get server's address (sockaddr) */
 222 #define CLGET_FD             6    /* get connections file descriptor */
 223 #define CLGET_SVC_ADDR       7    /* get server's address (netbuf)      XXX */
 224 #define CLSET_FD_CLOSE       8    /* close fd while clnt_destroy */
 225 #define CLSET_FD_NCLOSE      9    /* Do not close fd while clnt_destroy*/
 226 #define CLGET_XID            10   /* Get xid */
 227 #define CLSET_XID            11   /* Set xid */
 228 #define CLGET_VERS           12   /* Get version number */
 229 #define CLSET_VERS           13   /* Set version number */
 230 #define CLGET_PROG           14   /* Get program number */
 231 #define CLSET_PROG           15   /* Set program number */
 232 #define CLSET_SVC_ADDR       16   /* get server's address (netbuf)      XXX */
 233 #define CLSET_PUSH_TIMOD     17   /* push timod if not already present  XXX */
 234 #define CLSET_POP_TIMOD      18   /* pop timod                          XXX */
 235 /*
 236  * Connectionless only control operations
 237  */
 238 #define CLSET_RETRY_TIMEOUT     4       /* set retry timeout (timeval) */
 239 #define CLGET_RETRY_TIMEOUT     5       /* get retry timeout (timeval) */
 240
 241 /*
 242  * void
 243  * CLNT_DESTROY(rh);
 244  *      CLIENT *rh;
 245  */
 246 #define CLNT_DESTROY(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 247 #define clnt_destroy(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 248
 249
 250 /*
 251  * RPCTEST is a test program which is accessible on every rpc
 252  * transport/port.  It is used for testing, performance evaluation,
 253  * and network administration.
 254  */
 255
 256 #define RPCTEST_PROGRAM         ((u_long)1)
 257 #define RPCTEST_VERSION         ((u_long)1)
 258 #define RPCTEST_NULL_PROC       ((u_long)2)
 259 #define RPCTEST_NULL_BATCH_PROC ((u_long)3)
 260
 261 /*
 262  * By convention, procedure 0 takes null arguments and returns them
 263  */
 264
 265 #define NULLPROC ((u_long)0)
 266
 267 /*
 268  * Below are the client handle creation routines for the various
 269  * implementations of client side rpc.  They can return NULL if a
 270  * creation failure occurs.
 271  */
 272
 273 /*
 274  * Memory based rpc (for speed check and testing)
 275  * CLIENT *
 276  * clntraw_create(prog, vers)
 277  *      u_long prog;
 278  *      u_long vers;
 279  */
 280 extern CLIENT *clntraw_create __P ((__const u_long __prog,
 281                                     __const u_long __vers));
 282
 283
 284 /*
 285  * Generic client creation routine. Supported protocols are "udp" and "tcp"
 286  * CLIENT *
 287  * clnt_create(host, prog, vers, prot)
 288  *      char *host;     -- hostname
 289  *      u_long prog;    -- program number
 290  *      u_ong vers;     -- version number
 291  *      char *prot;     -- protocol
 292  */
 293 extern CLIENT *clnt_create __P ((__const char *__host, __const u_long __prog,
 294                                  __const u_long __vers, __const char *__prot));
 295
 296
 297 /*
 298  * TCP based rpc
 299  * CLIENT *
 300  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
 301  *      struct sockaddr_in *raddr;
 302  *      u_long prog;
 303  *      u_long version;
 304  *      register int *sockp;
 305  *      u_int sendsz;
 306  *      u_int recvsz;
 307  */
 308 extern CLIENT *clnttcp_create __P ((struct sockaddr_in *__raddr,
 309                                     u_long __prog, u_long __version,
 310                                     int *__sockp, u_int __sendsz,
 311                                     u_int __recvsz));
 312
 313 /*
 314  * UDP based rpc.
 315  * CLIENT *
 316  * clntudp_create(raddr, program, version, wait, sockp)
 317  *      struct sockaddr_in *raddr;
 318  *      u_long program;
 319  *      u_long version;
 320  *      struct timeval wait_resend;
 321  *      int *sockp;
 322  *
 323  * Same as above, but you specify max packet sizes.
 324  * CLIENT *
 325  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
 326  *      struct sockaddr_in *raddr;
 327  *      u_long program;
 328  *      u_long version;
 329  *      struct timeval wait_resend;
 330  *      int *sockp;
 331  *      u_int sendsz;
 332  *      u_int recvsz;
 333  */
 334 extern CLIENT *clntudp_create __P ((struct sockaddr_in *__raddr,
 335                                     u_long __program, u_long __version,
 336                                     struct timeval __wait_resend,
 337                                     int *__sockp));
 338 extern CLIENT *clntudp_bufcreate __P ((struct sockaddr_in *__raddr,
 339                                        u_long __program, u_long __version,
 340                                        struct timeval __wait_resend,
 341                                        int *__sockp, u_int __sendsz,
 342                                        u_int __recvsz));
 343
 344 extern int callrpc __P ((__const char *__host, __const u_long __prognum,
 345                          __const u_long __versnum, __const u_long __procnum,
 346                          __const xdrproc_t __inproc, __const char *__in,
 347                          __const xdrproc_t __outproc, char *__out));
 348 extern int _rpc_dtablesize __P ((void));
 349
 350 /*
 351  * Print why creation failed
 352  */
 353 extern void clnt_pcreateerror __P ((__const char *__msg));      /* stderr */
 354 extern char *clnt_spcreateerror __P ((__const char *__msg));    /* string */
 355
 356 /*
 357  * Like clnt_perror(), but is more verbose in its output
 358  */
 359 extern void clnt_perrno __P ((enum clnt_stat __num));   /* stderr */
 360
 361 /*
 362  * Print an English error message, given the client error code
 363  */
 364 extern void clnt_perror __P ((CLIENT *__clnt, __const char *__msg));
 365                                                         /* stderr */
 366 extern char *clnt_sperror __P ((CLIENT *__clnt, __const char *__msg));
 367                                                         /* string */
 368
 369 /*
 370  * If a creation fails, the following allows the user to figure out why.
 371  */
 372 struct rpc_createerr {
 373         enum clnt_stat cf_stat;
 374         struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
 375 };
 376
 377 extern struct rpc_createerr rpc_createerr;
 378
 379
 380
 381 /*
 382  * Copy error message to buffer.
 383  */
 384 extern char *clnt_sperrno __P ((enum clnt_stat __num)); /* string */
 385
 386 /*
 387  * get the port number on the host for the rpc program,version and proto
 388  */
 389 extern int getrpcport __P ((__const char * __host, u_long __prognum,
 390                            u_long __versnum, u_int proto));
 391
 392 /*
 393  * get the local host's IP address without consulting
 394  * name service library functions
 395  */
 396 extern void get_myaddress __P ((struct sockaddr_in *));
 397
 398 #define UDPMSGSIZE      8800    /* rpc imposed limit on udp msg size */
 399 #define RPCSMALLMSGSIZE 400     /* a more reasonable packet size */
 400
 401 __END_DECLS
 402
 403 #endif /* rpc/clnt.h */