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