usr/src/lib/libbc/inc/include/rpc/clnt.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 #pragma ident   "%Z%%M% %I%     %E% SMI"
  23
  24 /*
  25  * clnt.h - Client side remote procedure call interface.
  26  *
  27  * Copyright (C) 1984, Sun Microsystems, Inc.
  28  */
  29
  30 #ifndef _rpc_clnt_h
  31 #define _rpc_clnt_h
  32
  33 /*
  34  * Rpc calls return an enum clnt_stat.  This should be looked at more,
  35  * since each implementation is required to live with this (implementation
  36  * independent) list of errors.
  37  */
  38 enum clnt_stat {
  39         RPC_SUCCESS=0,                  /* call succeeded */
  40         /*
  41          * local errors
  42          */
  43         RPC_CANTENCODEARGS=1,           /* can't encode arguments */
  44         RPC_CANTDECODERES=2,            /* can't decode results */
  45         RPC_CANTSEND=3,                 /* failure in sending call */
  46         RPC_CANTRECV=4,                 /* failure in receiving result */
  47         RPC_TIMEDOUT=5,                 /* call timed out */
  48         RPC_INTR=18,                    /* call interrupted */
  49         /*
  50          * remote errors
  51          */
  52         RPC_VERSMISMATCH=6,             /* rpc versions not compatible */
  53         RPC_AUTHERROR=7,                /* authentication error */
  54         RPC_PROGUNAVAIL=8,              /* program not available */
  55         RPC_PROGVERSMISMATCH=9,         /* program version mismatched */
  56         RPC_PROCUNAVAIL=10,             /* procedure unavailable */
  57         RPC_CANTDECODEARGS=11,          /* decode arguments error */
  58         RPC_SYSTEMERROR=12,             /* generic "other problem" */
  59
  60         /*
  61          * callrpc & clnt_create errors
  62          */
  63         RPC_UNKNOWNHOST=13,             /* unknown host name */
  64         RPC_UNKNOWNPROTO=17,            /* unkown protocol */
  65
  66         /*
  67          * _ create errors
  68          */
  69         RPC_PMAPFAILURE=14,             /* the pmapper failed in its call */
  70         RPC_PROGNOTREGISTERED=15,       /* remote program is not registered */
  71         /*
  72          * unspecified error
  73          */
  74         RPC_FAILED=16
  75 };
  76
  77
  78 /*
  79  * Error info.
  80  */
  81 struct rpc_err {
  82         enum clnt_stat re_status;
  83         union {
  84                 int RE_errno;           /* realated system error */
  85                 enum auth_stat RE_why;  /* why the auth error occurred */
  86                 struct {
  87                         u_long low;     /* lowest verion supported */
  88                         u_long high;    /* highest verion supported */
  89                 } RE_vers;
  90                 struct {                /* maybe meaningful if RPC_FAILED */
  91                         long s1;
  92                         long s2;
  93                 } RE_lb;                /* life boot & debugging only */
  94         } ru;
  95 #define re_errno        ru.RE_errno
  96 #define re_why          ru.RE_why
  97 #define re_vers         ru.RE_vers
  98 #define re_lb           ru.RE_lb
  99 };
 100
 101
 102 /*
 103  * Client rpc handle.
 104  * Created by individual implementations, see e.g. rpc_udp.c.
 105  * Client is responsible for initializing auth, see e.g. auth_none.c.
 106  */
 107 typedef struct {
 108         AUTH    *cl_auth;                       /* authenticator */
 109         struct clnt_ops {
 110                 enum clnt_stat  (*cl_call)();   /* call remote procedure */
 111                 void            (*cl_abort)();  /* abort a call */
 112                 void            (*cl_geterr)(); /* get specific error code */
 113                 bool_t          (*cl_freeres)(); /* frees results */
 114                 void            (*cl_destroy)(); /* destroy this structure */
 115                 bool_t          (*cl_control)(); /* the ioctl() of rpc */
 116         } *cl_ops;
 117         caddr_t                 cl_private;     /* private stuff */
 118 } CLIENT;
 119
 120
 121 /*
 122  * client side rpc interface ops
 123  *
 124  * Parameter types are:
 125  *
 126  */
 127
 128 /*
 129  * enum clnt_stat
 130  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
 131  *      CLIENT *rh;
 132  *      u_long proc;
 133  *      xdrproc_t xargs;
 134  *      caddr_t argsp;
 135  *      xdrproc_t xres;
 136  *      caddr_t resp;
 137  *      struct timeval timeout;
 138  */
 139 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)     \
 140         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 141 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs)     \
 142         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 143
 144 /*
 145  * void
 146  * CLNT_ABORT(rh);
 147  *      CLIENT *rh;
 148  */
 149 #define CLNT_ABORT(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 150 #define clnt_abort(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 151
 152 /*
 153  * struct rpc_err
 154  * CLNT_GETERR(rh);
 155  *      CLIENT *rh;
 156  */
 157 #define CLNT_GETERR(rh, errp)   ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 158 #define clnt_geterr(rh, errp)   ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 159
 160
 161 /*
 162  * bool_t
 163  * CLNT_FREERES(rh, xres, resp);
 164  *      CLIENT *rh;
 165  *      xdrproc_t xres;
 166  *      caddr_t resp;
 167  */
 168 #define CLNT_FREERES(rh, xres, resp) ((*(rh)->cl_ops->cl_freeres)\
 169         (rh, xres, resp))
 170 #define clnt_freeres(rh, xres, resp) ((*(rh)->cl_ops->cl_freeres)\
 171         (rh, xres, resp))
 172
 173 /*
 174  * bool_t
 175  * CLNT_CONTROL(cl, request, info)
 176  *      CLIENT *cl;
 177  *      u_int request;
 178  *      char *info;
 179  */
 180 #define CLNT_CONTROL(cl, rq, in) ((*(cl)->cl_ops->cl_control)(cl, rq, in))
 181 #define clnt_control(cl, rq, in) ((*(cl)->cl_ops->cl_control)(cl, rq, in))
 182
 183 /*
 184  * control operations that apply to both udp and tcp transports
 185  */
 186 #define CLSET_TIMEOUT           1   /* set timeout (timeval) */
 187 #define CLGET_TIMEOUT           2   /* get timeout (timeval) */
 188 #define CLGET_SERVER_ADDR       3   /* get server's address (sockaddr) */
 189 #define CLGET_FD                6   /* get connections file descriptor */
 190 #define CLSET_FD_CLOSE          8   /* close fd while clnt_destroy */
 191 #define CLSET_FD_NCLOSE         9   /* Do not close fd while clnt_destroy */
 192 /*
 193  * udp only control operations
 194  */
 195 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
 196 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
 197
 198 /*
 199  * void
 200  * CLNT_DESTROY(rh);
 201  *      CLIENT *rh;
 202  */
 203 #define CLNT_DESTROY(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 204 #define clnt_destroy(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 205
 206
 207 /*
 208  * RPCTEST is a test program which is accessable on every rpc
 209  * transport/port.  It is used for testing, performance evaluation,
 210  * and network administration.
 211  */
 212
 213 #define RPCTEST_PROGRAM         ((u_long)1)
 214 #define RPCTEST_VERSION         ((u_long)1)
 215 #define RPCTEST_NULL_PROC       ((u_long)2)
 216 #define RPCTEST_NULL_BATCH_PROC ((u_long)3)
 217
 218 /*
 219  * By convention, procedure 0 takes null arguments and returns them
 220  */
 221
 222 #define NULLPROC ((u_long)0)
 223
 224 /*
 225  * Below are the client handle creation routines for the various
 226  * implementations of client side rpc.  They can return NULL if a
 227  * creation failure occurs.
 228  */
 229
 230 #ifndef KERNEL
 231 /*
 232  * Memory based rpc (for speed check and testing)
 233  * CLIENT *
 234  * clntraw_create(prog, vers)
 235  *      u_long prog;
 236  *      u_long vers;
 237  */
 238 extern CLIENT *clntraw_create();
 239
 240
 241 /*
 242  * Generic client creation routine. Supported protocols are "udp" and "tcp"
 243  */
 244 extern CLIENT *
 245 clnt_create(/*host, prog, vers, prot*/); /*
 246         char *host;     -- hostname
 247         u_long prog;    -- program number
 248         u_long vers;    -- version number
 249         char *prot;     -- protocol
 250 */
 251
 252 /*
 253  * Generic client creation routine. Supported protocols are "udp" and "tcp"
 254  */
 255 extern CLIENT *
 256 clnt_create_vers(/*host, prog, vers_out, vers_low, vers_high, prot*/);
 257 /*
 258         char *host;     -- hostname
 259         u_long prog;    -- program number
 260         u_long *vers_out;       -- servers best  version number
 261         u_long vers_low;        -- low version number
 262         u_long vers_high;       -- high version number
 263         char *prot;     -- protocol
 264 */
 265
 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();
 280
 281 /*
 282  * UDP based rpc.
 283  * CLIENT *
 284  * clntudp_create(raddr, program, version, wait, sockp)
 285  *      struct sockaddr_in *raddr;
 286  *      u_long program;
 287  *      u_long version;
 288  *      struct timeval wait;
 289  *      int *sockp;
 290  *
 291  * Same as above, but you specify max packet sizes.
 292  * CLIENT *
 293  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
 294  *      struct sockaddr_in *raddr;
 295  *      u_long program;
 296  *      u_long version;
 297  *      struct timeval wait;
 298  *      int *sockp;
 299  *      u_int sendsz;
 300  *      u_int recvsz;
 301  */
 302 extern CLIENT *clntudp_create();
 303 extern CLIENT *clntudp_bufcreate();
 304
 305 /*
 306  * Print why creation failed
 307  */
 308 void clnt_pcreateerror(/* char *msg */);        /* stderr */
 309 char *clnt_spcreateerror(/* char *msg */);      /* string */
 310
 311 /*
 312  * Like clnt_perror(), but is more verbose in its output
 313  */
 314 void clnt_perrno(/* enum clnt_stat num */);     /* stderr */
 315
 316 /*
 317  * Print an English error message, given the client error code
 318  */
 319 void clnt_perror(/* CLIENT *clnt, char *msg */);        /* stderr */
 320 char *clnt_sperror(/* CLIENT *clnt, char *msg */);      /* string */
 321
 322 /*
 323  * If a creation fails, the following allows the user to figure out why.
 324  */
 325 struct rpc_createerr {
 326         enum clnt_stat cf_stat;
 327         struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
 328 };
 329
 330 extern struct rpc_createerr rpc_createerr;
 331
 332
 333 #endif /* !KERNEL */
 334
 335 /*
 336  * Copy error message to buffer.
 337  */
 338 char *clnt_sperrno(/* enum clnt_stat num */);   /* string */
 339
 340
 341 #ifdef KERNEL
 342 /*
 343  * Kernel udp based rpc
 344  * CLIENT *
 345  * clntkudp_create(addr, pgm, vers)
 346  *      struct sockaddr_in *addr;
 347  *      u_long pgm;
 348  *      u_long vers;
 349  */
 350 extern CLIENT *clntkudp_create();
 351 #endif
 352
 353 /*
 354  * Timers used for the pseudo-transport protocol when using datagrams
 355  */
 356 struct rpc_timers {
 357         u_short         rt_srtt;        /* smoothed round-trip time */
 358         u_short         rt_deviate;     /* estimated deviation */
 359         u_long          rt_rtxcur;      /* current (backed-off) rto */
 360 };
 361
 362 /*
 363  * Feedback values used for possible congestion and rate control
 364  */
 365 #define FEEDBACK_REXMIT1        1       /* first retransmit */
 366 #define FEEDBACK_OK             2       /* no retransmits */
 367
 368 #define UDPMSGSIZE      8800    /* rpc imposed limit on udp msg size */
 369 #define RPCSMALLMSGSIZE 400     /* a more reasonable packet size */
 370
 371 #ifdef  KERNEL
 372 /*
 373  *      Alloc_xid presents an interface which kernel RPC clients
 374  *      should use to allocate their XIDs.  Its implementation
 375  *      may change over time (for example, to allow sharing of
 376  *      XIDs between the kernel and user-level applications, so
 377  *      all XID allocation should be done by calling alloc_xid().
 378  */
 379 extern u_long   clntxid;
 380 #define alloc_xid()     (clntxid++)
 381 #endif
 382
 383 #endif /*!_rpc_clnt_h*/