rfc1832.html

this gives details of the network programming

   be unfair to somebody.  Many architectures, such as the Motorola
   68000* and IBM 370*, support the big-endian byte-order.

   (4) Why is the XDR unit four bytes wide?

   There is a tradeoff in choosing the XDR unit size.  Choosing a small
   size such as two makes the encoded data small, but causes alignment
   problems for machines that aren't aligned on these boundaries.  A
   large size such as eight means the data will be aligned on virtually
   every machine, but causes the encoded data to grow too big.  We chose
   four as a compromise.  Four is big enough to support most
   architectures efficiently, except for rare machines such as the
   eight-byte aligned Cray*.  Four is also small enough to keep the
   encoded data restricted to a reasonable size.

   (5) Why must variable-length data be padded with zeros?

   It is desirable that the same data encode into the same thing on all
   machines, so that encoded data can be meaningfully compared or
   checksummed.  Forcing the padded bytes to be zero ensures this.

   (6) Why is there no explicit data-typing?

   Data-typing has a relatively high cost for what small advantages it
   may have.  One cost is the expansion of data due to the inserted type
   fields.  Another is the added cost of interpreting these type fields
   and acting accordingly.  And most protocols already know what type
   they expect, so data-typing supplies only redundant information.
   However, one can still get the benefits of data-typing using XDR. One
   way is to encode two things: first a string which is the XDR data
   description of the encoded data, and then the encoded data itself.
   Another way is to assign a value to all the types in XDR, and then
   define a universal type which takes this value as its discriminant
   and for each value, describes the corresponding data type.

5. THE XDR LANGUAGE SPECIFICATION

5.1 Notational Conventions

   This specification uses an extended Back-Naur Form notation for
   describing the XDR language.  Here is a brief description of the
    notation:

   (1) The characters '|', '(', ')', '[', ']', '"', and '*' are special.
   (2) Terminal symbols are strings of any characters surrounded by
   double quotes.  (3) Non-terminal symbols are strings of non-special
   characters.  (4) Alternative items are separated by a vertical bar
   ("|").  (5) Optional items are enclosed in brackets.  (6) Items are
   grouped together by enclosing them in parentheses.  (7) A '*'
   following an item means 0 or more occurrences of that item.

   For example,  consider  the  following pattern:

         "a " "very" (", " "very")* [" cold " "and "]  " rainy "
         ("day" | "night")

   An infinite number of strings match this pattern. A few of them are:

         "a very rainy day"
         "a very, very rainy day"
         "a very cold and  rainy day"
         "a very, very, very cold and  rainy night"

5.2 Lexical Notes

   (1) Comments begin with '/*' and terminate with '*/'.  (2) White
   space serves to separate items and is otherwise ignored.  (3) An
   identifier is a letter followed by an optional sequence of letters,
   digits or underbar ('_'). The case of identifiers is not ignored.
   (4) A constant is a sequence of one or more decimal digits,
   optionally preceded by a minus-sign ('-').

5.3 Syntax Information

      declaration:
           type-specifier identifier
         | type-specifier identifier "[" value "]"
         | type-specifier identifier "<" [ value ] ">"
         | "opaque" identifier "[" value "]"
         | "opaque" identifier "<" [ value ] ">"
         | "string" identifier "<" [ value ] ">"
         | type-specifier "*" identifier
         | "void"

      value:
           constant
         | identifier

      type-specifier:
           [ "unsigned" ] "int"
         | [ "unsigned" ] "hyper"
         | "float"
         | "double"
         | "quadruple"
         | "bool"
         | enum-type-spec
         | struct-type-spec
         | union-type-spec
         | identifier

      enum-type-spec:
         "enum" enum-body

      enum-body:
         "{"
            ( identifier "=" value )
            ( "," identifier "=" value )*
         "}"

      struct-type-spec:
         "struct" struct-body

      struct-body:
         "{"
            ( declaration ";" )
            ( declaration ";" )*
         "}"

      union-type-spec:
         "union" union-body

      union-body:
         "switch" "(" declaration ")" "{"
            ( "case" value ":" declaration ";" )
            ( "case" value ":" declaration ";" )*
            [ "default" ":" declaration ";" ]
         "}"

      constant-def:
         "const" identifier "=" constant ";"

      type-def:
           "typedef" declaration ";"
         | "enum" identifier enum-body ";"
         | "struct" identifier struct-body ";"
         | "union" identifier union-body ";"

      definition:
           type-def
         | constant-def

      specification:
           definition *

