tirpc/rpc/clnt.h

0001 /*  $NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $   */
0002
0003 /*
0004  * Copyright (c) 2010, Oracle America, Inc.
0005  * All rights reserved.
0006  *
0007  * Redistribution and use in source and binary forms, with or without
0008  * modification, are permitted provided that the following conditions are met:
0009  * - Redistributions of source code must retain the above copyright notice,
0010  *   this list of conditions and the following disclaimer.
0011  * - Redistributions in binary form must reproduce the above copyright notice,
0012  *   this list of conditions and the following disclaimer in the documentation
0013  *   and/or other materials provided with the distribution.
0014  * - Neither the name of the "Oracle America, Inc." nor the names of its
0015  *   contributors may be used to endorse or promote products derived
0016  *   from this software without specific prior written permission.
0017  *
0018  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0019  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0020  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0021  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
0022  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0023  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0024  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0025  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0026  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0027  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0028  * POSSIBILITY OF SUCH DAMAGE.
0029  *
0030  *  from: @(#)clnt.h 1.31 94/04/29 SMI
0031  *  from: @(#)clnt.h    2.1 88/07/29 4.0 RPCSRC
0032  * $FreeBSD: src/include/rpc/clnt.h,v 1.21 2003/01/24 01:47:55 fjoe Exp $
0033  */
0034
0035 /*
0036  * clnt.h - Client side remote procedure call interface.
0037  */
0038
0039 #ifndef _TIRPC_CLNT_H_
0040 #define _TIRPC_CLNT_H_
0041
0042 #include <rpc/clnt_stat.h>
0043 #include <rpc/auth.h>
0044
0045 #include <netconfig.h>
0046 #include <sys/un.h>
0047
0048 /*
0049  * Well-known IPV6 RPC broadcast address.
0050  */
0051 #define RPCB_MULTICAST_ADDR "ff02::202"
0052
0053 /*
0054  * the following errors are in general unrecoverable.  The caller
0055  * should give up rather than retry.
0056  */
0057 #define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \
0058     ((s) == RPC_CANTENCODEARGS) || \
0059     ((s) == RPC_CANTDECODERES) || \
0060     ((s) == RPC_VERSMISMATCH) || \
0061     ((s) == RPC_PROCUNAVAIL) || \
0062     ((s) == RPC_PROGUNAVAIL) || \
0063     ((s) == RPC_PROGVERSMISMATCH) || \
0064     ((s) == RPC_CANTDECODEARGS))
0065
0066 /*
0067  * Error info.
0068  */
0069 struct rpc_err {
0070     enum clnt_stat re_status;
0071     union {
0072         int RE_errno;       /* related system error */
0073         enum auth_stat RE_why;  /* why the auth error occurred */
0074         struct {
0075             rpcvers_t low;  /* lowest version supported */
0076             rpcvers_t high; /* highest version supported */
0077         } RE_vers;
0078         struct {        /* maybe meaningful if RPC_FAILED */
0079             int32_t s1;
0080             int32_t s2;
0081         } RE_lb;        /* life boot & debugging only */
0082     } ru;
0083 #define re_errno    ru.RE_errno
0084 #define re_why      ru.RE_why
0085 #define re_vers     ru.RE_vers
0086 #define re_lb       ru.RE_lb
0087 };
0088
0089
0090 /*
0091  * Client rpc handle.
0092  * Created by individual implementations
0093  * Client is responsible for initializing auth, see e.g. auth_none.c.
0094  */
0095 typedef struct __rpc_client {
0096     AUTH    *cl_auth;           /* authenticator */
0097     struct clnt_ops {
0098         /* call remote procedure */
0099         enum clnt_stat  (*cl_call)(struct __rpc_client *,
0100                     rpcproc_t, xdrproc_t, void *, xdrproc_t,
0101                         void *, struct timeval);
0102         /* abort a call */
0103         void        (*cl_abort)(struct __rpc_client *);
0104         /* get specific error code */
0105         void        (*cl_geterr)(struct __rpc_client *,
0106                     struct rpc_err *);
0107         /* frees results */
0108         bool_t      (*cl_freeres)(struct __rpc_client *,
0109                     xdrproc_t, void *);
0110         /* destroy this structure */
0111         void        (*cl_destroy)(struct __rpc_client *);
0112         /* the ioctl() of rpc */
0113         bool_t          (*cl_control)(struct __rpc_client *, u_int,
0114                     void *);
0115     } *cl_ops;
0116     void            *cl_private;    /* private stuff */
0117     char            *cl_netid;  /* network token */
0118     char            *cl_tp;     /* device name */
0119 } CLIENT;
0120
0121
0122 /*
0123  * Timers used for the pseudo-transport protocol when using datagrams
0124  */
0125 struct rpc_timers {
0126     u_short     rt_srtt;    /* smoothed round-trip time */
0127     u_short     rt_deviate; /* estimated deviation */
0128     u_long      rt_rtxcur;  /* current (backed-off) rto */
0129 };
0130
0131 /*
0132  * Feedback values used for possible congestion and rate control
0133  */
0134 #define FEEDBACK_REXMIT1    1   /* first retransmit */
0135 #define FEEDBACK_OK     2   /* no retransmits */
0136
0137 /* Used to set version of portmapper used in broadcast */
0138
0139 #define CLCR_SET_LOWVERS    3
0140 #define CLCR_GET_LOWVERS    4
0141
0142 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */
0143
0144 /*
0145  * client side rpc interface ops
0146  *
0147  * Parameter types are:
0148  *
0149  */
0150
0151 /*
0152  * enum clnt_stat
0153  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
0154  *  CLIENT *rh;
0155  *  rpcproc_t proc;
0156  *  xdrproc_t xargs;
0157  *  void *argsp;
0158  *  xdrproc_t xres;
0159  *  void *resp;
0160  *  struct timeval timeout;
0161  */
0162 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
0163     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
0164         argsp, xres, resp, secs))
0165 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
0166     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \
0167         argsp, xres, resp, secs))
0168
0169 /*
0170  * void
0171  * CLNT_ABORT(rh);
0172  *  CLIENT *rh;
0173  */
0174 #define CLNT_ABORT(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
0175 #define clnt_abort(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
0176
0177 /*
0178  * struct rpc_err
0179  * CLNT_GETERR(rh);
0180  *  CLIENT *rh;
0181  */
0182 #define CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
0183 #define clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
0184
0185
0186 /*
0187  * bool_t
0188  * CLNT_FREERES(rh, xres, resp);
0189  *  CLIENT *rh;
0190  *  xdrproc_t xres;
0191  *  void *resp;
0192  */
0193 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
0194 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
0195
0196 /*
0197  * bool_t
0198  * CLNT_CONTROL(cl, request, info)
0199  *      CLIENT *cl;
0200  *      u_int request;
0201  *      char *info;
0202  */
0203 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
0204 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
0205
0206 /*
0207  * control operations that apply to both udp and tcp transports
0208  */
0209 #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
0210 #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
0211 #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
0212 #define CLGET_FD        6   /* get connections file descriptor */
0213 #define CLGET_SVC_ADDR      7   /* get server's address (netbuf) */
0214 #define CLSET_FD_CLOSE      8   /* close fd while clnt_destroy */
0215 #define CLSET_FD_NCLOSE     9   /* Do not close fd while clnt_destroy */
0216 #define CLGET_XID       10  /* Get xid */
0217 #define CLSET_XID       11  /* Set xid */
0218 #define CLGET_VERS      12  /* Get version number */
0219 #define CLSET_VERS      13  /* Set version number */
0220 #define CLGET_PROG      14  /* Get program number */
0221 #define CLSET_PROG      15  /* Set program number */
0222 #define CLSET_SVC_ADDR      16  /* get server's address (netbuf) */
0223 #define CLSET_PUSH_TIMOD    17  /* push timod if not already present */
0224 #define CLSET_POP_TIMOD     18  /* pop timod */
0225 /*
0226  * Connectionless only control operations
0227  */
0228 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
0229 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
0230 #define CLSET_ASYNC     19
0231 #define CLSET_CONNECT       20  /* Use connect() for UDP. (int) */
0232
0233 /*
0234  * void
0235  * CLNT_DESTROY(rh);
0236  *  CLIENT *rh;
0237  */
0238 #define CLNT_DESTROY(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
0239 #define clnt_destroy(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
0240
0241
0242 /*
0243  * RPCTEST is a test program which is accessible on every rpc
0244  * transport/port.  It is used for testing, performance evaluation,
0245  * and network administration.
0246  */
0247
0248 #define RPCTEST_PROGRAM     ((rpcprog_t)1)
0249 #define RPCTEST_VERSION     ((rpcvers_t)1)
0250 #define RPCTEST_NULL_PROC   ((rpcproc_t)2)
0251 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3)
0252
0253 /*
0254  * By convention, procedure 0 takes null arguments and returns them
0255  */
0256
0257 #define NULLPROC ((rpcproc_t)0)
0258
0259 /*
0260  * Below are the client handle creation routines for the various
0261  * implementations of client side rpc.  They can return NULL if a
0262  * creation failure occurs.
0263  */
0264
0265 /*
0266  * Generic client creation routine. Supported protocols are those that
0267  * belong to the nettype namespace (/etc/netconfig).
0268  */
0269 #ifdef __cplusplus
0270 extern "C" {
0271 #endif
0272 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t,
0273                const char *);
0274 /*
0275  *
0276  *  const char *hostname;           -- hostname
0277  *  const rpcprog_t prog;           -- program number
0278  *  const rpcvers_t vers;           -- version number
0279  *  const char *nettype;            -- network type
0280  */
0281
0282  /*
0283  * Generic client creation routine. Just like clnt_create(), except
0284  * it takes an additional timeout parameter.
0285  */
0286 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t,
0287     const rpcvers_t, const char *, const struct timeval *);
0288 /*
0289  *
0290  *  const char *hostname;           -- hostname
0291  *  const rpcprog_t prog;           -- program number
0292  *  const rpcvers_t vers;           -- version number
0293  *  const char *nettype;            -- network type
0294  *  const struct timeval *tp;       -- timeout
0295  */
0296
0297 /*
0298  * Generic client creation routine. Supported protocols are which belong
0299  * to the nettype name space.
0300  */
0301 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *,
0302                 const rpcvers_t, const rpcvers_t,
0303                 const char *);
0304 /*
0305  *  const char *host;       -- hostname
0306  *  const rpcprog_t prog;       -- program number
0307  *  rpcvers_t *vers_out;        -- servers highest available version
0308  *  const rpcvers_t vers_low;   -- low version number
0309  *  const rpcvers_t vers_high;  -- high version number
0310  *  const char *nettype;        -- network type
0311  */
0312
0313 /*
0314  * Generic client creation routine. Supported protocols are which belong
0315  * to the nettype name space.
0316  */
0317 extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t,
0318     rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *,
0319     const struct timeval *);
0320 /*
0321  *  const char *host;       -- hostname
0322  *  const rpcprog_t prog;       -- program number
0323  *  rpcvers_t *vers_out;        -- servers highest available version
0324  *  const rpcvers_t vers_low;   -- low version number
0325  *  const rpcvers_t vers_high;  -- high version number
0326  *  const char *nettype;        -- network type
0327  *  const struct timeval *tp    -- timeout
0328  */
0329
0330 /*
0331  * Generic client creation routine. It takes a netconfig structure
0332  * instead of nettype
0333  */
0334 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t,
0335                   const rpcvers_t, const struct netconfig *);
0336 /*
0337  *  const char *hostname;           -- hostname
0338  *  const rpcprog_t prog;           -- program number
0339  *  const rpcvers_t vers;           -- version number
0340  *  const struct netconfig *netconf;    -- network config structure
0341  */
0342
0343 /*
0344  * Generic client creation routine. Just like clnt_tp_create(), except
0345  * it takes an additional timeout parameter.
0346  */
0347 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t,
0348     const rpcvers_t, const struct netconfig *, const struct timeval *);
0349 /*
0350  *  const char *hostname;           -- hostname
0351  *  const rpcprog_t prog;           -- program number
0352  *  const rpcvers_t vers;           -- version number
0353  *  const struct netconfig *netconf;    -- network config structure
0354  *  const struct timeval *tp        -- timeout
0355  */
0356
0357 /*
0358  * Generic TLI create routine. Only provided for compatibility.
0359  */
0360
0361 extern CLIENT *clnt_tli_create(const int, const struct netconfig *,
0362                    struct netbuf *, const rpcprog_t,
0363                    const rpcvers_t, const u_int, const u_int);
0364 /*
0365  *  const register int fd;      -- fd
0366  *  const struct netconfig *nconf;  -- netconfig structure
0367  *  struct netbuf *svcaddr;     -- servers address
0368  *  const u_long prog;          -- program number
0369  *  const u_long vers;          -- version number
0370  *  const u_int sendsz;         -- send size
0371  *  const u_int recvsz;         -- recv size
0372  */
0373
0374 /*
0375  * Low level clnt create routine for connectionful transports, e.g. tcp.
0376  */
0377 extern CLIENT *clnt_vc_create(const int, const struct netbuf *,
0378                   const rpcprog_t, const rpcvers_t,
0379                   u_int, u_int);
0380 /*
0381  * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create().
0382  */
0383 extern CLIENT *clntunix_create(struct sockaddr_un *,
0384                    u_long, u_long, int *, u_int, u_int);
0385 /*
0386  *  const int fd;               -- open file descriptor
0387  *  const struct netbuf *svcaddr;       -- servers address
0388  *  const rpcprog_t prog;           -- program number
0389  *  const rpcvers_t vers;           -- version number
0390  *  const u_int sendsz;         -- buffer recv size
0391  *  const u_int recvsz;         -- buffer send size
0392  */
0393
0394 /*
0395  * Low level clnt create routine for connectionless transports, e.g. udp.
0396  */
0397 extern CLIENT *clnt_dg_create(const int, const struct netbuf *,
0398                   const rpcprog_t, const rpcvers_t,
0399                   const u_int, const u_int);
0400 /*
0401  *  const int fd;               -- open file descriptor
0402  *  const struct netbuf *svcaddr;       -- servers address
0403  *  const rpcprog_t program;        -- program number
0404  *  const rpcvers_t version;        -- version number
0405  *  const u_int sendsz;         -- buffer recv size
0406  *  const u_int recvsz;         -- buffer send size
0407  */
0408
0409 /*
0410  * Memory based rpc (for speed check and testing)
0411  * CLIENT *
0412  * clnt_raw_create(prog, vers)
0413  *  u_long prog;
0414  *  u_long vers;
0415  */
0416 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t);
0417
0418 #ifdef __cplusplus
0419 }
0420 #endif
0421
0422
0423 /*
0424  * Print why creation failed
0425  */
0426 #ifdef __cplusplus
0427 extern "C" {
0428 #endif
0429 extern void clnt_pcreateerror(const char *);            /* stderr */
0430 extern char *clnt_spcreateerror(const char *);          /* string */
0431 #ifdef __cplusplus
0432 }
0433 #endif
0434
0435 /*
0436  * Like clnt_perror(), but is more verbose in its output
0437  */
0438 #ifdef __cplusplus
0439 extern "C" {
0440 #endif
0441 extern void clnt_perrno(enum clnt_stat);        /* stderr */
0442 extern char *clnt_sperrno(enum clnt_stat);      /* string */
0443 #ifdef __cplusplus
0444 }
0445 #endif
0446
0447 /*
0448  * Print an English error message, given the client error code
0449  */
0450 #ifdef __cplusplus
0451 extern "C" {
0452 #endif
0453 extern void clnt_perror(CLIENT *, const char *);        /* stderr */
0454 extern char *clnt_sperror(CLIENT *, const char *);      /* string */
0455 #ifdef __cplusplus
0456 }
0457 #endif
0458
0459
0460 /*
0461  * If a creation fails, the following allows the user to figure out why.
0462  */
0463 struct rpc_createerr {
0464     enum clnt_stat cf_stat;
0465     struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
0466 };
0467
0468 #ifdef __cplusplus
0469 extern "C" {
0470 #endif
0471 extern struct rpc_createerr *__rpc_createerr(void);
0472 #ifdef __cplusplus
0473 }
0474 #endif
0475 #define get_rpc_createerr() (*(__rpc_createerr()))
0476 #define rpc_createerr       (*(__rpc_createerr()))
0477
0478 /*
0479  * The simplified interface:
0480  * enum clnt_stat
0481  * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
0482  *  const char *host;
0483  *  const rpcprog_t prognum;
0484  *  const rpcvers_t versnum;
0485  *  const rpcproc_t procnum;
0486  *  const xdrproc_t inproc, outproc;
0487  *  const char *in;
0488  *  char *out;
0489  *  const char *nettype;
0490  */
0491 #ifdef __cplusplus
0492 extern "C" {
0493 #endif
0494 extern enum clnt_stat rpc_call(const char *, const rpcprog_t,
0495                    const rpcvers_t, const rpcproc_t,
0496                    const xdrproc_t, const char *,
0497                    const xdrproc_t, char *, const char *);
0498 #ifdef __cplusplus
0499 }
0500 #endif
0501
0502 /*
0503  * RPC broadcast interface
0504  * The call is broadcasted to all locally connected nets.
0505  *
0506  * extern enum clnt_stat
0507  * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
0508  *          eachresult, nettype)
0509  *  const rpcprog_t     prog;       -- program number
0510  *  const rpcvers_t     vers;       -- version number
0511  *  const rpcproc_t     proc;       -- procedure number
0512  *  const xdrproc_t xargs;      -- xdr routine for args
0513  *  caddr_t     argsp;      -- pointer to args
0514  *  const xdrproc_t xresults;   -- xdr routine for results
0515  *  caddr_t     resultsp;   -- pointer to results
0516  *  const resultproc_t  eachresult; -- call with each result
0517  *  const char      *nettype;   -- Transport type
0518  *
0519  * For each valid response received, the procedure eachresult is called.
0520  * Its form is:
0521  *      done = eachresult(resp, raddr, nconf)
0522  *          bool_t done;
0523  *          caddr_t resp;
0524  *          struct netbuf *raddr;
0525  *          struct netconfig *nconf;
0526  * where resp points to the results of the call and raddr is the
0527  * address if the responder to the broadcast.  nconf is the transport
0528  * on which the response was received.
0529  *
0530  * extern enum clnt_stat
0531  * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp,
0532  *          eachresult, inittime, waittime, nettype)
0533  *  const rpcprog_t     prog;       -- program number
0534  *  const rpcvers_t     vers;       -- version number
0535  *  const rpcproc_t     proc;       -- procedure number
0536  *  const xdrproc_t xargs;      -- xdr routine for args
0537  *  caddr_t     argsp;      -- pointer to args
0538  *  const xdrproc_t xresults;   -- xdr routine for results
0539  *  caddr_t     resultsp;   -- pointer to results
0540  *  const resultproc_t  eachresult; -- call with each result
0541  *  const int       inittime;   -- how long to wait initially
0542  *  const int       waittime;   -- maximum time to wait
0543  *  const char      *nettype;   -- Transport type
0544  */
0545
0546 typedef bool_t (*resultproc_t)(caddr_t, ...);
0547
0548 #ifdef __cplusplus
0549 extern "C" {
0550 #endif
0551 extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t,
0552                     const rpcproc_t, const xdrproc_t,
0553                     caddr_t, const xdrproc_t, caddr_t,
0554                     const resultproc_t, const char *);
0555 extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t,
0556                     const rpcproc_t, const xdrproc_t,
0557                     caddr_t, const xdrproc_t, caddr_t,
0558                     const resultproc_t, const int,
0559                     const int, const char *);
0560 #ifdef __cplusplus
0561 }
0562 #endif
0563
0564 /* For backward compatibility */
0565 #include <rpc/clnt_soc.h>
0566
0567 #endif /* !_TIRPC_CLNT_H_ */