original/man3/rpc.3

   1 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   2 .\"
   3 .\" %%%LICENSE_START(BSD_ONELINE_CDROM)
   4 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   5 .\" %%%LICENSE_END
   6 .\"
   7 .\" @(#)rpc.3n  2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
   8 .\"
   9 .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
  10 .\"
  11 .TH RPC 3 2013-09-26 "" "Linux Programmer's Manual"
  12 .SH NAME
  13 rpc \- library routines for remote procedure calls
  14 .SH SYNOPSIS AND DESCRIPTION
  15 These routines allow C programs to make procedure
  16 calls on other machines across the network.
  17 First, the client calls a procedure to send a data packet to the server.
  18 Upon receipt of the packet, the server calls a dispatch routine
  19 to perform the requested service, and then sends back a reply.
  20 Finally, the procedure call returns to the client.
  21 .\" .LP
  22 .\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05
  23 .\" Routines that are used for Secure RPC (DES authentication) are described in
  24 .\" .BR rpc_secure (3).
  25 .\" Secure RPC can be used only if DES encryption is available.
  26 .LP
  27 To take use of these routines, include the header file
  28 .IR "<rpc/rpc.h>" .
  29
  30 The prototypes below make use of the following types:
  31 .in +4n
  32 .nf
  33
  34 .BI "typedef int " bool_t ;
  35
  36 .BI "typedef bool_t (*" xdrproc_t ") (XDR *, void *, ...);"
  37
  38 .BI "typedef bool_t (*" resultproc_t ") (caddr_t " resp ,
  39 .BI "                                struct sockaddr_in *" raddr );
  40 .fi
  41 .in
  42 .LP
  43 See the header files for the declarations of the
  44 .IR AUTH ,
  45 .IR CLIENT ,
  46 .IR SVCXPRT ,
  47 and
  48 .IR XDR
  49 types.
  50 .LP
  51 .nf
  52 .BI "void auth_destroy(AUTH *" auth );
  53 .fi
  54 .IP
  55 A macro that destroys the authentication information associated with
  56 .IR auth .
  57 Destruction usually involves deallocation of private data structures.
  58 The use of
  59 .I auth
  60 is undefined after calling
  61 .BR auth_destroy ().
  62 .LP
  63 .nf
  64 .BI "AUTH *authnone_create(void);"
  65 .fi
  66 .IP
  67 Create and return an RPC
  68 authentication handle that passes nonusable authentication
  69 information with each remote procedure call.
  70 This is the default authentication used by RPC.
  71 .LP
  72 .nf
  73 .BI "AUTH *authunix_create(char *" host ", int " uid ", int " gid ,
  74 .BI "                      int " len ", int *" aup_gids );
  75 .fi
  76 .IP
  77 Create and return an RPC authentication handle that contains
  78 authentication information.
  79 The parameter
  80 .I host
  81 is the name of the machine on which the information was created;
  82 .I uid
  83 is the user's user ID;
  84 .I gid
  85 is the user's current group ID;
  86 .I len
  87 and
  88 .I aup_gids
  89 refer to a counted array of groups to which the user belongs.
  90 It is easy to impersonate a user.
  91 .LP
  92 .nf
  93 .BI "AUTH *authunix_create_default(void);"
  94 .fi
  95 .IP
  96 Calls
  97 .BR authunix_create ()
  98 with the appropriate parameters.
  99 .LP
 100 .nf
 101 .BI "int callrpc(char *" host ", unsigned long " prognum ,
 102 .BI "            unsigned long " versnum ", unsigned long " procnum ,
 103 .BI "            xdrproc_t " inproc ", char *" in ,
 104 .BI "            xdrproc_t " outproc ", char *" out );
 105 .fi
 106 .IP
 107 Call the remote procedure associated with
 108 .IR prognum ,
 109 .IR versnum ,
 110 and
 111 .I procnum
 112 on the machine,
 113 .IR host .
 114 The parameter
 115 .I in
 116 is the address of the procedure's argument(s), and
 117 .I out
 118 is the address of where to place the result(s);
 119 .I inproc
 120 is used to encode the procedure's parameters, and
 121 .I outproc
 122 is used to decode the procedure's results.
 123 This routine returns zero if it succeeds, or the value of
 124 .B "enum clnt_stat"
 125 cast to an integer if it fails.
 126 The routine
 127 .BR clnt_perrno ()
 128 is handy for translating failure statuses into messages.
 129 .IP
 130 Warning: calling remote procedures with this routine
 131 uses UDP/IP as a transport; see
 132 .BR clntudp_create ()
 133 for restrictions.
 134 You do not have control of timeouts or authentication using this routine.
 135 .LP
 136 .nf
 137 .BI "enum clnt_stat clnt_broadcast(unsigned long " prognum ,
 138 .BI "                     unsigned long " versnum ", unsigned long " procnum ,
 139 .BI "                     xdrproc_t " inproc ", char *" in ,
 140 .BI "                     xdrproc_t " outproc ", char *" out ,
 141 .BI "                     resultproc_t " eachresult );
 142 .fi
 143 .IP
 144 Like
 145 .BR callrpc (),
 146 except the call message is broadcast to all locally
 147 connected broadcast nets.
 148 Each time it receives a response, this routine calls
 149 .BR eachresult (),
 150 whose form is:
 151 .IP
 152 .in +4n
 153 .nf
 154 .BI "eachresult(char *" out ", struct sockaddr_in *" addr );
 155 .fi
 156 .in
 157 .IP
 158 where
 159 .I out
 160 is the same as
 161 .I out
 162 passed to
 163 .BR clnt_broadcast (),
 164 except that the remote procedure's output is decoded there;
 165 .I addr
 166 points to the address of the machine that sent the results.
 167 If
 168 .BR eachresult ()
 169 returns zero,
 170 .BR clnt_broadcast ()
 171 waits for more replies; otherwise it returns with appropriate status.
 172 .IP
 173 Warning: broadcast sockets are limited in size to the
 174 maximum transfer unit of the data link.
 175 For ethernet, this value is 1500 bytes.
 176 .LP
 177 .nf
 178 .BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum ,
 179 .BI "                    xdrproc_t " inproc ", char *" in ,
 180 .BI "                    xdrproc_t " outproc ", char *" out ,
 181 .BI "                    struct timeval " tout );
 182 .fi
 183 .IP
 184 A macro that calls the remote procedure
 185 .I procnum
 186 associated with the client handle,
 187 .IR clnt ,
 188 which is obtained with an RPC client creation routine such as
 189 .BR clnt_create ().
 190 The parameter
 191 .I in
 192 is the address of the procedure's argument(s), and
 193 .I out
 194 is the address of where to place the result(s);
 195 .I inproc
 196 is used to encode the procedure's parameters, and
 197 .I outproc
 198 is used to decode the procedure's results;
 199 .I tout
 200 is the time allowed for results to come back.
 201 .LP
 202 .nf
 203 .BI "clnt_destroy(CLIENT *" clnt );
 204 .fi
 205 .IP
 206 A macro that destroys the client's RPC handle.
 207 Destruction usually involves deallocation
 208 of private data structures, including
 209 .I clnt
 210 itself.
 211 Use of
 212 .I clnt
 213 is undefined after calling
 214 .BR clnt_destroy ().
 215 If the RPC library opened the associated socket, it will close it also.
 216 Otherwise, the socket remains open.
 217 .LP
 218 .nf
 219 .BI "CLIENT *clnt_create(char *" host ", unsigned long " prog ,
 220 .BI "                    unsigned long " vers ", char *" proto );
 221 .fi
 222 .IP
 223 Generic client creation routine.
 224 .I host
 225 identifies the name of the remote host where the server is located.
 226 .I proto
 227 indicates which kind of transport protocol to use.
 228 The currently supported values for this field are \(lqudp\(rq
 229 and \(lqtcp\(rq.
 230 Default timeouts are set, but can be modified using
 231 .BR clnt_control ().
 232 .IP
 233 Warning: Using UDP has its shortcomings.
 234 Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data,
 235 this transport cannot be used for procedures that take
 236 large arguments or return huge results.
 237 .LP
 238 .nf
 239 .BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info );
 240 .fi
 241 .IP
 242 A macro used to change or retrieve various information
 243 about a client object.
 244 .I req
 245 indicates the type of operation, and
 246 .I info
 247 is a pointer to the information.
 248 For both UDP and TCP, the supported values of
 249 .I req
 250 and their argument types and what they do are:
 251 .IP
 252 .in +4n
 253 .nf
 254 \fBCLSET_TIMEOUT\fP  \fIstruct timeval\fP // set total timeout
 255 \fBCLGET_TIMEOUT\fP  \fIstruct timeval\fP // get total timeout
 256 .fi
 257 .in
 258 .IP
 259 Note: if you set the timeout using
 260 .BR clnt_control (),
 261 the timeout parameter passed to
 262 .BR clnt_call ()
 263 will be ignored in all future calls.
 264 .IP
 265 .in +4n
 266 .nf
 267 \fBCLGET_SERVER_ADDR\fP  \fIstruct sockaddr_in \fP // get server's address
 268 .fi
 269 .in
 270 .IP
 271 The following operations are valid for UDP only:
 272 .IP
 273 .in +4n
 274 .nf
 275 \fBCLSET_RETRY_TIMEOUT\fP  \fIstruct timeval\fP // set the retry timeout
 276 \fBCLGET_RETRY_TIMEOUT\fP  \fIstruct timeval\fP // get the retry timeout
 277 .fi
 278 .in
 279 .IP
 280 The retry timeout is the time that "UDP RPC"
 281 waits for the server to reply before
 282 retransmitting the request.
 283 .LP
 284 .nf
 285 .BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out );
 286 .fi
 287 .IP
 288 A macro that frees any data allocated by the RPC/XDR
 289 system when it decoded the results of an RPC call.
 290 The parameter
 291 .I out
 292 is the address of the results, and
 293 .I outproc
 294 is the XDR routine describing the results.
 295 This routine returns one if the results were successfully freed,
 296 and zero otherwise.
 297 .LP
 298 .nf
 299 .BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp );
 300 .fi
 301 .IP
 302 A macro that copies the error structure out of the client
 303 handle to the structure at address
 304 .IR errp .
 305 .LP
 306 .nf
 307 .BI "void clnt_pcreateerror(char *" s );
 308 .fi
 309 .IP
 310 Print a message to standard error indicating why a client RPC
 311 handle could not be created.
 312 The message is prepended with string
 313 .I s
 314 and a colon.
 315 Used when a
 316 .BR clnt_create (),
 317 .BR clntraw_create (),
 318 .BR clnttcp_create (),
 319 or
 320 .BR clntudp_create ()
 321 call fails.
 322 .LP
 323 .nf
 324 .BI "void clnt_perrno(enum clnt_stat " stat );
 325 .fi
 326 .IP
 327 Print a message to standard error corresponding
 328 to the condition indicated by
 329 .IR stat .
 330 Used after
 331 .BR callrpc ().
 332 .LP
 333 .nf
 334 .BI "clnt_perror(CLIENT *" clnt ", char *" s );
 335 .fi
 336 .IP
 337 Print a message to standard error indicating why an RPC call failed;
 338 .I clnt
 339 is the handle used to do the call.
 340 The message is prepended with string
 341 .I s
 342 and a colon.
 343 Used after
 344 .BR clnt_call ().
 345 .LP
 346 .nf
 347 .BI "char *clnt_spcreateerror(char *" s );
 348 .fi
 349 .IP
 350 Like
 351 .BR clnt_pcreateerror (),
 352 except that it returns a string instead of printing to the standard error.
 353 .IP
 354 Bugs: returns pointer to static data that is overwritten on each call.
 355 .LP
 356 .nf
 357 .BI "char *clnt_sperrno(enum clnt_stat " stat );
 358 .fi
 359 .IP
 360 Take the same arguments as
 361 .BR clnt_perrno (),
 362 but instead of sending a message to the standard error indicating why an RPC
 363 call failed, return a pointer to a string which contains the message.
 364 The string ends with a NEWLINE.
 365 .IP
 366 .BR clnt_sperrno ()
 367 is used instead of
 368 .BR clnt_perrno ()
 369 if the program does not have a standard error (as a program
 370 running as a server quite likely does not), or if the programmer
 371 does not want the message to be output with
 372 .BR printf (3),
 373 or if a message format different than that supported by
 374 .BR clnt_perrno ()
 375 is to be used.
 376 Note: unlike
 377 .BR clnt_sperror ()
 378 and
 379 .BR clnt_spcreaterror (),
 380 .BR clnt_sperrno ()
 381 returns pointer to static data, but the
 382 result will not get overwritten on each call.
 383 .LP
 384 .nf
 385 .BI "char *clnt_sperror(CLIENT *" rpch ", char *" s );
 386 .fi
 387 .IP
 388 Like
 389 .BR clnt_perror (),
 390 except that (like
 391 .BR clnt_sperrno ())
 392 it returns a string instead of printing to standard error.
 393 .IP
 394 Bugs: returns pointer to static data that is overwritten on each call.
 395 .LP
 396 .nf
 397 .BI "CLIENT *clntraw_create(unsigned long " prognum \
 398 ", unsigned long " versnum );
 399 .fi
 400 .IP
 401 This routine creates a toy RPC client for the remote program
 402 .IR prognum ,
 403 version
 404 .IR versnum .
 405 The transport used to pass messages to the service is
 406 actually a buffer within the process's address space, so the
 407 corresponding RPC server should live in the same address space; see
 408 .BR svcraw_create ().
 409 This allows simulation of RPC and acquisition of RPC
 410 overheads, such as round trip times, without any kernel interference.
 411 This routine returns NULL if it fails.
 412 .LP
 413 .nf
 414 .BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr ,
 415 .BI "                unsigned long " prognum ", unsigned long " versnum ,
 416 .BI "                int *" sockp ", unsigned int " sendsz \
 417 ", unsigned int " recvsz );
 418 .fi
 419 .IP
 420 This routine creates an RPC client for the remote program
 421 .IR prognum ,
 422 version
 423 .IR versnum ;
 424 the client uses TCP/IP as a transport.
 425 The remote program is located at Internet address
 426 .IR *addr .
 427 If
 428 .\"The following inline font conversion is necessary for the hyphen indicator
 429 .I addr\->sin_port
 430 is zero, then it is set to the actual port that the remote
 431 program is listening on (the remote
 432 .B portmap
 433 service is consulted for this information).
 434 The parameter
 435 .I sockp
 436 is a socket; if it is
 437 .BR RPC_ANYSOCK ,
 438 then this routine opens a new one and sets
 439 .IR sockp .
 440 Since TCP-based RPC uses buffered I/O,
 441 the user may specify the size of the send and receive buffers
 442 with the parameters
 443 .I sendsz
 444 and
 445 .IR recvsz ;
 446 values of zero choose suitable defaults.
 447 This routine returns NULL if it fails.
 448 .LP
 449 .nf
 450 .BI "CLIENT *clntudp_create(struct sockaddr_in *" addr ,
 451 .BI "                unsigned long " prognum ", unsigned long " versnum ,
 452 .BI "                struct timeval " wait ", int *" sockp );
 453 .fi
 454 .IP
 455 This routine creates an RPC client for the remote program
 456 .IR prognum ,
 457 version
 458 .IR versnum ;
 459 the client uses use UDP/IP as a transport.
 460 The remote program is located at Internet address
 461 .IR addr .
 462 If
 463 .I addr\->sin_port
 464 is zero, then it is set to actual port that the remote
 465 program is listening on (the remote
 466 .B portmap
 467 service is consulted for this information).
 468 The parameter
 469 .I sockp
 470 is a socket; if it is
 471 .BR RPC_ANYSOCK ,
 472 then this routine opens a new one and sets
 473 .IR sockp .
 474 The UDP transport resends the call message in intervals of
 475 .I wait
 476 time until a response is received or until the call times out.
 477 The total time for the call to time out is specified by
 478 .BR clnt_call ().
 479 .IP
 480 Warning: since UDP-based RPC messages can hold only up to 8 Kbytes
 481 of encoded data, this transport cannot be used for procedures
 482 that take large arguments or return huge results.
 483 .LP
 484 .nf
 485 .BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr ,
 486 .BI "            unsigned long " prognum ", unsigned long " versnum ,
 487 .BI "            struct timeval " wait ", int *" sockp ,
 488 .BI "            unsigned int " sendsize ", unsigned int "recosize );
 489 .fi
 490 .IP
 491 This routine creates an RPC client for the remote program
 492 .IR prognum ,
 493 on
 494 .IR versnum ;
 495 the client uses use UDP/IP as a transport.
 496 The remote program is located at Internet address
 497 .IR addr .
 498 If
 499 .I addr\->sin_port
 500 is zero, then it is set to actual port that the remote
 501 program is listening on (the remote
 502 .B portmap
 503 service is consulted for this information).
 504 The parameter
 505 .I sockp
 506 is a socket; if it is
 507 .BR RPC_ANYSOCK ,
 508 then this routine opens a new one and sets
 509 .IR sockp .
 510 The UDP transport resends the call message in intervals of
 511 .I wait
 512 time until a response is received or until the call times out.
 513 The total time for the call to time out is specified by
 514 .BR clnt_call ().
 515 .IP
 516 This allows the user to specify the maximum packet
 517 size for sending and receiving UDP-based RPC messages.
 518 .LP
 519 .nf
 520 .BI "void get_myaddress(struct sockaddr_in *" addr );
 521 .fi
 522 .IP
 523 Stuff the machine's IP address into
 524 .IR *addr ,
 525 without consulting the library routines that deal with
 526 .IR /etc/hosts .
 527 The port number is always set to
 528 .BR htons(PMAPPORT) .
 529 .LP
 530 .nf
 531 .BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr );
 532 .fi
 533 .IP
 534 A user interface to the
 535 .B portmap
 536 service, which returns a list of the current RPC
 537 program-to-port mappings on the host located at IP address
 538 .IR *addr .
 539 This routine can return NULL.
 540 The command
 541 .IR "rpcinfo\ \-p"
 542 uses this routine.
 543 .LP
 544 .nf
 545 .BI "unsigned short pmap_getport(struct sockaddr_in *" addr ,
 546 .BI "                    unsigned long " prognum ", unsigned long " versnum ,
 547 .BI "                    unsigned int " protocol );
 548 .fi
 549 .IP
 550 A user interface to the
 551 .B portmap
 552 service, which returns the port number
 553 on which waits a service that supports program number
 554 .IR prognum ,
 555 version
 556 .IR versnum ,
 557 and speaks the transport protocol associated with
 558 .IR protocol .
 559 The value of
 560 .I protocol
 561 is most likely
 562 .B IPPROTO_UDP
 563 or
 564 .BR IPPROTO_TCP .
 565 A return value of zero means that the mapping does not exist
 566 or that the RPC system failed to contact the remote
 567 .B portmap
 568 service.
 569 In the latter case, the global variable
 570 .I rpc_createerr
 571 contains the RPC status.
 572 .LP
 573 .nf
 574 .BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr ,
 575 .BI "                    unsigned long " prognum ", unsigned long " versnum ,
 576 .BI "                    unsigned long " procnum ,
 577 .BI "                    xdrproc_t " inproc ", char *" in ,
 578 .BI "                    xdrproc_t " outproc ", char *" out ,
 579 .BI "                    struct timeval " tout ", unsigned long *" portp );
 580 .fi
 581 .IP
 582 A user interface to the
 583 .B portmap
 584 service, which instructs
 585 .B portmap
 586 on the host at IP address
 587 .I *addr
 588 to make an RPC call on your behalf to a procedure on that host.
 589 The parameter
 590 .I *portp
 591 will be modified to the program's port number if the procedure succeeds.
 592 The definitions of other parameters are discussed
 593 in
 594 .BR callrpc ()
 595 and
 596 .BR clnt_call ().
 597 This procedure should be used for a \(lqping\(rq and nothing else.
 598 See also
 599 .BR clnt_broadcast ().
 600 .LP
 601 .nf
 602 .BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum ,
 603 .BI "                unsigned int " protocol ", unsigned short " port );
 604 .fi
 605 .IP
 606 A user interface to the
 607 .B portmap
 608 service, which establishes a mapping between the triple
 609 .RI [ prognum , versnum , protocol ]
 610 and
 611 .I port
 612 on the machine's
 613 .B portmap
 614 service.
 615 The value of
 616 .I protocol
 617 is most likely
 618 .B IPPROTO_UDP
 619 or
 620 .BR IPPROTO_TCP .
 621 This routine returns one if it succeeds, zero otherwise.
 622 Automatically done by
 623 .BR svc_register ().
 624 .LP
 625 .nf
 626 .BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum );
 627 .fi
 628 .IP
 629 A user interface to the
 630 .B portmap
 631 service, which destroys all mapping between the triple
 632 .RI [ prognum , versnum , * ]
 633 and
 634 .B ports
 635 on the machine's
 636 .B portmap
 637 service.
 638 This routine returns one if it succeeds, zero otherwise.
 639 .LP
 640 .nf
 641 .BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum ,
 642 .BI "                unsigned long " procnum ", char *(*" procname ")(char *),"
 643 .BI "                xdrproc_t " inproc ", xdrproc_t " outproc );
 644 .fi
 645 .IP
 646 Register procedure
 647 .I procname
 648 with the RPC service package.
 649 If a request arrives for program
 650 .IR prognum ,
 651 version
 652 .IR versnum ,
 653 and procedure
 654 .IR procnum ,
 655 .I procname
 656 is called with a pointer to its parameter(s);
 657 .I progname
 658 should return a pointer to its static result(s);
 659 .I inproc
 660 is used to decode the parameters while
 661 .I outproc
 662 is used to encode the results.
 663 This routine returns zero if the registration succeeded, \-1 otherwise.
 664 .IP
 665 Warning: remote procedures registered in this form
 666 are accessed using the UDP/IP transport; see
 667 .BR svcudp_create ()
 668 for restrictions.
 669 .LP
 670 .nf
 671 .BI "struct rpc_createerr " rpc_createerr ;
 672 .fi
 673 .IP
 674 A global variable whose value is set by any RPC client creation routine
 675 that does not succeed.
 676 Use the routine
 677 .BR clnt_pcreateerror ()
 678 to print the reason why.
 679 .LP
 680 .nf
 681 .BI "void svc_destroy(SVCXPRT *" xprt );
 682 .fi
 683 .IP
 684 A macro that destroys the RPC service transport handle,
 685 .IR xprt .
 686 Destruction usually involves deallocation
 687 of private data structures, including
 688 .I xprt
 689 itself.
 690 Use of
 691 .I xprt
 692 is undefined after calling this routine.
 693 .LP
 694 .nf
 695 .BI "fd_set " svc_fdset ;
 696 .fi
 697 .IP
 698 A global variable reflecting the RPC service side's
 699 read file descriptor bit mask; it is suitable as a parameter to the
 700 .BR select (2)
 701 system call.
 702 This is of interest only if a service implementor does their own
 703 asynchronous event processing, instead of calling
 704 .BR svc_run ().
 705 This variable is read-only (do not pass its address to
 706 .BR select (2)!),
 707 yet it may change after calls to
 708 .BR svc_getreqset ()
 709 or any creation routines.
 710 .LP
 711 .nf
 712 .BI "int " svc_fds ;
 713 .fi
 714 .IP
 715 Similar to
 716 .BR svc_fdset ,
 717 but limited to 32 descriptors.
 718 This interface is obsoleted by
 719 .BR svc_fdset .
 720 .LP
 721 .nf
 722 .BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
 723 .fi
 724 .IP
 725 A macro that frees any data allocated by the RPC/XDR
 726 system when it decoded the arguments to a service procedure using
 727 .BR svc_getargs ().
 728 This routine returns 1 if the results were successfully freed,
 729 and zero otherwise.
 730 .LP
 731 .nf
 732 .BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
 733 .fi
 734 .IP
 735 A macro that decodes the arguments of an RPC request
 736 associated with the RPC service transport handle,
 737 .IR xprt .
 738 The parameter
 739 .I in
 740 is the address where the arguments will be placed;
 741 .I inproc
 742 is the XDR routine used to decode the arguments.
 743 This routine returns one if decoding succeeds, and zero otherwise.
 744 .LP
 745 .nf
 746 .BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt );
 747 .fi
 748 .IP
 749 The approved way of getting the network address of the caller
 750 of a procedure associated with the RPC service transport handle,
 751 .IR xprt .
 752 .LP
 753 .nf
 754 .BI "void svc_getreqset(fd_set *" rdfds );
 755 .fi
 756 .IP
 757 This routine is of interest only if a service implementor does not call
 758 .BR svc_run (),
 759 but instead implements custom asynchronous event processing.
 760 It is called when the
 761 .BR select (2)
 762 system call has determined that an RPC request has arrived on some
 763 RPC socket(s);
 764 .I rdfds
 765 is the resultant read file descriptor bit mask.
 766 The routine returns when all sockets associated with the value of
 767 .I rdfds
 768 have been serviced.
 769 .LP
 770 .nf
 771 .BI "void svc_getreq(int " rdfds );
 772 .fi
 773 .IP
 774 Similar to
 775 .BR svc_getreqset (),
 776 but limited to 32 descriptors.
 777 This interface is obsoleted by
 778 .BR svc_getreqset ().
 779 .LP
 780 .nf
 781 .BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum ,
 782 .BI "                    unsigned long " versnum ,
 783 .BI "                    void (*" dispatch ")(svc_req *, SVCXPRT *),"
 784 .BI "                    unsigned long " protocol );
 785 .fi
 786 .IP
 787 Associates
 788 .I prognum
 789 and
 790 .I versnum
 791 with the service dispatch procedure,
 792 .IR dispatch .
 793 If
 794 .I protocol
 795 is zero, the service is not registered with the
 796 .B portmap
 797 service.
 798 If
 799 .I protocol
 800 is nonzero, then a mapping of the triple
 801 .RI [ prognum , versnum , protocol ]
 802 to
 803 .I xprt\->xp_port
 804 is established with the local
 805 .B portmap
 806 service (generally
 807 .I protocol
 808 is zero,
 809 .B IPPROTO_UDP
 810 or
 811 .BR IPPROTO_TCP ).
 812 The procedure
 813 .I dispatch
 814 has the following form:
 815 .in +4n
 816 .nf
 817
 818 dispatch(struct svc_req *request, SVCXPRT *xprt);
 819 .fi
 820 .in
 821 .IP
 822 The
 823 .BR svc_register ()
 824 routine returns one if it succeeds, and zero otherwise.
 825 .LP
 826 .nf
 827 .B "void svc_run(void);"
 828 .fi
 829 .IP
 830 This routine never returns.
 831 It waits for RPC requests to arrive, and calls the appropriate service
 832 procedure using
 833 .BR svc_getreq ()
 834 when one arrives.
 835 This procedure is usually waiting for a
 836 .BR select (2)
 837 system call to return.
 838 .LP
 839 .nf
 840 .BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \
 841 ", char *" out );
 842 .fi
 843 .IP
 844 Called by an RPC service's dispatch routine to send the results of a
 845 remote procedure call.
 846 The parameter
 847 .I xprt
 848 is the request's associated transport handle;
 849 .I outproc
 850 is the XDR routine which is used to encode the results; and
 851 .I out
 852 is the address of the results.
 853 This routine returns one if it succeeds, zero otherwise.
 854 .LP
 855 .nf
 856 .BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum );
 857 .fi
 858 .IP
 859 Remove all mapping of the double
 860 .RI [ prognum , versnum ]
 861 to dispatch routines, and of the triple
 862 .RI [ prognum , versnum , * ]
 863 to port number.
 864 .LP
 865 .nf
 866 .BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why );
 867 .fi
 868 .IP
 869 Called by a service dispatch routine that refuses to perform
 870 a remote procedure call due to an authentication error.
 871 .LP
 872 .nf
 873 .BI "void svcerr_decode(SVCXPRT *" xprt );
 874 .fi
 875 .IP
 876 Called by a service dispatch routine that cannot successfully
 877 decode its parameters.
 878 See also
 879 .BR svc_getargs ().
 880 .LP
 881 .nf
 882 .BI "void svcerr_noproc(SVCXPRT *" xprt );
 883 .fi
 884 .IP
 885 Called by a service dispatch routine that does not implement
 886 the procedure number that the caller requests.
 887 .LP
 888 .nf
 889 .BI "void svcerr_noprog(SVCXPRT *" xprt );
 890 .fi
 891 .IP
 892 Called when the desired program is not registered with the RPC package.
 893 Service implementors usually do not need this routine.
 894 .LP
 895 .nf
 896 .BI "void svcerr_progvers(SVCXPRT *" xprt );
 897 .fi
 898 .IP
 899 Called when the desired version of a program is not registered
 900 with the RPC package.
 901 Service implementors usually do not need this routine.
 902 .LP
 903 .nf
 904 .BI "void svcerr_systemerr(SVCXPRT *" xprt );
 905 .fi
 906 .IP
 907 Called by a service dispatch routine when it detects a system
 908 error not covered by any particular protocol.
 909 For example, if a service can no longer allocate storage,
 910 it may call this routine.
 911 .LP
 912 .nf
 913 .BI "void svcerr_weakauth(SVCXPRT *" xprt );
 914 .fi
 915 .IP
 916 Called by a service dispatch routine that refuses to perform
 917 a remote procedure call due to insufficient authentication parameters.
 918 The routine calls
 919 .BR "svcerr_auth(xprt, AUTH_TOOWEAK)" .
 920 .LP
 921 .nf
 922 .BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize ,
 923 .BI "                      unsigned int " recvsize );
 924 .fi
 925 .IP
 926 Create a service on top of any open descriptor.
 927 Typically, this descriptor is a connected socket for a stream protocol such
 928 as TCP.
 929 .I sendsize
 930 and
 931 .I recvsize
 932 indicate sizes for the send and receive buffers.
 933 If they are zero, a reasonable default is chosen.
 934 .LP
 935 .nf
 936 .BI "SVCXPRT *svcraw_create(void);"
 937 .fi
 938 .IP
 939 This routine creates a toy RPC
 940 service transport, to which it returns a pointer.
 941 The transport is really a buffer within the process's address space,
 942 so the corresponding RPC client should live in the same address space; see
 943 .BR clntraw_create ().
 944 This routine allows simulation of RPC and acquisition of RPC
 945 overheads (such as round trip times), without any kernel interference.
 946 This routine returns NULL if it fails.
 947 .LP
 948 .nf
 949 .BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size ,
 950 .BI "                       unsigned int " recv_buf_size );
 951 .fi
 952 .IP
 953 This routine creates a TCP/IP-based RPC
 954 service transport, to which it returns a pointer.
 955 The transport is associated with the socket
 956 .IR sock ,
 957 which may be
 958 .BR RPC_ANYSOCK ,
 959 in which case a new socket is created.
 960 If the socket is not bound to a local TCP
 961 port, then this routine binds it to an arbitrary port.
 962 Upon completion,
 963 .I xprt\->xp_sock
 964 is the transport's socket descriptor, and
 965 .I xprt\->xp_port
 966 is the transport's port number.
 967 This routine returns NULL if it fails.
 968 Since TCP-based RPC uses buffered I/O,
 969 users may specify the size of buffers; values of zero
 970 choose suitable defaults.
 971 .LP
 972 .nf
 973 .BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize ,
 974 .BI "                          unsigned int " recosize );
 975 .fi
 976 .IP
 977 This routine creates a UDP/IP-based RPC
 978 service transport, to which it returns a pointer.
 979 The transport is associated with the socket
 980 .IR sock ,
 981 which may be
 982 .BR RPC_ANYSOCK ,
 983 in which case a new socket is created.
 984 If the socket is not bound to a local UDP
 985 port, then this routine binds it to an arbitrary port.
 986 Upon completion,
 987 .I xprt\->xp_sock
 988 is the transport's socket descriptor, and
 989 .I xprt\->xp_port
 990 is the transport's port number.
 991 This routine returns NULL if it fails.
 992 .IP
 993 This allows the user to specify the maximum packet size for sending and
 994 receiving UDP-based RPC messages.
 995 .LP
 996 .nf
 997 .BI "SVCXPRT *svcudp_create(int " sock );
 998 .fi
 999 .IP