5.4 Syntax Notes

   (1) The following are keywords and cannot be used as identifiers:
   "bool", "case", "const", "default", "double", "quadruple", "enum",
   "float", "hyper", "opaque", "string", "struct", "switch", "typedef",
   "union", "unsigned" and "void".

   (2) Only unsigned constants may be used as size specifications for
   arrays.  If an identifier is used, it must have been declared
   previously as an unsigned constant in a "const" definition.

   (3) Constant and type identifiers within the scope of a specification
   are in the same name space and must be declared uniquely within this
   scope.

   (4) Similarly, variable names must be unique within the scope of
   struct and union declarations. Nested struct and union declarations
   create new scopes.

   (5) The discriminant of a union must be of a type that evaluates to
   an integer. That is, "int", "unsigned int", "bool", an enumerated
   type or any typedefed type that evaluates to one of these is legal.
   Also, the case values must be one of the legal values of the
   discriminant.  Finally, a case value may not be specified more than
   once within the scope of a union declaration.

6. AN EXAMPLE OF AN XDR DATA DESCRIPTION

   Here is a short XDR data description of a thing called a "file",
   which might be used to transfer files from one machine to another.

         const MAXUSERNAME = 32;     /* max length of a user name */
         const MAXFILELEN = 65535;   /* max length of a file      */
         const MAXNAMELEN = 255;     /* max length of a file name */

         /*
          * Types of files:
          */
         enum filekind {
            TEXT = 0,       /* ascii data */
            DATA = 1,       /* raw data   */
            EXEC = 2        /* executable */
         };

         /*
          * File information, per kind of file:
          */
         union filetype switch (filekind kind) {
         case TEXT:
            void;                           /* no extra information */
         case DATA:
            string creator<MAXNAMELEN>;     /* data creator         */
         case EXEC:
            string interpretor<MAXNAMELEN>; /* program interpretor  */
         };

         /*
          * A complete file:
          */
         struct file {
            string filename<MAXNAMELEN>; /* name of file    */
            filetype type;               /* info about file */
            string owner<MAXUSERNAME>;   /* owner of file   */
            opaque data<MAXFILELEN>;     /* file data       */
         };

   Suppose now that there is a user named "john" who wants to store his
   lisp program "sillyprog" that contains just the data "(quit)".  His
   file would be encoded as follows:

       OFFSET  HEX BYTES       ASCII    COMMENTS
       ------  ---------       -----    --------
        0      00 00 00 09     ....     -- length of filename = 9
        4      73 69 6c 6c     sill     -- filename characters
        8      79 70 72 6f     ypro     -- ... and more characters ...
       12      67 00 00 00     g...     -- ... and 3 zero-bytes of fill
       16      00 00 00 02     ....     -- filekind is EXEC = 2
       20      00 00 00 04     ....     -- length of interpretor = 4
       24      6c 69 73 70     lisp     -- interpretor characters
       28      00 00 00 04     ....     -- length of owner = 4
       32      6a 6f 68 6e     john     -- owner characters
       36      00 00 00 06     ....     -- length of file data = 6
       40      28 71 75 69     (qui     -- file data bytes ...
       44      74 29 00 00     t)..     -- ... and 2 zero-bytes of fill

7. TRADEMARKS AND OWNERS

         SUN WORKSTATION  Sun Microsystems, Inc.
         VAX              Digital Equipment Corporation
         IBM-PC           International Business Machines Corporation
         Cray             Cray Research
         NFS              Sun Microsystems, Inc.
         Ethernet         Xerox Corporation.
         Motorola 68000   Motorola, Inc.
         IBM 370          International Business Machines Corporation

