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