rfc1057.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

Sun Microsystems                                               [Page 19]

RFC 1057            Remote Procedure Call, Version 2           June 1988


11.1 An Example Service Described in the RPC Language

   Here is an example of the specification of a simple ping program.

      program PING_PROG {
            /*
             * Latest and greatest version
             */
            version PING_VERS_PINGBACK {
               void
               PINGPROC_NULL(void) = 0;

               /*
                * Ping the client, return the round-trip time
                * (in microseconds). Returns -1 if the operation
                * timed out.
                */
               int
               PINGPROC_PINGBACK(void) = 1;
            } = 2;

            /*
             * Original version
             */
            version PING_VERS_ORIG {
               void
               PINGPROC_NULL(void) = 0;
            } = 1;
         } = 1;

         const PING_VERS = 2;      /* latest version */

   The first version described is PING_VERS_PINGBACK with two
   procedures, PINGPROC_NULL and PINGPROC_PINGBACK.  PINGPROC_NULL takes
   no arguments and returns no results, but it is useful for computing
   round-trip times from the client to the server and back again.  By
   convention, procedure 0 of any RPC protocol should have the same
   semantics, and never require any kind of authentication.  The second
   procedure is used for the client to have the server do a reverse ping
   operation back to the client, and it returns the amount of time (in
   microseconds) that the operation used.  The next version,
   PING_VERS_ORIG, is the original version of the protocol and it does
   not contain PINGPROC_PINGBACK procedure. It is useful for
   compatibility with old client programs, and as this program matures
   it may be dropped from the protocol entirely.






Sun Microsystems                                               [Page 20]

RFC 1057            Remote Procedure Call, Version 2           June 1988


11.2 The RPC Language Specification

   The RPC language is identical to the XDR language defined in RFC
   1014, except for the added definition of a "program-def" described
   below.

   program-def:
      "program" identifier "{"
         version-def
         version-def *
      "}" "=" constant ";"

   version-def:
      "version" identifier "{"
          procedure-def
          procedure-def *
      "}" "=" constant ";"

   procedure-def:
      type-specifier identifier "(" type-specifier
        ("," type-specifier )* ")" "=" constant ";"

11.3 Syntax Notes

   (1) The following keywords are added and cannot be used as
   identifiers: "program" and "version";

   (2) A version name cannot occur more than once within the scope of a
   program definition. Nor can a version number occur more than once
   within the scope of a program definition.

   (3) A procedure name cannot occur more than once within the scope of
   a version definition. Nor can a procedure number occur more than once
   within the scope of version definition.

   (4) Program identifiers are in the same name space as constant and
   type identifiers.

   (5) Only unsigned constants can be assigned to programs, versions and
   procedures.











Sun Microsystems                                               [Page 21]

RFC 1057            Remote Procedure Call, Version 2           June 1988


APPENDIX A: PORT MAPPER PROGRAM PROTOCOL

   The port mapper program maps RPC program and version numbers to
   transport-specific port numbers.  This program makes dynamic binding
   of remote programs possible.

   This is desirable because the range of reserved port numbers is very
   small and the number of potential remote programs is very large.  By
   running only the port mapper on a reserved port, the port numbers of
   other remote programs can be ascertained by querying the port mapper.

   The port mapper also aids in broadcast RPC.  A given RPC program will
   usually have different port number bindings on different machines, so
   there is no way to directly broadcast to all of these programs. The
   port mapper, however, does have a fixed port number.  So, to
   broadcast to a given program, the client actually sends its message
   to the port mapper located at the broadcast address. Each port mapper
   that picks up the broadcast then calls the local service specified by
   the client.  When the port mapper gets the reply from the local
   service, it sends the reply on back to the client.

A.1 Port Mapper Protocol Specification (in RPC Language)

         const PMAP_PORT = 111;      /* portmapper port number */

   A mapping of (program, version, protocol) to port number:

         struct mapping {
            unsigned int prog;
            unsigned int vers;
            unsigned int prot;
            unsigned int port;
         };

   Supported values for the "prot" field:

         const IPPROTO_TCP = 6;      /* protocol number for TCP/IP */
         const IPPROTO_UDP = 17;     /* protocol number for UDP/IP */

   A list of mappings:

         struct *pmaplist {
            mapping map;
            pmaplist next;
         };






Sun Microsystems                                               [Page 22]

