.\".\"  Must use -- tbl -- with this one.\".\" @(#)xdr.rfc.ms	2.2 88/08/05 4.0 RPCSRC.de BT.if \\n%=1 .tl ''- % -''...ND.\" prevent excess underlining in nroff.if n .fp 2 R.OH 'External Data Representation Standard''Page %'.EH 'Page %''External Data Representation Standard'.IX "External Data Representation".if \\n%=1 .bp.SH\&External Data Representation Standard: Protocol Specification.IX XDR RFC.IX XDR "protocol specification".LP.NH 0\&Status of this Standard.nr OF 1.IX XDR "RFC status".LPNote: This chapter specifies a protocol that Sun Microsystems, Inc., and others are using.  It has been designated RFC1014 by the ARPA NetworkInformation Center..NH 1Introduction\&.LPXDR is a standard for the description and encoding of data.  It isuseful for transferring data between different computerarchitectures, and has been used to communicate data between suchdiverse machines as the Sun Workstation, VAX, IBM-PC, and Cray.XDR fits into the ISO presentation layer, and is roughly analogous inpurpose to X.409, ISO Abstract Syntax Notation.  The major differencebetween these two is that XDR uses implicit typing, while X.409 usesexplicit typing..LPXDR uses a language to describe data formats.  The language can onlybe used only to describe data; it is not a programming language.This language allows one to describe intricate data formats in aconcise manner. The alternative of using graphical representations(itself an informal language) quickly becomes incomprehensible whenfaced with complexity.  The XDR language itself is similar to the Clanguage [1], just as Courier [4] is similar to Mesa. Protocols suchas Sun RPC (Remote Procedure Call) and the NFS (Network File System)use XDR to describe the format of their data..LPThe XDR standard makes the following assumption: that bytes (oroctets) are portable, where a byte is defined to be 8 bits of data.A given hardware device should encode the bytes onto the variousmedia in such a way that other hardware devices may decode the byteswithout loss of meaning.  For example, the Ethernet standardsuggests that bytes be encoded in "little-endian" style [2], or leastsignificant bit first..NH 2\&Basic Block Size.IX XDR "basic block size".IX XDR "block size".LPThe representation of all items requires a multiple of four bytes (or32 bits) of data.  The bytes are numbered 0 through n-1.  The bytesare read or written to some byte stream such that byte m alwaysprecedes byte m+1.  If the n bytes needed to contain the data are nota multiple of four, then the n bytes are followed by enough (0 to 3)residual zero bytes, r, to make the total byte count a multiple of 4..LPWe include the familiar graphic box notation for illustration andcomparison.  In most illustrations, each box (delimited by a plussign at the 4 corners and vertical bars and dashes) depicts a byte.Ellipses (...) between boxes show zero or more additional bytes whererequired..ie t .DS.el .DS L\fIA Block\fP\f(CW+--------+--------+...+--------+--------+...+--------+| byte 0 | byte 1 |...|byte n-1|    0   |...|    0   |+--------+--------+...+--------+--------+...+--------+|<-----------n bytes---------->|<------r bytes------>||<-----------n+r (where (n+r) mod 4 = 0)>----------->|\fP.DE.NH 1\&XDR Data Types.IX XDR "data types".IX "XDR data types".LPEach of the sections that follow describes a data type defined in theXDR standard, shows how it is declared in the language, and includesa graphic illustration of its encoding..LPFor each data type in the language we show a general paradigmdeclaration.  Note that angle brackets (< and >) denotevariable length sequences of data and square brackets ([ and ]) denotefixed-length sequences of data.  "n", "m" and "r" denote integers.For the full language specification and more formal definitions ofterms such as "identifier" and "declaration", refer to.I "The XDR Language Specification" ,below..LPFor some data types, more specific examples are included.  A more extensive example of a data description is in.I "An Example of an XDR Data Description"below..NH 2\&Integer.IX XDR integer.LPAn XDR signed integer is a 32-bit datum that encodes an integer inthe range [-2147483648,2147483647].  The integer is represented intwo's complement notation.  The most and least significant bytes are0 and 3, respectively.  Integers are declared as follows:.ie t .DS.el .DS L\fIInteger\fP\f(CW(MSB)                   (LSB)+-------+-------+-------+-------+|byte 0 |byte 1 |byte 2 |byte 3 |+-------+-------+-------+-------+<------------32 bits------------>\fP.DE.NH 2\&Unsigned Integer.IX XDR "unsigned integer".IX XDR "integer, unsigned".LPAn XDR unsigned integer is a 32-bit datum that encodes a nonnegativeinteger in the range [0,4294967295].  It is represented by anunsigned binary number whose most and least significant bytes are 0and 3, respectively.  An unsigned integer is declared as follows:.ie t .DS.el .DS L\fIUnsigned Integer\fP\f(CW(MSB)                   (LSB)+-------+-------+-------+-------+|byte 0 |byte 1 |byte 2 |byte 3 |+-------+-------+-------+-------+<------------32 bits------------>\fP.DE.NH 2\&Enumeration.IX XDR enumeration.LPEnumerations have the same representation as signed integers.Enumerations are handy for describing subsets of the integers.Enumerated data is declared as follows:.ft CW.DSenum { name-identifier = constant, ... } identifier;.DEFor example, the three colors red, yellow, and blue could bedescribed by an enumerated type:.DS.ft CWenum { RED = 2, YELLOW = 3, BLUE = 5 } colors;.DEIt is an error to encode as an enum any other integer than those thathave been given assignments in the enum declaration..NH 2\&Boolean.IX XDR boolean.LPBooleans are important enough and occur frequently enough to warranttheir own explicit type in the standard.  Booleans are declared asfollows:.DS.ft CWbool identifier;.DEThis is equivalent to:.DS.ft CWenum { FALSE = 0, TRUE = 1 } identifier;.DE.NH 2\&Hyper Integer and Unsigned Hyper Integer.IX XDR "hyper integer".IX XDR "integer, hyper".LPThe standard also defines 64-bit (8-byte) numbers called hyperinteger and unsigned hyper integer.  Their representations are theobvious extensions of integer and unsigned integer defined above.They are represented in two's complement notation.  The most andleast significant bytes are 0 and 7, respectively.  Theirdeclarations:.ie t .DS.el .DS L\fIHyper Integer\fP\fIUnsigned Hyper Integer\fP\f(CW(MSB)                                                   (LSB)+-------+-------+-------+-------+-------+-------+-------+-------+|byte 0 |byte 1 |byte 2 |byte 3 |byte 4 |byte 5 |byte 6 |byte 7 |+-------+-------+-------+-------+-------+-------+-------+-------+<----------------------------64 bits---------------------------->\fP.DE.NH 2\&Floating-point.IX XDR "integer, floating point".IX XDR "floating-point integer".LPThe standard defines the floating-point data type "float" (32 bits or4 bytes).  The encoding used is the IEEE standard for normalizedsingle-precision floating-point numbers [3].  The following threefields describe the single-precision floating-point number:.RS.IP \fBS\fP:The sign of the number.  Values 0 and  1 represent  positive andnegative, respectively.  One bit..IP \fBE\fP:The exponent of the number, base 2.  8  bits are devoted to thisfield.  The exponent is biased by 127..IP \fBF\fP:The fractional part of the number's mantissa,  base 2.   23 bitsare devoted to this field..RE.LPTherefore, the floating-point number is described by:.DS(-1)**S * 2**(E-Bias) * 1.F.DEIt is declared as follows:.ie t .DS.el .DS L\fISingle-Precision Floating-Point\fP\f(CW+-------+-------+-------+-------+|byte 0 |byte 1 |byte 2 |byte 3 |S|   E   |           F          |+-------+-------+-------+-------+1|<- 8 ->|<-------23 bits------>|<------------32 bits------------>\fP.DEJust as the most and least significant bytes of a number are 0 and 3,the most and least significant bits of a single-precision floating-point number are 0 and 31.  The beginning bit (and most significantbit) offsets of S, E, and F are 0, 1, and 9, respectively.  Note thatthese numbers refer to the mathematical positions of the bits, andNOT to their actual physical locations (which vary from medium tomedium)..LPThe IEEE specifications should be consulted concerning the encodingfor signed zero, signed infinity (overflow), and denormalized numbers(underflow) [3].  According to IEEE specifications, the "NaN" (not anumber) is system dependent and should not be used externally..NH 2\&Double-precision Floating-point.IX XDR "integer, double-precision floating point".IX XDR "double-precision floating-point integer".LPThe standard defines the encoding for the double-precision floating-point data type "double" (64 bits or 8 bytes).  The encoding used isthe IEEE standard for normalized double-precision floating-pointnumbers [3].  The standard encodes the following three fields, whichdescribe the double-precision floating-point number:.RS.IP \fBS\fP:The sign of the number.  Values  0 and 1  represent positive andnegative, respectively.  One bit..IP \fBE\fP:The exponent of the number, base 2.  11 bits are devoted to thisfield.  The exponent is biased by 1023..IP \fBF\fP:The fractional part of the number's  mantissa, base 2.   52 bitsare devoted to this field..RE.LPTherefore, the floating-point number is described by:.DS(-1)**S * 2**(E-Bias) * 1.F.DEIt is declared as follows:.ie t .DS.el .DS L\fIDouble-Precision Floating-Point\fP\f(CW+------+------+------+------+------+------+------+------+|byte 0|byte 1|byte 2|byte 3|byte 4|byte 5|byte 6|byte 7|S|    E   |                    F                        |+------+------+------+------+------+------+------+------+1|<--11-->|<-----------------52 bits------------------->|<-----------------------64 bits------------------------->\fP.DEJust as the most and least significant bytes of a number are 0 and 3,the most and least significant bits of a double-precision floating-point number are 0 and 63.  The beginning bit (and most significantbit) offsets of S, E , and F are 0, 1, and 12, respectively.  Notethat these numbers refer to the mathematical positions of the bits,and NOT to their actual physical locations (which vary from medium tomedium)..LPThe IEEE specifications should be consulted concerning the encodingfor signed zero, signed infinity (overflow), and denormalized numbers(underflow) [3].  According to IEEE specifications, the "NaN" (not anumber) is system dependent and should not be used externally..NH 2\&Fixed-length Opaque Data.IX XDR "fixed-length opaque data".IX XDR "opaque data, fixed length".LPAt times, fixed-length uninterpreted data needs to be passed amongmachines.  This data is called "opaque" and is declared as follows:.DS.ft CWopaque identifier[n];.DEwhere the constant n is the (static) number of bytes necessary tocontain the opaque data.  If n is not a multiple of four, then the nbytes are followed by enough (0 to 3) residual zero bytes, r, to makethe total byte count of the opaque object a multiple of four..ie t .DS.el .DS L\fIFixed-Length Opaque\fP\f(CW0        1     ...+--------+--------+...+--------+--------+...+--------+| byte 0 | byte 1 |...|byte n-1|    0   |...|    0   |+--------+--------+...+--------+--------+...+--------+|<-----------n bytes---------->|<------r bytes------>||<-----------n+r (where (n+r) mod 4 = 0)------------>|\fP.DE.NH 2\&Variable-length Opaque Data.IX XDR "variable-length opaque data".IX XDR "opaque data, variable length".LPThe standard also provides for variable-length (counted) opaque data,defined as a sequence of n (numbered 0 through n-1) arbitrary bytesto be the number n encoded as an unsigned integer (as describedbelow), and followed by the n bytes of the sequence..LPByte m of the sequence always precedes byte m+1 of the sequence, andbyte 0 of the sequence always follows the sequence's length (count).enough (0 to 3) residual zero bytes, r, to make the total byte counta multiple of four.  Variable-length opaque data is declared in thefollowing way:.DS.ft CWopaque identifier<m>;.DEor.DS.ft CWopaque identifier<>;.DEThe constant m denotes an upper bound of the number of bytes that thesequence may contain.  If m is not specified, as in the seconddeclaration, it is assumed to be (2**32) - 1, the maximum length.