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