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