rpc.subproj/rpc.3

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