1/* $NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $ */ 2 3/*- 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 * Copyright (c) 2010, Oracle America, Inc. 7 * All rights reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions are met: 11 * - Redistributions of source code must retain the above copyright notice, 12 * this list of conditions and the following disclaimer. 13 * - Redistributions in binary form must reproduce the above copyright notice, 14 * this list of conditions and the following disclaimer in the documentation 15 * and/or other materials provided with the distribution. 16 * - Neither the name of the "Oracle America, Inc." nor the names of its 17 * contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30 * POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33/* 34 * clnt.h - Client side remote procedure call interface. 35 */ 36 37#ifndef _RPC_CLNT_H_ 38#define _RPC_CLNT_H_ 39#include <rpc/clnt_stat.h> 40#include <sys/cdefs.h> 41#include <netconfig.h> 42#include <sys/un.h> 43 44/* 45 * Well-known IPV6 RPC broadcast address. 46 */ 47#define RPCB_MULTICAST_ADDR "ff02::202" 48 49/* 50 * the following errors are in general unrecoverable. The caller 51 * should give up rather than retry. 52 */ 53#define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \ 54 ((s) == RPC_CANTENCODEARGS) || \ 55 ((s) == RPC_CANTDECODERES) || \ 56 ((s) == RPC_VERSMISMATCH) || \ 57 ((s) == RPC_PROCUNAVAIL) || \ 58 ((s) == RPC_PROGUNAVAIL) || \ 59 ((s) == RPC_PROGVERSMISMATCH) || \ 60 ((s) == RPC_CANTDECODEARGS)) 61 62/* 63 * Error info. 64 */ 65struct rpc_err { 66 enum clnt_stat re_status; 67 union { 68 int RE_errno; /* related system error */ 69 enum auth_stat RE_why; /* why the auth error occurred */ 70 struct { 71 rpcvers_t low; /* lowest version supported */ 72 rpcvers_t high; /* highest version supported */ 73 } RE_vers; 74 struct { /* maybe meaningful if RPC_FAILED */ 75 int32_t s1; 76 int32_t s2; 77 } RE_lb; /* life boot & debugging only */ 78 } ru; 79#define re_errno ru.RE_errno 80#define re_why ru.RE_why 81#define re_vers ru.RE_vers 82#define re_lb ru.RE_lb 83}; 84 85 86/* 87 * Client rpc handle. 88 * Created by individual implementations 89 * Client is responsible for initializing auth, see e.g. auth_none.c. 90 */ 91typedef struct __rpc_client { 92 AUTH *cl_auth; /* authenticator */ 93 struct clnt_ops { 94 /* call remote procedure */ 95 enum clnt_stat (*cl_call)(struct __rpc_client *, 96 rpcproc_t, xdrproc_t, void *, xdrproc_t, 97 void *, struct timeval); 98 /* abort a call */ 99 void (*cl_abort)(struct __rpc_client *); 100 /* get specific error code */ 101 void (*cl_geterr)(struct __rpc_client *, 102 struct rpc_err *); 103 /* frees results */ 104 bool_t (*cl_freeres)(struct __rpc_client *, 105 xdrproc_t, void *); 106 /* destroy this structure */ 107 void (*cl_destroy)(struct __rpc_client *); 108 /* the ioctl() of rpc */ 109 bool_t (*cl_control)(struct __rpc_client *, u_int, 110 void *); 111 } *cl_ops; 112 void *cl_private; /* private stuff */ 113 char *cl_netid; /* network token */ 114 char *cl_tp; /* device name */ 115} CLIENT; 116 117 118/* 119 * Timers used for the pseudo-transport protocol when using datagrams 120 */ 121struct rpc_timers { 122 u_short rt_srtt; /* smoothed round-trip time */ 123 u_short rt_deviate; /* estimated deviation */ 124 u_long rt_rtxcur; /* current (backed-off) rto */ 125}; 126 127/* 128 * Feedback values used for possible congestion and rate control 129 */ 130#define FEEDBACK_REXMIT1 1 /* first retransmit */ 131#define FEEDBACK_OK 2 /* no retransmits */ 132 133/* Used to set version of portmapper used in broadcast */ 134 135#define CLCR_SET_LOWVERS 3 136#define CLCR_GET_LOWVERS 4 137 138#define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */ 139 140/* 141 * client side rpc interface ops 142 * 143 * Parameter types are: 144 * 145 */ 146 147/* 148 * enum clnt_stat 149 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout) 150 * CLIENT *rh; 151 * rpcproc_t proc; 152 * xdrproc_t xargs; 153 * void *argsp; 154 * xdrproc_t xres; 155 * void *resp; 156 * struct timeval timeout; 157 */ 158#define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \ 159 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \ 160 argsp, xres, resp, secs)) 161#define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \ 162 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \ 163 argsp, xres, resp, secs)) 164 165/* 166 * void 167 * CLNT_ABORT(rh); 168 * CLIENT *rh; 169 */ 170#define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh)) 171#define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh)) 172 173/* 174 * struct rpc_err 175 * CLNT_GETERR(rh); 176 * CLIENT *rh; 177 */ 178#define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp)) 179#define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp)) 180 181 182/* 183 * bool_t 184 * CLNT_FREERES(rh, xres, resp); 185 * CLIENT *rh; 186 * xdrproc_t xres; 187 * void *resp; 188 */ 189#define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp)) 190#define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp)) 191 192/* 193 * bool_t 194 * CLNT_CONTROL(cl, request, info) 195 * CLIENT *cl; 196 * u_int request; 197 * char *info; 198 */ 199#define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in)) 200#define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in)) 201 202/* 203 * control operations that apply to both udp and tcp transports 204 */ 205#define CLSET_TIMEOUT 1 /* set timeout (timeval) */ 206#define CLGET_TIMEOUT 2 /* get timeout (timeval) */ 207#define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */ 208#define CLGET_FD 6 /* get connections file descriptor */ 209#define CLGET_SVC_ADDR 7 /* get server's address (netbuf) */ 210#define CLSET_FD_CLOSE 8 /* close fd while clnt_destroy */ 211#define CLSET_FD_NCLOSE 9 /* Do not close fd while clnt_destroy */ 212#define CLGET_XID 10 /* Get xid */ 213#define CLSET_XID 11 /* Set xid */ 214#define CLGET_VERS 12 /* Get version number */ 215#define CLSET_VERS 13 /* Set version number */ 216#define CLGET_PROG 14 /* Get program number */ 217#define CLSET_PROG 15 /* Set program number */ 218#define CLSET_SVC_ADDR 16 /* get server's address (netbuf) */ 219#define CLSET_PUSH_TIMOD 17 /* push timod if not already present */ 220#define CLSET_POP_TIMOD 18 /* pop timod */ 221/* 222 * Connectionless only control operations 223 */ 224#define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */ 225#define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */ 226#define CLSET_ASYNC 19 227#define CLSET_CONNECT 20 /* Use connect() for UDP. (int) */ 228 229/* 230 * void 231 * CLNT_DESTROY(rh); 232 * CLIENT *rh; 233 */ 234#define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh)) 235#define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh)) 236 237 238/* 239 * RPCTEST is a test program which is accessible on every rpc 240 * transport/port. It is used for testing, performance evaluation, 241 * and network administration. 242 */ 243 244#define RPCTEST_PROGRAM ((rpcprog_t)1) 245#define RPCTEST_VERSION ((rpcvers_t)1) 246#define RPCTEST_NULL_PROC ((rpcproc_t)2) 247#define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3) 248 249/* 250 * By convention, procedure 0 takes null arguments and returns them 251 */ 252 253#define NULLPROC ((rpcproc_t)0) 254 255/* 256 * Below are the client handle creation routines for the various 257 * implementations of client side rpc. They can return NULL if a 258 * creation failure occurs. 259 */ 260 261/* 262 * Generic client creation routine. Supported protocols are those that 263 * belong to the nettype namespace (/etc/netconfig). 264 */ 265__BEGIN_DECLS 266extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t, 267 const char *); 268/* 269 * 270 * const char *hostname; -- hostname 271 * const rpcprog_t prog; -- program number 272 * const rpcvers_t vers; -- version number 273 * const char *nettype; -- network type 274 */ 275 276 /* 277 * Generic client creation routine. Just like clnt_create(), except 278 * it takes an additional timeout parameter. 279 */ 280extern CLIENT * clnt_create_timed(const char *, const rpcprog_t, 281 const rpcvers_t, const char *, const struct timeval *); 282/* 283 * 284 * const char *hostname; -- hostname 285 * const rpcprog_t prog; -- program number 286 * const rpcvers_t vers; -- version number 287 * const char *nettype; -- network type 288 * const struct timeval *tp; -- timeout 289 */ 290 291/* 292 * Generic client creation routine. Supported protocols are which belong 293 * to the nettype name space. 294 */ 295extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *, 296 const rpcvers_t, const rpcvers_t, 297 const char *); 298/* 299 * const char *host; -- hostname 300 * const rpcprog_t prog; -- program number 301 * rpcvers_t *vers_out; -- servers highest available version 302 * const rpcvers_t vers_low; -- low version number 303 * const rpcvers_t vers_high; -- high version number 304 * const char *nettype; -- network type 305 */ 306 307/* 308 * Generic client creation routine. Supported protocols are which belong 309 * to the nettype name space. 310 */ 311extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t, 312 rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *, 313 const struct timeval *); 314/* 315 * const char *host; -- hostname 316 * const rpcprog_t prog; -- program number 317 * rpcvers_t *vers_out; -- servers highest available version 318 * const rpcvers_t vers_low; -- low version number 319 * const rpcvers_t vers_high; -- high version number 320 * const char *nettype; -- network type 321 * const struct timeval *tp -- timeout 322 */ 323 324/* 325 * Generic client creation routine. It takes a netconfig structure 326 * instead of nettype 327 */ 328extern CLIENT *clnt_tp_create(const char *, const rpcprog_t, 329 const rpcvers_t, const struct netconfig *); 330/* 331 * const char *hostname; -- hostname 332 * const rpcprog_t prog; -- program number 333 * const rpcvers_t vers; -- version number 334 * const struct netconfig *netconf; -- network config structure 335 */ 336 337/* 338 * Generic client creation routine. Just like clnt_tp_create(), except 339 * it takes an additional timeout parameter. 340 */ 341extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t, 342 const rpcvers_t, const struct netconfig *, const struct timeval *); 343/* 344 * const char *hostname; -- hostname 345 * const rpcprog_t prog; -- program number 346 * const rpcvers_t vers; -- version number 347 * const struct netconfig *netconf; -- network config structure 348 * const struct timeval *tp -- timeout 349 */ 350 351/* 352 * Generic TLI create routine. Only provided for compatibility. 353 */ 354 355extern CLIENT *clnt_tli_create(const int, const struct netconfig *, 356 struct netbuf *, const rpcprog_t, 357 const rpcvers_t, const u_int, const u_int); 358/* 359 * const register int fd; -- fd 360 * const struct netconfig *nconf; -- netconfig structure 361 * struct netbuf *svcaddr; -- servers address 362 * const u_long prog; -- program number 363 * const u_long vers; -- version number 364 * const u_int sendsz; -- send size 365 * const u_int recvsz; -- recv size 366 */ 367 368/* 369 * Low level clnt create routine for connectionful transports, e.g. tcp. 370 */ 371extern CLIENT *clnt_vc_create(const int, const struct netbuf *, 372 const rpcprog_t, const rpcvers_t, 373 u_int, u_int); 374/* 375 * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create(). 376 */ 377extern CLIENT *clntunix_create(struct sockaddr_un *, 378 u_long, u_long, int *, u_int, u_int); 379/* 380 * const int fd; -- open file descriptor 381 * const struct netbuf *svcaddr; -- servers address 382 * const rpcprog_t prog; -- program number 383 * const rpcvers_t vers; -- version number 384 * const u_int sendsz; -- buffer recv size 385 * const u_int recvsz; -- buffer send size 386 */ 387 388/* 389 * Low level clnt create routine for connectionless transports, e.g. udp. 390 */ 391extern CLIENT *clnt_dg_create(const int, const struct netbuf *, 392 const rpcprog_t, const rpcvers_t, 393 const u_int, const u_int); 394/* 395 * const int fd; -- open file descriptor 396 * const struct netbuf *svcaddr; -- servers address 397 * const rpcprog_t program; -- program number 398 * const rpcvers_t version; -- version number 399 * const u_int sendsz; -- buffer recv size 400 * const u_int recvsz; -- buffer send size 401 */ 402 403/* 404 * Memory based rpc (for speed check and testing) 405 * CLIENT * 406 * clnt_raw_create(prog, vers) 407 * u_long prog; 408 * u_long vers; 409 */ 410extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t); 411 412__END_DECLS 413 414 415/* 416 * Print why creation failed 417 */ 418__BEGIN_DECLS 419extern void clnt_pcreateerror(const char *); /* stderr */ 420extern char *clnt_spcreateerror(const char *); /* string */ 421__END_DECLS 422 423/* 424 * Like clnt_perror(), but is more verbose in its output 425 */ 426__BEGIN_DECLS 427extern void clnt_perrno(enum clnt_stat); /* stderr */ 428extern char *clnt_sperrno(enum clnt_stat); /* string */ 429__END_DECLS 430 431/* 432 * Print an English error message, given the client error code 433 */ 434__BEGIN_DECLS 435extern void clnt_perror(CLIENT *, const char *); /* stderr */ 436extern char *clnt_sperror(CLIENT *, const char *); /* string */ 437__END_DECLS 438 439 440/* 441 * If a creation fails, the following allows the user to figure out why. 442 */ 443struct rpc_createerr { 444 enum clnt_stat cf_stat; 445 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */ 446}; 447 448__BEGIN_DECLS 449extern struct rpc_createerr *__rpc_createerr(void); 450__END_DECLS 451#define rpc_createerr (*(__rpc_createerr())) 452 453/* 454 * The simplified interface: 455 * enum clnt_stat 456 * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype) 457 * const char *host; 458 * const rpcprog_t prognum; 459 * const rpcvers_t versnum; 460 * const rpcproc_t procnum; 461 * const xdrproc_t inproc, outproc; 462 * const char *in; 463 * char *out; 464 * const char *nettype; 465 */ 466__BEGIN_DECLS 467extern enum clnt_stat rpc_call(const char *, const rpcprog_t, 468 const rpcvers_t, const rpcproc_t, 469 const xdrproc_t, const char *, 470 const xdrproc_t, char *, const char *); 471__END_DECLS 472 473/* 474 * RPC broadcast interface 475 * The call is broadcasted to all locally connected nets. 476 * 477 * extern enum clnt_stat 478 * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp, 479 * eachresult, nettype) 480 * const rpcprog_t prog; -- program number 481 * const rpcvers_t vers; -- version number 482 * const rpcproc_t proc; -- procedure number 483 * const xdrproc_t xargs; -- xdr routine for args 484 * caddr_t argsp; -- pointer to args 485 * const xdrproc_t xresults; -- xdr routine for results 486 * caddr_t resultsp; -- pointer to results 487 * const resultproc_t eachresult; -- call with each result 488 * const char *nettype; -- Transport type 489 * 490 * For each valid response received, the procedure eachresult is called. 491 * Its form is: 492 * done = eachresult(resp, raddr, nconf) 493 * bool_t done; 494 * caddr_t resp; 495 * struct netbuf *raddr; 496 * struct netconfig *nconf; 497 * where resp points to the results of the call and raddr is the 498 * address if the responder to the broadcast. nconf is the transport 499 * on which the response was received. 500 * 501 * extern enum clnt_stat 502 * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp, 503 * eachresult, inittime, waittime, nettype) 504 * const rpcprog_t prog; -- program number 505 * const rpcvers_t vers; -- version number 506 * const rpcproc_t proc; -- procedure number 507 * const xdrproc_t xargs; -- xdr routine for args 508 * caddr_t argsp; -- pointer to args 509 * const xdrproc_t xresults; -- xdr routine for results 510 * caddr_t resultsp; -- pointer to results 511 * const resultproc_t eachresult; -- call with each result 512 * const int inittime; -- how long to wait initially 513 * const int waittime; -- maximum time to wait 514 * const char *nettype; -- Transport type 515 */ 516 517typedef bool_t (*resultproc_t)(caddr_t, ...); 518 519__BEGIN_DECLS 520extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t, 521 const rpcproc_t, const xdrproc_t, 522 caddr_t, const xdrproc_t, caddr_t, 523 const resultproc_t, const char *); 524extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t, 525 const rpcproc_t, const xdrproc_t, 526 caddr_t, const xdrproc_t, caddr_t, 527 const resultproc_t, const int, 528 const int, const char *); 529__END_DECLS 530 531/* For backward compatibility */ 532#include <rpc/clnt_soc.h> 533 534#endif /* !_RPC_CLNT_H_ */ 535