lib/libc/rpc/rpc.3

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