man3/rpc.3

   1 .\" @(#)rpc.3n  2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
   2 .TH RPC 3 1988-02-16
   3 .SH NAME
   4 rpc \- library routines for remote procedure calls
   5 .SH "SYNOPSIS AND DESCRIPTION"
   6 These routines allow C programs to make procedure
   7 calls on other machines across the network.
   8 First, the client calls a procedure to send a
   9 data packet to the server.
  10 Upon receipt of the packet, the server calls a dispatch routine
  11 to perform the requested service, and then sends back a
  12 reply.
  13 Finally, the procedure call returns to the client.
  14 .LP
  15 Routines that are used for Secure RPC (DES authentication) are described in
  16 .BR rpc_secure (3).
  17 Secure RPC can be used only if DES encryption is available.
  18 .LP
  19 .ft B
  20 .nf
  21 .sp .5
  22 #include <rpc/rpc.h>
  23 .fi
  24 .ft R
  25 .br
  26 .if t .ne 8
  27 .LP
  28 .ft B
  29 .nf
  30 .sp .5
  31 void
  32 auth_destroy(auth)
  33 \s-1AUTH\s0 *auth;
  34 .fi
  35 .ft R
  36 .IP
  37 A macro that destroys the authentication information associated with
  38 .IR auth .
  39 Destruction usually involves deallocation of private data
  40 structures. The use of
  41 .I auth
  42 is undefined after calling
  43 .BR auth_destroy() .
  44 .br
  45 .if t .ne 6
  46 .LP
  47 .ft B
  48 .nf
  49 .sp .5
  50 \s-1AUTH\s0 *
  51 authnone_create()
  52 .fi
  53 .ft R
  54 .IP
  55 Create and returns an
  56 .SM RPC
  57 authentication handle that passes nonusable authentication
  58 information with each remote procedure call. This is the
  59 default authentication used by
  60 .SM RPC.
  61 .if t .ne 10
  62 .LP
  63 .ft B
  64 .nf
  65 .sp .5
  66 \s-1AUTH\s0 *
  67 authunix_create(host, uid, gid, len, aup_gids)
  68 char *host;
  69 int uid, gid, len, *aup.gids;
  70 .fi
  71 .ft R
  72 .IP
  73 Create and return an
  74 .SM RPC
  75 authentication handle that contains
  76 .UX
  77 authentication information.
  78 The parameter
  79 .I host
  80 is the name of the machine on which the information was
  81 created;
  82 .I uid
  83 is the user's user
  84 .SM ID ;
  85 .I gid
  86 is the user's current group
  87 .SM ID ;
  88 .I len
  89 and
  90 .I aup_gids
  91 refer to a counted array of groups to which the user belongs.
  92 It is easy to impersonate a user.
  93 .br
  94 .if t .ne 5
  95 .LP
  96 .ft B
  97 .nf
  98 .sp .5
  99 \s-1AUTH\s0 *
 100 authunix_create_default()
 101 .fi
 102 .ft R
 103 .IP
 104 Calls
 105 .B authunix_create()
 106 with the appropriate parameters.
 107 .br
 108 .if t .ne 13
 109 .LP
 110 .ft B
 111 .nf
 112 .sp .5
 113 callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
 114 char *host;
 115 u_long prognum, versnum, procnum;
 116 char *in, *out;
 117 xdrproc_t inproc, outproc;
 118 .fi
 119 .ft R
 120 .IP
 121 Call the remote procedure associated with
 122 .IR prognum ,
 123 .IR versnum ,
 124 and
 125 .I procnum
 126 on the machine,
 127 .IR host .
 128 The parameter
 129 .I in
 130 is the address of the procedure's argument(s), and
 131 .I out
 132 is the address of where to place the result(s);
 133 .I inproc
 134 is used to encode the procedure's parameters, and
 135 .I outproc
 136 is used to decode the procedure's results.
 137 This routine returns zero if it succeeds, or the value of
 138 .B "enum clnt_stat"
 139 cast to an integer if it fails.
 140 The routine
 141 .B clnt_perrno()
 142 is handy for translating failure statuses into messages.
 143 .IP
 144 Warning: calling remote procedures with this routine
 145 uses
 146 .SM UDP/IP
 147 as a transport; see
 148 .B clntudp_create()
 149 for restrictions.
 150 You do not have control of timeouts or authentication using
 151 this routine.
 152 .br
 153 .if t .ne 16
 154 .LP
 155 .ft B
 156 .nf
 157 .sp .5
 158 enum clnt_stat
 159 clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult)
 160 u_long prognum, versnum, procnum;
 161 char *in, *out;
 162 xdrproc_t inproc, outproc;
 163 resultproc_t eachresult;
 164 .fi
 165 .ft R
 166 .IP
 167 Like
 168 .BR callrpc() ,
 169 except the call message is broadcast to all locally
 170 connected broadcast nets. Each time it receives a
 171 response, this routine calls
 172 .BR eachresult() ,
 173 whose form is:
 174 .IP
 175 .RS 1i
 176 .ft B
 177 .nf
 178 eachresult(out, addr)
 179 char *out;
 180 struct sockaddr_in *addr;
 181 .ft R
 182 .fi
 183 .RE
 184 .IP
 185 where
 186 .I out
 187 is the same as
 188 .I out
 189 passed to
 190 .BR clnt_broadcast() ,
 191 except that the remote procedure's output is decoded there;
 192 .I addr
 193 points to the address of the machine that sent the results.
 194 If
 195 .B eachresult()
 196 returns zero,
 197 .B clnt_broadcast()
 198 waits for more replies; otherwise it returns with appropriate
 199 status.
 200 .IP
 201 Warning: broadcast sockets are limited in size to the
 202 maximum transfer unit of the data link. For ethernet,
 203 this value is 1500 bytes.
 204 .br
 205 .if t .ne 13
 206 .LP
 207 .ft B
 208 .nf
 209 .sp .5
 210 enum clnt_stat
 211 clnt_call(clnt, procnum, inproc, in, outproc, out, tout)
 212 \s-1CLIENT\s0 *clnt;
 213 u_long
 214 procnum;
 215 xdrproc_t inproc, outproc;
 216 char *in, *out;
 217 struct timeval tout;
 218 .fi
 219 .ft R
 220 .IP
 221 A macro that calls the remote procedure
 222 .I procnum
 223 associated with the client handle,
 224 .IR clnt ,
 225 which is obtained with an
 226 .SM RPC
 227 client creation routine such as
 228 .BR clnt_create() .
 229 The parameter
 230 .I in
 231 is the address of the procedure's argument(s), and
 232 .I out
 233 is the address of where to place the result(s);
 234 .I inproc
 235 is used to encode the procedure's parameters, and
 236 .I outproc
 237 is used to decode the procedure's results;
 238 .I tout
 239 is the time allowed for results to come back.
 240 .br
 241 .if t .ne 7
 242 .LP
 243 .ft B
 244 .nf
 245 .sp .5
 246 clnt_destroy(clnt)
 247 \s-1CLIENT\s0 *clnt;
 248 .fi
 249 .ft R
 250 .IP
 251 A macro that destroys the client's
 252 .SM RPC
 253 handle. Destruction usually involves deallocation
 254 of private data structures, including
 255 .I clnt
 256 itself.  Use of
 257 .I clnt
 258 is undefined after calling
 259 .BR clnt_destroy() .
 260 If the
 261 .SM RPC
 262 library opened the associated socket, it will close it also.
 263 Otherwise, the socket remains open.
 264 .br
 265 .if t .ne 10
 266 .LP
 267 .ft B
 268 .nf
 269 .sp .5
 270 \s-1CLIENT\s0 *
 271 clnt_create(host, prog, vers, proto)
 272 char *host;
 273 u_long prog, vers;
 274 char *proto;
 275 .fi
 276 .ft R
 277 .IP
 278 Generic client creation routine.
 279 .I host
 280 identifies the name of the remote host where the server
 281 is located.
 282 .I proto
 283 indicates which kind of transport protocol to use. The
 284 currently supported values for this field are \(lqudp\(rq
 285 and \(lqtcp\(rq.
 286 Default timeouts are set, but can be modified using
 287 .BR clnt_control() .
 288 .IP
 289 Warning: Using
 290 .SM UDP
 291 has its shortcomings.  Since
 292 .SM UDP\s0-based
 293 .SM RPC
 294 messages can only hold up to 8 Kbytes of encoded data,
 295 this transport cannot be used for procedures that take
 296 large arguments or return huge results.
 297 .br
 298 .if t .ne 10
 299 .LP
 300 .ft B
 301 .nf
 302 .sp .5
 303 bool_t
 304 clnt_control(cl, req, info)
 305 \s-1CLIENT\s0 *cl;
 306 char *info;
 307 .fi
 308 .ft R
 309 .IP
 310 A macro used to change or retrieve various information
 311 about a client object.
 312 .I req
 313 indicates the type of operation, and
 314 .I info
 315 is a pointer to the information. For both
 316 .SM UDP
 317 and
 318 .SM TCP\s0,
 319 the supported values of
 320 .I req
 321 and their argument types and what they do are:
 322 .IP
 323 .nf
 324 .ta +2.0i +2.0i +2.0i
 325 .SM CLSET_TIMEOUT\s0    struct timeval  set total timeout
 326 .SM CLGET_TIMEOUT\s0    struct timeval  get total timeout
 327 .fi
 328 .IP
 329 Note: if you set the timeout using
 330 .BR clnt_control() ,
 331 the timeout parameter passed to
 332 .B clnt_call()
 333 will be ignored in all future calls.
 334 .IP
 335 .nf
 336 .SM CLGET_SERVER_ADDR\s0        struct sockaddr_in      get server's address
 337 .fi
 338 .br
 339 .IP
 340 The following operations are valid for
 341 .SM UDP
 342 only:
 343 .IP
 344 .nf
 345 .ta +2.0i +2.0i +2.0i
 346 .SM CLSET_RETRY_TIMEOUT\s0      struct timeval  set the retry timeout
 347 .SM CLGET_RETRY_TIMEOUT\s0      struct timeval  get the retry timeout
 348 .fi
 349 .br
 350 .IP
 351 The retry timeout is the time that
 352 .SM "UDP RPC"
 353 waits for the server to reply before
 354 retransmitting the request.
 355 .br
 356 .if t .ne 10
 357 .LP
 358 .ft B
 359 .nf
 360 .sp .5
 361 clnt_freeres(clnt, outproc, out)
 362 \s-1CLIENT\s0 *clnt;
 363 xdrproc_t outproc;
 364 char *out;
 365 .fi
 366 .ft R
 367 .IP
 368 A macro that frees any data allocated by the
 369 .SM RPC/XDR
 370 system when it decoded the results of an
 371 .SM RPC
 372 call.  The
 373 parameter
 374 .I out
 375 is the address of the results, and
 376 .I outproc
 377 is the
 378 .SM XDR
 379 routine describing the results.
 380 This routine returns one if the results were successfully
 381 freed,
 382 and zero otherwise.
 383 .br
 384 .if t .ne 6
 385 .LP
 386 .ft B
 387 .nf
 388 .sp .5
 389 void
 390 clnt_geterr(clnt, errp)
 391 \s-1CLIENT\s0 *clnt;
 392 struct rpc_err *errp;
 393 .fi
 394 .ft R
 395 .IP
 396 A macro that copies the error structure out of the client
 397 handle
 398 to the structure at address
 399 .IR errp .
 400 .br
 401 .if t .ne 8
 402 .LP
 403 .ft B
 404 .nf
 405 .sp .5
 406 void
 407 clnt_pcreateerror(s)
 408 char *s;
 409 .fi
 410 .ft R
 411 .IP
 412 Print a message to standard error indicating
 413 why a client
 414 .SM RPC
 415 handle could not be created.
 416 The message is prepended with string
 417 .I s
 418 and a colon.
 419 Used when a
 420 .BR clnt_create() ,
 421 .BR clntraw_create() ,
 422 .BR clnttcp_create() ,
 423 or
 424 .B clntudp_create()
 425 call fails.
 426 .br
 427 .if t .ne 8
 428 .LP
 429 .ft B
 430 .nf
 431 .sp .5
 432 void
 433 clnt_perrno(stat)
 434 enum clnt_stat stat;
 435 .fi
 436 .ft R
 437 .IP
 438 Print a message to standard error corresponding
 439 to the condition indicated by
 440 .IR stat .
 441 Used after
 442 .BR callrpc() .
 443 .br
 444 .if t .ne 8
 445 .LP
 446 .ft B
 447 .nf
 448 .sp .5
 449 clnt_perror(clnt, s)
 450 \s-1CLIENT\s0 *clnt;
 451 char *s;
 452 .fi
 453 .ft R
 454 .IP
 455 Print a message to standard error indicating why an
 456 .SM RPC
 457 call failed;
 458 .I clnt
 459 is the handle used to do the call.
 460 The message is prepended with string
 461 .I s
 462 and a colon.
 463 Used after
 464 .BR clnt_call() .
 465 .br
 466 .if t .ne 9
 467 .LP
 468 .ft B
 469 .nf
 470 .sp .5
 471 char *
 472 clnt_spcreateerror
 473 char *s;
 474 .fi
 475 .ft R
 476 .IP
 477 Like
 478 .BR clnt_pcreateerror() ,
 479 except that it returns a string
 480 instead of printing to the standard error.
 481 .IP
 482 Bugs: returns pointer to static data that is overwritten
 483 on each call.
 484 .br
 485 .if t .ne 9
 486 .LP
 487 .ft B
 488 .nf
 489 .sp .5
 490 char *
 491 clnt_sperrno(stat)
 492 enum clnt_stat stat;
 493 .fi
 494 .ft R
 495 .IP
 496 Take the same arguments as
 497 .BR clnt_perrno() ,
 498 but instead of sending a message to the standard error
 499 indicating why an
 500 .SM RPC
 501 call failed, return a pointer to a string which contains
 502 the message.  The string ends with a
 503 .SM NEWLINE\s0.
 504 .IP
 505 .B clnt_sperrno()
 506 is used instead of
 507 .B clnt_perrno()
 508 if the program does not have a standard error (as a program
 509 running as a server quite likely does not), or if the
 510 programmer
 511 does not want the message to be output with
 512 .BR printf ,
 513 or if a message format different than that supported by
 514 .B clnt_perrno()
 515 is to be used.
 516 Note: unlike
 517 .B clnt_sperror()
 518 and
 519 .BR clnt_spcreaterror() ,
 520 .B clnt_sperrno()
 521 returns pointer to static data, but the
 522 result will not get overwritten on each call.
 523 .br
 524 .if t .ne 7
 525 .LP
 526 .ft B
 527 .nf
 528 .sp .5
 529 char *
 530 clnt_sperror(rpch, s)
 531 \s-1CLIENT\s0 *rpch;
 532 char *s;
 533 .fi
 534 .ft R
 535 .IP
 536 Like
 537 .BR clnt_perror() ,
 538 except that (like
 539 .BR clnt_sperrno() )
 540 it returns a string instead of printing to standard error.
 541 .IP
 542 Bugs: returns pointer to static data that is overwritten
 543 on each call.
 544 .br
 545 .if t .ne 10
 546 .LP
 547 .ft B
 548 .nf
 549 .sp .5
 550 \s-1CLIENT\s0 *
 551 clntraw_create(prognum, versnum)
 552 u_long prognum, versnum;
 553 .fi
 554 .ft R
 555 .IP
 556 This routine creates a toy
 557 .SM RPC
 558 client for the remote program
 559 .IR prognum ,
 560 version
 561 .IR versnum .
 562 The transport used to pass messages to the service is
 563 actually a buffer within the process's address space, so the
 564 corresponding
 565 .SM RPC
 566 server should live in the same address space; see
 567 .BR svcraw_create() .
 568 This allows simulation of
 569 .SM RPC
 570 and acquisition of
 571 .SM RPC
 572 overheads, such as round trip times, without any
 573 kernel interference. This routine returns
 574 .SM NULL
 575 if it fails.
 576 .br
 577 .if t .ne 15
 578 .LP
 579 .ft B
 580 .nf
 581 .sp .5
 582 \s-1CLIENT\s0 *
 583 clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)
 584 struct sockaddr_in *addr;
 585 u_long prognum, versnum;
 586 int *sockp;
 587 u_int sendsz, recvsz;
 588 .fi
 589 .ft R
 590 .IP
 591 This routine creates an
 592 .SM RPC
 593 client for the remote program
 594 .IR prognum ,
 595 version
 596 .IR versnum ;
 597 the client uses
 598 .SM TCP/IP
 599 as a transport. The remote program is located at Internet
 600 address
 601 .IR *addr .
 602 If
 603 .\"The following in-line font conversion is necessary for the hyphen indicator
 604 \fB\%addr\->sin_port\fR
 605 is zero, then it is set to the actual port that the remote
 606 program is listening on (the remote
 607 .B portmap
 608 service is consulted for this information). The parameter
 609 .I sockp
 610 is a socket; if it is
 611 .BR \s-1RPC_ANYSOCK\s0 ,
 612 then this routine opens a new one and sets
 613 .IR sockp .
 614 Since
 615 .SM TCP\s0-based
 616 .SM RPC
 617 uses buffered
 618 .SM I/O ,
 619 the user may specify the size of the send and receive buffers
 620 with the parameters
 621 .I sendsz
 622 and
 623 .IR recvsz ;
 624 values of zero choose suitable defaults.
 625 This routine returns
 626 .SM NULL
 627 if it fails.
 628 .br
 629 .if t .ne 15
 630 .LP
 631 .ft B
 632 .nf
 633 .sp .5
 634 \s-1CLIENT\s0 *
 635 clntudp_create(addr, prognum, versnum, wait, sockp)
 636 struct sockaddr_in *addr;
 637 u_long prognum, versnum;
 638 struct timeval wait;
 639 int *sockp;
 640 .fi
 641 .ft R
 642 .IP
 643 This routine creates an
 644 .SM RPC
 645 client for the remote program
 646 .IR prognum ,
 647 version
 648 .IR versnum ;
 649 the client uses use
 650 .SM UDP/IP
 651 as a transport. The remote program is located at Internet
 652 address
 653 .IR addr .
 654 If
 655 \fB\%addr\->sin_port\fR
 656 is zero, then it is set to actual port that the remote
 657 program is listening on (the remote
 658 .B portmap
 659 service is consulted for this information). The parameter
 660 .I sockp
 661 is a socket; if it is
 662 .BR \s-1RPC_ANYSOCK\s0 ,
 663 then this routine opens a new one and sets
 664 .IR sockp .
 665 The
 666 .SM UDP
 667 transport resends the call message in intervals of
 668 .B wait
 669 time until a response is received or until the call times
 670 out.
 671 The total time for the call to time out is specified by
 672 .BR clnt_call() .
 673 .IP
 674 Warning: since
 675 .SM UDP\s0-based
 676 .SM RPC
 677 messages can only hold up to 8 Kbytes
 678 of encoded data, this transport cannot be used for procedures
 679 that take large arguments or return huge results.
 680 .br
 681 .if t .ne 8
 682 .LP
 683 .ft B
 684 .nf
 685 .sp .5
 686 \s-1CLIENT\s0 *
 687 clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsize, recosize)
 688 struct sockaddr_in *addr;
 689 u_long prognum, versnum;
 690 struct timeval wait;
 691 int *sockp;
 692 unsigned int sendsize;
 693 unsigned int recosize;
 694 .fi
 695 .ft R
 696 .IP
 697 This routine creates an
 698 .SM RPC
 699 client for the remote program
 700 .IR prognum ,
 701 on
 702 .IR versnum ;
 703 the client uses use
 704 .SM UDP/IP
 705 as a transport. The remote program is located at Internet
 706 address
 707 .IR addr .
 708 If
 709 \fB\%addr\->sin_port\fR
 710 is zero, then it is set to actual port that the remote
 711 program is listening on (the remote
 712 .B portmap
 713 service is consulted for this information). The parameter
 714 .I sockp
 715 is a socket; if it is
 716 .BR \s-1RPC_ANYSOCK\s0 ,
 717 then this routine opens a new one and sets
 718 .BR sockp .
 719 The
 720 .SM UDP
 721 transport resends the call message in intervals of
 722 .B wait
 723 time until a response is received or until the call times
 724 out.
 725 The total time for the call to time out is specified by
 726 .BR clnt_call() .
 727 .IP
 728 This allows the user to specify the maximum packet size for sending and receiving
 729 .SM UDP\s0-based
 730 .SM RPC
 731 messages.
 732 .br
 733 .if t .ne 7
 734 .LP
 735 .ft B
 736 .nf
 737 .sp .5
 738 void
 739 get_myaddress(addr)
 740 struct sockaddr_in *addr;
 741 .fi
 742 .ft R
 743 .IP
 744 Stuff the machine's
 745 .SM IP
 746 address into
 747 .IR *addr ,
 748 without consulting the library routines that deal with
 749 .BR /etc/hosts .
 750 The port number is always set to
 751 .BR htons(\s-1PMAPPORT\s0) .
 752 .br
 753 .if t .ne 10
 754 .LP
 755 .ft B
 756 .nf
 757 .sp .5
 758 struct pmaplist *
 759 pmap_getmaps(addr)
 760 struct sockaddr_in *addr;
 761 .fi
 762 .ft R
 763 .IP
 764 A user interface to the
 765 .B portmap
 766 service, which returns a list of the current
 767 .SM RPC
 768 program-to-port mappings
 769 on the host located at
 770 .SM IP
 771 address
 772 .IR *addr .
 773 This routine can return
 774 .SM NULL .
 775 The command
 776 .RB ` "rpcinfo \-p" '
 777 uses this routine.
 778 .br
 779 .if t .ne 12
 780 .LP
 781 .ft B
 782 .nf
 783 .sp .5
 784 u_short
 785 pmap_getport(addr, prognum, versnum, protocol)
 786 struct sockaddr_in *addr;
 787 u_long prognum, versnum, protocol;
 788 .fi
 789 .ft R
 790 .IP
 791 A user interface to the
 792 .B portmap
 793 service, which returns the port number
 794 on which waits a service that supports program number
 795 .IR prognum ,
 796 version
 797 .IR versnum ,
 798 and speaks the transport protocol associated with
 799 .IR protocol .
 800 The value of
 801 .I protocol
 802 is most likely
 803 .B
 804 .SM IPPROTO_UDP
 805 or
 806 .BR \s-1IPPROTO_TCP\s0 .
 807 A return value of zero means that the mapping does not exist
 808 or that
 809 the
 810 .SM RPC
 811 system failed to contact the remote
 812 .B portmap
 813 service.  In the latter case, the global variable
 814 .B rpc_createerr()
 815 contains the
 816 .SM RPC
 817 status.
 818 .br
 819 .if t .ne 15
 820 .LP
 821 .ft B
 822 .nf
 823 .sp .5
 824 enum clnt_stat
 825 pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out, tout, portp)
 826 struct sockaddr_in *addr;
 827 u_long prognum, versnum, procnum;
 828 char *in, *out;
 829 xdrproc_t inproc, outproc;
 830 struct timeval tout;
 831 u_long *portp;
 832 .fi
 833 .ft R
 834 .IP
 835 A user interface to the
 836 .B portmap
 837 service, which instructs
 838 .B portmap
 839 on the host at
 840 .SM IP
 841 address
 842 .I *addr
 843 to make an
 844 .SM RPC
 845 call on your behalf to a procedure on that host.
 846 The parameter
 847 .I *portp
 848 will be modified to the program's port number if the
 849 procedure
 850 succeeds. The definitions of other parameters are discussed
 851 in
 852 .B callrpc()
 853 and
 854 .BR clnt_call() .
 855 This procedure should be used for a \(lqping\(rq and nothing
 856 else.
 857 See also
 858 .BR clnt_broadcast() .
 859 .br
 860 .if t .ne 9
 861 .LP
 862 .ft B
 863 .nf
 864 .sp .5
 865 pmap_set(prognum, versnum, protocol, port)
 866 u_long prognum, versnum, protocol;
 867 u_short port;
 868 .fi
 869 .ft R
 870 .IP
 871 A user interface to the
 872 .B portmap
 873 service, which establishes a mapping between the triple
 874 .RI [ prognum , versnum , protocol\fR]
 875 and
 876 .I port
 877 on the machine's
 878 .B portmap
 879 service. The value of
 880 .I protocol
 881 is most likely
 882 .B
 883 .SM IPPROTO_UDP
 884 or
 885 .BR \s-1IPPROTO_TCP\s0 .
 886 This routine returns one if it succeeds, zero otherwise.
 887 Automatically done by
 888 .BR svc_register() .
 889 .br
 890 .if t .ne 7
 891 .LP
 892 .ft B
 893 .nf
 894 .sp .5
 895 pmap_unset(prognum, versnum)
 896 u_long prognum, versnum;
 897 .fi
 898 .ft R
 899 .IP
 900 A user interface to the
 901 .B portmap
 902 service, which destroys all mapping between the triple
 903 .RI [ prognum , versnum , *\fR]
 904 and
 905 .B ports
 906 on the machine's
 907 .B portmap
 908 service. This routine returns one if it succeeds, zero
 909 otherwise.
 910 .br
 911 .if t .ne 15
 912 .LP
 913 .ft B
 914 .nf
 915 .sp .5
 916 registerrpc(prognum, versnum, procnum, procname, inproc, outproc)
 917 u_long prognum, versnum, procnum;
 918 char *(*procname) () ;
 919 xdrproc_t inproc, outproc;
 920 .fi
 921 .ft R
 922 .IP
 923 Register procedure
 924 .I procname
 925 with the
 926 .SM RPC
 927 service package.  If a request arrives for program
 928 .IR prognum ,
 929 version
 930 .IR versnum ,
 931 and procedure
 932 .IR procnum ,
 933 .I procname
 934 is called with a pointer to its parameter(s);
 935 .I progname
 936 should return a pointer to its static result(s);
 937 .I inproc
 938 is used to decode the parameters while
 939 .I outproc
 940 is used to encode the results.
 941 This routine returns zero if the registration succeeded, \-1
 942 otherwise.
 943 .IP
 944 Warning: remote procedures registered in this form
 945 are accessed using the
 946 .SM UDP/IP
 947 transport; see
 948 .B svcudp_create()
 949 for restrictions.
 950 .br
 951 .if t .ne 5
 952 .LP
 953 .ft B
 954 .nf
 955 .sp .5
 956 struct rpc_createerr     rpc_createerr;
 957 .fi
 958 .ft R
 959 .IP
 960 A global variable whose value is set by any
 961 .SM RPC
 962 client creation routine
 963 that does not succeed.  Use the routine
 964 .B clnt_pcreateerror()
 965 to print the reason why.
 966 .if t .ne 7
 967 .LP
 968 .ft B
 969 .nf
 970 .sp .5
 971 svc_destroy(xprt)
 972 \s-1SVCXPRT\s0 *
 973 xprt;
 974 .fi
 975 .ft R
 976 .IP
 977 A macro that destroys the
 978 .SM RPC
 979 service transport handle,
 980 .IR xprt .
 981 Destruction usually involves deallocation
 982 of private data structures, including
 983 .I xprt
 984 itself.  Use of
 985 .I xprt
 986 is undefined after calling this routine.
 987 .br
 988 .if t .ne 8
 989 .LP
 990 .ft B
 991 .nf
 992 .sp .5
 993 fd_set svc_fdset;
 994 .fi
 995 .ft R
 996 .IP
 997 A global variable reflecting the
 998 .SM RPC
 999 service side's
1000 read file descriptor bit mask; it is suitable as a parameter
1001 to the
1002 .B select
1003 system call. This is only of interest
1004 if a service implementor does not call
1005 .BR svc_run() ,
1006 but rather does his own asynchronous event processing.
1007 This variable is read-only (do not pass its address to
1008 .BR select !),
1009 yet it may change after calls to
1010 .B svc_getreqset()
1011 or any creation routines.
1012 .br
1013 .if t .ne 6
1014 .LP
1015 .ft B
1016 .nf
1017 .sp .5
1018 int svc_fds;
1019 .fi
1020 .ft R
1021 .IP
1022 Similar to
1023 .BR svc_fdset ,
1024 but limited to 32 descriptors. This
1025 interface is obsoleted by
1026 .BR svc_fdset .
1027 .br
1028 .if t .ne 9
1029 .LP
1030 .ft B
1031 .nf
1032 .sp .5
1033 svc_freeargs(xprt, inproc, in)
1034 \s-1SVCXPRT\s0 *xprt;
1035 xdrproc_t inproc;
1036 char *in;
1037 .fi
1038 .ft R
1039 .IP
1040 A macro that frees any data allocated by the
1041 .SM RPC/XDR
1042 system when it decoded the arguments to a service procedure
1043 using
1044 .BR svc_getargs() .
1045 This routine returns 1 if the results were successfully
1046 freed,
1047 and zero otherwise.
1048 .br
1049 .if t .ne 10
1050 .LP
1051 .ft B
1052 .nf
1053 .sp .5
1054 svc_getargs(xprt, inproc, in)
1055 \s-1SVCXPRT\s0 *xprt;
1056 xdrproc_t inproc;
1057 char *in;
1058 .fi
1059 .ft R
1060 .IP
1061 A macro that decodes the arguments of an
1062 .SM RPC
1063 request
1064 associated with the
1065 .SM RPC
1066 service transport handle,
1067 .IR xprt .
1068 The parameter
1069 .I in
1070 is the address where the arguments will be placed;
1071 .I inproc
1072 is the
1073 .SM XDR
1074 routine used to decode the arguments.
1075 This routine returns one if decoding succeeds, and zero
1076 otherwise.
1077 .br
1078 .if t .ne 9
1079 .LP
1080 .ft B
1081 .nf
1082 .sp .5
1083 struct sockaddr_in *
1084 svc_getcaller(xprt)
1085 \s-1SVCXPRT\s0 *xprt;
1086 .fi
1087 .ft R
1088 .IP
1089 The approved way of getting the network address of the caller
1090 of a procedure associated with the
1091 .SM RPC
1092 service transport handle,
1093 .IR xprt .
1094 .br
1095 .if t .ne 9
1096 .LP
1097 .ft B
1098 .nf
1099 .sp .5
1100 svc_getreqset(rdfds)
1101 fd_set *rdfds;
1102 .fi
1103 .ft R
1104 .IP
1105 This routine is only of interest if a service implementor
1106 does not call
1107 .BR svc_run() ,
1108 but instead implements custom asynchronous event processing.
1109 It is called when the
1110 .B select
1111 system call has determined that an
1112 .SM RPC
1113 request has arrived on some
1114 .SM RPC
1115 .B socket(s) ;
1116 .I rdfds
1117 is the resultant read file descriptor bit mask.
1118 The routine returns when all sockets associated with the
1119 value of
1120 .I rdfds
1121 have been serviced.
1122 .br
1123 .if t .ne 6
1124 .LP
1125 .ft B
1126 .nf
1127 .sp .5
1128 svc_getreq(rdfds)
1129 int rdfds;
1130 .fi
1131 .ft R
1132 .IP
1133 Similar to
1134 .BR svc_getreqset() ,
1135 but limited to 32 descriptors. This interface is obsoleted by
1136 .BR svc_getreqset() .
1137 .br
1138 .if t .ne 17
1139 .LP
1140 .ft B
1141 .nf
1142 .sp .5
1143 svc_register(xprt, prognum, versnum, dispatch, protocol)
1144 \s-1SVCXPRT\s0 *xprt;
1145 u_long prognum, versnum;
1146 void (*dispatch) ();
1147 u_long protocol;
1148 .fi
1149 .ft R
1150 .IP
1151 Associates
1152 .I prognum
1153 and
1154 .I versnum
1155 with the service dispatch procedure,
1156 .IR dispatch .
1157 If
1158 .I protocol
1159 is zero, the service is not registered with the
1160 .B portmap
1161 service.  If
1162 .I protocol
1163 is non-zero, then a mapping of the triple
1164 .RI [ prognum , versnum , protocol\fR]
1165 to
1166 \fB\%xprt\->xp_port\fR
1167 is established with the local
1168 .B portmap
1169 service (generally
1170 .I protocol
1171 is zero,
1172 .B
1173 .SM IPPROTO_UDP
1174 or
1175 .B
1176 .SM IPPROTO_TCP
1177 ).
1178 The procedure
1179 .I dispatch
1180 has the following form:
1181 .RS 1i
1182 .ft B
1183 .nf
1184 dispatch(request, xprt)
1185 struct svc_req *request;
1186 \s-1SVCXPRT\s0 *xprt;
1187 .ft R
1188 .fi
1189 .RE
1190 .IP
1191 The
1192 .B svc_register()
1193 routine returns one if it succeeds, and zero otherwise.
1194 .br
1195 .if t .ne 6
1196 .LP
1197 .ft B
1198 .nf
1199 .sp .5
1200 svc_run()
1201 .fi
1202 .ft R
1203 .IP
1204 This routine never returns. It waits for
1205 .SM RPC
1206 requests to arrive, and calls the appropriate service
1207 procedure using
1208 .B svc_getreq()
1209 when one arrives. This procedure is usually waiting for a
1210 .B select()
1211 system call to return.
1212 .br
1213 .if t .ne 9
1214 .LP
1215 .ft B
1216 .nf
1217 .sp .5
1218 svc_sendreply(xprt, outproc, out)
1219 \s-1SVCXPRT\s0 *xprt;
1220 xdrproc_t outproc;
1221 char *out;
1222 .fi
1223 .ft R
1224 .IP
1225 Called by an
1226 .SM RPC
1227 service's dispatch routine to send the results of a
1228 remote procedure call.  The parameter
1229 .I xprt
1230 is the request's associated transport handle;
1231 .I outproc
1232 is the
1233 .SM XDR
1234 routine which is used to encode the results; and
1235 .I out
1236 is the address of the results.
1237 This routine returns one if it succeeds, zero otherwise.
1238 .br
1239 .if t .ne 7
1240 .LP
1241 .ft B
1242 .nf
1243 .sp .5
1244 void
1245 svc_unregister(prognum, versnum)
1246 u_long prognum, versnum;
1247 .fi
1248 .ft R
1249 .IP
1250 Remove all mapping of the double
1251 .RI [ prognum , versnum ]
1252 to dispatch routines, and of the triple
1253 .RI [ prognum , versnum , *\fR]
1254 to port number.
1255 .br
1256 .if t .ne 9
1257 .LP
1258 .ft B
1259 .nf
1260 .sp .5
1261 void
1262 svcerr_auth(xprt, why)
1263 \s-1SVCXPRT\s0 *xprt;
1264 enum auth_stat why;
1265 .fi
1266 .ft R
1267 .IP
1268 Called by a service dispatch routine that refuses to perform
1269 a remote procedure call due to an authentication error.
1270 .br
1271 .if t .ne 7
1272 .LP
1273 .ft B
1274 .nf
1275 .sp .5
1276 void
1277 svcerr_decode(xprt)
1278 \s-1SVCXPRT\s0 *xprt;
1279 .fi
1280 .ft R
1281 .IP
1282 Called by a service dispatch routine that cannot successfully
1283 decode its parameters. See also
1284 .BR svc_getargs() .
1285 .br
1286 .if t .ne 7
1287 .LP
1288 .ft B
1289 .nf
1290 .sp .5
1291 void
1292 svcerr_noproc(xprt)
1293 \s-1SVCXPRT\s0 *xprt;
1294 .fi
1295 .ft R
1296 .IP
1297 Called by a service dispatch routine that does not implement
1298 the procedure number that the caller requests.
1299 .br
1300 .if t .ne 7
1301 .LP
1302 .ft B
1303 .nf
1304 .sp .5
1305 void
1306 svcerr_noprog(xprt)
1307 \s-1SVCXPRT\s0 *xprt;
1308 .fi
1309 .ft R
1310 .IP
1311 Called when the desired program is not registered with the
1312 .SM RPC
1313 package. Service implementors usually do not need this routine.
1314 .br
1315 .if t .ne 7
1316 .LP
1317 .ft B
1318 .nf
1319 .sp .5
1320 void
1321 svcerr_progvers(xprt)
1322 \s-1SVCXPRT\s0 *xprt;
1323 .fi
1324 .ft R
1325 .IP
1326 Called when the desired version of a program is not registered
1327 with the
1328 .SM RPC
1329 package. Service implementors usually do not need this routine.
1330 .br
1331 .if t .ne 7
1332 .LP
1333 .ft B
1334 .nf
1335 .sp .5
1336 void
1337 svcerr_systemerr(xprt)
1338 \s-1SVCXPRT\s0 *xprt;
1339 .fi
1340 .ft R
1341 .IP
1342 Called by a service dispatch routine when it detects a system
1343 error
1344 not covered by any particular protocol.
1345 For example, if a service can no longer allocate storage,
1346 it may call this routine.
1347 .br
1348 .if t .ne 8
1349 .LP
1350 .ft B
1351 .nf
1352 .sp .5
1353 void
1354 svcerr_weakauth(xprt)
1355 \s-1SVCXPRT\s0 *xprt;
1356 .fi
1357 .ft R
1358 .IP
1359 Called by a service dispatch routine that refuses to perform
1360 a remote procedure call due to insufficient
1361 authentication parameters.  The routine calls
1362 .BR "svcerr_auth(xprt, \s-1AUTH_TOOWEAK\s0)" .
1363 .br
1364 .if t .ne 11
1365 .LP
1366 .ft B
1367 .nf
1368 .sp .5
1369 \s-1SVCXPRT\s0 *
1370 svcfd_create(fd, sendsize, recvsize)
1371 int fd;
1372 u_int sendsize;
1373 u_int recvsize;
1374 .fi
1375 .ft R
1376 .IP
1377 Create a service on top of any open descriptor. Typically,
1378 this
1379 descriptor is a connected socket for a stream protocol such
1380 as
1381 .SM TCP\s0.
1382 .I sendsize
1383 and
1384 .I recvsize
1385 indicate sizes for the send and receive buffers.  If they are
1386 zero, a reasonable default is chosen.
1387 .br
1388 .if t .ne 11
1389 .LP
1390 .ft B
1391 .nf
1392 .sp .5
1393 \s-1SVCXPRT\s0 *
1394 svcraw_create()
1395 .fi
1396 .ft R
1397 .IP
1398 This routine creates a toy
1399 .SM RPC
1400 service transport, to which it returns a pointer.  The
1401 transport
1402 is really a buffer within the process's address space,
1403 so the corresponding
1404 .SM RPC
1405 client should live in the same
1406 address space;
1407 see
1408 .BR clntraw_create() .
1409 This routine allows simulation of
1410 .SM RPC
1411 and acquisition of
1412 .SM RPC
1413 overheads (such as round trip times), without any kernel
1414 interference.
1415 This routine returns
1416 .SM NULL
1417 if it fails.
1418 .br
1419 .if t .ne 11
1420 .LP
1421 .ft B
1422 .nf
1423 .sp .5
1424 \s-1SVCXPRT\s0 *
1425 svctcp_create(sock, send_buf_size, recv_buf_size)
1426 int sock;
1427 u_int send_buf_size, recv_buf_size;
1428 .fi
1429 .ft R
1430 .IP
1431 This routine creates a
1432 .SM TCP/IP\s0-based
1433 .SM RPC
1434 service transport, to which it returns a pointer.
1435 The transport is associated with the socket
1436 .IR sock ,
1437 which may be
1438 .BR \s-1RPC_ANYSOCK\s0 ,
1439 in which case a new socket is created.
1440 If the socket is not bound to a local
1441 .SM TCP
1442 port, then this routine binds it to an arbitrary port.  Upon
1443 completion,
1444 \fB\%xprt\->xp_sock\fR
1445 is the transport's socket descriptor, and
1446 \fB\%xprt\->xp_port\fR
1447 is the transport's port number.
1448 This routine returns
1449 .SM NULL
1450 if it fails. Since
1451 .SM TCP\s0-based
1452 .SM RPC
1453 uses buffered
1454 .SM I/O ,
1455 users may specify the size of buffers; values of zero
1456 choose suitable defaults.
1457 .br
1458 .if t .ne 10
1459 .LP
1460 .ft B
1461 .nf
1462 .sp .5
1463 \s-1SVCXPRT\s0 *
1464 svcudp_bufcreate(sock, sendsize, recosize)
1465 int sock;
1466 .fi
1467 .ft R
1468 .IP
1469 This routine creates a
1470 .SM UDP/IP\s0-based
1471 .SM RPC
1472 service transport, to which it returns a pointer.
1473 The transport is associated with the socket
1474 .IR sock ,
1475 which may be
1476 .BR \s-1RPC_ANYSOCK\s0 ,
1477 in which case a new socket is created.
1478 If the socket is not bound to a local
1479 .SM UDP
1480 port, then this routine binds it to an arbitrary port. Upon
1481 completion,
1482 \fB\%xprt\->xp_sock\fR
1483 is the transport's socket descriptor, and
1484 \fB\%xprt\->xp_port\fR
1485 is the transport's port number.
1486 This routine returns
1487 .SM NULL
1488 if it fails.
1489 .IP
1490 This allows the user to specify the maximum packet size for sending and
1491 receiving
1492 .SM UDP\s0-based
1493 .SM RPC messages.
1494 .br
1495 .if t .ne 5
1496 .LP
1497 .ft B
1498 .nf
1499 .sp .5
1500 \s-1SVCXPRT\s0 *
1501 svcudp_create(sock)
1502 int sock;
1503 .fi
1504 .ft R
1505 .IP
1506 This call is equivalent to
1507 \fIsvcudp_bufcreate(sock,SZ,SZ)\fP
1508 for some default size \fISZ\fP.
1509 .br
1510 .if t .ne 7
1511 .LP
1512 .ft B
1513 .nf
1514 .sp .5
1515 xdr_accepted_reply(xdrs, ar)
1516 \s-1XDR\s0 *xdrs;
1517 struct accepted_reply *ar;
1518 .fi
1519 .ft R
1520 .IP
1521 Used for encoding
1522 .SM RPC
1523 reply messages. This routine is useful for users who
1524 wish to generate
1525 \s-1RPC\s0-style
1526 messages without using the
1527 .SM RPC
1528 package.
1529 .br
1530 .if t .ne 7
1531 .LP
1532 .ft B
1533 .nf
1534 .sp .5
1535 xdr_authunix_parms(xdrs, aupp)
1536 \s-1XDR\s0 *xdrs;
1537 struct authunix_parms *aupp;
1538 .fi
1539 .ft R
1540 .IP
1541 Used for describing
1542 .SM UNIX
1543 credentials. This routine is useful for users
1544 who wish to generate these credentials without using the
1545 .SM RPC
1546 authentication package.
1547 .br
1548 .if t .ne 7
1549 .LP
1550 .ft B
1551 .nf
1552 .sp .5
1553 void
1554 xdr_callhdr(xdrs, chdr)
1555 \s-1XDR\s0 *xdrs;
1556 struct rpc_msg *chdr;
1557 .fi
1558 .ft R
1559 .IP
1560 Used for describing
1561 .SM RPC
1562 call header messages.
1563 This routine is useful for users who wish to generate
1564 .SM RPC\s0-style
1565 messages without using the
1566 .SM RPC
1567 package.
1568 .br
1569 .if t .ne 7
1570 .LP
1571 .ft B
1572 .nf
1573 .sp .5
1574 xdr_callmsg(xdrs, cmsg)
1575 \s-1XDR\s0 *xdrs;
1576 struct rpc_msg *cmsg;
1577 .fi
1578 .ft R
1579 .IP
1580 Used for describing
1581 .SM RPC
1582 call messages.
1583 This routine is useful for users who wish to generate
1584 .SM RPC\s0-style
1585 messages without using the
1586 .SM RPC
1587 package.
1588 .br
1589 .if t .ne 7
1590 .LP
1591 .ft B
1592 .nf
1593 .sp .5
1594 xdr_opaque_auth(xdrs, ap)
1595 \s-1XDR\s0 *xdrs;
1596 struct opaque_auth *ap;
1597 .fi
1598 .ft R
1599 .IP
1600 Used for describing
1601 .SM RPC
1602 authentication information messages.
1603 This routine is useful for users who wish to generate
1604 .SM RPC\s0-style
1605 messages without using the
1606 .SM RPC
1607 package.
1608 .br
1609 .if t .ne 7
1610 .LP
1611 .ft B
1612 .nf
1613 .sp .5
1614 xdr_pmap(xdrs, regs)
1615 \s-1XDR\s0 *xdrs;
1616 struct pmap *regs;
1617 .fi
1618 .ft R
1619 .IP
1620 Used for describing parameters to various
1621 .B portmap
1622 procedures, externally.
1623 This routine is useful for users who wish to generate
1624 these parameters without using the
1625 .B pmap
1626 interface.
1627 .br
1628 .if t .ne 7
1629 .LP
1630 .ft B
1631 .nf
1632 .sp .5
1633 xdr_pmaplist(xdrs, rp)
1634 \s-1XDR\s0 *xdrs;
1635 struct pmaplist **rp;
1636 .fi
1637 .ft R
1638 .IP
1639 Used for describing a list of port mappings, externally.
1640 This routine is useful for users who wish to generate
1641 these parameters without using the
1642 .B pmap
1643 interface.
1644 .br
1645 .if t .ne 7
1646 .LP
1647 .ft B
1648 .nf
1649 .sp .5
1650 xdr_rejected_reply(xdrs, rr)
1651 \s-1XDR\s0 *xdrs;
1652 struct rejected_reply *rr;
1653 .fi
1654 .ft R
1655 .IP
1656 Used for describing
1657 .SM RPC
1658 reply messages.
1659 This routine is useful for users who wish to generate
1660 .SM RPC\s0-style
1661 messages without using the
1662 .SM RPC
1663 package.
1664 .br
1665 .if t .ne 8
1666 .LP
1667 .ft B
1668 .nf
1669 .sp .5
1670 xdr_replymsg(xdrs, rmsg)
1671 \s-1XDR\s0 *xdrs;
1672 struct rpc_msg *rmsg;
1673 .fi
1674 .ft R
1675 .IP
1676 Used for describing
1677 .SM RPC
1678 reply messages.
1679 This routine is useful for users who wish to generate
1680 .SM RPC
1681 style messages without using the
1682 .SM RPC
1683 package.
1684 .br
1685 .if t .ne 8
1686 .LP
1687 .ft B
1688 .nf
1689 .sp .5
1690 void
1691 xprt_register(xprt)
1692 \s-1SVCXPRT\s0 *xprt;
1693 .fi
1694 .ft R
1695 .IP
1696 After
1697 .SM RPC
1698 service transport handles are created,
1699 they should register themselves with the
1700 .SM RPC
1701 service package.
1702 This routine modifies the global variable
1703 .BR svc_fds() .
1704 Service implementors usually do not need this routine.
1705 .br
1706 .if t .ne 8
1707 .LP
1708 .ft B
1709 .nf
1710 .sp .5
1711 void
1712 xprt_unregister(xprt)
1713 \s-1SVCXPRT\s0 *xprt;
1714 .fi
1715 .ft R
1716 .IP
1717 Before an
1718 .SM RPC
1719 service transport handle is destroyed,
1720 it should unregister itself with the
1721 .SM RPC
1722 service package.
1723 This routine modifies the global variable
1724 .BR svc_fds() .
1725 Service implementors usually do not need this routine.
1726 .SH "SEE ALSO"
1727 .BR rpc_secure (3),
1728 .BR xdr (3)
1729 .br
1730 The following manuals:
1731 .RS
1732 .ft I
1733 Remote Procedure Calls: Protocol Specification
1734 .br
1735 Remote Procedure Call Programming Guide
1736 .br
1737 rpcgen Programming Guide
1738 .br
1739 .ft R
1740 .RE
1741 .IR "\s-1RPC\s0: Remote Procedure Call Protocol Specification" ,
1742 .SM RFC1050, Sun Microsystems, Inc.,
1743 .SM USC-ISI\s0.