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