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