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