idnits 2.17.1 draft-ietf-nfsv4-rfc1832bis-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3667, Section 5.1 on line 13. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1169. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document seems to lack an RFC 3979 Section 5, para. 1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ( - It does however have an RFC 2026 Section 10.4(A) Disclaimer.) ** The document seems to lack an RFC 3979 Section 5, para. 2 IPR Disclosure Acknowledgement. ** The document seems to lack an RFC 3979 Section 5, para. 3 IPR Disclosure Invitation -- however, there's a paragraph with a matching beginning. Boilerplate error? ( - It does however have an RFC 2026 Section 10.4(B) IPR Disclosure Invitation.) ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 612 has weird spacing: '... eggbox fresh...' == Line 802 has weird spacing: '...onsider the ...' == Line 811 has weird spacing: '...old and rainy...' == Line 812 has weird spacing: '...old and rainy...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 2004) is 7248 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '-2147483648' is mentioned on line 157, but not defined -- Looks like a reference, but probably isn't: '2147483647' on line 157 -- Looks like a reference, but probably isn't: '0' on line 172 -- Looks like a reference, but probably isn't: '4294967295' on line 172 == Missing Reference: 'DOZEN' is mentioned on line 612, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE' Summary: 9 errors (**), 0 flaws (~~), 8 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group M. Eisler 2 Internet-Draft Editor 3 Document: draft-ietf-nfsv4-rfc1832bis-04.txt Network Appliance, Inc. 4 June 2004 6 XDR: External Data Representation Standard 8 Status of this Memo 10 By submitting this Internet-Draft, I certify that any applicable 11 patent or other IPR claims of which I am aware have been disclosed, 12 or will be disclosed, and any of which I become aware will be 13 disclosed, in accordance with RFC 3668. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as 18 Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than a "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/1id-abstracts.html 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html 31 ABSTRACT 33 This document describes the External Data Representation Standard 34 (XDR) protocol as it is currently deployed and accepted. 36 TABLE OF CONTENTS 38 1. Changes from RFC1832 . . . . . . . . . . . . . . . . . . . . . 2 39 2. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . 2 40 3. BASIC BLOCK SIZE . . . . . . . . . . . . . . . . . . . . . . . 3 41 4. XDR DATA TYPES . . . . . . . . . . . . . . . . . . . . . . . . 3 42 4.1. Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 4 43 4.2. Unsigned Integer . . . . . . . . . . . . . . . . . . . . . . 4 44 4.3. Enumeration . . . . . . . . . . . . . . . . . . . . . . . . 4 45 4.4. Boolean . . . . . . . . . . . . . . . . . . . . . . . . . . 5 46 4.5. Hyper Integer and Unsigned Hyper Integer . . . . . . . . . . 5 47 4.6. Floating-point . . . . . . . . . . . . . . . . . . . . . . . 5 48 4.7. Double-precision Floating-point . . . . . . . . . . . . . . 6 49 4.8. Quadruple-precision Floating-point . . . . . . . . . . . . . 7 50 4.9. Fixed-length Opaque Data . . . . . . . . . . . . . . . . . . 8 51 4.10. Variable-length Opaque Data . . . . . . . . . . . . . . . . 9 52 4.11. String . . . . . . . . . . . . . . . . . . . . . . . . . 10 53 4.12. Fixed-length Array . . . . . . . . . . . . . . . . . . . 10 54 4.13. Variable-length Array . . . . . . . . . . . . . . . . . . 11 55 4.14. Structure . . . . . . . . . . . . . . . . . . . . . . . . 11 56 4.15. Discriminated Union . . . . . . . . . . . . . . . . . . . 12 57 4.16. Void . . . . . . . . . . . . . . . . . . . . . . . . . . 12 58 4.17. Constant . . . . . . . . . . . . . . . . . . . . . . . . 13 59 4.18. Typedef . . . . . . . . . . . . . . . . . . . . . . . . . 13 60 4.19. Optional-data . . . . . . . . . . . . . . . . . . . . . . 14 61 4.20. Areas for Future Enhancement . . . . . . . . . . . . . . 15 62 5. DISCUSSION . . . . . . . . . . . . . . . . . . . . . . . . . 16 63 6. THE XDR LANGUAGE SPECIFICATION . . . . . . . . . . . . . . . 17 64 6.1. Notational Conventions . . . . . . . . . . . . . . . . . . 17 65 6.2. Lexical Notes . . . . . . . . . . . . . . . . . . . . . . 18 66 6.3. Syntax Information . . . . . . . . . . . . . . . . . . . . 18 67 6.4. Syntax Notes . . . . . . . . . . . . . . . . . . . . . . . 20 68 7. AN EXAMPLE OF AN XDR DATA DESCRIPTION . . . . . . . . . . . 20 69 8. Security Considerations . . . . . . . . . . . . . . . . . . 21 70 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . 22 71 10. TRADEMARKS AND OWNERS . . . . . . . . . . . . . . . . . . . 22 72 11. ANSI/IEEE Standard 754-1985 . . . . . . . . . . . . . . . . 22 73 12. NORMATIVE REFERENCES . . . . . . . . . . . . . . . . . . . 24 74 13. INFORMATIVE REFERENCES . . . . . . . . . . . . . . . . . . 24 75 14. Editor's Address . . . . . . . . . . . . . . . . . . . . . 24 76 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 24 77 16. IPR Notices . . . . . . . . . . . . . . . . . . . . . . . . 25 78 17. Copyright Notice . . . . . . . . . . . . . . . . . . . . . 25 80 1. Changes from RFC1832 82 This document makes no technical changes to RFC1832 and is published 83 for the purpose of noting IANA considerations and distinguishing 84 normative from informative references. 86 2. INTRODUCTION 88 XDR is a standard for the description and encoding of data. It is 89 useful for transferring data between different computer 90 architectures, and has been used to communicate data between such 91 diverse machines as the SUN WORKSTATION*, VAX*, IBM-PC*, and Cray*. 92 XDR fits into the ISO presentation layer, and is roughly analogous in 93 purpose to X.409, ISO Abstract Syntax Notation. The major difference 94 between these two is that XDR uses implicit typing, while X.409 uses 95 explicit typing. 97 XDR uses a language to describe data formats. The language can only 98 be used only to describe data; it is not a programming language. 99 This language allows one to describe intricate data formats in a 100 concise manner. The alternative of using graphical representations 101 (itself an informal language) quickly becomes incomprehensible when 102 faced with complexity. The XDR language itself is similar to the C 103 language [KERN], just as Courier [COUR] is similar to Mesa. Protocols 104 such as ONC RPC (Remote Procedure Call) and the NFS* (Network File 105 System) use XDR to describe the format of their data. 107 The XDR standard makes the following assumption: that bytes (or 108 octets) are portable, where a byte is defined to be 8 bits of data. 109 A given hardware device should encode the bytes onto the various 110 media in such a way that other hardware devices may decode the bytes 111 without loss of meaning. For example, the Ethernet* standard 112 suggests that bytes be encoded in "little-endian" style [COHE], or 113 least significant bit first. 115 3. BASIC BLOCK SIZE 117 The representation of all items requires a multiple of four bytes (or 118 32 bits) of data. The bytes are numbered 0 through n-1. The bytes 119 are read or written to some byte stream such that byte m always 120 precedes byte m+1. If the n bytes needed to contain the data are not 121 a multiple of four, then the n bytes are followed by enough (0 to 3) 122 residual zero bytes, r, to make the total byte count a multiple of 4. 124 We include the familiar graphic box notation for illustration and 125 comparison. In most illustrations, each box (delimited by a plus 126 sign at the 4 corners and vertical bars and dashes) depicts a byte. 127 Ellipses (...) between boxes show zero or more additional bytes where 128 required. 130 +--------+--------+...+--------+--------+...+--------+ 131 | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | BLOCK 132 +--------+--------+...+--------+--------+...+--------+ 133 |<-----------n bytes---------->|<------r bytes------>| 134 |<-----------n+r (where (n+r) mod 4 = 0)>----------->| 136 4. XDR DATA TYPES 138 Each of the sections that follow describes a data type defined in the 139 XDR standard, shows how it is declared in the language, and includes 140 a graphic illustration of its encoding. 142 For each data type in the language we show a general paradigm 143 declaration. Note that angle brackets (< and >) denote 144 variable length sequences of data and square brackets ([ and ]) 145 denote fixed-length sequences of data. "n", "m" and "r" denote 146 integers. For the full language specification and more formal 147 definitions of terms such as "identifier" and "declaration", refer 148 to section 6: "The XDR Language Specification". 150 For some data types, more specific examples are included. A more 151 extensive example of a data description is in section 7: "An Example 152 of an XDR Data Description". 154 4.1. Integer 156 An XDR signed integer is a 32-bit datum that encodes an integer in 157 the range [-2147483648,2147483647]. The integer is represented in 158 two's complement notation. The most and least significant bytes are 159 0 and 3, respectively. Integers are declared as follows: 161 int identifier; 163 (MSB) (LSB) 164 +-------+-------+-------+-------+ 165 |byte 0 |byte 1 |byte 2 |byte 3 | INTEGER 166 +-------+-------+-------+-------+ 167 <------------32 bits------------> 169 4.2. Unsigned Integer 171 An XDR unsigned integer is a 32-bit datum that encodes a nonnegative 172 integer in the range [0,4294967295]. It is represented by an 173 unsigned binary number whose most and least significant bytes are 0 174 and 3, respectively. An unsigned integer is declared as follows: 176 unsigned int identifier; 178 (MSB) (LSB) 179 +-------+-------+-------+-------+ 180 |byte 0 |byte 1 |byte 2 |byte 3 | UNSIGNED INTEGER 181 +-------+-------+-------+-------+ 182 <------------32 bits------------> 184 4.3. Enumeration 186 Enumerations have the same representation as signed integers. 187 Enumerations are handy for describing subsets of the integers. 188 Enumerated data is declared as follows: 190 enum { name-identifier = constant, ... } identifier; 192 For example, the three colors red, yellow, and blue could be 193 described by an enumerated type: 195 enum { RED = 2, YELLOW = 3, BLUE = 5 } colors; 197 It is an error to encode as an enum any other integer than those that 198 have been given assignments in the enum declaration. 200 4.4. Boolean 202 Booleans are important enough and occur frequently enough to warrant 203 their own explicit type in the standard. Booleans are declared as 204 follows: 206 bool identifier; 208 This is equivalent to: 210 enum { FALSE = 0, TRUE = 1 } identifier; 212 4.5. Hyper Integer and Unsigned Hyper Integer 214 The standard also defines 64-bit (8-byte) numbers called hyper 215 integer and unsigned hyper integer. Their representations are the 216 obvious extensions of integer and unsigned integer defined above. 217 They are represented in two's complement notation. The most and 218 least significant bytes are 0 and 7, respectively. Their 219 declarations: 221 hyper identifier; unsigned hyper identifier; 223 (MSB) (LSB) 224 +-------+-------+-------+-------+-------+-------+-------+-------+ 225 |byte 0 |byte 1 |byte 2 |byte 3 |byte 4 |byte 5 |byte 6 |byte 7 | 226 +-------+-------+-------+-------+-------+-------+-------+-------+ 227 <----------------------------64 bits----------------------------> 228 HYPER INTEGER 229 UNSIGNED HYPER INTEGER 231 4.6. Floating-point 233 The standard defines the floating-point data type "float" (32 bits or 234 4 bytes). The encoding used is the IEEE standard for normalized 235 single-precision floating-point numbers [IEEE]. The following three 236 fields describe the single-precision floating-point number: 238 S: The sign of the number. Values 0 and 1 represent positive and 239 negative, respectively. One bit. 241 E: The exponent of the number, base 2. 8 bits are devoted to this 242 field. The exponent is biased by 127. 244 F: The fractional part of the number's mantissa, base 2. 23 bits 245 are devoted to this field. 247 Therefore, the floating-point number is described by: 249 (-1)**S * 2**(E-Bias) * 1.F 251 It is declared as follows: 253 float identifier; 255 +-------+-------+-------+-------+ 256 |byte 0 |byte 1 |byte 2 |byte 3 | SINGLE-PRECISION 257 S| E | F | FLOATING-POINT NUMBER 258 +-------+-------+-------+-------+ 259 1|<- 8 ->|<-------23 bits------>| 260 <------------32 bits------------> 262 Just as the most and least significant bytes of a number are 0 and 3, 263 the most and least significant bits of a single-precision floating- 264 point number are 0 and 31. The beginning bit (and most significant 265 bit) offsets of S, E, and F are 0, 1, and 9, respectively. Note that 266 these numbers refer to the mathematical positions of the bits, and 267 NOT to their actual physical locations (which vary from medium to 268 medium). 270 The IEEE specifications should be consulted concerning the encoding 271 for signed zero, signed infinity (overflow), and denormalized numbers 272 (underflow) [IEEE]. According to IEEE specifications, the "NaN" (not 273 a number) is system dependent and should not be interpreted within 274 XDR as anything other than "NaN". 276 4.7. Double-precision Floating-point 278 The standard defines the encoding for the double-precision floating- 279 point data type "double" (64 bits or 8 bytes). The encoding used is 280 the IEEE standard for normalized double-precision floating-point 281 numbers [IEEE]. The standard encodes the following three fields, 282 which describe the double-precision floating-point number: 284 S: The sign of the number. Values 0 and 1 represent positive and 285 negative, respectively. One bit. 287 E: The exponent of the number, base 2. 11 bits are devoted to 288 this field. The exponent is biased by 1023. 290 F: The fractional part of the number's mantissa, base 2. 52 bits 291 are devoted to this field. 293 Therefore, the floating-point number is described by: 295 (-1)**S * 2**(E-Bias) * 1.F 297 It is declared as follows: 299 double identifier; 301 +------+------+------+------+------+------+------+------+ 302 |byte 0|byte 1|byte 2|byte 3|byte 4|byte 5|byte 6|byte 7| 303 S| E | F | 304 +------+------+------+------+------+------+------+------+ 305 1|<--11-->|<-----------------52 bits------------------->| 306 <-----------------------64 bits-------------------------> 307 DOUBLE-PRECISION FLOATING-POINT 309 Just as the most and least significant bytes of a number are 0 and 3, 310 the most and least significant bits of a double-precision floating- 311 point number are 0 and 63. The beginning bit (and most significant 312 bit) offsets of S, E , and F are 0, 1, and 12, respectively. Note 313 that these numbers refer to the mathematical positions of the bits, 314 and NOT to their actual physical locations (which vary from medium to 315 medium). 317 The IEEE specifications should be consulted concerning the encoding 318 for signed zero, signed infinity (overflow), and denormalized numbers 319 (underflow) [IEEE]. According to IEEE specifications, the "NaN" (not 320 a number) is system dependent and should not be interpreted within 321 XDR as anything other than "NaN". 323 4.8. Quadruple-precision Floating-point 325 The standard defines the encoding for the quadruple-precision 326 floating-point data type "quadruple" (128 bits or 16 bytes). The 327 encoding used is designed to be a simple analog of of the encoding 328 used for single and double-precision floating-point numbers using one 329 form of IEEE double extended precision. The standard encodes the 330 following three fields, which describe the quadruple-precision 331 floating-point number: 333 S: The sign of the number. Values 0 and 1 represent positive and 334 negative, respectively. One bit. 336 E: The exponent of the number, base 2. 15 bits are devoted to 337 this field. The exponent is biased by 16383. 339 F: The fractional part of the number's mantissa, base 2. 112 bits 340 are devoted to this field. 342 Therefore, the floating-point number is described by: 344 (-1)**S * 2**(E-Bias) * 1.F 346 It is declared as follows: 348 quadruple identifier; 350 +------+------+------+------+------+------+-...--+------+ 351 |byte 0|byte 1|byte 2|byte 3|byte 4|byte 5| ... |byte15| 352 S| E | F | 353 +------+------+------+------+------+------+-...--+------+ 354 1|<----15---->|<-------------112 bits------------------>| 355 <-----------------------128 bits------------------------> 356 QUADRUPLE-PRECISION FLOATING-POINT 358 Just as the most and least significant bytes of a number are 0 and 3, 359 the most and least significant bits of a quadruple-precision 360 floating-point number are 0 and 127. The beginning bit (and most 361 significant bit) offsets of S, E , and F are 0, 1, and 16, 362 respectively. Note that these numbers refer to the mathematical 363 positions of the bits, and NOT to their actual physical locations 364 (which vary from medium to medium). 366 The encoding for signed zero, signed infinity (overflow), and 367 denormalized numbers are analogs of the corresponding encodings for 368 single and double-precision floating-point numbers [SPAR], [HPRE]. 369 The "NaN" encoding as it applies to quadruple-precision 370 floating-point numbers is system dependent and should not be 371 interpreted within XDR as anything other than "NaN". 373 4.9. Fixed-length Opaque Data 375 At times, fixed-length uninterpreted data needs to be passed among 376 machines. This data is called "opaque" and is declared as follows: 378 opaque identifier[n]; 380 where the constant n is the (static) number of bytes necessary to 381 contain the opaque data. If n is not a multiple of four, then the n 382 bytes are followed by enough (0 to 3) residual zero bytes, r, to make 383 the total byte count of the opaque object a multiple of four. 385 0 1 ... 386 +--------+--------+...+--------+--------+...+--------+ 387 | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | 388 +--------+--------+...+--------+--------+...+--------+ 389 |<-----------n bytes---------->|<------r bytes------>| 390 |<-----------n+r (where (n+r) mod 4 = 0)------------>| 391 FIXED-LENGTH OPAQUE 393 4.10. Variable-length Opaque Data 395 The standard also provides for variable-length (counted) opaque data, 396 defined as a sequence of n (numbered 0 through n-1) arbitrary bytes 397 to be the number n encoded as an unsigned integer (as described 398 below), and followed by the n bytes of the sequence. 400 Byte m of the sequence always precedes byte m+1 of the sequence, and 401 byte 0 of the sequence always follows the sequence's length (count). 402 If n is not a multiple of four, then the n bytes are followed by 403 enough (0 to 3) residual zero bytes, r, to make the total byte count 404 a multiple of four. Variable-length opaque data is declared in the 405 following way: 407 opaque identifier; 408 or 409 opaque identifier<>; 411 The constant m denotes an upper bound of the number of bytes that the 412 sequence may contain. If m is not specified, as in the second 413 declaration, it is assumed to be (2**32) - 1, the maximum length. 414 The constant m would normally be found in a protocol specification. 415 For example, a filing protocol may state that the maximum data 416 transfer size is 8192 bytes, as follows: 418 opaque filedata<8192>; 420 0 1 2 3 4 5 ... 421 +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ 422 | length n |byte0|byte1|...| n-1 | 0 |...| 0 | 423 +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ 424 |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| 425 |<----n+r (where (n+r) mod 4 = 0)---->| 426 VARIABLE-LENGTH OPAQUE 428 It is an error to encode a length greater than the maximum described 429 in the specification. 431 4.11. String 433 The standard defines a string of n (numbered 0 through n-1) ASCII 434 bytes to be the number n encoded as an unsigned integer (as described 435 above), and followed by the n bytes of the string. Byte m of the 436 string always precedes byte m+1 of the string, and byte 0 of the 437 string always follows the string's length. If n is not a multiple of 438 four, then the n bytes are followed by enough (0 to 3) residual zero 439 bytes, r, to make the total byte count a multiple of four. Counted 440 byte strings are declared as follows: 442 string object; 443 or 444 string object<>; 446 The constant m denotes an upper bound of the number of bytes that a 447 string may contain. If m is not specified, as in the second 448 declaration, it is assumed to be (2**32) - 1, the maximum length. 449 The constant m would normally be found in a protocol specification. 450 For example, a filing protocol may state that a file name can be no 451 longer than 255 bytes, as follows: 453 string filename<255>; 455 0 1 2 3 4 5 ... 456 +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ 457 | length n |byte0|byte1|...| n-1 | 0 |...| 0 | 458 +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ 459 |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| 460 |<----n+r (where (n+r) mod 4 = 0)---->| 461 STRING 463 It is an error to encode a length greater than the maximum described 464 in the specification. 466 4.12. Fixed-length Array 468 Declarations for fixed-length arrays of homogeneous elements are in 469 the following form: 471 type-name identifier[n]; 473 Fixed-length arrays of elements numbered 0 through n-1 are encoded by 474 individually encoding the elements of the array in their natural 475 order, 0 through n-1. Each element's size is a multiple of four 476 bytes. Though all elements are of the same type, the elements may 477 have different sizes. For example, in a fixed-length array of 478 strings, all elements are of type "string", yet each element will 479 vary in its length. 481 +---+---+---+---+---+---+---+---+...+---+---+---+---+ 482 | element 0 | element 1 |...| element n-1 | 483 +---+---+---+---+---+---+---+---+...+---+---+---+---+ 484 |<--------------------n elements------------------->| 486 FIXED-LENGTH ARRAY 488 4.13. Variable-length Array 490 Counted arrays provide the ability to encode variable-length arrays 491 of homogeneous elements. The array is encoded as the element count n 492 (an unsigned integer) followed by the encoding of each of the array's 493 elements, starting with element 0 and progressing through element n- 494 1. The declaration for variable-length arrays follows this form: 496 type-name identifier; 497 or 498 type-name identifier<>; 500 The constant m specifies the maximum acceptable element count of an 501 array; if m is not specified, as in the second declaration, it is 502 assumed to be (2**32) - 1. 504 0 1 2 3 505 +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ 506 | n | element 0 | element 1 |...|element n-1| 507 +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ 508 |<-4 bytes->|<--------------n elements------------->| 509 COUNTED ARRAY 511 It is an error to encode a value of n that is greater than the 512 maximum described in the specification. 514 4.14. Structure 516 Structures are declared as follows: 518 struct { 519 component-declaration-A; 520 component-declaration-B; 521 ... 522 } identifier; 524 The components of the structure are encoded in the order of their 525 declaration in the structure. Each component's size is a multiple of 526 four bytes, though the components may be different sizes. 528 +-------------+-------------+... 529 | component A | component B |... STRUCTURE 530 +-------------+-------------+... 532 4.15. Discriminated Union 534 A discriminated union is a type composed of a discriminant followed 535 by a type selected from a set of prearranged types according to the 536 value of the discriminant. The type of discriminant is either "int", 537 "unsigned int", or an enumerated type, such as "bool". The component 538 types are called "arms" of the union, and are preceded by the value 539 of the discriminant which implies their encoding. Discriminated 540 unions are declared as follows: 542 union switch (discriminant-declaration) { 543 case discriminant-value-A: 544 arm-declaration-A; 545 case discriminant-value-B: 546 arm-declaration-B; 547 ... 548 default: default-declaration; 549 } identifier; 551 Each "case" keyword is followed by a legal value of the discriminant. 552 The default arm is optional. If it is not specified, then a valid 553 encoding of the union cannot take on unspecified discriminant values. 554 The size of the implied arm is always a multiple of four bytes. 556 The discriminated union is encoded as its discriminant followed by 557 the encoding of the implied arm. 559 0 1 2 3 560 +---+---+---+---+---+---+---+---+ 561 | discriminant | implied arm | DISCRIMINATED UNION 562 +---+---+---+---+---+---+---+---+ 563 |<---4 bytes--->| 565 4.16. Void 567 An XDR void is a 0-byte quantity. Voids are useful for describing 568 operations that take no data as input or no data as output. They are 569 also useful in unions, where some arms may contain data and others do 570 not. The declaration is simply as follows: 572 void; 574 Voids are illustrated as follows: 576 ++ 577 || VOID 578 ++ 579 --><-- 0 bytes 581 4.17. Constant 583 The data declaration for a constant follows this form: 585 const name-identifier = n; 587 "const" is used to define a symbolic name for a constant; it does not 588 declare any data. The symbolic constant may be used anywhere a 589 regular constant may be used. For example, the following defines a 590 symbolic constant DOZEN, equal to 12. 592 const DOZEN = 12; 594 4.18. Typedef 596 "typedef" does not declare any data either, but serves to define new 597 identifiers for declaring data. The syntax is: 599 typedef declaration; 601 The new type name is actually the variable name in the declaration 602 part of the typedef. For example, the following defines a new type 603 called "eggbox" using an existing type called "egg": 605 typedef egg eggbox[DOZEN]; 607 Variables declared using the new type name have the same type as the 608 new type name would have in the typedef, if it was considered a 609 variable. For example, the following two declarations are equivalent 610 in declaring the variable "fresheggs": 612 eggbox fresheggs; egg fresheggs[DOZEN]; 614 When a typedef involves a struct, enum, or union definition, there is 615 another (preferred) syntax that may be used to define the same type. 616 In general, a typedef of the following form: 618 typedef <> identifier; 620 may be converted to the alternative form by removing the "typedef" 621 part and placing the identifier after the "struct", "union", or 622 "enum" keyword, instead of at the end. For example, here are the two 623 ways to define the type "bool": 625 typedef enum { /* using typedef */ 626 FALSE = 0, 627 TRUE = 1 628 } bool; 630 enum bool { /* preferred alternative */ 631 FALSE = 0, 632 TRUE = 1 633 }; 635 The reason this syntax is preferred is one does not have to wait 636 until the end of a declaration to figure out the name of the new 637 type. 639 4.19. Optional-data 641 Optional-data is one kind of union that occurs so frequently that we 642 give it a special syntax of its own for declaring it. It is declared 643 as follows: 645 type-name *identifier; 647 This is equivalent to the following union: 649 union switch (bool opted) { 650 case TRUE: 651 type-name element; 652 case FALSE: 653 void; 654 } identifier; 656 It is also equivalent to the following variable-length array 657 declaration, since the boolean "opted" can be interpreted as the 658 length of the array: 660 type-name identifier<1>; 662 Optional-data is not so interesting in itself, but it is very useful 663 for describing recursive data-structures such as linked-lists and 664 trees. For example, the following defines a type "stringlist" that 665 that encodes lists of zero or more arbitrary length strings: 667 struct stringentry { 668 string item<>; 669 stringentry *next; 670 }; 672 typedef stringentry *stringlist; 674 It could have been equivalently declared as the following union: 676 union stringlist switch (bool opted) { 677 case TRUE: 678 struct { 679 string item<>; 680 stringlist next; 681 } element; 682 case FALSE: 683 void; 684 }; 686 or as a variable-length array: 688 struct stringentry { 689 string item<>; 690 stringentry next<1>; 691 }; 693 typedef stringentry stringlist<1>; 695 Both of these declarations obscure the intention of the stringlist 696 type, so the optional-data declaration is preferred over both of 697 them. The optional-data type also has a close correlation to how 698 recursive data structures are represented in high-level languages 699 such as Pascal or C by use of pointers. In fact, the syntax is the 700 same as that of the C language for pointers. 702 4.20. Areas for Future Enhancement 704 The XDR standard lacks representations for bit fields and bitmaps, 705 since the standard is based on bytes. Also missing are packed (or 706 binary-coded) decimals. 708 The intent of the XDR standard was not to describe every kind of data 709 that people have ever sent or will ever want to send from machine to 710 machine. Rather, it only describes the most commonly used data-types 711 of high-level languages such as Pascal or C so that applications 712 written in these languages will be able to communicate easily over 713 some medium. 715 One could imagine extensions to XDR that would let it describe almost 716 any existing protocol, such as TCP. The minimum necessary for this 717 are support for different block sizes and byte-orders. The XDR 718 discussed here could then be considered the 4-byte big-endian member 719 of a larger XDR family. 721 5. DISCUSSION 723 (1) Why use a language for describing data? What's wrong with 724 diagrams? 726 There are many advantages in using a data-description language such 727 as XDR versus using diagrams. Languages are more formal than 728 diagrams and lead to less ambiguous descriptions of data. Languages 729 are also easier to understand and allow one to think of other issues 730 instead of the low-level details of bit-encoding. Also, there is a 731 close analogy between the types of XDR and a high-level language such 732 as C or Pascal. This makes the implementation of XDR encoding and 733 decoding modules an easier task. Finally, the language specification 734 itself is an ASCII string that can be passed from machine to machine 735 to perform on-the-fly data interpretation. 737 (2) Why is there only one byte-order for an XDR unit? 739 Supporting two byte-orderings requires a higher level protocol for 740 determining in which byte-order the data is encoded. Since XDR is 741 not a protocol, this can't be done. The advantage of this, though, 742 is that data in XDR format can be written to a magnetic tape, for 743 example, and any machine will be able to interpret it, since no 744 higher level protocol is necessary for determining the byte-order. 746 (3) Why is the XDR byte-order big-endian instead of little-endian? 747 Isn't this unfair to little-endian machines such as the VAX(r), which 748 has to convert from one form to the other? 750 Yes, it is unfair, but having only one byte-order means you have to 751 be unfair to somebody. Many architectures, such as the Motorola 752 68000* and IBM 370*, support the big-endian byte-order. 754 (4) Why is the XDR unit four bytes wide? 756 There is a tradeoff in choosing the XDR unit size. Choosing a small 757 size such as two makes the encoded data small, but causes alignment 758 problems for machines that aren't aligned on these boundaries. A 759 large size such as eight means the data will be aligned on virtually 760 every machine, but causes the encoded data to grow too big. We chose 761 four as a compromise. Four is big enough to support most 762 architectures efficiently, except for rare machines such as the 763 eight-byte aligned Cray*. Four is also small enough to keep the 764 encoded data restricted to a reasonable size. 766 (5) Why must variable-length data be padded with zeros? 768 It is desirable that the same data encode into the same thing on all 769 machines, so that encoded data can be meaningfully compared or 770 checksummed. Forcing the padded bytes to be zero ensures this. 772 (6) Why is there no explicit data-typing? 774 Data-typing has a relatively high cost for what small advantages it 775 may have. One cost is the expansion of data due to the inserted type 776 fields. Another is the added cost of interpreting these type fields 777 and acting accordingly. And most protocols already know what type 778 they expect, so data-typing supplies only redundant information. 779 However, one can still get the benefits of data-typing using XDR. One 780 way is to encode two things: first a string which is the XDR data 781 description of the encoded data, and then the encoded data itself. 782 Another way is to assign a value to all the types in XDR, and then 783 define a universal type which takes this value as its discriminant 784 and for each value, describes the corresponding data type. 786 6. THE XDR LANGUAGE SPECIFICATION 788 6.1. Notational Conventions 790 This specification uses an extended Back-Naur Form notation for 791 describing the XDR language. Here is a brief description of the 792 notation: 794 (1) The characters '|', '(', ')', '[', ']', '"', and '*' are special. 795 (2) Terminal symbols are strings of any characters surrounded by 796 double quotes. (3) Non-terminal symbols are strings of non-special 797 characters. (4) Alternative items are separated by a vertical bar 798 ("|"). (5) Optional items are enclosed in brackets. (6) Items are 799 grouped together by enclosing them in parentheses. (7) A '*' 800 following an item means 0 or more occurrences of that item. 802 For example, consider the following pattern: 804 "a " "very" (", " "very")* [" cold " "and "] " rainy " 805 ("day" | "night") 807 An infinite number of strings match this pattern. A few of them are: 809 "a very rainy day" 810 "a very, very rainy day" 811 "a very cold and rainy day" 812 "a very, very, very cold and rainy night" 814 6.2. Lexical Notes 816 (1) Comments begin with '/*' and terminate with '*/'. (2) White 817 space serves to separate items and is otherwise ignored. (3) An 818 identifier is a letter followed by an optional sequence of letters, 819 digits or underbar ('_'). The case of identifiers is not ignored. 820 (4) A decimal constant expresses a number in base 10, and is a 821 sequence of one or more decimal digits, where the first digit is not 822 a zero, and is optionally preceded by a minus-sign ('-'). (5) A 823 hexadecimal constant expresses a number in base 16, and must be 824 preceded by '0x', followed by one or hexadecimal digits ('A', 'B', 825 'C', 'D', E', 'F', 'a', 'b', 'c', 'd', 'e', 'f', '0', '1', '2', '3', 826 '4', '5', '6', '7', '8', '9'). (6) An octal constant expresses a 827 number in base 8, always leads with digit 0, and is a sequence of 828 one or more octal digits ('0', '1', '2', '3', '4', '5', '6', '7'). 830 6.3. Syntax Information 832 declaration: 833 type-specifier identifier 834 | type-specifier identifier "[" value "]" 835 | type-specifier identifier "<" [ value ] ">" 836 | "opaque" identifier "[" value "]" 837 | "opaque" identifier "<" [ value ] ">" 838 | "string" identifier "<" [ value ] ">" 839 | type-specifier "*" identifier 840 | "void" 842 value: 843 constant 844 | identifier 846 constant: 847 decimal-constant | hexadecimal-constant | octal-constant 849 type-specifier: 850 [ "unsigned" ] "int" 851 | [ "unsigned" ] "hyper" 852 | "float" 853 | "double" 854 | "quadruple" 855 | "bool" 856 | enum-type-spec 857 | struct-type-spec 858 | union-type-spec 859 | identifier 861 enum-type-spec: 862 "enum" enum-body 864 enum-body: 865 "{" 866 ( identifier "=" value ) 867 ( "," identifier "=" value )* 868 "}" 870 struct-type-spec: 871 "struct" struct-body 873 struct-body: 874 "{" 875 ( declaration ";" ) 876 ( declaration ";" )* 877 "}" 879 union-type-spec: 880 "union" union-body 882 union-body: 883 "switch" "(" declaration ")" "{" 884 case-spec 885 case-spec * 886 [ "default" ":" declaration ";" ] 887 "}" 889 case-spec: 890 ( "case" value ":") 891 ( "case" value ":") * 892 declaration ";" 894 constant-def: 895 "const" identifier "=" constant ";" 897 type-def: 898 "typedef" declaration ";" 899 | "enum" identifier enum-body ";" 900 | "struct" identifier struct-body ";" 901 | "union" identifier union-body ";" 903 definition: 904 type-def 905 | constant-def 907 specification: 908 definition * 910 6.4. Syntax Notes 912 (1) The following are keywords and cannot be used as identifiers: 913 "bool", "case", "const", "default", "double", "quadruple", "enum", 914 "float", "hyper", "int", "opaque", "string", "struct", "switch", 915 "typedef", "union", "unsigned" and "void". 917 (2) Only unsigned constants may be used as size specifications for 918 arrays. If an identifier is used, it must have been declared 919 previously as an unsigned constant in a "const" definition. 921 (3) Constant and type identifiers within the scope of a specification 922 are in the same name space and must be declared uniquely within this 923 scope. 925 (4) Similarly, variable names must be unique within the scope of 926 struct and union declarations. Nested struct and union declarations 927 create new scopes. 929 (5) The discriminant of a union must be of a type that evaluates to 930 an integer. That is, "int", "unsigned int", "bool", an enumerated 931 type or any typedefed type that evaluates to one of these is legal. 932 Also, the case values must be one of the legal values of the 933 discriminant. Finally, a case value may not be specified more than 934 once within the scope of a union declaration. 936 7. AN EXAMPLE OF AN XDR DATA DESCRIPTION 938 Here is a short XDR data description of a thing called a "file", 939 which might be used to transfer files from one machine to another. 941 const MAXUSERNAME = 32; /* max length of a user name */ 942 const MAXFILELEN = 65535; /* max length of a file */ 943 const MAXNAMELEN = 255; /* max length of a file name */ 945 /* 946 * Types of files: 947 */ 948 enum filekind { 949 TEXT = 0, /* ascii data */ 950 DATA = 1, /* raw data */ 951 EXEC = 2 /* executable */ 952 }; 953 /* 954 * File information, per kind of file: 955 */ 956 union filetype switch (filekind kind) { 957 case TEXT: 958 void; /* no extra information */ 959 case DATA: 960 string creator; /* data creator */ 961 case EXEC: 962 string interpretor; /* program interpretor */ 963 }; 965 /* 966 * A complete file: 967 */ 968 struct file { 969 string filename; /* name of file */ 970 filetype type; /* info about file */ 971 string owner; /* owner of file */ 972 opaque data; /* file data */ 973 }; 975 Suppose now that there is a user named "john" who wants to store his 976 lisp program "sillyprog" that contains just the data "(quit)". His 977 file would be encoded as follows: 979 OFFSET HEX BYTES ASCII COMMENTS 980 ------ --------- ----- -------- 981 0 00 00 00 09 .... -- length of filename = 9 982 4 73 69 6c 6c sill -- filename characters 983 8 79 70 72 6f ypro -- ... and more characters ... 984 12 67 00 00 00 g... -- ... and 3 zero-bytes of fill 985 16 00 00 00 02 .... -- filekind is EXEC = 2 986 20 00 00 00 04 .... -- length of interpretor = 4 987 24 6c 69 73 70 lisp -- interpretor characters 988 28 00 00 00 04 .... -- length of owner = 4 989 32 6a 6f 68 6e john -- owner characters 990 36 00 00 00 06 .... -- length of file data = 6 991 40 28 71 75 69 (qui -- file data bytes ... 992 44 74 29 00 00 t).. -- ... and 2 zero-bytes of fill 994 8. Security Considerations 996 Security issues are not discussed in this memo. 998 9. IANA Considerations 1000 It is possible, if not likely, that new data types will 1001 be added to XDR in the future. The process for adding 1002 new types is via a standards track RFC and not 1003 registration of new types with IANA. Standards track RFCs 1004 that update or replace this document should be 1005 documented as such in the RFC Editor's database of 1006 RFCs. 1008 10. TRADEMARKS AND OWNERS 1010 SUN WORKSTATION Sun Microsystems, Inc. 1011 VAX Hewlett-Packard Company 1012 IBM-PC International Business Machines Corporation 1013 Cray Cray Inc. 1014 NFS Sun Microsystems, Inc. 1015 Ethernet Xerox Corporation. 1016 Motorola 68000 Motorola, Inc. 1017 IBM 370 International Business Machines Corporation 1019 11. ANSI/IEEE Standard 754-1985 1021 The definition of NaNs, signed zero and infinity, and denormalized 1022 numbers from [IEEE] is reproduced here for convenience. The 1023 definitions for quadruple-precision floating point numbers are 1024 analogs of those for single and double-precision floating point 1025 numbers, and are defined in [IEEE]. 1027 In the following, 'S' stands for the sign bit, 'E' for the exponent, 1028 and 'F' for the fractional part. The symbol 'u' stands for an 1029 undefined bit (0 or 1). 1031 For single-precision floating point numbers: 1033 Type S (1 bit) E (8 bits) F (23 bits) 1034 ---- --------- ---------- ----------- 1035 signalling NaN u 255 (max) .0uuuuu---u 1036 (with at least 1037 one 1 bit) 1038 quiet NaN u 255 (max) .1uuuuu---u 1040 negative infinity 1 255 (max) .000000---0 1042 positive infinity 0 255 (max) .000000---0 1044 negative zero 1 0 .000000---0 1045 positive zero 0 0 .000000---0 1047 For double-precision floating point numbers: 1049 Type S (1 bit) E (11 bits) F (52 bits) 1050 ---- --------- ----------- ----------- 1051 signalling NaN u 2047 (max) .0uuuuu---u 1052 (with at least 1053 one 1 bit) 1054 quiet NaN u 2047 (max) .1uuuuu---u 1056 negative infinity 1 2047 (max) .000000---0 1058 positive infinity 0 2047 (max) .000000---0 1060 negative zero 1 0 .000000---0 1062 positive zero 0 0 .000000---0 1064 For quadruple-precision floating point numbers: 1066 Type S (1 bit) E (15 bits) F (112 bits) 1067 ---- --------- ----------- ------------ 1068 signalling NaN u 32767 (max) .0uuuuu---u 1069 (with at least 1070 one 1 bit) 1071 quiet NaN u 32767 (max) .1uuuuu---u 1073 negative infinity 1 32767 (max) .000000---0 1075 positive infinity 0 32767 (max) .000000---0 1077 negative zero 1 0 .000000---0 1079 positive zero 0 0 .000000---0 1081 Subnormal numbers are represented as follows: 1083 Precision Exponent Value 1084 --------- -------- ----- 1085 Single 0 (-1)**S * 2**(-126) * 0.F 1087 Double 0 (-1)**S * 2**(-1022) * 0.F 1089 Quadruple 0 (-1)**S * 2**(-16382) * 0.F 1091 12. NORMATIVE REFERENCES 1093 [IEEE] "IEEE Standard for Binary Floating-Point Arithmetic", 1094 ANSI/IEEE Standard 754-1985, Institute of Electrical and 1095 Electronics Engineers, August 1985. 1097 13. INFORMATIVE REFERENCES 1099 [KERN] Brian W. Kernighan & Dennis M. Ritchie, "The C Programming 1100 Language", Bell Laboratories, Murray Hill, New Jersey, 1978. 1102 [COHE] Danny Cohen, "On Holy Wars and a Plea for Peace", IEEE 1103 Computer, October 1981. 1105 [COUR] "Courier: The Remote Procedure Call Protocol", XEROX 1106 Corporation, XSIS 038112, December 1981. 1108 [SPAR] "The SPARC Architecture Manual: Version 8", Prentice Hall, 1109 ISBN 0-13-825001-4. 1111 [HPRE] "HP Precision Architecture Handbook", June 1987, 5954-9906. 1113 14. Editor's Address 1115 Mike Eisler 1116 5765 Chase Point Circle 1117 Colorado Springs, CO 80919 1118 USA 1120 Phone: 719-599-9026 1121 EMail: mike@eisler.com 1123 15. Acknowledgements 1125 Bob Lyon was Sun's visible force behind ONC RPC in the 1980s. Sun 1126 Microsystems, Inc. is listed as the author of RFC1014, which RFC1832 1127 was heavily derived from. Raj Srinivasan in turn edited RFC1014 into 1128 RFC1832. Raj and the rest of the old ONC RPC working group produced 1129 RFC1832 from which this document is derived. Mike Eisler and Bill 1130 Janssen submitted the implementation reports for this standard. Kevin 1131 Coffman and Benny Halevy reviewed this document and gave feedback. 1132 Peter Astrand and Bryan Olson pointed out several errors in RFC1832 1133 which are corrected in this document. 1135 16. IPR Notices 1137 The IETF takes no position regarding the validity or scope of any 1138 intellectual property or other rights that might be claimed to 1139 pertain to the implementation or use of the technology described in 1140 this document or the extent to which any license under such rights 1141 might or might not be available; neither does it represent that it 1142 has made any effort to identify any such rights. Information on the 1143 IETF's procedures with respect to rights in standards-track and 1144 standards-related documentation can be found in BCP-11. Copies of 1145 claims of rights made available for publication and any assurances of 1146 licenses to be made available, or the result of an attempt made to 1147 obtain a general license or permission for the use of such 1148 proprietary rights by implementors or users of this specification can 1149 be obtained from the IETF Secretariat. 1151 The IETF invites any interested party to bring to its attention any 1152 copyrights, patents or patent applications, or other proprietary 1153 rights which may cover technology that may be required to practice 1154 this standard. Please address the information to the IETF Executive 1155 Director. 1157 17. Copyright Notice 1159 Copyright (C) The Internet Society (2004). This document is subject 1160 to the rights, licenses and restrictions contained in BCP 78, and 1161 except as set forth therein, the authors retain all their rights. 1163 This document and the information contained herein are provided on an 1164 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1165 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1166 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1167 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1168 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1169 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.