1.\" $NetBSD: rpc_soc.3,v 1.2 2000/06/07 13:39:43 simonb Exp $ 2.\" 3.Dd February 16, 1988 4.Dt RPC_SOC 3 5.Os 6.Sh NAME 7.Nm rpc_soc , 8.Nm auth_destroy , 9.Nm authnone_create , 10.Nm authunix_create , 11.Nm authunix_create_default , 12.Nm callrpc , 13.Nm clnt_broadcast , 14.Nm clnt_call , 15.Nm clnt_control , 16.Nm clnt_create , 17.Nm clnt_destroy , 18.Nm clnt_freeres , 19.Nm clnt_geterr , 20.Nm clnt_pcreateerror , 21.Nm clnt_perrno , 22.Nm clnt_perror , 23.Nm clnt_spcreateerror , 24.Nm clnt_sperrno , 25.Nm clnt_sperror , 26.Nm clntraw_create , 27.Nm clnttcp_create , 28.Nm clntudp_bufcreate , 29.Nm clntudp_create , 30.Nm clntunix_create , 31.Nm get_myaddress , 32.Nm pmap_getmaps , 33.Nm pmap_getport , 34.Nm pmap_rmtcall , 35.Nm pmap_set , 36.Nm pmap_unset , 37.Nm registerrpc , 38.Nm rpc_createerr , 39.Nm svc_destroy , 40.Nm svc_fds , 41.Nm svc_fdset , 42.Nm svc_getargs , 43.Nm svc_getcaller , 44.Nm svc_getreq , 45.Nm svc_getreqset , 46.Nm svc_register , 47.Nm svc_run , 48.Nm svc_sendreply , 49.Nm svc_unregister , 50.Nm svcerr_auth , 51.Nm svcerr_decode , 52.Nm svcerr_noproc , 53.Nm svcerr_noprog , 54.Nm svcerr_progvers , 55.Nm svcerr_systemerr , 56.Nm svcerr_weakauth , 57.Nm svcfd_create , 58.Nm svcunixfd_create , 59.Nm svcraw_create , 60.Nm svcunix_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 LIBRARY 74.Lb libc 75.Sh SYNOPSIS 76.In rpc/rpc.h 77.Pp 78See 79.Sx DESCRIPTION 80for function declarations. 81.Sh DESCRIPTION 82.Bf -symbolic 83The 84.Fn svc_* 85and 86.Fn clnt_* 87functions described in this page are the old, TS-RPC 88interface to the XDR and RPC library, and exist for backward compatibility. 89The new interface is described in the pages 90referenced from 91.Xr rpc 3 . 92.Ef 93.Pp 94These routines allow C programs to make procedure 95calls on other machines across the network. 96First, the client calls a procedure to send a 97data packet to the server. 98Upon receipt of the packet, the server calls a dispatch routine 99to perform the requested service, and then sends back a 100reply. 101Finally, the procedure call returns to the client. 102.Pp 103Routines that are used for Secure 104.Tn RPC ( DES 105authentication) are described in 106.Xr rpc_secure 3 . 107Secure 108.Tn RPC 109can be used only if 110.Tn DES 111encryption is available. 112.Pp 113.Bl -tag -width indent -compact 114.It Xo 115.Ft void 116.Xc 117.It Xo 118.Fn auth_destroy "AUTH *auth" 119.Xc 120.Pp 121A macro that destroys the authentication information associated with 122.Fa auth . 123Destruction usually involves deallocation of private data 124structures. 125The use of 126.Fa auth 127is undefined after calling 128.Fn auth_destroy . 129.Pp 130.It Xo 131.Ft "AUTH *" 132.Xc 133.It Xo 134.Fn authnone_create 135.Xc 136.Pp 137Create and return an 138.Tn RPC 139authentication handle that passes nonusable authentication 140information with each remote procedure call. 141This is the 142default authentication used by 143.Tn RPC . 144.Pp 145.It Xo 146.Ft "AUTH *" 147.Xc 148.It Xo 149.Fn authunix_create "char *host" "u_int uid" "u_int gid" "int len" "u_int *aup_gids" 150.Xc 151.Pp 152Create and return an 153.Tn RPC 154authentication handle that contains 155.Ux 156authentication information. 157The 158.Fa host 159argument 160is the name of the machine on which the information was 161created; 162.Fa uid 163is the user's user ID; 164.Fa gid 165is the user's current group ID; 166.Fa len 167and 168.Fa aup_gids 169refer to a counted array of groups to which the user belongs. 170It is easy to impersonate a user. 171.Pp 172.It Xo 173.Ft "AUTH *" 174.Xc 175.It Xo 176.Fn authunix_create_default 177.Xc 178.Pp 179Calls 180.Fn authunix_create 181with the appropriate arguments. 182.Pp 183.It Xo 184.Ft int 185.Fo callrpc 186.Fa "char *host" 187.Fa "u_long prognum" 188.Fa "u_long versnum" 189.Fa "u_long procnum" 190.Fa "xdrproc_t inproc" 191.Fa "void *in" 192.Fa "xdrproc_t outproc" 193.Fa "void *out" 194.Fc 195.Xc 196.Pp 197Call the remote procedure associated with 198.Fa prognum , 199.Fa versnum , 200and 201.Fa procnum 202on the machine 203.Fa host . 204The 205.Fa in 206argument 207is the address of the procedure's argument(s), and 208.Fa out 209is the address of where to place the result(s); 210.Fa inproc 211is used to encode the procedure's arguments, and 212.Fa outproc 213is used to decode the procedure's results. 214This routine returns zero if it succeeds, or the value of 215.Vt "enum clnt_stat" 216cast to an integer if it fails. 217The routine 218.Fn clnt_perrno 219is handy for translating failure statuses into messages. 220.Pp 221Warning: calling remote procedures with this routine 222uses 223.Tn UDP/IP 224as a transport; see 225.Fn clntudp_create 226for restrictions. 227You do not have control of timeouts or authentication using 228this routine. 229.Pp 230.It Xo 231.Ft "enum clnt_stat" 232.Xc 233.It Xo 234.Fo clnt_broadcast 235.Fa "u_long prognum" 236.Fa "u_long versnum" 237.Fa "u_long procnum" 238.Fa "xdrproc_t inproc" 239.Fa "char *in" 240.Fa "xdrproc_t outproc" 241.Fa "char *out" 242.Fa "bool_t (*eachresult)(caddr_t, struct sockaddr_in *)" 243.Fc 244.Xc 245.Pp 246Like 247.Fn callrpc , 248except the call message is broadcast to all locally 249connected broadcast nets. 250Each time it receives a 251response, this routine calls 252.Fn eachresult , 253whose form is: 254.Bd -ragged -offset indent 255.Ft bool_t 256.Fn eachresult "caddr_t out" "struct sockaddr_in *addr" 257.Ed 258.Pp 259where 260.Fa out 261is the same as 262.Fa out 263passed to 264.Fn clnt_broadcast , 265except that the remote procedure's output is decoded there; 266.Fa addr 267points to the address of the machine that sent the results. 268If 269.Fn eachresult 270returns zero, 271.Fn clnt_broadcast 272waits for more replies; otherwise it returns with appropriate 273status. 274.Pp 275Warning: broadcast sockets are limited in size to the 276maximum transfer unit of the data link. 277For ethernet, 278this value is 1500 bytes. 279.Pp 280.It Xo 281.Ft "enum clnt_stat" 282.Xc 283.It Xo 284.Fo clnt_call 285.Fa "CLIENT *clnt" 286.Fa "u_long procnum" 287.Fa "xdrproc_t inproc" 288.Fa "char *in" 289.Fa "xdrproc_t outproc" 290.Fa "char *out" 291.Fa "struct timeval tout" 292.Fc 293.Xc 294.Pp 295A macro that calls the remote procedure 296.Fa procnum 297associated with the client handle, 298.Fa clnt , 299which is obtained with an 300.Tn RPC 301client creation routine such as 302.Fn clnt_create . 303The 304.Fa in 305argument 306is the address of the procedure's argument(s), and 307.Fa out 308is the address of where to place the result(s); 309.Fa inproc 310is used to encode the procedure's arguments, and 311.Fa outproc 312is used to decode the procedure's results; 313.Fa tout 314is the time allowed for results to come back. 315.Pp 316.It Xo 317.Ft void 318.Fn clnt_destroy "CLIENT *clnt" 319.Xc 320.Pp 321A macro that destroys the client's 322.Tn RPC 323handle. 324Destruction usually involves deallocation 325of private data structures, including 326.Fa clnt 327itself. 328Use of 329.Fa clnt 330is undefined after calling 331.Fn clnt_destroy . 332If the 333.Tn RPC 334library opened the associated socket, it will close it also. 335Otherwise, the socket remains open. 336.Pp 337.It Xo 338.Ft CLIENT * 339.Xc 340.It Xo 341.Fn clnt_create "char *host" "u_long prog" "u_long vers" "char *proto" 342.Xc 343.Pp 344Generic client creation routine. 345The 346.Fa host 347argument 348identifies the name of the remote host where the server 349is located. 350The 351.Fa proto 352argument 353indicates which kind of transport protocol to use. 354The 355currently supported values for this field are 356.Qq Li udp 357and 358.Qq Li tcp . 359Default timeouts are set, but can be modified using 360.Fn clnt_control . 361.Pp 362Warning: Using 363.Tn UDP 364has its shortcomings. 365Since 366.Tn UDP Ns \-based 367.Tn RPC 368messages can only hold up to 8 Kbytes of encoded data, 369this transport cannot be used for procedures that take 370large arguments or return huge results. 371.Pp 372.It Xo 373.Ft bool_t 374.Xc 375.It Xo 376.Fn clnt_control "CLIENT *cl" "u_int req" "char *info" 377.Xc 378.Pp 379A macro used to change or retrieve various information 380about a client object. 381The 382.Fa req 383argument 384indicates the type of operation, and 385.Fa info 386is a pointer to the information. 387For both 388.Tn UDP 389and 390.Tn TCP , 391the supported values of 392.Fa req 393and their argument types and what they do are: 394.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in" 395.It Dv CLSET_TIMEOUT Ta 396.Vt "struct timeval" Ta "set total timeout" 397.It Dv CLGET_TIMEOUT Ta 398.Vt "struct timeval" Ta "get total timeout" 399.El 400.Pp 401Note: if you set the timeout using 402.Fn clnt_control , 403the timeout argument passed to 404.Fn clnt_call 405will be ignored in all future calls. 406.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in" 407.It Dv CLGET_SERVER_ADDR Ta 408.Vt "struct sockaddr_in" Ta "get server's address" 409.El 410.Pp 411The following operations are valid for 412.Tn UDP 413only: 414.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in" 415.It Dv CLSET_RETRY_TIMEOUT Ta 416.Vt "struct timeval" Ta "set the retry timeout" 417.It Dv CLGET_RETRY_TIMEOUT Ta 418.Vt "struct timeval" Ta "get the retry timeout" 419.El 420.Pp 421The retry timeout is the time that 422.Tn "UDP RPC" 423waits for the server to reply before 424retransmitting the request. 425.Pp 426.It Xo 427.Ft bool_t 428.Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out" 429.Xc 430.Pp 431A macro that frees any data allocated by the 432.Tn RPC/XDR 433system when it decoded the results of an 434.Tn RPC 435call. 436The 437.Fa out 438argument 439is the address of the results, and 440.Fa outproc 441is the 442.Tn XDR 443routine describing the results. 444This routine returns one if the results were successfully 445freed, 446and zero otherwise. 447.Pp 448.It Xo 449.Ft void 450.Xc 451.It Xo 452.Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp" 453.Xc 454.Pp 455A macro that copies the error structure out of the client 456handle 457to the structure at address 458.Fa errp . 459.Pp 460.It Xo 461.Ft void 462.Xc 463.It Xo 464.Fn clnt_pcreateerror "char *s" 465.Xc 466.Pp 467prints a message to standard error indicating 468why a client 469.Tn RPC 470handle could not be created. 471The message is prepended with string 472.Fa s 473and a colon. 474A newline is appended at the end of the message. 475Used when a 476.Fn clnt_create , 477.Fn clntraw_create , 478.Fn clnttcp_create , 479or 480.Fn clntudp_create 481call fails. 482.Pp 483.It Xo 484.Ft void 485.Xc 486.It Xo 487.Fn clnt_perrno "enum clnt_stat stat" 488.Xc 489.Pp 490Print a message to standard error corresponding 491to the condition indicated by 492.Fa stat . 493A newline is appended at the end of the message. 494Used after 495.Fn callrpc . 496.Pp 497.It Xo 498.Ft void 499.Fn clnt_perror "CLIENT *clnt" "char *s" 500.Xc 501.Pp 502Print a message to standard error indicating why an 503.Tn RPC 504call failed; 505.Fa clnt 506is the handle used to do the call. 507The message is prepended with string 508.Fa s 509and a colon. 510A newline is appended at the end of the message. 511Used after 512.Fn clnt_call . 513.Pp 514.It Xo 515.Ft "char *" 516.Xc 517.It Xo 518.Fn clnt_spcreateerror "char *s" 519.Xc 520.Pp 521Like 522.Fn clnt_pcreateerror , 523except that it returns a string 524instead of printing to the standard error. 525.Pp 526Bugs: returns pointer to static data that is overwritten 527on each call. 528.Pp 529.It Xo 530.Ft "char *" 531.Xc 532.It Xo 533.Fn clnt_sperrno "enum clnt_stat stat" 534.Xc 535.Pp 536Take the same arguments as 537.Fn clnt_perrno , 538but instead of sending a message to the standard error 539indicating why an 540.Tn RPC 541call failed, return a pointer to a string which contains 542the message. 543.Pp 544The 545.Fn clnt_sperrno 546function 547is used instead of 548.Fn clnt_perrno 549if the program does not have a standard error (as a program 550running as a server quite likely does not), or if the 551programmer 552does not want the message to be output with 553.Fn printf , 554or if a message format different from that supported by 555.Fn clnt_perrno 556is to be used. 557.Pp 558Note: unlike 559.Fn clnt_sperror 560and 561.Fn clnt_spcreateerror , 562.Fn clnt_sperrno 563returns pointer to static data, but the 564result will not get overwritten on each call. 565.Pp 566.It Xo 567.Ft "char *" 568.Xc 569.It Xo 570.Fn clnt_sperror "CLIENT *rpch" "char *s" 571.Xc 572.Pp 573Like 574.Fn clnt_perror , 575except that (like 576.Fn clnt_sperrno ) 577it returns a string instead of printing to standard error. 578.Pp 579Bugs: returns pointer to static data that is overwritten 580on each call. 581.Pp 582.It Xo 583.Ft "CLIENT *" 584.Xc 585.It Xo 586.Fn clntraw_create "u_long prognum" "u_long versnum" 587.Xc 588.Pp 589This routine creates a toy 590.Tn RPC 591client for the remote program 592.Fa prognum , 593version 594.Fa versnum . 595The transport used to pass messages to the service is 596actually a buffer within the process's address space, so the 597corresponding 598.Tn RPC 599server should live in the same address space; see 600.Fn svcraw_create . 601This allows simulation of 602.Tn RPC 603and acquisition of 604.Tn RPC 605overheads, such as round trip times, without any 606kernel interference. 607This routine returns 608.Dv NULL 609if it fails. 610.Pp 611.It Xo 612.Ft "CLIENT *" 613.Xc 614.It Xo 615.Fo clnttcp_create 616.Fa "struct sockaddr_in *addr" 617.Fa "u_long prognum" 618.Fa "u_long versnum" 619.Fa "int *sockp" 620.Fa "u_int sendsz" 621.Fa "u_int recvsz" 622.Fc 623.Xc 624.Pp 625This routine creates an 626.Tn RPC 627client for the remote program 628.Fa prognum , 629version 630.Fa versnum ; 631the client uses 632.Tn TCP/IP 633as a transport. 634The remote program is located at Internet 635address 636.Fa addr . 637If 638.Fa addr\->sin_port 639is zero, then it is set to the actual port that the remote 640program is listening on (the remote 641.Xr rpcbind 8 642service is consulted for this information). 643The 644.Fa sockp 645argument 646is a socket; if it is 647.Dv RPC_ANYSOCK , 648then this routine opens a new one and sets 649.Fa sockp . 650Since 651.Tn TCP Ns \-based 652.Tn RPC 653uses buffered 654.Tn I/O , 655the user may specify the size of the send and receive buffers 656with the 657.Fa sendsz 658and 659.Fa recvsz 660arguments; 661values of zero choose suitable defaults. 662This routine returns 663.Dv NULL 664if it fails. 665.Pp 666.It Xo 667.Ft "CLIENT *" 668.Xc 669.It Xo 670.Fo clntudp_create 671.Fa "struct sockaddr_in *addr" 672.Fa "u_long prognum" 673.Fa "u_long versnum" 674.Fa "struct timeval wait" 675.Fa "int *sockp" 676.Fc 677.Xc 678.Pp 679This routine creates an 680.Tn RPC 681client for the remote program 682.Fa prognum , 683version 684.Fa versnum ; 685the client uses 686.Tn UDP/IP 687as a transport. 688The remote program is located at Internet 689address 690.Fa addr . 691If 692.Fa addr\->sin_port 693is zero, then it is set to actual port that the remote 694program is listening on (the remote 695.Xr rpcbind 8 696service is consulted for this information). 697The 698.Fa sockp 699argument 700is a socket; if it is 701.Dv RPC_ANYSOCK , 702then this routine opens a new one and sets 703.Fa sockp . 704The 705.Tn UDP 706transport resends the call message in intervals of 707.Fa wait 708time until a response is received or until the call times 709out. 710The total time for the call to time out is specified by 711.Fn clnt_call . 712.Pp 713Warning: since 714.Tn UDP Ns \-based 715.Tn RPC 716messages can only hold up to 8 Kbytes 717of encoded data, this transport cannot be used for procedures 718that take large arguments or return huge results. 719.Pp 720.It Xo 721.Ft "CLIENT *" 722.Xc 723.It Xo 724.Fo clntudp_bufcreate 725.Fa "struct sockaddr_in *addr" 726.Fa "u_long prognum" 727.Fa "u_long versnum" 728.Fa "struct timeval wait" 729.Fa "int *sockp" 730.Fa "unsigned int sendsize" 731.Fa "unsigned int recosize" 732.Fc 733.Xc 734.Pp 735This routine creates an 736.Tn RPC 737client for the remote program 738.Fa prognum , 739on 740.Fa versnum ; 741the client uses 742.Tn UDP/IP 743as a transport. 744The remote program is located at Internet 745address 746.Fa addr . 747If 748.Fa addr\->sin_port 749is zero, then it is set to actual port that the remote 750program is listening on (the remote 751.Xr rpcbind 8 752service is consulted for this information). 753The 754.Fa sockp 755argument 756is a socket; if it is 757.Dv RPC_ANYSOCK , 758then this routine opens a new one and sets 759.Fa sockp . 760The 761.Tn UDP 762transport resends the call message in intervals of 763.Fa wait 764time until a response is received or until the call times 765out. 766The total time for the call to time out is specified by 767.Fn clnt_call . 768.Pp 769This allows the user to specify the maximum packet size 770for sending and receiving 771.Tn UDP Ns \-based 772.Tn RPC 773messages. 774.Pp 775.It Xo 776.Ft "CLIENT *" 777.Xc 778.It Xo 779.Fo clntunix_create 780.Fa "struct sockaddr_un *raddr" 781.Fa "u_long prognum" 782.Fa "u_long versnum" 783.Fa "int *sockp" 784.Fa "u_int sendsz" 785.Fa "u_int recvsz" 786.Fc 787.Xc 788.Pp 789This routine creates an 790.Tn RPC 791client for the local 792program 793.Fa prognum , 794version 795.Fa versnum ; 796the client uses 797.Ux Ns -domain 798sockets as a transport. 799The local program is located at the 800.Fa *raddr . 801The 802.Fa sockp 803argument 804is a socket; if it is 805.Dv RPC_ANYSOCK , 806then this routine opens a new one and sets 807.Fa sockp . 808Since 809.Ux Ns -based 810.Tn RPC 811uses buffered 812.Tn I/O , 813the user may specify the size of the send and receive buffers 814with the 815.Fa sendsz 816and 817.Fa recvsz 818arguments; 819values of zero choose suitable defaults. 820This routine returns 821.Dv NULL 822if it fails. 823.Pp 824.It Xo 825.Ft int 826.Xc 827.It Xo 828.Fn get_myaddress "struct sockaddr_in *addr" 829.Xc 830.Pp 831Stuff the machine's 832.Tn IP 833address into 834.Fa addr , 835without consulting the library routines that deal with 836.Pa /etc/hosts . 837The port number is always set to 838.Fn htons PMAPPORT . 839Returns zero on success, non-zero on failure. 840.Pp 841.It Xo 842.Ft "struct pmaplist *" 843.Xc 844.It Xo 845.Fn pmap_getmaps "struct sockaddr_in *addr" 846.Xc 847.Pp 848A user interface to the 849.Xr rpcbind 8 850service, which returns a list of the current 851.Tn RPC 852program\-to\-port mappings 853on the host located at 854.Tn IP 855address 856.Fa addr . 857This routine can return 858.Dv NULL . 859The command 860.Dq Nm rpcinfo Fl p 861uses this routine. 862.Pp 863.It Xo 864.Ft u_short 865.Xc 866.It Xo 867.Fo pmap_getport 868.Fa "struct sockaddr_in *addr" 869.Fa "u_long prognum" 870.Fa "u_long versnum" 871.Fa "u_long protocol" 872.Fc 873.Xc 874.Pp 875A user interface to the 876.Xr rpcbind 8 877service, which returns the port number 878on which waits a service that supports program number 879.Fa prognum , 880version 881.Fa versnum , 882and speaks the transport protocol associated with 883.Fa protocol . 884The value of 885.Fa protocol 886is most likely 887.Dv IPPROTO_UDP 888or 889.Dv IPPROTO_TCP . 890A return value of zero means that the mapping does not exist 891or that 892the 893.Tn RPC 894system failed to contact the remote 895.Xr rpcbind 8 896service. 897In the latter case, the global variable 898.Va rpc_createerr 899contains the 900.Tn RPC 901status. 902.Pp 903.It Xo 904.Ft "enum clnt_stat" 905.Xc 906.It Xo 907.Fo pmap_rmtcall 908.Fa "struct sockaddr_in *addr" 909.Fa "u_long prognum" 910.Fa "u_long versnum" 911.Fa "u_long procnum" 912.Fa "xdrproc_t inproc" 913.Fa "char *in" 914.Fa "xdrproc_t outproc" 915.Fa "char *out" 916.Fa "struct timeval tout" 917.Fa "u_long *portp" 918.Fc 919.Xc 920.Pp 921A user interface to the 922.Xr rpcbind 8 923service, which instructs 924.Xr rpcbind 8 925on the host at 926.Tn IP 927address 928.Fa addr 929to make an 930.Tn RPC 931call on your behalf to a procedure on that host. 932The 933.Fa portp 934argument 935will be modified to the program's port number if the 936procedure 937succeeds. 938The definitions of other arguments are discussed 939in 940.Fn callrpc 941and 942.Fn clnt_call . 943This procedure should be used for a 944.Dq ping 945and nothing 946else. 947See also 948.Fn clnt_broadcast . 949.Pp 950.It Xo 951.Ft bool_t 952.Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port" 953.Xc 954.Pp 955A user interface to the 956.Xr rpcbind 8 957service, which establishes a mapping between the triple 958.Pq Fa prognum , versnum , protocol 959and 960.Fa port 961on the machine's 962.Xr rpcbind 8 963service. 964The value of 965.Fa protocol 966is most likely 967.Dv IPPROTO_UDP 968or 969.Dv IPPROTO_TCP . 970This routine returns one if it succeeds, zero otherwise. 971Automatically done by 972.Fn svc_register . 973.Pp 974.It Xo 975.Ft bool_t 976.Fn pmap_unset "u_long prognum" "u_long versnum" 977.Xc 978.Pp 979A user interface to the 980.Xr rpcbind 8 981service, which destroys all mapping between the triple 982.Pq Fa prognum , versnum , * 983and 984.Fa ports 985on the machine's 986.Xr rpcbind 8 987service. 988This routine returns one if it succeeds, zero 989otherwise. 990.Pp 991.It Xo 992.Ft bool_t 993.Fo registerrpc 994.Fa "u_long prognum" 995.Fa "u_long versnum" 996.Fa "u_long procnum" 997.Fa "char *(*procname)(void)" 998.Fa "xdrproc_t inproc" 999.Fa "xdrproc_t outproc" 1000.Fc 1001.Xc 1002.Pp 1003Register procedure 1004.Fa procname 1005with the 1006.Tn RPC 1007service package. 1008If a request arrives for program 1009.Fa prognum , 1010version 1011.Fa versnum , 1012and procedure 1013.Fa procnum , 1014.Fa procname 1015is called with a pointer to its argument(s); 1016.Fa progname 1017should return a pointer to its static result(s); 1018.Fa inproc 1019is used to decode the arguments while 1020.Fa outproc 1021is used to encode the results. 1022This routine returns zero if the registration succeeded, \-1 1023otherwise. 1024.Pp 1025Warning: remote procedures registered in this form 1026are accessed using the 1027.Tn UDP/IP 1028transport; see 1029.Fn svcudp_create 1030for restrictions. 1031.Pp 1032.It Xo 1033.Vt "struct rpc_createerr" rpc_createerr ; 1034.Xc 1035.Pp 1036A global variable whose value is set by any 1037.Tn RPC 1038client creation routine 1039that does not succeed. 1040Use the routine 1041.Fn clnt_pcreateerror 1042to print the reason why. 1043.Pp 1044.It Xo 1045.Ft bool_t 1046.Fn svc_destroy "SVCXPRT * xprt" 1047.Xc 1048.Pp 1049A macro that destroys the 1050.Tn RPC 1051service transport handle, 1052.Fa xprt . 1053Destruction usually involves deallocation 1054of private data structures, including 1055.Fa xprt 1056itself. 1057Use of 1058.Fa xprt 1059is undefined after calling this routine. 1060.Pp 1061.It Xo 1062.Vt fd_set svc_fdset ; 1063.Xc 1064.Pp 1065A global variable reflecting the 1066.Tn RPC 1067service side's 1068read file descriptor bit mask; it is suitable as a template argument 1069to the 1070.Xr select 2 1071system call. 1072This is only of interest 1073if a service implementor does not call 1074.Fn svc_run , 1075but rather does his own asynchronous event processing. 1076This variable is read\-only (do not pass its address to 1077.Xr select 2 ! ) , 1078yet it may change after calls to 1079.Fn svc_getreqset 1080or any creation routines. 1081As well, note that if the process has descriptor limits 1082which are extended beyond 1083.Dv FD_SETSIZE , 1084this variable will only be usable for the first 1085.Dv FD_SETSIZE 1086descriptors. 1087.Pp 1088.It Xo 1089.Vt int svc_fds ; 1090.Xc 1091.Pp 1092Similar to 1093.Va svc_fdset , 1094but limited to 32 descriptors. 1095This 1096interface is obsoleted by 1097.Va svc_fdset . 1098.Pp 1099.It Xo 1100.Ft bool_t 1101.Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" 1102.Xc 1103.Pp 1104A macro that frees any data allocated by the 1105.Tn RPC/XDR 1106system when it decoded the arguments to a service procedure 1107using 1108.Fn svc_getargs . 1109This routine returns 1 if the results were successfully 1110freed, 1111and zero otherwise. 1112.Pp 1113.It Xo 1114.Ft bool_t 1115.Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" 1116.Xc 1117.Pp 1118A macro that decodes the arguments of an 1119.Tn RPC 1120request 1121associated with the 1122.Tn RPC 1123service transport handle, 1124.Fa xprt . 1125The 1126.Fa in 1127argument 1128is the address where the arguments will be placed; 1129.Fa inproc 1130is the 1131.Tn XDR 1132routine used to decode the arguments. 1133This routine returns one if decoding succeeds, and zero 1134otherwise. 1135.Pp 1136.It Xo 1137.Ft "struct sockaddr_in *" 1138.Xc 1139.It Xo 1140.Fn svc_getcaller "SVCXPRT *xprt" 1141.Xc 1142.Pp 1143The approved way of getting the network address of the caller 1144of a procedure associated with the 1145.Tn RPC 1146service transport handle, 1147.Fa xprt . 1148.Pp 1149.It Xo 1150.Ft void 1151.Fn svc_getreqset "fd_set *rdfds" 1152.Xc 1153.Pp 1154This routine is only of interest if a service implementor 1155does not call 1156.Fn svc_run , 1157but instead implements custom asynchronous event processing. 1158It is called when the 1159.Xr select 2 1160system call has determined that an 1161.Tn RPC 1162request has arrived on some 1163.Tn RPC 1164socket(s); 1165.Fa rdfds 1166is the resultant read file descriptor bit mask. 1167The routine returns when all sockets associated with the 1168value of 1169.Fa rdfds 1170have been serviced. 1171.Pp 1172.It Xo 1173.Ft void 1174.Fn svc_getreq "int rdfds" 1175.Xc 1176.Pp 1177Similar to 1178.Fn svc_getreqset , 1179but limited to 32 descriptors. 1180This interface is obsoleted by 1181.Fn svc_getreqset . 1182.Pp 1183.It Xo 1184.Ft bool_t 1185.Fo svc_register 1186.Fa "SVCXPRT *xprt" 1187.Fa "u_long prognum" 1188.Fa "u_long versnum" 1189.Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)" 1190.Fa "int protocol" 1191.Fc 1192.Xc 1193.Pp 1194Associates 1195.Fa prognum 1196and 1197.Fa versnum 1198with the service dispatch procedure, 1199.Fn dispatch . 1200If 1201.Fa protocol 1202is zero, the service is not registered with the 1203.Xr rpcbind 8 1204service. 1205If 1206.Fa protocol 1207is non-zero, then a mapping of the triple 1208.Pq Fa prognum , versnum , protocol 1209to 1210.Fa xprt\->xp_port 1211is established with the local 1212.Xr rpcbind 8 1213service (generally 1214.Fa protocol 1215is zero, 1216.Dv IPPROTO_UDP 1217or 1218.Dv IPPROTO_TCP ) . 1219The procedure 1220.Fn dispatch 1221has the following form: 1222.Bd -ragged -offset indent 1223.Ft bool_t 1224.Fn dispatch "struct svc_req *request" "SVCXPRT *xprt" 1225.Ed 1226.Pp 1227The 1228.Fn svc_register 1229routine returns one if it succeeds, and zero otherwise. 1230.Pp 1231.It Xo 1232.Fn svc_run 1233.Xc 1234.Pp 1235This routine never returns. 1236It waits for 1237.Tn RPC 1238requests to arrive, and calls the appropriate service 1239procedure using 1240.Fn svc_getreq 1241when one arrives. 1242This procedure is usually waiting for a 1243.Xr select 2 1244system call to return. 1245.Pp 1246.It Xo 1247.Ft bool_t 1248.Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out" 1249.Xc 1250.Pp 1251Called by an 1252.Tn RPC 1253service's dispatch routine to send the results of a 1254remote procedure call. 1255The 1256.Fa xprt 1257argument 1258is the request's associated transport handle; 1259.Fa outproc 1260is the 1261.Tn XDR 1262routine which is used to encode the results; and 1263.Fa out 1264is the address of the results. 1265This routine returns one if it succeeds, zero otherwise. 1266.Pp 1267.It Xo 1268.Ft void 1269.Xc 1270.It Xo 1271.Fn svc_unregister "u_long prognum" "u_long versnum" 1272.Xc 1273.Pp 1274Remove all mapping of the double 1275.Pq Fa prognum , versnum 1276to dispatch routines, and of the triple 1277.Pq Fa prognum , versnum , * 1278to port number. 1279.Pp 1280.It Xo 1281.Ft void 1282.Xc 1283.It Xo 1284.Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why" 1285.Xc 1286.Pp 1287Called by a service dispatch routine that refuses to perform 1288a remote procedure call due to an authentication error. 1289.Pp 1290.It Xo 1291.Ft void 1292.Xc 1293.It Xo 1294.Fn svcerr_decode "SVCXPRT *xprt" 1295.Xc 1296.Pp 1297Called by a service dispatch routine that cannot successfully 1298decode its arguments. 1299See also 1300.Fn svc_getargs . 1301.Pp 1302.It Xo 1303.Ft void 1304.Xc 1305.It Xo 1306.Fn svcerr_noproc "SVCXPRT *xprt" 1307.Xc 1308.Pp 1309Called by a service dispatch routine that does not implement 1310the procedure number that the caller requests. 1311.Pp 1312.It Xo 1313.Ft void 1314.Xc 1315.It Xo 1316.Fn svcerr_noprog "SVCXPRT *xprt" 1317.Xc 1318.Pp 1319Called when the desired program is not registered with the 1320.Tn RPC 1321package. 1322Service implementors usually do not need this routine. 1323.Pp 1324.It Xo 1325.Ft void 1326.Xc 1327.It Xo 1328.Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers" 1329.Xc 1330.Pp 1331Called when the desired version of a program is not registered 1332with the 1333.Tn RPC 1334package. 1335Service implementors usually do not need this routine. 1336.Pp 1337.It Xo 1338.Ft void 1339.Xc 1340.It Xo 1341.Fn svcerr_systemerr "SVCXPRT *xprt" 1342.Xc 1343.Pp 1344Called by a service dispatch routine when it detects a system 1345error 1346not covered by any particular protocol. 1347For example, if a service can no longer allocate storage, 1348it may call this routine. 1349.Pp 1350.It Xo 1351.Ft void 1352.Xc 1353.It Xo 1354.Fn svcerr_weakauth "SVCXPRT *xprt" 1355.Xc 1356.Pp 1357Called by a service dispatch routine that refuses to perform 1358a remote procedure call due to insufficient 1359authentication arguments. 1360The routine calls 1361.Fn svcerr_auth xprt AUTH_TOOWEAK . 1362.Pp 1363.It Xo 1364.Ft "SVCXPRT *" 1365.Xc 1366.It Xo 1367.Fn svcraw_create void 1368.Xc 1369.Pp 1370This routine creates a toy 1371.Tn RPC 1372service transport, to which it returns a pointer. 1373The transport 1374is really a buffer within the process's address space, 1375so the corresponding 1376.Tn RPC 1377client should live in the same 1378address space; 1379see 1380.Fn clntraw_create . 1381This routine allows simulation of 1382.Tn RPC 1383and acquisition of 1384.Tn RPC 1385overheads (such as round trip times), without any kernel 1386interference. 1387This routine returns 1388.Dv NULL 1389if it fails. 1390.Pp 1391.It Xo 1392.Ft "SVCXPRT *" 1393.Xc 1394.It Xo 1395.Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" 1396.Xc 1397.Pp 1398This routine creates a 1399.Tn TCP/IP Ns \-based 1400.Tn RPC 1401service transport, to which it returns a pointer. 1402The transport is associated with the socket 1403.Fa sock , 1404which may be 1405.Dv RPC_ANYSOCK , 1406in which case a new socket is created. 1407If the socket is not bound to a local 1408.Tn TCP 1409port, then this routine binds it to an arbitrary port. 1410Upon completion, 1411.Fa xprt\->xp_fd 1412is the transport's socket descriptor, and 1413.Fa xprt\->xp_port 1414is the transport's port number. 1415This routine returns 1416.Dv NULL 1417if it fails. 1418Since 1419.Tn TCP Ns \-based 1420.Tn RPC 1421uses buffered 1422.Tn I/O , 1423users may specify the size of buffers; values of zero 1424choose suitable defaults. 1425.Pp 1426.It Xo 1427.Ft "SVCXPRT *" 1428.Xc 1429.It Xo 1430.Fn svcunix_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" "char *path" 1431.Xc 1432.Pp 1433This routine creates a 1434.Ux Ns -based 1435.Tn RPC 1436service transport, to which it returns a pointer. 1437The transport is associated with the socket 1438.Fa sock , 1439which may be 1440.Dv RPC_ANYSOCK , 1441in which case a new socket is created. 1442The 1443.Fa *path 1444argument 1445is a variable-length file system pathname of 1446at most 104 characters. 1447This file is 1448.Em not 1449removed when the socket is closed. 1450The 1451.Xr unlink 2 1452system call must be used to remove the file. 1453Upon completion, 1454.Fa xprt\->xp_fd 1455is the transport's socket descriptor. 1456This routine returns 1457.Dv NULL 1458if it fails. 1459Since 1460.Ux Ns -based 1461.Tn RPC 1462uses buffered 1463.Tn I/O , 1464users may specify the size of buffers; values of zero 1465choose suitable defaults. 1466.Pp 1467.It Xo 1468.Ft "SVCXPRT *" 1469.Xc 1470.It Xo 1471.Fn svcunixfd_create "int fd" "u_int sendsize" "u_int recvsize" 1472.Xc 1473.Pp 1474Create a service on top of any open descriptor. 1475The 1476.Fa sendsize 1477and 1478.Fa recvsize 1479arguments 1480indicate sizes for the send and receive buffers. 1481If they are 1482zero, a reasonable default is chosen. 1483.Pp 1484.It Xo 1485.Ft "SVCXPRT *" 1486.Xc 1487.It Xo 1488.Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize" 1489.Xc 1490.Pp 1491Create a service on top of any open descriptor. 1492Typically, 1493this 1494descriptor is a connected socket for a stream protocol such 1495as 1496.Tn TCP . 1497The 1498.Fa sendsize 1499and 1500.Fa recvsize 1501arguments 1502indicate sizes for the send and receive buffers. 1503If they are 1504zero, a reasonable default is chosen. 1505.Pp 1506.It Xo 1507.Ft "SVCXPRT *" 1508.Xc 1509.It Xo 1510.Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize" 1511.Xc 1512.Pp 1513This routine creates a 1514.Tn UDP/IP Ns \-based 1515.Tn RPC 1516service transport, to which it returns a pointer. 1517The transport is associated with the socket 1518.Fa sock , 1519which may be 1520.Dv RPC_ANYSOCK , 1521in which case a new socket is created. 1522If the socket is not bound to a local 1523.Tn UDP 1524port, then this routine binds it to an arbitrary port. 1525Upon 1526completion, 1527.Fa xprt\->xp_fd 1528is the transport's socket descriptor, and 1529.Fa xprt\->xp_port 1530is the transport's port number. 1531This routine returns 1532.Dv NULL 1533if it fails. 1534.Pp 1535This allows the user to specify the maximum packet size for sending and 1536receiving 1537.Tn UDP Ns \-based 1538.Tn RPC 1539messages. 1540.Pp 1541.It Xo 1542.Ft bool_t 1543.Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar" 1544.Xc 1545.Pp 1546Used for encoding 1547.Tn RPC 1548reply messages. 1549This routine is useful for users who 1550wish to generate 1551.Tn RPC Ns \-style 1552messages without using the 1553.Tn RPC 1554package. 1555.Pp 1556.It Xo 1557.Ft bool_t 1558.Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp" 1559.Xc 1560.Pp 1561Used for describing 1562.Ux 1563credentials. 1564This routine is useful for users 1565who wish to generate these credentials without using the 1566.Tn RPC 1567authentication package. 1568.Pp 1569.It Xo 1570.Ft void 1571.Xc 1572.It Xo 1573.Ft bool_t 1574.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr" 1575.Xc 1576.Pp 1577Used for describing 1578.Tn RPC 1579call header messages. 1580This routine is useful for users who wish to generate 1581.Tn RPC Ns \-style 1582messages without using the 1583.Tn RPC 1584package. 1585.Pp 1586.It Xo 1587.Ft bool_t 1588.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg" 1589.Xc 1590.Pp 1591Used for describing 1592.Tn RPC 1593call messages. 1594This routine is useful for users who wish to generate 1595.Tn RPC Ns \-style 1596messages without using the 1597.Tn RPC 1598package. 1599.Pp 1600.It Xo 1601.Ft bool_t 1602.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap" 1603.Xc 1604.Pp 1605Used for describing 1606.Tn RPC 1607authentication information messages. 1608This routine is useful for users who wish to generate 1609.Tn RPC Ns \-style 1610messages without using the 1611.Tn RPC 1612package. 1613.Pp 1614.It Xo 1615.Vt struct pmap ; 1616.Xc 1617.It Xo 1618.Ft bool_t 1619.Fn xdr_pmap "XDR *xdrs" "struct pmap *regs" 1620.Xc 1621.Pp 1622Used for describing arguments to various 1623.Xr rpcbind 8 1624procedures, externally. 1625This routine is useful for users who wish to generate 1626these arguments without using the 1627.Fn pmap_* 1628interface. 1629.Pp 1630.It Xo 1631.Ft bool_t 1632.Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp" 1633.Xc 1634.Pp 1635Used for describing a list of port mappings, externally. 1636This routine is useful for users who wish to generate 1637these arguments without using the 1638.Fn pmap_* 1639interface. 1640.Pp 1641.It Xo 1642.Ft bool_t 1643.Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr" 1644.Xc 1645.Pp 1646Used for describing 1647.Tn RPC 1648reply messages. 1649This routine is useful for users who wish to generate 1650.Tn RPC Ns \-style 1651messages without using the 1652.Tn RPC 1653package. 1654.Pp 1655.It Xo 1656.Ft bool_t 1657.Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg" 1658.Xc 1659.Pp 1660Used for describing 1661.Tn RPC 1662reply messages. 1663This routine is useful for users who wish to generate 1664.Tn RPC 1665style messages without using the 1666.Tn RPC 1667package. 1668.Pp 1669.It Xo 1670.Ft void 1671.Xc 1672.It Xo 1673.Fn xprt_register "SVCXPRT *xprt" 1674.Xc 1675.Pp 1676After 1677.Tn RPC 1678service transport handles are created, 1679they should register themselves with the 1680.Tn RPC 1681service package. 1682This routine modifies the global variable 1683.Va svc_fds . 1684Service implementors usually do not need this routine. 1685.Pp 1686.It Xo 1687.Ft void 1688.Xc 1689.It Xo 1690.Fn xprt_unregister "SVCXPRT *xprt" 1691.Xc 1692.Pp 1693Before an 1694.Tn RPC 1695service transport handle is destroyed, 1696it should unregister itself with the 1697.Tn RPC 1698service package. 1699This routine modifies the global variable 1700.Va svc_fds . 1701Service implementors usually do not need this routine. 1702.El 1703.Sh SEE ALSO 1704.Xr rpc_secure 3 , 1705.Xr xdr 3 1706.Rs 1707.%T "Remote Procedure Calls: Protocol Specification" 1708.Re 1709.Rs 1710.%T "Remote Procedure Call Programming Guide" 1711.Re 1712.Rs 1713.%T "rpcgen Programming Guide" 1714.Re 1715.Rs 1716.%T "RPC: Remote Procedure Call Protocol Specification" 1717.%O RFC1050 1718.%Q "Sun Microsystems, Inc., USC-ISI" 1719.Re 1720