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