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