RFC 1057            Remote Procedure Call, Version 2           June 1988


   Arguments to callit:

         struct call_args {
            unsigned int prog;
            unsigned int vers;
            unsigned int proc;
            opaque args<>;
         };

   Results of callit:

         struct call_result {
            unsigned int port;
            opaque res<>;
         };

   Port mapper procedures:

         program PMAP_PROG {
            version PMAP_VERS {
               void
               PMAPPROC_NULL(void)         = 0;

               bool
               PMAPPROC_SET(mapping)       = 1;

               bool
               PMAPPROC_UNSET(mapping)     = 2;

               unsigned int
               PMAPPROC_GETPORT(mapping)   = 3;

               pmaplist
               PMAPPROC_DUMP(void)         = 4;

               call_result
               PMAPPROC_CALLIT(call_args)  = 5;
            } = 2;
         } = 100000;

A.2 Port Mapper Operation

   The portmapper program currently supports two protocols (UDP and
   TCP).  The portmapper is contacted by talking to it on assigned port
   number 111 (SUNRPC) on either of these protocols.






Sun Microsystems                                               [Page 23]

RFC 1057            Remote Procedure Call, Version 2           June 1988


   The following is a description of each of the portmapper procedures:

   PMAPPROC_NULL:

   This procedure does no work.  By convention, procedure zero of any
   protocol takes no parameters and returns no results.

   PMAPPROC_SET:

   When a program first becomes available on a machine, it registers
   itself with the port mapper program on the same machine.  The program
   passes its program number "prog", version number "vers", transport
   protocol number "prot", and the port "port" on which it awaits
   service request.  The procedure returns a boolean reply whose value
   is "TRUE" if the procedure successfully established the mapping and
   "FALSE" otherwise.  The procedure refuses to establish a mapping if
   one already exists for the tuple "(prog, vers, prot)".

   PMAPPROC_UNSET:

   When a program becomes unavailable, it should unregister itself with
   the port mapper program on the same machine.  The parameters and
   results have meanings identical to those of "PMAPPROC_SET".  The
   protocol and port number fields of the argument are ignored.

   PMAPPROC_GETPORT:

   Given a program number "prog", version number "vers", and transport
   protocol number "prot", this procedure returns the port number on
   which the program is awaiting call requests.  A port value of zeros
   means the program has not been registered.  The "port" field of the
   argument is ignored.

   PMAPPROC_DUMP:

   This procedure enumerates all entries in the port mapper's database.
   The procedure takes no parameters and returns a list of program,
   version, protocol, and port values.

   PMAPPROC_CALLIT:

   This procedure allows a client to call another remote procedure on
   the same machine without knowing the remote procedure's port number.
   It is intended for supporting broadcasts to arbitrary remote programs
   via the well-known port mapper's port.  The parameters "prog",
   "vers", "proc", and the bytes of "args" are the program number,
   version number, procedure number, and parameters of the remote
   procedure.  Note:



Sun Microsystems                                               [Page 24]

RFC 1057            Remote Procedure Call, Version 2           June 1988


   (1) This procedure only sends a reply if the procedure was
   successfully executed and is silent (no reply) otherwise.

   (2) The port mapper communicates with the remote program using UDP
   only.

   The procedure returns the remote program's port number, and the reply
   is the reply of the remote procedure.

REFERENCES

   [1] Birrell, A. D.  & Nelson, B. J., "Implementing Remote Procedure
       Calls", XEROX CSL-83-7, October 1983.

   [2] Cheriton, D., "VMTP: Versatile Message Transaction Protocol",
       Preliminary Version 0.3, Stanford University, January 1987.

   [3] Diffie & Hellman, "New Directions in Cryptography", IEEE
       Transactions on Information Theory IT-22, November 1976.

   [4] Mills, D., "Network Time Protocol", RFC-958, M/A-COM Linkabit,
       September 1985.

   [5] National Bureau of Standards, "Data Encryption Standard", Federal
       Information Processing Standards Publication 46, January 1977.

   [6] Postel, J., "Transmission Control Protocol - DARPA Internet
       Program Protocol Specification", RFC-793, Information Sciences
       Institute, September 1981.

   [7] Postel, J., "User Datagram Protocol", RFC-768, Information
       Sciences Institute, August 1980.

   [8] Reynolds, J., and Postel, J., "Assigned Numbers", RFC-1010,
       Information Sciences Institute, May 1987.

   [9] Sun Microsystems, "XDR: External Data Representation Standard",
       RFC-1014, June 1987.













Sun Microsystems                                               [Page 25]