1000 This call is equivalent to
1001 .I svcudp_bufcreate(sock,SZ,SZ)
1002 for some default size
1003 .IR SZ .
1004 .LP
1005 .nf
1006 .BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar );
1007 .fi
1008 .IP
1009 Used for encoding RPC reply messages.
1010 This routine is useful for users who wish to generate
1011 RPC-style messages without using the RPC package.
1012 .LP
1013 .nf
1014 .BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp );
1015 .fi
1016 .IP
1017 Used for describing UNIX credentials.
1018 This routine is useful for users
1019 who wish to generate these credentials without using the RPC
1020 authentication package.
1021 .LP
1022 .nf
1023 .BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr );
1024 .fi
1025 .IP
1026 Used for describing RPC call header messages.
1027 This routine is useful for users who wish to generate
1028 RPC-style messages without using the RPC package.
1029 .LP
1030 .nf
1031 .BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg );
1032 .fi
1033 .IP
1034 Used for describing RPC call messages.
1035 This routine is useful for users who wish to generate RPC-style
1036 messages without using the RPC package.
1037 .LP
1038 .nf
1039 .BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap );
1040 .fi
1041 .IP
1042 Used for describing RPC authentication information messages.
1043 This routine is useful for users who wish to generate
1044 RPC-style messages without using the RPC package.
1045 .LP
1046 .nf
1047 .BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs );
1048 .fi
1049 .IP
1050 Used for describing parameters to various
1051 .B portmap
1052 procedures, externally.
1053 This routine is useful for users who wish to generate
1054 these parameters without using the
1055 .B pmap
1056 interface.
1057 .LP
1058 .nf
1059 .BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp );
1060 .fi
1061 .IP
1062 Used for describing a list of port mappings, externally.
1063 This routine is useful for users who wish to generate
1064 these parameters without using the
1065 .B pmap
1066 interface.
1067 .LP
1068 .nf
1069 .BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr );
1070 .fi
1071 .IP
1072 Used for describing RPC reply messages.
1073 This routine is useful for users who wish to generate
1074 RPC-style messages without using the RPC package.
1075 .LP
1076 .nf
1077 .BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg );
1078 .fi
1079 .IP
1080 Used for describing RPC reply messages.
1081 This routine is useful for users who wish to generate
1082 RPC style messages without using the RPC package.
1083 .LP
1084 .nf
1085 .BI "void xprt_register(SVCXPRT *" xprt );
1086 .fi
1087 .IP
1088 After RPC service transport handles are created,
1089 they should register themselves with the RPC service package.
1090 This routine modifies the global variable
1091 .IR svc_fds .
1092 Service implementors usually do not need this routine.
1093 .LP
1094 .nf
1095 .BI "void xprt_unregister(SVCXPRT *" xprt );
1096 .fi
1097 .IP
1098 Before an RPC service transport handle is destroyed,
1099 it should unregister itself with the RPC service package.
1100 This routine modifies the global variable
1101 .IR svc_fds .
1102 Service implementors usually do not need this routine.
1103 .SH SEE ALSO
1104 .\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05
1105 .\" .BR rpc_secure (3),
1106 .BR xdr (3)
1107
1108 The following manuals:
1109 .RS
1110 Remote Procedure Calls: Protocol Specification
1111 .br
1112 Remote Procedure Call Programming Guide
1113 .br
1114 rpcgen Programming Guide
1115 .br
1116 .RE
1117
1118 .IR "RPC: Remote Procedure Call Protocol Specification" ,
1119 RFC\ 1050, Sun Microsystems, Inc.,
1120 USC-ISI.
1121 .SH COLOPHON
1122 This page is part of release 3.68 of the Linux
1123 .I man-pages
1124 project.
1125 A description of the project,
1126 information about reporting bugs,
1127 and the latest version of this page,
1128 can be found at
1129 \%http://www.kernel.org/doc/man\-pages/.