![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rpc.prog2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / sunrpc / doc|
Return to rpc.prog2 CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / sunrpc / doc |
1.1 ! root 1: .H A "Synopsis of RPC Routines" ! 2: .SH ! 3: auth_destroy() ! 4: .LP ! 5: .LS ! 6: void ! 7: auth_destroy(auth) ! 8: AUTH *auth; ! 9: .LE ! 10: A macro that destroys the authentication information associated with ! 11: .L auth . ! 12: Destruction usually involves deallocation ! 13: of private data structures. The use of ! 14: .L auth ! 15: is undefined after calling ! 16: .L auth_destroy() . ! 17: .SH ! 18: authnone_create() ! 19: .LP ! 20: .LS ! 21: AUTH * ! 22: authnone_create() ! 23: .LE ! 24: Creates and returns an RPC authentication handle that passes no ! 25: usable authentication information with each remote procedure call. ! 26: .SH ! 27: authunix_create() ! 28: .LP ! 29: .LS ! 30: AUTH * ! 31: authunix_create(host, uid, gid, len, aup_gids) ! 32: char *host; ! 33: int uid, gid, len, *aup_gids; ! 34: .LE ! 35: Creates and returns an RPC authentication handle that contains ! 36: .UX ! 37: authentication information. ! 38: The parameter ! 39: .L host ! 40: is the name of the machine on which the information was created; ! 41: .L uid ! 42: is the user's user ID; ! 43: .L gid ! 44: is the user's current group ID; ! 45: .L len ! 46: and ! 47: .L aup_gids ! 48: refer to a counted array of groups to which the user belongs. ! 49: It is easy to impersonate a user. ! 50: .SH ! 51: authunix_create_default() ! 52: .LP ! 53: .LS ! 54: AUTH * ! 55: authunix_create_default() ! 56: .LE ! 57: Calls ! 58: .L authunix_create() ! 59: with the appropriate parameters. ! 60: .SH ! 61: callrpc() ! 62: .LP ! 63: .LS ! 64: callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out) ! 65: char *host; ! 66: u_long prognum, versnum, procnum; ! 67: char *in, *out; ! 68: xdrproc_t inproc, outproc; ! 69: .LE ! 70: Calls the remote procedure associated with ! 71: .L prognum , ! 72: .L versnum , ! 73: and ! 74: .L procnum ! 75: on the machine, ! 76: .L host . ! 77: The parameter ! 78: .L in ! 79: is the address of the procedure's argument(s), and ! 80: .L out ! 81: is the address of where to place the result(s); ! 82: .L inproc ! 83: is used to encode the procedure's parameters, and ! 84: .L outproc ! 85: is used to decode the procedure's results. ! 86: This routine returns zero if it succeeds, or the value of ! 87: .L "enum clnt_stat" ! 88: cast to an integer if it fails. ! 89: The routine ! 90: .L clnt_perrno() ! 91: is handy for translating failure statuses into messages. ! 92: Warning: calling remote procedures with this routine ! 93: uses UDP/IP as a transport; see ! 94: .L clntudp_create() ! 95: for restrictions. ! 96: .SH ! 97: clnt_broadcast() ! 98: .LP ! 99: .LS ! 100: enum clnt_stat ! 101: clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult) ! 102: u_long prognum, versnum, procnum; ! 103: char *in, *out; ! 104: xdrproc_t inproc, outproc; ! 105: resultproc_t eachresult; ! 106: .LE ! 107: Like ! 108: .L callrpc() , ! 109: except the call message is broadcast to all locally connected broadcast nets. ! 110: Each time it receives a response, this routine calls ! 111: .L eachresult , ! 112: whose form is ! 113: .LS ! 114: eachresult(out, addr) ! 115: char *out; ! 116: struct sockaddr_in *addr; ! 117: .LE ! 118: where ! 119: .L out ! 120: is the same as ! 121: .L out ! 122: passed to ! 123: .L clnt_broadcast() , ! 124: except that the remote procedure's output is decoded there; ! 125: .L addr ! 126: points to the address of the machine that sent the results. If ! 127: .L eachresult() ! 128: returns zero, ! 129: .L clnt_broadcast() ! 130: waits for more replies; ! 131: otherwise it returns with appropriate status. ! 132: .SH ! 133: clnt_call() ! 134: .LP ! 135: .LS ! 136: enum clnt_stat ! 137: clnt_call(clnt, procnum, inproc, in, outproc, out, tout) ! 138: CLIENT *clnt; long procnum; ! 139: xdrproc_t inproc, outproc; ! 140: char *in, *out; ! 141: struct timeval tout; ! 142: .LE ! 143: A macro that calls the remote procedure ! 144: .L procnum ! 145: associated with the client handle, ! 146: .L clnt , ! 147: which is obtained with an RPC client creation routine such as ! 148: .L clntudp_create . ! 149: The parameter ! 150: .L in ! 151: is the address of the procedure's argument(s), and ! 152: .L out ! 153: is the address of where to place the result(s); ! 154: .L inproc ! 155: is used to encode the procedure's parameters, and ! 156: .L outproc ! 157: is used to decode the procedure's results; ! 158: .L tout ! 159: is the time allowed for results to come back. ! 160: .SH ! 161: clnt_destroy() ! 162: .LP ! 163: .LS ! 164: clnt_destroy(clnt) ! 165: CLIENT *clnt; ! 166: .LE ! 167: A macro that destroys the client's RPC handle. ! 168: Destruction usually involves deallocation ! 169: of private data structures, including ! 170: .L clnt ! 171: itself. Use of ! 172: .L clnt ! 173: is undefined after calling ! 174: .L clnt_destroy() . ! 175: Warning: client destruction routines do not close sockets associated with ! 176: .L clnt ; ! 177: this is the responsibility of the user. ! 178: .SH ! 179: clnt_freeres() ! 180: .LP ! 181: .LS ! 182: clnt_freeres(clnt, outproc, out) ! 183: CLIENT *clnt; ! 184: xdrproc_t outproc; ! 185: char *out; ! 186: .LE ! 187: A macro that frees any data allocated by the RPC/XDR system ! 188: when it decoded the results of an RPC call. ! 189: The parameter ! 190: .L out ! 191: is the address of the results, and ! 192: .L outproc ! 193: is the XDR routine describing the results in simple primitives. ! 194: This routine returns one if the results were successfully freed, ! 195: and zero otherwise. ! 196: .SH ! 197: clnt_geterr() ! 198: .LP ! 199: .LS ! 200: void ! 201: clnt_geterr(clnt, errp) ! 202: CLIENT *clnt; ! 203: struct rpc_err *errp; ! 204: .LE ! 205: A macro that copies the error structure out of the client handle ! 206: to the structure at address ! 207: .L errp . ! 208: .SH ! 209: clnt_pcreateerror() ! 210: .LP ! 211: .LS ! 212: void ! 213: clnt_pcreateerror(s) ! 214: char *s; ! 215: .LE ! 216: Prints a message to standard error indicating ! 217: why a client RPC handle could not be created. ! 218: The message is prepended with string ! 219: .L s ! 220: and a colon. ! 221: .SH ! 222: clnt_perrno() ! 223: .LP ! 224: .LS ! 225: void ! 226: clnt_perrno(stat) ! 227: enum clnt_stat; ! 228: .LE ! 229: Prints a message to standard error corresponding ! 230: to the condition indicated by ! 231: .L stat . ! 232: .SH ! 233: clnt_perror() ! 234: .LP ! 235: .LS ! 236: clnt_perror(clnt, s) ! 237: CLIENT *clnt; ! 238: char *s; ! 239: .LE ! 240: Prints a message to standard error indicating why an RPC call failed; ! 241: .L clnt ! 242: is the handle used to do the call. ! 243: The message is prepended with string ! 244: .L s ! 245: and a colon. ! 246: .SH ! 247: clntraw_create() ! 248: .LP ! 249: .LS ! 250: CLIENT * ! 251: clntraw_create(prognum, versnum) ! 252: u_long prognum, versnum; ! 253: .LE ! 254: This routine creates a toy RPC client for the remote program ! 255: .L prognum , ! 256: version ! 257: .L versnum . ! 258: The transport used to pass messages to the service ! 259: is actually a buffer within the process's address space, ! 260: so the corresponding RPC server should live in the same address space; see ! 261: .L svcraw_create() . ! 262: This allows simulation of RPC and acquisition of RPC overheads, ! 263: such as round trip times, without any kernel interference. ! 264: This routine returns NULL if it fails. ! 265: .SH ! 266: clnttcp_create() ! 267: .LP ! 268: .LS ! 269: CLIENT * ! 270: clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz) ! 271: struct sockaddr_in *addr; ! 272: u_long prognum, versnum; ! 273: int *sockp; ! 274: u_int sendsz, recvsz; ! 275: .LE ! 276: This routine creates an RPC client for the remote program ! 277: .L prognum , ! 278: version ! 279: .L versnum ; ! 280: the client uses TCP/IP as a transport. ! 281: The remote program is located at Internet address ! 282: .L *addr . ! 283: If ! 284: .L addr->sin_port ! 285: is zero, then it is set to the actual port that the remote ! 286: program is listening on (the remote ! 287: .I portmap ! 288: service is consulted for this information). ! 289: The parameter ! 290: .L *sockp ! 291: is a socket; if it is RPC_ANYSOCK, then ! 292: this routine opens a new one and sets ! 293: .L *sockp . ! 294: Since TCP-based RPC uses buffered I/O, the user may specify ! 295: the size of the send and receive buffers with the parameters ! 296: .L sendsz ! 297: and ! 298: .L recvsz ; ! 299: values of zero choose suitable defaults. ! 300: This routine returns NULL if it fails. ! 301: .SH ! 302: clntudp_create() ! 303: .LP ! 304: .LS ! 305: CLIENT * ! 306: clntudp_create(addr, prognum, versnum, wait, sockp) ! 307: struct sockaddr_in *addr; ! 308: u_long prognum, versnum; ! 309: struct timeval wait; ! 310: int *sockp; ! 311: .LE ! 312: This routine creates an RPC client for the remote program ! 313: .L prognum , ! 314: version ! 315: .L versnum ; ! 316: the client uses use UDP/IP as a transport. ! 317: The remote program is located at Internet address ! 318: .L *addr . ! 319: If ! 320: .L addr->sin_port ! 321: is zero, then it is set to actual port that the remote ! 322: program is listening on (the remote ! 323: .I portmap ! 324: service is consulted for this information). ! 325: The parameter ! 326: .L *sockp ! 327: is a socket; if it is RPC_ANYSOCK, ! 328: then this routine opens a new one and sets ! 329: .L *sockp . ! 330: The UDP transport resends the call message in intervals of ! 331: .L wait ! 332: time until a response is received or until the call times out. ! 333: Warning: since UDP-based RPC messages can only hold up to 8 Kbytes ! 334: of encoded data, this transport cannot be used for procedures ! 335: that take large arguments or return huge results. ! 336: .SH ! 337: get_myaddress() ! 338: .LP ! 339: .LS ! 340: void ! 341: get_myaddress(addr) ! 342: struct sockaddr_in *addr; ! 343: .LE ! 344: Stuffs the machine's IP address into ! 345: .L *addr , ! 346: without consulting the library routines that deal with ! 347: .I /etc/hosts . ! 348: The port number is always set to ! 349: .L htons(PMAPPORT) . ! 350: .SH ! 351: pmap_getmaps() ! 352: .LP ! 353: .LS ! 354: struct pmaplist * ! 355: pmap_getmaps(addr) ! 356: struct sockaddr_in *addr; ! 357: .LE ! 358: A user interface to the ! 359: .I portmap ! 360: service, which returns a list of the current RPC program-to-port mappings ! 361: on the host located at IP address ! 362: .L *addr . ! 363: This routine can return NULL. The command ! 364: .L "rpcinfo -p" ! 365: uses this routine. ! 366: .SH ! 367: pmap_getport() ! 368: .LP ! 369: .LS ! 370: u_short ! 371: pmap_getport(addr, prognum, versnum, protocol) ! 372: struct sockaddr_in *addr; ! 373: u_long prognum, versnum, protocol; ! 374: .LE ! 375: A user interface to the ! 376: .I portmap ! 377: service, which returns the port number ! 378: on which waits a service that supports program number ! 379: .L prognum , ! 380: version ! 381: .L versnum , ! 382: and speaks the transport protocol associated with protocol. ! 383: A return value of zero means that the mapping does not exist or that ! 384: the RPC system failured to contact the remote ! 385: .I portmap ! 386: service. In the latter case, the global variable ! 387: .L rpc_createerr ! 388: contains the RPC status. ! 389: .SH ! 390: pmap_rmtcall() ! 391: .LP ! 392: .LS ! 393: enum clnt_stat ! 394: pmap_rmtcall(addr, prognum, versnum, procnum, ! 395: inproc, in, outproc, out, tout, portp) ! 396: struct sockaddr_in *addr; ! 397: u_long prognum, versnum, procnum; ! 398: char *in, *out; ! 399: xdrproc_t inproc, outproc; ! 400: struct timeval tout; ! 401: u_long *portp; ! 402: .LE ! 403: A user interface to the ! 404: .I portmap ! 405: service, which instructs ! 406: .I portmap ! 407: on the host at IP address ! 408: .L *addr ! 409: to make an RPC call on your behalf to a procedure on that host. ! 410: The parameter ! 411: .L *portp ! 412: will be modified to the program's port number if the procedure succeeds. ! 413: The definitions of other parameters are discussed in ! 414: .L callrpc() ! 415: and ! 416: .L clnt_call() ; ! 417: see also ! 418: .L clnt_broadcast() . ! 419: .SH ! 420: pmap_set() ! 421: .LP ! 422: .LS ! 423: pmap_set(prognum, versnum, protocol, port) ! 424: u_long prognum, versnum, protocol; ! 425: u_short port; ! 426: .LE ! 427: A user interface to the ! 428: .I portmap ! 429: service, which establishes a mapping between the triple ! 430: .L [prognum,versnum,protocol] ! 431: and ! 432: .L port ! 433: on the machine's ! 434: .I portmap ! 435: service. The value of protocol is most likely IPPROTO_UDP or IPPROTO_TCP. ! 436: This routine returns one if it succeeds, zero otherwise. ! 437: .SH ! 438: pmap_unset() ! 439: .LP ! 440: .LS ! 441: pmap_unset(prognum, versnum) ! 442: u_long prognum, versnum; ! 443: .LE ! 444: A user interface to the ! 445: .I portmap ! 446: service, which destroys all mappings between the triple ! 447: .L [prognum,versnum,*] ! 448: and ! 449: .L ports ! 450: on the machine's ! 451: .I portmap ! 452: service. ! 453: This routine returns one if it succeeds, zero otherwise. ! 454: .SH ! 455: registerrpc() ! 456: .LP ! 457: .LS ! 458: registerrpc(prognum, versnum, procnum, procname, inproc, outproc) ! 459: u_long prognum, versnum, procnum; ! 460: char *(*procname)(); ! 461: xdrproc_t inproc, outproc; ! 462: .LE ! 463: Registers procedure ! 464: .L procname ! 465: with the RPC service package. If a request arrives for program ! 466: .L prognum , ! 467: version ! 468: .L versnum , ! 469: and procedure ! 470: .L procnum , ! 471: .L procname ! 472: is called with a pointer to its parameter(s); ! 473: .L progname ! 474: should return a pointer to its static result(s); ! 475: .L inproc ! 476: is used to decode the parameters while ! 477: .L outproc ! 478: is used to encode the results. ! 479: This routine returns zero if the registration succeeded, \-1 otherwise. ! 480: Warning: remote procedures registered in this form ! 481: are accessed using the UDP/IP transport; see ! 482: .L svcudp_create() ! 483: for restrictions. ! 484: .SH ! 485: rpc_createerr ! 486: .LP ! 487: .LS ! 488: struct rpc_createerr rpc_createerr; ! 489: .LE ! 490: A global variable whose value is set by any RPC client creation routine ! 491: that does not succeed. Use the routine ! 492: .L clnt_pcreateerror() ! 493: to print the reason why. ! 494: .SH ! 495: svc_destroy() ! 496: .LP ! 497: .LS ! 498: svc_destroy(xprt) ! 499: SVCXPRT *xprt; ! 500: .LE ! 501: A macro that destroys the RPC service transport handle, ! 502: .L xprt . ! 503: Destruction usually involves deallocation ! 504: of private data structures, including ! 505: .L xprt ! 506: itself. Use of ! 507: .L xprt ! 508: is undefined after calling this routine. ! 509: .SH ! 510: svc_fds ! 511: .LP ! 512: .LS ! 513: int svc_fds; ! 514: .LE ! 515: A global variable reflecting the RPC service side's ! 516: read file descriptor bit mask; it is suitable as a parameter to the ! 517: .L select ! 518: system call. This is only of interest ! 519: if a service implementor does not call ! 520: .L svc_run() , ! 521: but rather does his own asynchronous event processing. ! 522: This variable is read-only (do not pass its address to ! 523: .L select !), ! 524: yet it may change after calls to ! 525: .L svc_getreq() ! 526: or any creation routines. ! 527: .SH ! 528: svc_freeargs() ! 529: .LP ! 530: .LS ! 531: svc_freeargs(xprt, inproc, in) ! 532: SVCXPRT *xprt; ! 533: xdrproc_t inproc; ! 534: char *in; ! 535: .LE ! 536: A macro that frees any data allocated by the RPC/XDR system ! 537: when it decoded the arguments to a service procedure using ! 538: .L svc_getargs(). ! 539: This routine returns one if the results were successfully freed, ! 540: and zero otherwise. ! 541: .SH ! 542: svc_getargs() ! 543: .LP ! 544: .LS ! 545: svc_getargs(xprt, inproc, in) ! 546: SVCXPRT *xprt; ! 547: xdrproc_t inproc; ! 548: char *in; ! 549: .LE ! 550: A macro that decodes the arguments of an RPC request ! 551: associated with the RPC service transport handle, ! 552: .L xprt . ! 553: The parameter ! 554: .L in ! 555: is the address where the arguments will be placed; ! 556: .L inproc ! 557: is the XDR routine used to decode the arguments. ! 558: This routine returns one if decoding succeeds, and zero otherwise. ! 559: .SH ! 560: svc_getcaller() ! 561: .LP ! 562: .LS ! 563: struct sockaddr_in ! 564: svc_getcaller(xprt) ! 565: SVCXPRT *xprt; ! 566: .LE ! 567: The approved way of getting the network address of the caller ! 568: of a procedure associated with the RPC service transport handle, ! 569: .L xprt . ! 570: .SH ! 571: svc_getreq() ! 572: .LP ! 573: .LS ! 574: svc_getreq(rdfds) ! 575: int rdfds; ! 576: .LE ! 577: This routine is only of interest if a service implementor does not call ! 578: .L svc_run() , ! 579: but instead implements custom asynchronous event processing. ! 580: It is called when the ! 581: .L select ! 582: system call has determined that an RPC request ! 583: has arrived on some RPC socket(s); ! 584: .L rdfds ! 585: is the resultant read file descriptor bit mask. ! 586: The routine returns when all sockets associated with the value of ! 587: .L rdfds ! 588: have been serviced. ! 589: .SH ! 590: svc_register() ! 591: .LP ! 592: .LS ! 593: svc_register(xprt, prognum, versnum, dispatch, protocol) ! 594: SVCXPRT *xprt; ! 595: u_long prognum, versnum; ! 596: void (*dispatch)(); ! 597: u_long protocol; ! 598: .LE ! 599: Associates ! 600: .L prognum ! 601: and ! 602: .L versnum ! 603: with the service dispatch procedure, ! 604: .L dispatch . ! 605: If ! 606: .L protocol ! 607: is non-zero, then a mapping of the triple ! 608: .L [prognum,versnum,protocol] ! 609: to ! 610: .L xprt->xp_port ! 611: is also established with the local ! 612: .I portmap ! 613: service (generally ! 614: .L protocol ! 615: is zero, IPPROTO_UDP or IPPROTO_TCP). ! 616: The procedure ! 617: .L dispatch() ! 618: has the following form: ! 619: .LS ! 620: dispatch(request, xprt) ! 621: struct svc_req *request; ! 622: SVCXPRT *xprt; ! 623: .LE ! 624: The ! 625: .L svc_register ! 626: routine returns one if it succeeds, and zero otherwise. ! 627: .SH ! 628: svc_run() ! 629: .LP ! 630: .LS ! 631: svc_run() ! 632: .LE ! 633: This routine never returns. It waits for RPC requests to arrive ! 634: and calls the appropriate service procedure (using ! 635: .L svc_getreq ) ! 636: when one arrives. This procedure is usually waiting for a ! 637: .L select ! 638: system call to return. ! 639: .SH ! 640: svc_sendreply() ! 641: .LP ! 642: .LS ! 643: svc_sendreply(xprt, outproc, out) ! 644: SVCXPRT *xprt; ! 645: xdrproc_t outproc; ! 646: char *out; ! 647: .LE ! 648: Called by an RPC service's dispatch routine ! 649: to send the results of a remote procedure call. ! 650: The parameter ! 651: .L xprt ! 652: is the caller's associated transport handle; ! 653: .L outproc ! 654: is the XDR routine which is used to encode the results; and ! 655: .L out ! 656: is the address of the results. ! 657: This routine returns one if it succeeds, zero otherwise. ! 658: .SH ! 659: svc_unregister() ! 660: .LP ! 661: .LS ! 662: void ! 663: svc_unregister(prognum, versnum) ! 664: u_long prognum, versnum; ! 665: .LE ! 666: Removes all mapping of the double ! 667: .L [prognum,versnum] ! 668: to dispatch routines, and of the triple ! 669: .L [prognum,versnum,*] ! 670: to port number. ! 671: .SH ! 672: svcerr_auth() ! 673: .LP ! 674: .LS ! 675: void ! 676: svcerr_auth(xprt, why) ! 677: SVCXPRT *xprt; ! 678: enum auth_stat why; ! 679: .LE ! 680: Called by a service dispatch routine that refuses to perform ! 681: a remote procedure call due to an authentication error. ! 682: .SH ! 683: svcerr_decode() ! 684: .LP ! 685: .LS ! 686: void ! 687: svcerr_decode(xprt) ! 688: SVCXPRT *xprt; ! 689: .LE ! 690: Called by a service dispatch routine that can't successfully ! 691: decode its parameters. See also ! 692: .L svc_getargs() . ! 693: .SH ! 694: svcerr_noproc() ! 695: .LP ! 696: .LS ! 697: void ! 698: svcerr_noproc(xprt) ! 699: SVCXPRT *xprt; ! 700: .LE ! 701: Called by a service dispatch routine that doesn't implement ! 702: the desired procedure number the caller request. ! 703: .SH ! 704: svcerr_noprog() ! 705: .LP ! 706: .LS ! 707: void ! 708: svcerr_noprog(xprt) ! 709: SVCXPRT *xprt; ! 710: .LE ! 711: Called when the desired program is not registered with the RPC package. ! 712: Service implementors usually don't need this routine. ! 713: .SH ! 714: svcerr_progvers() ! 715: .LP ! 716: .LS ! 717: void ! 718: svcerr_progvers(xprt) ! 719: SVCXPRT *xprt; ! 720: .LE ! 721: Called when the desired version of a program is not registered ! 722: with the RPC package. ! 723: Service implementors usually don't need this routine. ! 724: .SH ! 725: svcerr_systemerr() ! 726: .LP ! 727: .LS ! 728: void ! 729: svcerr_systemerr(xprt) ! 730: SVCXPRT *xprt; ! 731: .LE ! 732: Called by a service dispatch routine when it detects a system error ! 733: not covered by any particular protocol. ! 734: For example, if a service can no longer allocate storage, ! 735: it may call this routine. ! 736: .SH ! 737: svcerr_weakauth() ! 738: .LP ! 739: .LS ! 740: void ! 741: svcerr_weakauth(xprt) ! 742: SVCXPRT *xprt; ! 743: .LE ! 744: Called by a service dispatch routine that refuses to perform ! 745: a remote procedure call due to insufficient (but correct) ! 746: authentication parameters. The routine calls ! 747: .L svcerr_auth(xprt,AUTH_TOOWEAK) . ! 748: .SH ! 749: svcraw_create() ! 750: .LP ! 751: .LS ! 752: SVCXPRT * ! 753: svcraw_create() ! 754: .LE ! 755: This routine creates a toy RPC service transport, ! 756: to which it returns a pointer. The transport ! 757: is really a buffer within the process's address space, ! 758: so the corresponding RPC client should live in the same address space; see ! 759: .L clntraw_create() . ! 760: This routine allows simulation of RPC and acquisition of RPC overheads ! 761: (such as round trip times), without any kernel interference. ! 762: This routine returns NULL if it fails. ! 763: .SH ! 764: svctcp_create() ! 765: .LP ! 766: .LS ! 767: SVCXPRT * ! 768: svctcp_create(sock, send_buf_size, recv_buf_size) ! 769: int sock; ! 770: u_int send_buf_size, recv_buf_size; ! 771: .LE ! 772: This routine creates a TCP/IP-based RPC service transport, ! 773: to which it returns a pointer. ! 774: The transport is associated with the socket ! 775: .L sock , ! 776: which may be RPC_ANYSOCK, in which case a new socket is created. ! 777: If the socket is not bound to a local TCP port, then this routine ! 778: binds it to an arbitrary port. Upon completion, ! 779: .L xprt->xp_sock ! 780: is the transport's socket number, and ! 781: .L xprt->xp_port ! 782: is the transport's port number. ! 783: This routine returns NULL if it fails. ! 784: Since TCP-based RPC uses buffered I/O, users may specify the size of the ! 785: .L send ! 786: and ! 787: .L receive ! 788: buffers; values of zero choose suitable defaults. ! 789: .SH ! 790: svcudp_create() ! 791: .LP ! 792: .LS ! 793: SVCXPRT * ! 794: svcudp_create(sock) ! 795: int sock; ! 796: .LE ! 797: This routine creates a UDP/IP-based RPC service transport, ! 798: to which it returns a pointer. ! 799: The transport is associated with the socket ! 800: .L sock , ! 801: which may be RPC_ANYSOCK, in which case a new socket is created. ! 802: If the socket is not bound to a local UDP port, then this routine ! 803: binds it to an arbitrary port. Upon completion, ! 804: .L xprt->xp_sock ! 805: is the transport's socket number, and ! 806: .L xprt->xp_port ! 807: is the transport's port number. ! 808: This routine returns NULL if it fails. ! 809: Warning: since UDP-based RPC messages can only hold up to 8 Kbytes ! 810: of encoded data, this transport cannot be used for procedures ! 811: that take large arguments or return huge results. ! 812: .SH ! 813: xdr_accepted_reply() ! 814: .LP ! 815: .LS ! 816: xdr_accepted_reply(xdrs, ar) ! 817: XDR *xdrs; ! 818: struct accepted_reply *ar; ! 819: .LE ! 820: Used for describing RPC messages, externally. ! 821: This routine is useful for users who wish to generate ! 822: RPC-style messages without using the RPC package. ! 823: .SH ! 824: xdr_array() ! 825: .LP ! 826: .LS ! 827: xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc) ! 828: XDR *xdrs; ! 829: char **arrp; ! 830: u_int *sizep, maxsize, elsize; ! 831: xdrproc_t elproc; ! 832: .LE ! 833: A filter primitive that translates between arrays ! 834: and their corresponding external representations. ! 835: The parameter ! 836: .L arrp ! 837: is the address of the pointer to the array, while ! 838: .L sizep ! 839: is the address of the element count of the array; ! 840: this element count cannot exceed ! 841: .L maxsize . ! 842: The parameter ! 843: .L elsize ! 844: is the ! 845: .L sizeof() ! 846: each of the array's elements, and ! 847: .L elproc ! 848: is an XDR filter that translates between ! 849: the array elements' C form, and their external representation. ! 850: This routine returns one if it succeeds, zero otherwise. ! 851: .SH ! 852: xdr_authunix_parms() ! 853: .LP ! 854: .LS ! 855: xdr_authunix_parms(xdrs, aupp) ! 856: XDR *xdrs; ! 857: struct authunix_parms *aupp; ! 858: .LE ! 859: Used for describing UNIX credentials, externally. ! 860: This routine is useful for users who wish to generate ! 861: these credentials without using the RPC authentication package. ! 862: .SH ! 863: xdr_bool() ! 864: .LP ! 865: .LS ! 866: xdr_bool(xdrs, bp) ! 867: XDR *xdrs; ! 868: bool_t *bp; ! 869: .LE ! 870: A filter primitive that translates between booleans (C integers) ! 871: and their external representations. ! 872: When encoding data, this filter produces values of either one or zero. ! 873: This routine returns one if it succeeds, zero otherwise. ! 874: .SH ! 875: xdr_bytes() ! 876: .LP ! 877: .LS ! 878: xdr_bytes(xdrs, sp, sizep, maxsize) ! 879: XDR *xdrs; ! 880: char **sp; ! 881: u_int *sizep, maxsize; ! 882: .LE ! 883: A filter primitive that translates between counted byte strings ! 884: and their external representations. ! 885: The parameter ! 886: .L sp ! 887: is the address of the string pointer. ! 888: The length of the string is located at address ! 889: .L sizep ; ! 890: strings cannot be longer than ! 891: .L maxsize . ! 892: This routine returns one if it succeeds, zero otherwise. ! 893: .SH ! 894: xdr_callhdr() ! 895: .LP ! 896: .LS ! 897: void ! 898: xdr_callhdr(xdrs, chdr) ! 899: XDR *xdrs; ! 900: struct rpc_msg *chdr; ! 901: .LE ! 902: Used for describing RPC messages, externally. ! 903: This routine is useful for users who wish to generate ! 904: RPC-style messages without using the RPC package. ! 905: .SH ! 906: xdr_callmsg() ! 907: .LP ! 908: .LS ! 909: xdr_callmsg(xdrs, cmsg) ! 910: XDR *xdrs; ! 911: struct rpc_msg *cmsg; ! 912: .LE ! 913: Used for describing RPC messages, externally. ! 914: This routine is useful for users who wish to generate ! 915: RPC-style messages without using the RPC package. ! 916: .SH ! 917: xdr_double() ! 918: .LP ! 919: .LS ! 920: xdr_double(xdrs, dp) ! 921: XDR *xdrs; ! 922: double *dp; ! 923: .LE ! 924: A filter primitive that translates between C ! 925: .L double ! 926: precision numbers and their external representations. ! 927: This routine returns one if it succeeds, zero otherwise. ! 928: .SH ! 929: xdr_enum() ! 930: .LP ! 931: .LS ! 932: xdr_enum(xdrs, ep) ! 933: XDR *xdrs; ! 934: enum_t *ep; ! 935: .LE ! 936: A filter primitive that translates between C ! 937: .L enum s ! 938: (actually integers) and their external representations. ! 939: This routine returns one if it succeeds, zero otherwise. ! 940: .SH ! 941: xdr_float() ! 942: .LP ! 943: .LS ! 944: xdr_float(xdrs, fp) ! 945: XDR *xdrs; ! 946: float *fp; ! 947: .LE ! 948: A filter primitive that translates between C ! 949: .L float s ! 950: and their external representations. ! 951: This routine returns one if it succeeds, zero otherwise. ! 952: .SH ! 953: xdr_inline() ! 954: .LP ! 955: .LS ! 956: long * ! 957: xdr_inline(xdrs, len) ! 958: XDR *xdrs; ! 959: int len; ! 960: .LE ! 961: A macro that invokes the in-line routine associated with the XDR stream, ! 962: .L xdrs . ! 963: The routine returns a pointer ! 964: to a contiguous piece of the stream's buffer; ! 965: .L len ! 966: is the byte length of the desired buffer. ! 967: Note that pointer is cast to ! 968: .L "long *" . ! 969: Warning: ! 970: .L xdr_inline() ! 971: may return 0 (NULL) if it cannot allocate ! 972: a contiguous piece of a buffer. ! 973: Therefore the behavior may vary among stream instances; ! 974: it exists for the sake of efficiency. ! 975: .SH ! 976: xdr_int() ! 977: .LP ! 978: .LS ! 979: xdr_int(xdrs, ip) ! 980: XDR *xdrs; ! 981: int *ip; ! 982: .LE ! 983: A filter primitive that translates between C integers ! 984: and their external representations. ! 985: This routine returns one if it succeeds, zero otherwise. ! 986: .SH ! 987: xdr_long() ! 988: .LP ! 989: .LS ! 990: xdr_long(xdrs, lp) ! 991: XDR *xdrs; ! 992: long *lp; ! 993: .LE ! 994: A filter primitive that translates between C ! 995: .L long ! 996: integers and their external representations. ! 997: This routine returns one if it succeeds, zero otherwise. ! 998: .SH ! 999: xdr_opaque() ! 1000: .LP ! 1001: .LS ! 1002: xdr_opaque(xdrs, cp, cnt) ! 1003: XDR *xdrs; ! 1004: char *cp; ! 1005: u_int cnt; ! 1006: .LE ! 1007: A filter primitive that translates between fixed size opaque data ! 1008: and its external representation. ! 1009: The parameter ! 1010: .L cp ! 1011: is the address of the opaque object, and ! 1012: .L cnt ! 1013: is its size in bytes. ! 1014: This routine returns one if it succeeds, zero otherwise. ! 1015: .SH ! 1016: xdr_opaque_auth() ! 1017: .LP ! 1018: .LS ! 1019: xdr_opaque_auth(xdrs, ap) ! 1020: XDR *xdrs; ! 1021: struct opaque_auth *ap; ! 1022: .LE ! 1023: Used for describing RPC messages, externally. ! 1024: This routine is useful for users who wish to generate ! 1025: RPC-style messages without using the RPC package. ! 1026: .SH ! 1027: xdr_pmap() ! 1028: .LP ! 1029: .LS ! 1030: xdr_pmap(xdrs, regs) ! 1031: XDR *xdrs; ! 1032: struct pmap *regs; ! 1033: .LE ! 1034: Used for describing parameters to various ! 1035: .I portmap ! 1036: procedures, externally. ! 1037: This routine is useful for users who wish to generate ! 1038: these parameters without using the ! 1039: .L pmap ! 1040: interface. ! 1041: .SH ! 1042: xdr_pmaplist() ! 1043: .LP ! 1044: .LS ! 1045: xdr_pmaplist(xdrs, rp) ! 1046: XDR *xdrs; ! 1047: struct pmaplist **rp; ! 1048: .LE ! 1049: Used for describing a list of port mappings, externally. ! 1050: This routine is useful for users who wish to generate ! 1051: these parameters without using the ! 1052: .L pmap ! 1053: interface. ! 1054: .SH ! 1055: xdr_reference() ! 1056: .LP ! 1057: .LS ! 1058: xdr_reference(xdrs, pp, size, proc) ! 1059: XDR *xdrs; ! 1060: char **pp; ! 1061: u_int size; ! 1062: xdrproc_t proc; ! 1063: .LE ! 1064: A primitive that provides pointer chasing within structures. ! 1065: The parameter ! 1066: .L pp ! 1067: is the address of the pointer; ! 1068: .L size ! 1069: is the ! 1070: .L sizeof() ! 1071: the structure that ! 1072: .L *pp ! 1073: points to; and ! 1074: .L proc ! 1075: is an XDR procedure that filters the structure ! 1076: between its C form and its external representation. ! 1077: This routine returns one if it succeeds, zero otherwise. ! 1078: .SH ! 1079: xdr_rejected_reply() ! 1080: .LP ! 1081: .LS ! 1082: xdr_rejected_reply(xdrs, rr) ! 1083: XDR *xdrs; ! 1084: struct rejected_reply *rr; ! 1085: .LE ! 1086: Used for describing RPC messages, externally. ! 1087: This routine is useful for users who wish to generate ! 1088: RPC-style messages without using the RPC package. ! 1089: .SH ! 1090: xdr_replymsg() ! 1091: .LP ! 1092: .LS ! 1093: xdr_replymsg(xdrs, rmsg) ! 1094: XDR *xdrs; ! 1095: struct rpc_msg *rmsg; ! 1096: .LE ! 1097: Used for describing RPC messages, externally. ! 1098: This routine is useful for users who wish to generate ! 1099: RPC style messages without using the RPC package. ! 1100: .SH ! 1101: xdr_short() ! 1102: .LP ! 1103: .LS ! 1104: xdr_short(xdrs, sp) ! 1105: XDR *xdrs; ! 1106: short *sp; ! 1107: .LE ! 1108: A filter primitive that translates between C ! 1109: .L short ! 1110: integers and their external representations. ! 1111: This routine returns one if it succeeds, zero otherwise. ! 1112: .SH ! 1113: xdr_string() ! 1114: .LP ! 1115: .LS ! 1116: xdr_string(xdrs, sp, maxsize) ! 1117: XDR *xdrs; ! 1118: char **sp; ! 1119: u_int maxsize; ! 1120: .LE ! 1121: A filter primitive that translates between C strings and their ! 1122: corresponding external representations. ! 1123: Strings cannot cannot be longer than ! 1124: .L maxsize . ! 1125: Note that ! 1126: .L sp ! 1127: is the address of the string's pointer. ! 1128: This routine returns one if it succeeds, zero otherwise. ! 1129: .SH ! 1130: xdr_u_int() ! 1131: .LP ! 1132: .LS ! 1133: xdr_u_int(xdrs, up) ! 1134: XDR *xdrs; ! 1135: unsigned *up; ! 1136: .LE ! 1137: A filter primitive that translates between C ! 1138: .L unsigned ! 1139: integers and their external representations. ! 1140: This routine returns one if it succeeds, zero otherwise. ! 1141: .SH ! 1142: xdr_u_long() ! 1143: .LP ! 1144: .LS ! 1145: xdr_u_long(xdrs, ulp) ! 1146: XDR *xdrs; ! 1147: unsigned long *ulp; ! 1148: .LE ! 1149: A filter primitive that translates between C ! 1150: .L "unsigned long" ! 1151: integers and their external representations. ! 1152: This routine returns one if it succeeds, zero otherwise. ! 1153: .SH ! 1154: xdr_u_short() ! 1155: .LP ! 1156: .LS ! 1157: xdr_u_short(xdrs, usp) ! 1158: XDR *xdrs; ! 1159: unsigned short *usp; ! 1160: .LE ! 1161: A filter primitive that translates between C ! 1162: .L "unsigned short" ! 1163: integers and their external representations. ! 1164: This routine returns one if it succeeds, zero otherwise. ! 1165: .SH ! 1166: xdr_union() ! 1167: .LP ! 1168: .LS ! 1169: xdr_union(xdrs, dscmp, unp, choices, dfault) ! 1170: XDR *xdrs; ! 1171: int *dscmp; ! 1172: char *unp; ! 1173: struct xdr_discrim *choices; ! 1174: xdrproc_t dfault; ! 1175: .LE ! 1176: A filter primitive that translates between a discriminated C ! 1177: .L union ! 1178: and its corresponding external representation. The parameter ! 1179: .L dscmp ! 1180: is the address of the union's discriminant, while ! 1181: .L unp ! 1182: in the address of the union. ! 1183: This routine returns one if it succeeds, zero otherwise. ! 1184: .SH ! 1185: xdr_void() ! 1186: .LP ! 1187: .LS ! 1188: xdr_void() ! 1189: .LE ! 1190: This routine always returns one. ! 1191: .SH ! 1192: xdr_wrapstring() ! 1193: .LP ! 1194: .LS ! 1195: xdr_wrapstring(xdrs, sp) ! 1196: XDR *xdrs; ! 1197: char **sp; ! 1198: .LE ! 1199: A primitive that calls ! 1200: .L xdr_string(xdrs,sp,MAXUNSIGNED); ! 1201: where MAXUNSIGNED is the maximum value of an unsigned integer. ! 1202: This is handy because the RPC package passes ! 1203: only two parameters XDR routines, whereas ! 1204: .L xdr_string() , ! 1205: one of the most frequently used primitives, requires three parameters. ! 1206: This routine returns one if it succeeds, zero otherwise. ! 1207: .SH ! 1208: xprt_register() ! 1209: .LP ! 1210: .LS ! 1211: void ! 1212: xprt_register(xprt) ! 1213: SVCXPRT *xprt; ! 1214: .LE ! 1215: After RPC service transport handles are created, ! 1216: they should register themselves with the RPC service package. ! 1217: This routine modifies the global variable ! 1218: .L svc_fds . ! 1219: Service implementors usually don't need this routine. ! 1220: .SH ! 1221: xprt_unregister() ! 1222: .LP ! 1223: .LS ! 1224: void ! 1225: xprt_unregister(xprt) ! 1226: SVCXPRT *xprt; ! 1227: .LE ! 1228: Before an RPC service transport handle is destroyed, ! 1229: it should unregister itself with the RPC service package. ! 1230: This routine modifies the global variable ! 1231: .L svc_fds . ! 1232: Service implementors usually don't need this routine.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.