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