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 */ 65 struct 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 */ 91 typedef 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 */ 121 struct 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 266 extern 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 */ 280 extern 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 */ 295 extern 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 */ 311 extern 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 */ 328 extern 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 */ 341 extern 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 355 extern 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 */ 371 extern 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 */ 377 extern 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 */ 391 extern 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 */ 410 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t); 411 412 __END_DECLS 413 414 415 /* 416 * Print why creation failed 417 */ 418 __BEGIN_DECLS 419 extern void clnt_pcreateerror(const char *); /* stderr */ 420 extern 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 427 extern void clnt_perrno(enum clnt_stat); /* stderr */ 428 extern 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 435 extern void clnt_perror(CLIENT *, const char *); /* stderr */ 436 extern 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 */ 443 struct 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 449 extern 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 467 extern 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 517 typedef bool_t (*resultproc_t)(caddr_t, ...); 518 519 __BEGIN_DECLS 520 extern 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 *); 524 extern 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