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