1 /* $NetBSD: clnt.h,v 1.14 2000/06/02 22:57:55 fvdl Exp $ */ 2 3 /* 4 * The contents of this file are subject to the Sun Standards 5 * License Version 1.0 the (the "License";) You may not use 6 * this file except in compliance with the License. You may 7 * obtain a copy of the License at lib/libc/rpc/LICENSE 8 * 9 * Software distributed under the License is distributed on 10 * an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either 11 * express or implied. See the License for the specific 12 * language governing rights and limitations under the License. 13 * 14 * The Original Code is Copyright 1998 by Sun Microsystems, Inc 15 * 16 * The Initial Developer of the Original Code is: Sun 17 * Microsystems, Inc. 18 * 19 * All Rights Reserved. 20 * 21 * Sun RPC is a product of Sun Microsystems, Inc. and is provided for 22 * unrestricted use provided that this legend is included on all tape 23 * media and as a part of the software program in whole or part. Users 24 * may copy or modify Sun RPC without charge, but are not authorized 25 * to license or distribute it to anyone else except as part of a product or 26 * program developed by the user. 27 * 28 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE 29 * WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR 30 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. 31 * 32 * Sun RPC is provided with no support and without any obligation on the 33 * part of Sun Microsystems, Inc. to assist in its use, correction, 34 * modification or enhancement. 35 * 36 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE 37 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC 38 * OR ANY PART THEREOF. 39 * 40 * In no event will Sun Microsystems, Inc. be liable for any lost revenue 41 * or profits or other special, indirect and consequential damages, even if 42 * Sun has been advised of the possibility of such damages. 43 * 44 * Sun Microsystems, Inc. 45 * 2550 Garcia Avenue 46 * Mountain View, California 94043 47 * 48 * from: @(#)clnt.h 1.31 94/04/29 SMI 49 * from: @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC 50 * $FreeBSD$ 51 */ 52 53 /* 54 * clnt.h - Client side remote procedure call interface. 55 * 56 * Copyright (c) 1986-1991,1994-1999 by Sun Microsystems, Inc. 57 * All rights reserved. 58 */ 59 60 #ifndef _RPC_CLNT_H_ 61 #define _RPC_CLNT_H_ 62 #include <rpc/clnt_stat.h> 63 #include <sys/cdefs.h> 64 #ifdef _KERNEL 65 #include <rpc/netconfig.h> 66 #else 67 #include <netconfig.h> 68 #endif 69 #include <sys/un.h> 70 71 /* 72 * Well-known IPV6 RPC broadcast address. 73 */ 74 #define RPCB_MULTICAST_ADDR "ff02::202" 75 76 /* 77 * the following errors are in general unrecoverable. The caller 78 * should give up rather than retry. 79 */ 80 #define IS_UNRECOVERABLE_RPC(s) (((s) == RPC_AUTHERROR) || \ 81 ((s) == RPC_CANTENCODEARGS) || \ 82 ((s) == RPC_CANTDECODERES) || \ 83 ((s) == RPC_VERSMISMATCH) || \ 84 ((s) == RPC_PROCUNAVAIL) || \ 85 ((s) == RPC_PROGUNAVAIL) || \ 86 ((s) == RPC_PROGVERSMISMATCH) || \ 87 ((s) == RPC_CANTDECODEARGS)) 88 89 /* 90 * Error info. 91 */ 92 struct rpc_err { 93 enum clnt_stat re_status; 94 union { 95 int RE_errno; /* related system error */ 96 enum auth_stat RE_why; /* why the auth error occurred */ 97 struct { 98 rpcvers_t low; /* lowest version supported */ 99 rpcvers_t high; /* highest version supported */ 100 } RE_vers; 101 struct { /* maybe meaningful if RPC_FAILED */ 102 int32_t s1; 103 int32_t s2; 104 } RE_lb; /* life boot & debugging only */ 105 } ru; 106 #define re_errno ru.RE_errno 107 #define re_why ru.RE_why 108 #define re_vers ru.RE_vers 109 #define re_lb ru.RE_lb 110 }; 111 112 113 /* 114 * Client rpc handle. 115 * Created by individual implementations 116 * Client is responsible for initializing auth, see e.g. auth_none.c. 117 */ 118 typedef struct __rpc_client { 119 AUTH *cl_auth; /* authenticator */ 120 struct clnt_ops { 121 /* call remote procedure */ 122 enum clnt_stat (*cl_call)(struct __rpc_client *, 123 rpcproc_t, xdrproc_t, void *, xdrproc_t, 124 void *, struct timeval); 125 /* abort a call */ 126 void (*cl_abort)(struct __rpc_client *); 127 /* get specific error code */ 128 void (*cl_geterr)(struct __rpc_client *, 129 struct rpc_err *); 130 /* frees results */ 131 bool_t (*cl_freeres)(struct __rpc_client *, 132 xdrproc_t, void *); 133 /* destroy this structure */ 134 void (*cl_destroy)(struct __rpc_client *); 135 /* the ioctl() of rpc */ 136 bool_t (*cl_control)(struct __rpc_client *, u_int, 137 void *); 138 } *cl_ops; 139 void *cl_private; /* private stuff */ 140 char *cl_netid; /* network token */ 141 char *cl_tp; /* device name */ 142 } CLIENT; 143 144 145 /* 146 * Timers used for the pseudo-transport protocol when using datagrams 147 */ 148 struct rpc_timers { 149 u_short rt_srtt; /* smoothed round-trip time */ 150 u_short rt_deviate; /* estimated deviation */ 151 u_long rt_rtxcur; /* current (backed-off) rto */ 152 }; 153 154 /* 155 * Feedback values used for possible congestion and rate control 156 */ 157 #define FEEDBACK_REXMIT1 1 /* first retransmit */ 158 #define FEEDBACK_OK 2 /* no retransmits */ 159 160 /* Used to set version of portmapper used in broadcast */ 161 162 #define CLCR_SET_LOWVERS 3 163 #define CLCR_GET_LOWVERS 4 164 165 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */ 166 167 /* 168 * client side rpc interface ops 169 * 170 * Parameter types are: 171 * 172 */ 173 174 /* 175 * enum clnt_stat 176 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout) 177 * CLIENT *rh; 178 * rpcproc_t proc; 179 * xdrproc_t xargs; 180 * void *argsp; 181 * xdrproc_t xres; 182 * void *resp; 183 * struct timeval timeout; 184 */ 185 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \ 186 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \ 187 argsp, xres, resp, secs)) 188 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \ 189 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, \ 190 argsp, xres, resp, secs)) 191 192 /* 193 * void 194 * CLNT_ABORT(rh); 195 * CLIENT *rh; 196 */ 197 #define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh)) 198 #define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh)) 199 200 /* 201 * struct rpc_err 202 * CLNT_GETERR(rh); 203 * CLIENT *rh; 204 */ 205 #define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp)) 206 #define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp)) 207 208 209 /* 210 * bool_t 211 * CLNT_FREERES(rh, xres, resp); 212 * CLIENT *rh; 213 * xdrproc_t xres; 214 * void *resp; 215 */ 216 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp)) 217 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp)) 218 219 /* 220 * bool_t 221 * CLNT_CONTROL(cl, request, info) 222 * CLIENT *cl; 223 * u_int request; 224 * char *info; 225 */ 226 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in)) 227 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in)) 228 229 /* 230 * control operations that apply to both udp and tcp transports 231 */ 232 #define CLSET_TIMEOUT 1 /* set timeout (timeval) */ 233 #define CLGET_TIMEOUT 2 /* get timeout (timeval) */ 234 #define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */ 235 #define CLGET_FD 6 /* get connections file descriptor */ 236 #define CLGET_SVC_ADDR 7 /* get server's address (netbuf) */ 237 #define CLSET_FD_CLOSE 8 /* close fd while clnt_destroy */ 238 #define CLSET_FD_NCLOSE 9 /* Do not close fd while clnt_destroy */ 239 #define CLGET_XID 10 /* Get xid */ 240 #define CLSET_XID 11 /* Set xid */ 241 #define CLGET_VERS 12 /* Get version number */ 242 #define CLSET_VERS 13 /* Set version number */ 243 #define CLGET_PROG 14 /* Get program number */ 244 #define CLSET_PROG 15 /* Set program number */ 245 #define CLSET_SVC_ADDR 16 /* get server's address (netbuf) */ 246 #define CLSET_PUSH_TIMOD 17 /* push timod if not already present */ 247 #define CLSET_POP_TIMOD 18 /* pop timod */ 248 /* 249 * Connectionless only control operations 250 */ 251 #define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */ 252 #define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */ 253 #define CLSET_ASYNC 19 254 #define CLSET_CONNECT 20 /* Use connect() for UDP. (int) */ 255 256 #ifdef _KERNEL 257 /* 258 * Kernel control operations. The default msleep string is "rpcrecv", 259 * and sleeps are non-interruptible by default. 260 */ 261 #define CLSET_WAITCHAN 21 /* set string to use in msleep call */ 262 #define CLGET_WAITCHAN 22 /* get string used in msleep call */ 263 #define CLSET_INTERRUPTIBLE 23 /* set interruptible flag */ 264 #define CLGET_INTERRUPTIBLE 24 /* set interruptible flag */ 265 #endif 266 267 268 /* 269 * void 270 * CLNT_DESTROY(rh); 271 * CLIENT *rh; 272 */ 273 #define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh)) 274 #define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh)) 275 276 277 /* 278 * RPCTEST is a test program which is accessible on every rpc 279 * transport/port. It is used for testing, performance evaluation, 280 * and network administration. 281 */ 282 283 #define RPCTEST_PROGRAM ((rpcprog_t)1) 284 #define RPCTEST_VERSION ((rpcvers_t)1) 285 #define RPCTEST_NULL_PROC ((rpcproc_t)2) 286 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3) 287 288 /* 289 * By convention, procedure 0 takes null arguments and returns them 290 */ 291 292 #define NULLPROC ((rpcproc_t)0) 293 294 /* 295 * Below are the client handle creation routines for the various 296 * implementations of client side rpc. They can return NULL if a 297 * creation failure occurs. 298 */ 299 300 /* 301 * Generic client creation routine. Supported protocols are those that 302 * belong to the nettype namespace (/etc/netconfig). 303 */ 304 __BEGIN_DECLS 305 #ifdef _KERNEL 306 307 /* 308 * struct socket *so; -- socket 309 * struct sockaddr *svcaddr; -- servers address 310 * rpcprog_t prog; -- program number 311 * rpcvers_t vers; -- version number 312 * size_t sendsz; -- buffer recv size 313 * size_t recvsz; -- buffer send size 314 */ 315 extern CLIENT *clnt_dg_create(struct socket *so, 316 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version, 317 size_t sendsz, size_t recvsz); 318 319 /* 320 * struct socket *so; -- socket 321 * struct sockaddr *svcaddr; -- servers address 322 * rpcprog_t prog; -- program number 323 * rpcvers_t vers; -- version number 324 * size_t sendsz; -- buffer recv size 325 * size_t recvsz; -- buffer send size 326 */ 327 extern CLIENT *clnt_vc_create(struct socket *so, 328 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version, 329 size_t sendsz, size_t recvsz); 330 331 /* 332 * struct netconfig *nconf; -- network type 333 * struct sockaddr *svcaddr; -- servers address 334 * rpcprog_t prog; -- program number 335 * rpcvers_t vers; -- version number 336 * size_t sendsz; -- buffer recv size 337 * size_t recvsz; -- buffer send size 338 */ 339 extern CLIENT *clnt_reconnect_create(struct netconfig *nconf, 340 struct sockaddr *svcaddr, rpcprog_t program, rpcvers_t version, 341 size_t sendsz, size_t recvsz); 342 343 #else 344 345 extern CLIENT *clnt_create(const char *, const rpcprog_t, const rpcvers_t, 346 const char *); 347 /* 348 * 349 * const char *hostname; -- hostname 350 * const rpcprog_t prog; -- program number 351 * const rpcvers_t vers; -- version number 352 * const char *nettype; -- network type 353 */ 354 355 /* 356 * Generic client creation routine. Just like clnt_create(), except 357 * it takes an additional timeout parameter. 358 */ 359 extern CLIENT * clnt_create_timed(const char *, const rpcprog_t, 360 const rpcvers_t, const char *, const struct timeval *); 361 /* 362 * 363 * const char *hostname; -- hostname 364 * const rpcprog_t prog; -- program number 365 * const rpcvers_t vers; -- version number 366 * const char *nettype; -- network type 367 * const struct timeval *tp; -- timeout 368 */ 369 370 /* 371 * Generic client creation routine. Supported protocols are which belong 372 * to the nettype name space. 373 */ 374 extern CLIENT *clnt_create_vers(const char *, const rpcprog_t, rpcvers_t *, 375 const rpcvers_t, const rpcvers_t, 376 const char *); 377 /* 378 * const char *host; -- hostname 379 * const rpcprog_t prog; -- program number 380 * rpcvers_t *vers_out; -- servers highest available version 381 * const rpcvers_t vers_low; -- low version number 382 * const rpcvers_t vers_high; -- high version number 383 * const char *nettype; -- network type 384 */ 385 386 /* 387 * Generic client creation routine. Supported protocols are which belong 388 * to the nettype name space. 389 */ 390 extern CLIENT * clnt_create_vers_timed(const char *, const rpcprog_t, 391 rpcvers_t *, const rpcvers_t, const rpcvers_t, const char *, 392 const struct timeval *); 393 /* 394 * const char *host; -- hostname 395 * const rpcprog_t prog; -- program number 396 * rpcvers_t *vers_out; -- servers highest available version 397 * const rpcvers_t vers_low; -- low version number 398 * const rpcvers_t vers_high; -- high version number 399 * const char *nettype; -- network type 400 * const struct timeval *tp -- timeout 401 */ 402 403 /* 404 * Generic client creation routine. It takes a netconfig structure 405 * instead of nettype 406 */ 407 extern CLIENT *clnt_tp_create(const char *, const rpcprog_t, 408 const rpcvers_t, const struct netconfig *); 409 /* 410 * const char *hostname; -- hostname 411 * const rpcprog_t prog; -- program number 412 * const rpcvers_t vers; -- version number 413 * const struct netconfig *netconf; -- network config structure 414 */ 415 416 /* 417 * Generic client creation routine. Just like clnt_tp_create(), except 418 * it takes an additional timeout parameter. 419 */ 420 extern CLIENT * clnt_tp_create_timed(const char *, const rpcprog_t, 421 const rpcvers_t, const struct netconfig *, const struct timeval *); 422 /* 423 * const char *hostname; -- hostname 424 * const rpcprog_t prog; -- program number 425 * const rpcvers_t vers; -- version number 426 * const struct netconfig *netconf; -- network config structure 427 * const struct timeval *tp -- timeout 428 */ 429 430 /* 431 * Generic TLI create routine. Only provided for compatibility. 432 */ 433 434 extern CLIENT *clnt_tli_create(const int, const struct netconfig *, 435 struct netbuf *, const rpcprog_t, 436 const rpcvers_t, const u_int, const u_int); 437 /* 438 * const register int fd; -- fd 439 * const struct netconfig *nconf; -- netconfig structure 440 * struct netbuf *svcaddr; -- servers address 441 * const u_long prog; -- program number 442 * const u_long vers; -- version number 443 * const u_int sendsz; -- send size 444 * const u_int recvsz; -- recv size 445 */ 446 447 /* 448 * Low level clnt create routine for connectionful transports, e.g. tcp. 449 */ 450 extern CLIENT *clnt_vc_create(const int, const struct netbuf *, 451 const rpcprog_t, const rpcvers_t, 452 u_int, u_int); 453 /* 454 * Added for compatibility to old rpc 4.0. Obsoleted by clnt_vc_create(). 455 */ 456 extern CLIENT *clntunix_create(struct sockaddr_un *, 457 u_long, u_long, int *, u_int, u_int); 458 /* 459 * const int fd; -- open file descriptor 460 * const struct netbuf *svcaddr; -- servers address 461 * const rpcprog_t prog; -- program number 462 * const rpcvers_t vers; -- version number 463 * const u_int sendsz; -- buffer recv size 464 * const u_int recvsz; -- buffer send size 465 */ 466 467 /* 468 * Low level clnt create routine for connectionless transports, e.g. udp. 469 */ 470 extern CLIENT *clnt_dg_create(const int, const struct netbuf *, 471 const rpcprog_t, const rpcvers_t, 472 const u_int, const u_int); 473 /* 474 * const int fd; -- open file descriptor 475 * const struct netbuf *svcaddr; -- servers address 476 * const rpcprog_t program; -- program number 477 * const rpcvers_t version; -- version number 478 * const u_int sendsz; -- buffer recv size 479 * const u_int recvsz; -- buffer send size 480 */ 481 482 /* 483 * Memory based rpc (for speed check and testing) 484 * CLIENT * 485 * clnt_raw_create(prog, vers) 486 * u_long prog; 487 * u_long vers; 488 */ 489 extern CLIENT *clnt_raw_create(rpcprog_t, rpcvers_t); 490 #endif 491 492 __END_DECLS 493 494 495 /* 496 * Print why creation failed 497 */ 498 __BEGIN_DECLS 499 extern void clnt_pcreateerror(const char *); /* stderr */ 500 extern char *clnt_spcreateerror(const char *); /* string */ 501 __END_DECLS 502 503 /* 504 * Like clnt_perror(), but is more verbose in its output 505 */ 506 __BEGIN_DECLS 507 extern void clnt_perrno(enum clnt_stat); /* stderr */ 508 extern char *clnt_sperrno(enum clnt_stat); /* string */ 509 __END_DECLS 510 511 /* 512 * Print an English error message, given the client error code 513 */ 514 __BEGIN_DECLS 515 extern void clnt_perror(CLIENT *, const char *); /* stderr */ 516 extern char *clnt_sperror(CLIENT *, const char *); /* string */ 517 __END_DECLS 518 519 520 /* 521 * If a creation fails, the following allows the user to figure out why. 522 */ 523 struct rpc_createerr { 524 enum clnt_stat cf_stat; 525 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */ 526 }; 527 528 #ifdef _KERNEL 529 extern struct rpc_createerr rpc_createerr; 530 #else 531 __BEGIN_DECLS 532 extern struct rpc_createerr *__rpc_createerr(void); 533 __END_DECLS 534 #define rpc_createerr (*(__rpc_createerr())) 535 #endif 536 537 /* 538 * The simplified interface: 539 * enum clnt_stat 540 * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype) 541 * const char *host; 542 * const rpcprog_t prognum; 543 * const rpcvers_t versnum; 544 * const rpcproc_t procnum; 545 * const xdrproc_t inproc, outproc; 546 * const char *in; 547 * char *out; 548 * const char *nettype; 549 */ 550 __BEGIN_DECLS 551 extern enum clnt_stat rpc_call(const char *, const rpcprog_t, 552 const rpcvers_t, const rpcproc_t, 553 const xdrproc_t, const char *, 554 const xdrproc_t, char *, const char *); 555 __END_DECLS 556 557 /* 558 * RPC broadcast interface 559 * The call is broadcasted to all locally connected nets. 560 * 561 * extern enum clnt_stat 562 * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp, 563 * eachresult, nettype) 564 * const rpcprog_t prog; -- program number 565 * const rpcvers_t vers; -- version number 566 * const rpcproc_t proc; -- procedure number 567 * const xdrproc_t xargs; -- xdr routine for args 568 * caddr_t argsp; -- pointer to args 569 * const xdrproc_t xresults; -- xdr routine for results 570 * caddr_t resultsp; -- pointer to results 571 * const resultproc_t eachresult; -- call with each result 572 * const char *nettype; -- Transport type 573 * 574 * For each valid response received, the procedure eachresult is called. 575 * Its form is: 576 * done = eachresult(resp, raddr, nconf) 577 * bool_t done; 578 * caddr_t resp; 579 * struct netbuf *raddr; 580 * struct netconfig *nconf; 581 * where resp points to the results of the call and raddr is the 582 * address if the responder to the broadcast. nconf is the transport 583 * on which the response was received. 584 * 585 * extern enum clnt_stat 586 * rpc_broadcast_exp(prog, vers, proc, xargs, argsp, xresults, resultsp, 587 * eachresult, inittime, waittime, nettype) 588 * const rpcprog_t prog; -- program number 589 * const rpcvers_t vers; -- version number 590 * const rpcproc_t proc; -- procedure number 591 * const xdrproc_t xargs; -- xdr routine for args 592 * caddr_t argsp; -- pointer to args 593 * const xdrproc_t xresults; -- xdr routine for results 594 * caddr_t resultsp; -- pointer to results 595 * const resultproc_t eachresult; -- call with each result 596 * const int inittime; -- how long to wait initially 597 * const int waittime; -- maximum time to wait 598 * const char *nettype; -- Transport type 599 */ 600 601 typedef bool_t (*resultproc_t)(caddr_t, ...); 602 603 __BEGIN_DECLS 604 extern enum clnt_stat rpc_broadcast(const rpcprog_t, const rpcvers_t, 605 const rpcproc_t, const xdrproc_t, 606 caddr_t, const xdrproc_t, caddr_t, 607 const resultproc_t, const char *); 608 extern enum clnt_stat rpc_broadcast_exp(const rpcprog_t, const rpcvers_t, 609 const rpcproc_t, const xdrproc_t, 610 caddr_t, const xdrproc_t, caddr_t, 611 const resultproc_t, const int, 612 const int, const char *); 613 __END_DECLS 614 615 #ifndef _KERNEL 616 /* For backward compatibility */ 617 #include <rpc/clnt_soc.h> 618 #endif 619 620 #endif /* !_RPC_CLNT_H_ */ 621