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