1.\" $OpenBSD: rpc.3,v 1.43 2010/10/29 12:43:09 jmc Exp $ 2.\" 3.\" Copyright (c) 1998 Theo de Raadt 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" Copyright (c) 2010, Oracle America, Inc. 27.\" 28.\" Redistribution and use in source and binary forms, with or without 29.\" modification, are permitted provided that the following conditions are 30.\" met: 31.\" 32.\" * Redistributions of source code must retain the above copyright 33.\" notice, this list of conditions and the following disclaimer. 34.\" * Redistributions in binary form must reproduce the above 35.\" copyright notice, this list of conditions and the following 36.\" disclaimer in the documentation and/or other materials 37.\" provided with the distribution. 38.\" * Neither the name of the "Oracle America, Inc." nor the names of its 39.\" contributors may be used to endorse or promote products derived 40.\" from this software without specific prior written permission. 41.\" 42.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 43.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 44.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 45.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 46.\" COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 47.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 48.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 49.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 50.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 51.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 52.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 53.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 54.\" 55.Dd $Mdocdate: October 29 2010 $ 56.Dt RPC 3 57.Os 58.Sh NAME 59.Nm callrpc , 60.Nm clnt_broadcast , 61.Nm clnt_call , 62.Nm clnt_control , 63.Nm clnt_create , 64.Nm clnt_destroy , 65.Nm clnt_freeres , 66.Nm clnt_pcreateerror , 67.Nm clnt_perrno , 68.Nm clnt_perror , 69.Nm clnt_spcreateerror , 70.Nm clnt_sperrno , 71.Nm clnt_sperror , 72.Nm clntraw_create , 73.Nm clnttcp_create , 74.Nm clntudp_bufcreate , 75.Nm clntudp_create , 76.Nm clnt_geterr , 77.Nm get_myaddress , 78.Nm pmap_getmaps , 79.Nm pmap_getport , 80.Nm pmap_rmtcall , 81.Nm pmap_set , 82.Nm pmap_unset , 83.Nm registerrpc , 84.Nm rpc_createerr , 85.Nm svc_destroy , 86.Nm svc_fds , 87.Nm svc_fdset , 88.Nm svc_freeargs , 89.Nm svc_getargs , 90.Nm svc_getcaller , 91.Nm svc_getreq , 92.Nm svc_getreq_common , 93.Nm svc_getreq_poll , 94.Nm svc_getreqset , 95.Nm svc_getreqset2 , 96.Nm svc_register , 97.Nm svc_max_pollfd , 98.Nm svc_pollfd , 99.Nm svc_run , 100.Nm svc_sendreply , 101.Nm svc_unregister , 102.Nm svcerr_auth , 103.Nm svcerr_decode , 104.Nm svcerr_noproc , 105.Nm svcerr_noprog , 106.Nm svcerr_progvers , 107.Nm svcerr_systemerr , 108.Nm svcerr_weakauth , 109.Nm svcfd_create , 110.Nm svcraw_create , 111.Nm svctcp_create , 112.Nm svcudp_create , 113.Nm svcudp_bufcreate , 114.Nm xdr_accepted_reply , 115.Nm xdr_authunix_parms , 116.Nm xdr_callhdr , 117.Nm xdr_callmsg , 118.Nm xdr_opaque_auth , 119.Nm xdr_pmap , 120.Nm xdr_pmaplist , 121.Nm xdr_rejected_reply , 122.Nm xdr_replymsg , 123.Nm xprt_register , 124.Nm xprt_unregister 125.Nd library routines for remote procedure calls 126.Sh SYNOPSIS 127.Fd #include <rpc/rpc.h> 128.Ft int 129.Fn callrpc "char *host" "u_long prognum" "u_long versnum" "u_long procnum" "xdrproc_t inproc" "char *in" "xdrproc_t outproc" "char *out" 130.Ft "enum clnt_stat" 131.Fn clnt_broadcast "u_long prognum" "u_long versnum" "u_long procnum" "xdrproc_t inproc" "char *in" "xdrproc_t outproc" "char *out" "resultproc_t eachresult" 132.Ft "enum clnt_stat" 133.Fn clnt_call "CLIENT *clnt" "u_long procnum" "xdrproc_t inproc" "char *in" "xdrproc_t outproc" "char *out" "struct timeval tout" 134.Ft int 135.Fn clnt_destroy "CLIENT *clnt" 136.Ft CLIENT * 137.Fn clnt_create "char *host" "u_long prog" "u_long vers" "char *proto" 138.Ft bool_t 139.Fn clnt_control "CLIENT *cl" "int req" "char *info" 140.Ft int 141.Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out" 142.Ft void 143.Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp" 144.Ft void 145.Fn clnt_pcreateerror "char *s" 146.Ft void 147.Fn clnt_perrno "enum clnt_stat stat" 148.Ft int 149.Fn clnt_perror "CLIENT *clnt" "char *s" 150.Ft char * 151.Fn clnt_spcreateerror "char *s" 152.Ft char * 153.Fn clnt_sperrno "enum clnt_stat stat" 154.Ft char * 155.Fn clnt_sperror "CLIENT *rpch" "char *s" 156.Ft CLIENT * 157.Fn clntraw_create "u_long prognum" "u_long versnum" 158.Ft CLIENT * 159.Fn clnttcp_create "struct sockaddr_in *addr" "u_long prognum" "u_long versnum" "int *sockp" "u_int sendsz" "u_int recvsz" 160.Ft CLIENT * 161.Fn clntudp_create "struct sockaddr_in *addr" "u_long prognum" "u_long versnum" "struct timeval wait" "int *sockp" 162.Ft CLIENT * 163.Fn clntudp_bufcreate "struct sockaddr_in *addr" "u_long prognum" "u_long versnum" "struct timeval wait" "int *sockp" "unsigned int sendsize" "unsigned int recosize" 164.Ft int 165.Fn get_myaddress "struct sockaddr_in *addr" 166.Ft struct pmaplist * 167.Fn pmap_getmaps "struct sockaddr_in *addr" 168.Ft u_short 169.Fn pmap_getport "struct sockaddr_in *addr" "u_long prognum" "u_long versnum" "u_long protocol" 170.Ft "enum clnt_stat" 171.Fn pmap_rmtcall "struct sockaddr_in *" "u_long prog" "u_long vers" "u_long proc" "xdrproc_t inp" "char *in" "xdrproc_t outp" "char *out" "struct timeval tv" "u_long *portp" 172.Ft int 173.Fn pmap_set "u_long prognum" "u_long versnum" "u_int protocol" "int port" 174.Ft int 175.Fn pmap_unset "u_long prognum" "u_long versnum" 176.Ft int 177.Fn registerrpc "u_long prognum" "u_long versnum" "u_long procnum" "char *(*procname)() " "xdrproc_t inproc" "xdrproc_t outproc" 178.Ft struct rpc_createerr 179.Fa rpc_createerr ; 180.Ft int 181.Fn svc_destroy "SVCXPRT *xprt" 182.Ft struct pollfd * 183.Fa svc_pollfd ; 184.Ft int 185.Fa svc_max_pollfd ; 186.Ft fd_set 187.Fa svc_fdset ; 188.Ft fd_set 189.Fa *__svc_fdset ; 190.Ft int 191.Fa __svc_fdsetsize ; 192.Ft int 193.Fa svc_fds ; 194.Ft int 195.Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" 196.Ft int 197.Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" 198.Ft struct sockaddr_in * 199.Fn svc_getcaller "SVCXPRT *xprt" 200.Ft int 201.Fn svc_getreq_common "int fd" 202.Ft int 203.Fn svc_getreq_poll "struct pollfd *pfds" "const int pollretval" 204.Ft int 205.Fn svc_getreqset "fd_set *rdfds" 206.Ft int 207.Fn svc_getreqset2 "fd_set *rdfds" "int width" 208.Ft int 209.Fn svc_getreq "int rdfds" 210.Ft int 211.Fn svc_register "SVCXPRT *xprt" "u_long prognum" "u_long versnum" "void (*dispatch)()" "u_long protocol" 212.Ft int 213.Fn svc_run "void" 214.Ft int 215.Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out" 216.Ft void 217.Fn svc_unregister "u_long prognum" "u_long versnum" 218.Ft void 219.Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why" 220.Ft void 221.Fn svcerr_decode "SVCXPRT *xprt" 222.Ft void 223.Fn svcerr_noproc "SVCXPRT *xprt" 224.Ft void 225.Fn svcerr_noprog "SVCXPRT *xprt" 226.Ft void 227.Fn svcerr_progvers "SVCXPRT *xprt" 228.Ft void 229.Fn svcerr_systemerr "SVCXPRT *xprt" 230.Ft void 231.Fn svcerr_weakauth "SVCXPRT *xprt" 232.Ft SVCXPRT * 233.Fn svcraw_create "void" 234.Ft SVCXPRT * 235.Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" 236.Ft SVCXPRT * 237.Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize" 238.Ft SVCXPRT * 239.Fn svcudp_create "int sock" 240.Ft SVCXPRT * 241.Fn svcudp_bufcreate "int sock" "u_int sendsz" "u_int recvsz" 242.Ft bool_t 243.Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar" 244.Ft bool_t 245.Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp" 246.Ft void 247.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr" 248.Ft int 249.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg" 250.Ft int 251.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap" 252.Ft int 253.Fn xdr_pmap "XDR *xdrs" "struct pmap *regs" 254.Ft int 255.Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp" 256.Ft int 257.Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr" 258.Ft int 259.Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg" 260.Ft void 261.Fn xprt_register "SVCXPRT *xprt" 262.Ft void 263.Fn xprt_unregister "SVCXPRT *xprt" 264.Sh DESCRIPTION 265These routines allow C programs to make procedure 266calls on other machines across the network. 267First, the client calls a procedure to send a 268data packet to the server. 269Upon receipt of the packet, the server calls a dispatch routine 270to perform the requested service, and then sends back a 271reply. 272Finally, the procedure call returns to the client. 273.Pp 274.\"Routines that are used for Secure RPC (DES authentication) are described in 275.\".Xr rpc_secure 3 . 276.\"Secure RPC can be used only if DES encryption is available. 277.Fn callrpc 278calls the remote procedure associated with 279.Fa prognum , 280.Fa versnum , 281and 282.Fa procnum 283on the machine, 284.Fa host . 285The parameter 286.Fa in 287is the address of the procedure's argument(s), and 288.Fa out 289is the address of where to place the result(s); 290.Fa inproc 291is used to encode the procedure's parameters, and 292.Fa outproc 293is used to decode the procedure's results. 294This routine returns zero if it succeeds, or the value of 295.Fa enum clnt_stat 296cast to an integer if it fails. 297The routine 298.Fn clnt_perrno 299is handy for translating failure statuses into messages. 300.Pp 301.Sy Warning: 302calling remote procedures with this routine uses UDP/IP 303as a transport; see 304.Fn clntudp_create 305for restrictions. 306You do not have control of timeouts or authentication using 307this routine. 308.Pp 309.Fn clnt_broadcast 310is like 311.Fn callrpc , 312except the call message is broadcast to all locally 313connected broadcast nets. 314Each time it receives a response, this routine calls 315.Fa eachresult , 316whose form is: 317.Bd -literal -offset indent 318.Ft int 319.Fn eachresult "char *out" "struct sockaddr_in *addr" 320.Ed 321.Pp 322where 323.Fa out 324is the same as 325.Fa out 326passed to 327.Fn clnt_broadcast , 328except that the remote procedure's output is decoded there; 329.Fa addr 330points to the address of the machine that sent the results. 331If 332.Fa eachresult 333returns zero, 334.Fn clnt_broadcast 335waits for more replies; otherwise it returns with appropriate 336status. 337.Pp 338.Sy Warning: 339broadcast sockets are limited in size to the 340maximum transfer unit of the data link. 341For Ethernet, this value is 1500 bytes. 342.Pp 343.Fn clnt_call 344is a macro that calls the remote procedure 345.Fa procnum 346associated with the client handle, 347.Fa clnt , 348which is obtained with an RPC client creation routine such as 349.Fn clnt_create . 350The parameter 351.Fa in 352is the address of the procedure's argument(s), and 353.Fa out 354is the address of where to place the result(s); 355.Fa inproc 356is used to encode the procedure's parameters, and 357.Fa outproc 358is used to decode the procedure's results; 359.Fa tout 360is the time allowed for results to come back. 361.Pp 362.Fn clnt_destroy 363is a macro that destroys the client's RPC handle. 364Destruction usually involves deallocation of private data structures, including 365.Fa clnt 366itself. 367Use of 368.Fa clnt 369is undefined after calling 370.Fn clnt_destroy . 371If the RPC library opened the associated socket, it will close it also. 372Otherwise, the socket remains open. 373.Pp 374.Fn clnt_create 375is a generic client creation routine. 376.Fa host 377identifies the name of the remote host where the server 378is located. 379.Fa proto 380indicates which kind of transport protocol to use. 381The currently supported values for this field are 382.Qq udp 383and 384.Qq tcp . 385Default timeouts are set, but can be modified using 386.Fn clnt_control . 387This routine returns 388.Dv NULL 389if it fails. 390.Pp 391.Sy Warning: 392Using UDP has its shortcomings. 393Since UDP-based RPC 394messages can only hold up to 8 Kbytes of encoded data, 395this transport cannot be used for procedures that take 396large arguments or return huge results. 397.Pp 398.Fn clnt_control 399is a macro used to change or retrieve various information 400about a client object. 401.Fa req 402indicates the type of operation, and 403.Fa info 404is a pointer to the information. 405For both UDP and TCP, 406the supported values of 407.Fa req 408and their argument types and what they do are: 409.Bd -literal -offset indent 410CLSET_TIMEOUT struct timeval set total timeout 411CLGET_TIMEOUT struct timeval get total timeout 412.Ed 413.Pp 414.Sy Note: 415if you set the timeout using 416.Fn clnt_control , 417the timeout parameter passed to 418.Fn clnt_call 419will be ignored in all future calls. 420.Bd -literal -offset indent 421CLGET_SERVER_ADDR struct sockaddr_in get server's address 422.Ed 423.Pp 424The following operations are valid for UDP only: 425.Bd -literal -offset indent 426CLSET_RETRY_TIMEOUT struct timeval set the retry timeout 427CLGET_RETRY_TIMEOUT struct timeval get the retry timeout 428.Ed 429.Pp 430The retry timeout is the time that UDP RPC 431waits for the server to reply before 432retransmitting the request. 433.Pp 434.Fn clnt_freeres 435is a macro that frees any data allocated by the RPC/XDR 436system when it decoded the results of an RPC call. 437The parameter 438.Fa out 439is the address of the results, and 440.Fa outproc 441is the XDR routine describing the results. 442This routine returns one if the results were successfully 443freed, 444and zero otherwise. 445.Pp 446.Fn clnt_geterr 447is a macro that copies the error structure out of the client 448handle 449to the structure at address 450.Fa errp . 451.Pp 452.Fn clnt_pcreateerror 453prints a message to standard error indicating 454why a client RPC handle could not be created. 455The message is prepended with string 456.Fa s 457and a colon. 458Used when a 459.Fn clnt_create , 460.Fn clntraw_create , 461.Fn clnttcp_create , 462or 463.Fn clntudp_create 464call fails. 465.Pp 466.Fn clnt_perrno 467prints a message to standard error corresponding 468to the condition indicated by 469.Fa stat . 470Used after 471.Fn callrpc . 472.Pp 473.Fn clnt_perror 474prints a message to standard error indicating why an RPC call failed; 475.Fa clnt 476is the handle used to do the call. 477The message is prepended with string 478.Fa s 479and a colon. 480Used after 481.Fn clnt_call . 482.Pp 483.Fn clnt_spcreateerror 484is like 485.Fn clnt_pcreateerror , 486except that it returns a string 487instead of printing to the standard error. 488.Pp 489.Sy Bugs: 490returns pointer to static data that is overwritten 491on each call. 492.Pp 493.Fn clnt_sperrno 494takes the same arguments as 495.Fn clnt_perrno , 496but instead of sending a message to the standard error 497indicating why an RPC 498call failed, returns a pointer to a string which contains 499the message. 500Unlike 501.Fn clnt_perror , 502it does not append a newline character 503to the end of the message. 504.Pp 505.Fn clnt_sperrno 506is used instead of 507.Fn clnt_perrno 508if the program does not have a standard error (as a program 509running as a server quite likely does not), or if the 510programmer 511does not want the message to be output with 512.Fn printf , 513or if a message format different than that supported by 514.Fn clnt_perrno 515is to be used. 516.Pp 517.Sy Note: 518unlike 519.Fn clnt_sperror 520and 521.Fn clnt_spcreaterror , 522.Fn clnt_sperrno 523returns a pointer to static data, but the 524result will not get overwritten on each call. 525.Pp 526.Fn clnt_sperror 527is like 528.Fn clnt_perror , 529except that (like 530.Fn clnt_sperrno ) 531it returns a string instead of printing to standard error. 532.Pp 533.Sy Bugs: 534returns pointer to static data that is overwritten 535on each call. 536.Pp 537.Fn clntraw_create 538is a routine which creates a toy RPC client for the remote program 539.Fa prognum , 540version 541.Fa versnum . 542The transport used to pass messages to the service is 543actually a buffer within the process's address space, so the 544corresponding RPC server should live in the same address space; see 545.Fn svcraw_create . 546This allows simulation of RPC and acquisition of RPC 547overheads, such as round trip times, without any 548kernel interference. 549This routine returns 550.Dv NULL 551if it fails. 552.Pp 553.Fn clnttcp_create 554is a routine which creates an RPC client for the remote program 555.Fa prognum , 556version 557.Fa versnum ; 558the client uses TCP/IP as a transport. 559The remote program is located at Internet address 560.Fa *addr . 561If 562.Fa addr-\*(Gtsin_port 563is zero, then it is set to the actual port that the remote 564program is listening on (the remote 565.Xr portmap 8 566service is consulted for this information). 567The parameter 568.Fa sockp 569is a socket; if it is 570.Fa RPC_ANYSOCK , 571then this routine opens a new one and sets 572.Fa sockp . 573Since TCP-based RPC uses buffered I/O, 574the user may specify the size of the send and receive buffers 575with the parameters 576.Fa sendsz 577and 578.Fa recvsz ; 579values of zero choose suitable defaults. 580This routine returns 581.Dv NULL 582if it fails. 583.Pp 584.Fn clntudp_create 585is a routine which creates an RPC client for the remote program 586.Fa prognum , 587on 588.Fa versnum ; 589the client uses use UDP/IP as a transport. 590The remote program is located at Internet address 591.Fa addr . 592If 593.Fa addr-\*(Gtsin_port 594is zero, then it is set to actual port that the remote 595program is listening on (the remote 596.Xr portmap 8 597service is consulted for this information). 598The parameter 599.Fa sockp 600is a socket; if it is 601.Fa RPC_ANYSOCK , 602then this routine opens a new one and sets 603.Fa sockp . 604The UDP transport resends the call message in intervals of 605.Fa wait 606time until a response is received or until the call times 607out. 608The total time for the call to time out is specified by 609.Fn clnt_call . 610This routine returns 611.Dv NULL 612if it fails. 613.Pp 614.Fn clntudp_bufcreate 615is like 616.Fn clntudp_create , 617except that it allows the user to specify the maximum packet size for sending 618and receiving UDP-based RPC 619messages instead of using the default size limit of 8800 bytes. 620.Pp 621.Fn get_myaddress 622stuffs the machine's IP address into 623.Fa *addr , 624without consulting the library routines that deal with 625.Pa /etc/hosts . 626The port number is always set to 627.Fa htons(PMAPPORT) . 628Returns zero on success, non-zero on failure. 629.Pp 630.Fn pmap_getmaps 631is a function interface to the 632.Xr portmap 8 633service, which returns a list of the current RPC program-to-port mappings 634on the host located at IP address 635.Fa *addr . 636This routine can return 637.Dv NULL . 638The command 639.Qq Li rpcinfo \-p 640uses this routine. 641.Pp 642.Fn pmap_getport 643is a user interface to the 644.Xr portmap 8 645service, which returns the port number 646on which waits a service that supports program number 647.Fa prognum , 648version 649.Fa versnum , 650and speaks the transport protocol associated with 651.Fa protocol . 652The value of 653.Fa protocol 654is most likely 655.Dv IPPROTO_UDP 656or 657.Dv IPPROTO_TCP . 658A return value of zero means that the mapping does not exist 659or that 660the RPC system failured to contact the remote 661.Xr portmap 8 662service. 663In the latter case, the global variable 664.Fn rpc_createerr 665contains the RPC status. 666.Pp 667.Fn pmap_rmtcall 668is a user interface to the 669.Xr portmap 8 670service, which instructs 671.Xr portmap 8 672on the host at IP address 673.Fa *addr 674to make an RPC call on your behalf to a procedure on that host. 675The parameter 676.Fa *portp 677will be modified to the program's port number if the 678procedure 679succeeds. 680The definitions of other parameters are discussed in 681.Fn callrpc 682and 683.Fn clnt_call . 684This procedure should be used for a 685.Qq ping 686and nothing else. 687See also 688.Fn clnt_broadcast . 689.Pp 690.Fn pmap_set 691is a user interface to the 692.Xr portmap 8 693service, which establishes a mapping between the triple 694.Fa [ prognum , versnum , protocol ] 695and 696.Fa port 697on the machine's 698.Xr portmap 8 699service. 700The value of 701.Fa protocol 702is most likely 703.Dv IPPROTO_UDP 704or 705.Dv IPPROTO_TCP . 706This routine returns one if it succeeds, zero otherwise. 707Automatically done by 708.Fn svc_register . 709.Pp 710.Fn pmap_unset 711is a user interface to the 712.Xr portmap 8 713service, which destroys all mapping between the triple 714.Fa [ prognum , versnum , * ] 715and 716.Fa ports 717on the machine's 718.Xr portmap 8 719service. 720This routine returns one if it succeeds, zero otherwise. 721.Pp 722.Fn registerrpc 723will register a procedure 724.Fa procname 725with the RPC service package. 726If a request arrives for program 727.Fa prognum , 728version 729.Fa versnum , 730and procedure 731.Fa procnum , 732.Fa procname 733is called with a pointer to its parameter(s); 734.Fa procname 735should return a pointer to its static result(s); 736.Fa inproc 737is used to decode the parameters while 738.Fa outproc 739is used to encode the results. 740This routine returns zero if the registration succeeded, \-1 741otherwise. 742.Pp 743.Sy Warning: 744remote procedures registered in this form 745are accessed using the UDP/IP transport; see 746.Fn svcudp_create 747for restrictions. 748.Pp 749.Fa rpc_createerr 750is a global variable whose value is set by any RPC client creation routine 751that does not succeed. 752Use the routine 753.Fn clnt_pcreateerror 754to print the reason why. 755.Pp 756.Fn svc_destroy 757is a macro that destroys the RPC service transport handle, 758.Fa xprt . 759Destruction usually involves deallocation 760of private data structures, including 761.Fa xprt 762itself. 763Use of 764.Fa xprt 765is undefined after calling this routine. 766.Pp 767.Fa svc_pollfd 768is a global variable reflecting the RPC service side's 769read file descriptor array. 770This variable is only of interest if service implementors do not call 771.Fn svc_run , 772but rather do their own asynchronous event processing. 773This variable is read-only, and it may change after calls to 774.Fn svc_getreq_poll 775or any creation routines. 776Do not pass it directly to 777.Xr poll 2 ! 778Instead, make a copy and pass that instead. 779.Pp 780.Fa svc_max_pollfd 781is a global variable containing the maximum length of the 782.Fa svc_pollfd 783array. 784.Fa svc_max_pollfd 785is not a hard limit; it will grow automatically as needed. 786This variable is read-only, and it may change after calls to 787.Fn svc_getreq_poll 788or any creation routines. 789The purpose of 790.Fa svc_max_pollfd 791is to allow a service implementor to make a copy of 792.Fa svc_pollfd 793that may in turn be passed to 794.Xr poll 2 . 795.Pp 796.Fa __svc_fdset 797and 798.Fa __svc_fdsetsize 799are global variables reflecting the RPC service side's 800read file descriptor bit mask. 801.Fa __svc_fdsetsize 802is a count of the number of checkable bits in 803.Fa __svc_fdset , 804and can expand to the full size that 805.Xr select 2 806supports, hence exceeding 807.Fa FD_SETSIZE 808if required. 809These variables are only of interest 810if service implementors do not call 811.Fn svc_run , 812but rather do their own asynchronous event processing. 813This variable is read-only, and it may change after calls to 814.Fn svc_getreqset 815or any creation routines. 816Do not pass its address to 817.Xr select 2 ! 818Instead, pass the address of a copy. 819These variables are considered obsolete; new programs should use 820.Fa svc_pollfd 821and 822.Fa svc_max_pollfd 823instead. 824.Pp 825.Fa svc_fdset 826is similar to 827.Fa __svc_fdset 828but limited to 829.Fa FD_SETSIZE 830descriptors. 831This is only of interest 832if service implementors do not call 833.Fn svc_run , 834but rather do their own asynchronous event processing. 835This variable is read-only, and it may change after calls to 836.Fn svc_getreqset 837or any creation routines. 838Do not pass it directly to 839.Xr select 2 ! 840Instead, make a copy and pass that instead. 841.Pp 842Additionally, note that if the process has descriptor limits 843which are extended beyond 844.Fa FD_SETSIZE , 845this variable will only be usable for the first 846.Fa FD_SETSIZE 847descriptors. 848This variable is considered obsolete; new programs should use 849.Fa svc_pollfd 850which does not have this limit. 851.Pp 852.Fa svc_fds 853is similar to 854.Fa svc_fedset , 855but limited to 32 descriptors. 856This interface is obsoleted by 857.Fa svc_fdset 858and is included for source compatibility only. 859.Pp 860.Fn svc_freeargs 861is a macro that frees any data allocated by the RPC/XDR 862system when it decoded the arguments to a service procedure 863using 864.Fn svc_getargs . 865This routine returns 1 if the results were successfully 866freed, 867and zero otherwise. 868.Pp 869.Fn svc_getargs 870is a macro that decodes the arguments of an RPC request 871associated with the RPC service transport handle, 872.Fa xprt . 873The parameter 874.Fa in 875is the address where the arguments will be placed; 876.Fa inproc 877is the XDR routine used to decode the arguments. 878This routine returns one if decoding succeeds, and zero 879otherwise. 880.Pp 881.Fn svc_getcaller 882is the approved way of getting the network address of the caller 883of a procedure associated with the RPC service transport handle, 884.Fa xprt . 885.Pp 886.Fn svc_getreq_common 887is called to handle a request on the given socket. 888It is used internally by 889.Fn svc_getreq_poll , 890.Fn svc_getreqset , 891.Fn svc_getreqset2 , 892and 893.Fn svc_getreq . 894.Pp 895.Fn svc_getreq_poll 896is a routine which is only of interest if a service implementor 897does not call 898.Fn svc_run , 899but instead implements custom asynchronous event processing. 900It is called when the 901.Xr poll 2 902system call has determined that an RPC request has arrived on some RPC 903.Fa socket(s) ; 904.Fa pollretval 905is the value returned by 906.Xr poll 2 907and 908.Fa pfds 909is the array of 910.Fa pollfd 911structures passed to 912.Xr poll 2 . 913The routine returns when all sockets described by 914.Fa pollfd 915have been serviced. 916.Pp 917.Fn svc_getreqset 918is a routine which is only of interest if a service implementor 919does not call 920.Fn svc_run , 921but instead implements custom asynchronous event processing. 922It is called when the 923.Xr select 2 924system call has determined that an RPC request has arrived on some RPC 925.Fa socket(s) ; 926.Fa rdfds 927is the resultant read file descriptor bit mask. 928The routine returns when all sockets associated with the 929value of 930.Fa rdfds 931have been serviced. 932.Pp 933.Fn svc_getreqset2 934is a non-standard routine which is only of interest if a service 935implementor does not call 936.Fn svc_run , 937but instead implements custom asynchronous event processing. 938It is called when the 939.Xr select 2 940system call has determined that an RPC request has arrived on some RPC 941.Fa socket(s) ; 942.Fa rdfds 943is the resultant read file descriptor bit mask. 944The routine returns when all sockets associated with the 945value of 946.Fa rdfds 947have been serviced. 948This interface is non-portable, but provided for applications which 949need to deal with large fd_set sizes. 950.Pp 951.Fn svc_getreq 952is similar to 953.Fa svc_getreqset , 954but limited to 32 descriptors. 955This interface is obsoleted by 956.Fa svc_getreq_poll 957and 958.Fa svc_getreqset . 959.Pp 960.Fn svc_register 961associates 962.Fa prognum 963and 964.Fa versnum 965with the service dispatch procedure, 966.Fa dispatch . 967If 968.Fa protocol 969is zero, the service is not registered with the 970.Xr portmap 8 971service. 972If 973.Fa protocol 974is non-zero, then a mapping of the triple 975.Fa [ prognum , versnum , protocol ] 976to 977.Fa xprt-\*(Gtxp_port 978is established with the local 979.Xr portmap 8 980service (generally 981.Fa protocol 982is zero, 983.Dv IPPROTO_UDP 984or 985.Dv IPPROTO_TCP ) . 986The procedure 987.Fa dispatch 988has the following form: 989.Ft int 990.Fn dispatch "struct svc_req *request" "SVCXPRT *xprt" 991The 992.Fn svc_register 993routine returns one if it succeeds, and zero otherwise. 994.Pp 995.Fn svc_run 996never returns. 997It waits for RPC requests to arrive, and calls the appropriate service 998procedure using 999.Fn svc_getreq_poll 1000when one arrives. 1001This procedure is usually waiting for a 1002.Xr poll 2 1003system call to return. 1004.Pp 1005.Fn svc_sendreply 1006is called by an RPC service's dispatch routine to send the results of a 1007remote procedure call. 1008The parameter 1009.Fa xprt 1010is the request's associated transport handle; 1011.Fa outproc 1012is the XDR routine which is used to encode the results; and 1013.Fa out 1014is the address of the results. 1015This routine returns one if it succeeds, zero otherwise. 1016.Pp 1017.Fn svc_unregister 1018removes all mapping of the double 1019.Fa [ prognum , versnum ] 1020to dispatch routines, and of the triple 1021.Fa [ prognum , versnum , * ] 1022to port number. 1023.Pp 1024.Fn svcerr_auth 1025is called by a service dispatch routine that refuses to perform 1026a remote procedure call due to an authentication error. 1027.Pp 1028.Fn svcerr_decode 1029is called by a service dispatch routine that cannot successfully 1030decode its parameters. 1031See also 1032.Fn svc_getargs . 1033.Pp 1034.Fn svcerr_noproc 1035is called by a service dispatch routine that does not implement 1036the procedure number that the caller requests. 1037.Pp 1038.Fn svcerr_noprog 1039is called when the desired program is not registered with the RPC 1040package. 1041Service implementors usually do not need this routine. 1042.Pp 1043.Fn svcerr_progvers 1044is called when the desired version of a program is not registered 1045with the RPC package. 1046Service implementors usually do not need this routine. 1047.Pp 1048.Fn svcerr_systemerr 1049is called by a service dispatch routine when it detects a system 1050error 1051not covered by any particular protocol. 1052For example, if a service can no longer allocate storage, 1053it may call this routine. 1054.Pp 1055.Fn svcerr_weakauth 1056is called by a service dispatch routine that refuses to perform 1057a remote procedure call due to insufficient 1058authentication parameters. 1059The routine calls 1060.Fa "svcerr_auth(xprt, AUTH_TOOWEAK)" . 1061.Pp 1062.Fn svcraw_create 1063is a routine which creates a toy RPC 1064service transport, to which it returns a pointer. 1065The transport is really a buffer within the process's address space, 1066so the corresponding RPC client should live in the same 1067address space; 1068see 1069.Fn clntraw_create . 1070This routine allows simulation of RPC and acquisition of RPC 1071overheads (such as round trip times), without any kernel 1072interference. 1073This routine returns 1074.Dv NULL 1075if it fails. 1076.Pp 1077.Fn svctcp_create 1078is a routine which creates a TCP/IP-based RPC 1079service transport, to which it returns a pointer. 1080The transport is associated with the socket 1081.Fa sock , 1082which may be 1083.Fa RPC_ANYSOCK , 1084in which case a new socket is created. 1085If the socket is not bound to a local TCP 1086port, then this routine binds it to an arbitrary port. 1087Upon completion, 1088.Fa xprt-\*(Gtxp_sock 1089is the transport's socket descriptor, and 1090.Fa xprt-\*(Gtxp_port 1091is the transport's port number. 1092This routine returns 1093.Dv NULL 1094if it fails. 1095Since TCP-based RPC uses buffered I/O, 1096users may specify the size of buffers; values of zero 1097choose suitable defaults. 1098.Pp 1099.Fn svcfd_create 1100will create a service on top of any open descriptor. 1101Typically, this descriptor is a connected socket for a stream protocol such 1102as TCP. 1103.Fa sendsize 1104and 1105.Fa recvsize 1106indicate sizes for the send and receive buffers. 1107If they are zero, a reasonable default is chosen. 1108.Pp 1109.Fn svcudp_create 1110is a routine which creates a UDP/IP-based RPC 1111service transport, to which it returns a pointer. 1112The transport is associated with the socket 1113.Fa sock , 1114which may be 1115.Fa RPC_ANYSOCK , 1116in which case a new socket is created. 1117If the socket is not bound to a local UDP 1118port, then this routine binds it to an arbitrary port. 1119Upon completion, 1120.Fa xprt-\*(Gtxp_sock 1121is the transport's socket descriptor, and 1122.Fa xprt-\*(Gtxp_port 1123is the transport's port number. 1124This routine returns 1125.Dv NULL 1126if it fails. 1127.Pp 1128.Fn svcudp_bufcreate 1129is like 1130.Fn svcudp_create , 1131except that it allows the user to specify the maximum packet size for sending 1132and receiving UDP-based RPC 1133messages instead of using the default size limit of 8800 bytes. 1134.Pp 1135.Fn xdr_accepted_reply 1136is used for encoding RPC reply messages. 1137This routine is useful for users who wish to generate RPC-style 1138messages without using the RPC package. 1139.Pp 1140.Fn xdr_authunix_parms 1141is used for describing 1142.Ux 1143credentials. 1144This routine is useful for users 1145who wish to generate these credentials without using the RPC 1146authentication package. 1147.Pp 1148.Fn xdr_callhdr 1149is used for describing RPC call header messages. 1150This routine is useful for users who wish to generate RPC-style 1151messages without using the RPC package. 1152.Pp 1153.Fn xdr_callmsg 1154is used for describing RPC call messages. 1155This routine is useful for users who wish to generate RPC-style 1156messages without using the RPC package. 1157.Pp 1158.Fn xdr_opaque_auth 1159is used for describing RPC authentication information messages. 1160This routine is useful for users who wish to generate RPC-style 1161messages without using the RPC package. 1162.Pp 1163.Fn xdr_pmap 1164is used for describing parameters to various 1165.Xr portmap 8 1166procedures, externally. 1167This routine is useful for users who wish to generate 1168these parameters without using the pmap interface. 1169.Pp 1170.Fn xdr_pmaplist 1171is used for describing a list of port mappings, externally. 1172This routine is useful for users who wish to generate 1173these parameters without using the pmap interface. 1174.Pp 1175.Fn xdr_rejected_reply 1176is used for describing RPC reply messages. 1177This routine is useful for users who wish to generate RPC-style 1178messages without using the RPC package. 1179.Pp 1180.Fn xdr_replymsg 1181is used for describing RPC reply messages. 1182This routine is useful for users who wish to generate RPC-style 1183messages without using the RPC package. 1184.Pp 1185.Fn xprt_register 1186is used to register transport handles. 1187After RPC service transport handles are created, 1188they should register themselves with the RPC service package. 1189This routine modifies the global variables 1190.Fa svc_pollfd , 1191.Fa svc_fdset , 1192.Fa __svc_fdset 1193and may modify 1194.Fa svc_max_pollfd 1195and 1196.Fa __svc_fdsetsize . 1197Service implementors usually do not need this routine. 1198.Pp 1199.Fn xprt_unregister 1200is used to unregister a transport handle. 1201Before an RPC service transport handle is destroyed, 1202it should unregister itself with the RPC service package. 1203This routine modifies the global variable 1204.Fa svc_pollfd , 1205.Fa svc_fdset , 1206and 1207.Fa __svc_fdset . 1208Service implementors usually do not need this routine. 1209.Sh SEE ALSO 1210.\"Xr rpc_secure 3 , 1211.Xr rpcgen 1 , 1212.Xr poll 2 , 1213.Xr select 2 , 1214.Xr getrpcent 3 , 1215.Xr getrpcport 3 , 1216.Xr rpcauth 3 , 1217.Xr xdr 3 , 1218.Xr rpc 5 , 1219.Xr portmap 8 1220.Pp 1221The following manuals: 1222.Rs 1223.%A "Sun Microsystems, Inc." 1224.%T "Remote Procedure Calls: Protocol Specification" 1225.Re 1226.Rs 1227.%A "Sun Microsystems, Inc." 1228.%T "Remote Procedure Call Programming Guide" 1229.Re 1230.Rs 1231.%A "Sun Microsystems, Inc." 1232.%T "rpcgen Programming Guide" 1233.Re 1234.Rs 1235.%A "Sun Microsystems, Inc." 1236.%T "RPC: Remote Procedure Call Protocol Specification" 1237.Re 1238.Rs 1239.%A "Sun Microsystems, Inc." 1240.%D "June 1988" 1241.%T "RFC 1057" 1242.Re 1243