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