APPENDIX A: ANSI/IEEE Standard 754-1985

   The definition of NaNs, signed zero and infinity, and denormalized
   numbers from [3] is reproduced here for convenience.  The definitions
   for quadruple-precision floating point numbers are analogs of those
   for single and double-precision floating point numbers, and are
   defined in [3].

   In the following, 'S' stands for the sign bit, 'E' for the exponent,
   and 'F' for the fractional part.  The symbol 'u' stands for an
   undefined bit (0 or 1).

   For single-precision floating point numbers:

    Type                  S (1 bit)   E (8 bits)    F (23 bits)
    ----                  ---------   ----------    -----------
    signalling NaN        u           255 (max)     .0uuuuu---u
                                                    (with at least
                                                     one 1 bit)
    quiet NaN             u           255 (max)     .1uuuuu---u

    negative infinity     1           255 (max)     .000000---0

    positive infinity     0           255 (max)     .000000---0

    negative zero         1           0             .000000---0

    positive zero         0           0             .000000---0

For double-precision floating point numbers:

    Type                  S (1 bit)   E (11 bits)   F (52 bits)
    ----                  ---------   -----------   -----------
    signalling NaN        u           2047 (max)    .0uuuuu---u
                                                    (with at least
                                                     one 1 bit)
    quiet NaN             u           2047 (max)    .1uuuuu---u

    negative infinity     1           2047 (max)    .000000---0

    positive infinity     0           2047 (max)    .000000---0

    negative zero         1           0             .000000---0

    positive zero         0           0             .000000---0

For quadruple-precision floating point numbers:

    Type                  S (1 bit)   E (15 bits)   F (112 bits)
    ----                  ---------   -----------   ------------
    signalling NaN        u           32767 (max)   .0uuuuu---u
                                                    (with at least
                                                     one 1 bit)
    quiet NaN             u           32767 (max)   .1uuuuu---u

    negative infinity     1           32767 (max)   .000000---0

    positive infinity     0           32767 (max)   .000000---0

    negative zero         1           0             .000000---0

    positive zero         0           0             .000000---0

Subnormal numbers are represented as follows:

    Precision            Exponent       Value
    ---------            --------       -----
    Single               0              (-1)**S * 2**(-126) * 0.F

    Double               0              (-1)**S * 2**(-1022) * 0.F

    Quadruple            0              (-1)**S * 2**(-16382) * 0.F

APPENDIX B: REFERENCES

   [1]  Brian W. Kernighan & Dennis M. Ritchie, "The C Programming
        Language", Bell Laboratories, Murray Hill, New Jersey, 1978.

   [2]  Danny Cohen, "On Holy Wars and a Plea for Peace", IEEE Computer,
        October 1981.

   [3]  "IEEE Standard for Binary Floating-Point Arithmetic", ANSI/IEEE
        Standard 754-1985, Institute of Electrical and Electronics
        Engineers, August 1985.

   [4]  "Courier: The Remote Procedure Call Protocol", XEROX
        Corporation, XSIS 038112, December 1981.

   [5]  "The SPARC Architecture Manual: Version 8", Prentice Hall,
        ISBN 0-13-825001-4.

   [6]  "HP Precision Architecture Handbook", June 1987, 5954-9906.

   [7]  Srinivasan, R., "Remote Procedure Call Protocol Version 2",
        <A HREF="../../../../../www.faqs.org/rfcs/rfc1831.html">RFC 1831</A>, Sun Microsystems, Inc., August 1995.

Security Considerations

   Security issues are not discussed in this memo.

Author's Address

   Raj Srinivasan
   Sun Microsystems, Inc.
   ONC Technologies
   2550 Garcia Avenue
   M/S MTV-5-40
   Mountain View, CA  94043
   USA

   Phone: [phone]
   Fax:   [phone]
   EMail: <A HREF="mailto:[e-mail]">[e-mail]</A>

</PRE>
<P ALIGN=CENTER><IMG SRC="../../../../images/clrbar.gif" HEIGHT=2 WIDTH=500 ALT="---"></P>
<P ALIGN=CENTER>[ <A HREF="../../../../rfcs/index.html">Index</A> | 
<A HREF="../../../../rfcs/rfcsearch.html">Search</A> | 
<A HREF="../../../../rfcs/changed.html">What's New</A> | 
<A HREF="mailto:[e-mail]">Comments</A> | 
<A HREF="../../../../rfcs/rfchelp.html">Help</A> ]</P>
<SMALL>
<ADDRESS>
<P ALIGN=CENTER>
Comments/Questions about this archive ? Send mail to <A NAME=name HREF="mailto:[e-mail]">[e-mail]</A>
</P>
</ADDRESS>
</SMALL>
</BODY>
</HTML>