idnits 2.17.1 draft-ietf-nfsv4-rfc1832bis-03.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 1164. ** 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 799 has weird spacing: '...onsider the ...' == Line 808 has weird spacing: '...old and rainy...' == Line 809 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 7256 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-03.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 . . . . . . . . . . . . . . . . . . . . . . . 19 68 7. AN EXAMPLE OF AN XDR DATA DESCRIPTION . . . . . . . . . . . 20 69 8. Security Considerations . . . . . . . . . . . . . . . . . . 21 70 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . 21 71 10. TRADEMARKS AND OWNERS . . . . . . . . . . . . . . . . . . . 22 72 11. ANSI/IEEE Standard 754-1985 . . . . . . . . . . . . . . . . 22 73 12. NORMATIVE REFERENCES . . . . . . . . . . . . . . . . . . . 23 74 13. INFORMATIVE REFERENCES . . . . . . . . . . . . . . . . . . 23 75 14. Editor's Address . . . . . . . . . . . . . . . . . . . . . 24 76 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 24 77 16. IPR Notices . . . . . . . . . . . . . . . . . . . . . . . . 24 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 { string item<>; 669 stringentry *next; }; 671 typedef stringentry *stringlist; 673 It could have been equivalently declared as the following union: 675 union stringlist switch (bool opted) { 676 case TRUE: 677 struct { 678 string item<>; 679 stringlist next; 680 } element; 681 case FALSE: 682 void; 683 }; 685 or as a variable-length array: 687 struct stringentry { string item<>; 688 stringentry next<1>; }; 690 typedef stringentry stringlist<1>; 692 Both of these declarations obscure the intention of the stringlist 693 type, so the optional-data declaration is preferred over both of 694 them. The optional-data type also has a close correlation to how 695 recursive data structures are represented in high-level languages 696 such as Pascal or C by use of pointers. In fact, the syntax is the 697 same as that of the C language for pointers. 699 4.20. Areas for Future Enhancement 701 The XDR standard lacks representations for bit fields and bitmaps, 702 since the standard is based on bytes. Also missing are packed (or 703 binary-coded) decimals. 705 The intent of the XDR standard was not to describe every kind of data 706 that people have ever sent or will ever want to send from machine to 707 machine. Rather, it only describes the most commonly used data-types 708 of high-level languages such as Pascal or C so that applications 709 written in these languages will be able to communicate easily over 710 some medium. 712 One could imagine extensions to XDR that would let it describe almost 713 any existing protocol, such as TCP. The minimum necessary for this 714 are support for different block sizes and byte-orders. The XDR 715 discussed here could then be considered the 4-byte big-endian member 716 of a larger XDR family. 718 5. DISCUSSION 720 (1) Why use a language for describing data? What's wrong with 721 diagrams? 723 There are many advantages in using a data-description language such 724 as XDR versus using diagrams. Languages are more formal than 725 diagrams and lead to less ambiguous descriptions of data. Languages 726 are also easier to understand and allow one to think of other issues 727 instead of the low-level details of bit-encoding. Also, there is a 728 close analogy between the types of XDR and a high-level language such 729 as C or Pascal. This makes the implementation of XDR encoding and 730 decoding modules an easier task. Finally, the language specification 731 itself is an ASCII string that can be passed from machine to machine 732 to perform on-the-fly data interpretation. 734 (2) Why is there only one byte-order for an XDR unit? 736 Supporting two byte-orderings requires a higher level protocol for 737 determining in which byte-order the data is encoded. Since XDR is 738 not a protocol, this can't be done. The advantage of this, though, 739 is that data in XDR format can be written to a magnetic tape, for 740 example, and any machine will be able to interpret it, since no 741 higher level protocol is necessary for determining the byte-order. 743 (3) Why is the XDR byte-order big-endian instead of little-endian? 744 Isn't this unfair to little-endian machines such as the VAX(r), which 745 has to convert from one form to the other? 747 Yes, it is unfair, but having only one byte-order means you have to 748 be unfair to somebody. Many architectures, such as the Motorola 749 68000* and IBM 370*, support the big-endian byte-order. 751 (4) Why is the XDR unit four bytes wide? 753 There is a tradeoff in choosing the XDR unit size. Choosing a small 754 size such as two makes the encoded data small, but causes alignment 755 problems for machines that aren't aligned on these boundaries. A 756 large size such as eight means the data will be aligned on virtually 757 every machine, but causes the encoded data to grow too big. We chose 758 four as a compromise. Four is big enough to support most 759 architectures efficiently, except for rare machines such as the 760 eight-byte aligned Cray*. Four is also small enough to keep the 761 encoded data restricted to a reasonable size. 763 (5) Why must variable-length data be padded with zeros? 765 It is desirable that the same data encode into the same thing on all 766 machines, so that encoded data can be meaningfully compared or 767 checksummed. Forcing the padded bytes to be zero ensures this. 769 (6) Why is there no explicit data-typing? 771 Data-typing has a relatively high cost for what small advantages it 772 may have. One cost is the expansion of data due to the inserted type 773 fields. Another is the added cost of interpreting these type fields 774 and acting accordingly. And most protocols already know what type 775 they expect, so data-typing supplies only redundant information. 776 However, one can still get the benefits of data-typing using XDR. One 777 way is to encode two things: first a string which is the XDR data 778 description of the encoded data, and then the encoded data itself. 779 Another way is to assign a value to all the types in XDR, and then 780 define a universal type which takes this value as its discriminant 781 and for each value, describes the corresponding data type. 783 6. THE XDR LANGUAGE SPECIFICATION 785 6.1. Notational Conventions 787 This specification uses an extended Back-Naur Form notation for 788 describing the XDR language. Here is a brief description of the 789 notation: 791 (1) The characters '|', '(', ')', '[', ']', '"', and '*' are special. 792 (2) Terminal symbols are strings of any characters surrounded by 793 double quotes. (3) Non-terminal symbols are strings of non-special 794 characters. (4) Alternative items are separated by a vertical bar 795 ("|"). (5) Optional items are enclosed in brackets. (6) Items are 796 grouped together by enclosing them in parentheses. (7) A '*' 797 following an item means 0 or more occurrences of that item. 799 For example, consider the following pattern: 801 "a " "very" (", " "very")* [" cold " "and "] " rainy " 802 ("day" | "night") 804 An infinite number of strings match this pattern. A few of them are: 806 "a very rainy day" 807 "a very, very rainy day" 808 "a very cold and rainy day" 809 "a very, very, very cold and rainy night" 811 6.2. Lexical Notes 813 (1) Comments begin with '/*' and terminate with '*/'. (2) White 814 space serves to separate items and is otherwise ignored. (3) An 815 identifier is a letter followed by an optional sequence of letters, 816 digits or underbar ('_'). The case of identifiers is not ignored. 817 (4) A decimal constant expresses a number in base 10, and is a 818 sequence of one or more decimal digits, where the first digit is not 819 a zero, and is optionally preceded by a minus-sign ('-'). (5) A 820 hexadecimal constant expresses a number in base 16, and must be 821 preceded by '0x', followed by one or hexadecimal digits ('A', 'B', 822 'C', 'D', E', 'F', 'a', 'b', 'c', 'd', 'e', 'f', '0', '1', '2', '3', 823 '4', '5', '6', '7', '8', '9'). (6) An octal constant expresses a 824 number in base 8, always leads with digit 0, and is a sequence of 825 one or more octal digits ('0', '1', '2', '3', '4', '5', '6', '7'). 827 6.3. Syntax Information 829 declaration: 830 type-specifier identifier 831 | type-specifier identifier "[" value "]" 832 | type-specifier identifier "<" [ value ] ">" 833 | "opaque" identifier "[" value "]" 834 | "opaque" identifier "<" [ value ] ">" 835 | "string" identifier "<" [ value ] ">" 836 | type-specifier "*" identifier 837 | "void" 839 value: 840 constant 841 | identifier 843 constant: 844 decimal-constant | hexadecimal-constant | octal-constant 846 type-specifier: 847 [ "unsigned" ] "int" 848 | [ "unsigned" ] "hyper" 849 | "float" 850 | "double" 851 | "quadruple" 852 | "bool" 853 | enum-type-spec 854 | struct-type-spec 855 | union-type-spec 856 | identifier 858 enum-type-spec: 860 "enum" enum-body 862 enum-body: 863 "{" 864 ( identifier "=" value ) 865 ( "," identifier "=" value )* 866 "}" 868 struct-type-spec: 869 "struct" struct-body 871 struct-body: 872 "{" 873 ( declaration ";" ) 874 ( declaration ";" )* 875 "}" 877 union-type-spec: 878 "union" union-body 880 union-body: 881 "switch" "(" declaration ")" "{" 882 ( "case" value ":" declaration ";" ) 883 ( "case" value ":" declaration ";" )* 884 [ "default" ":" declaration ";" ] 885 "}" 887 constant-def: 888 "const" identifier "=" constant ";" 890 type-def: 891 "typedef" declaration ";" 892 | "enum" identifier enum-body ";" 893 | "struct" identifier struct-body ";" 894 | "union" identifier union-body ";" 896 definition: 897 type-def 898 | constant-def 900 specification: 901 definition * 903 6.4. Syntax Notes 905 (1) The following are keywords and cannot be used as identifiers: 906 "bool", "case", "const", "default", "double", "quadruple", "enum", 907 "float", "hyper", "int", "opaque", "string", "struct", "switch", 908 "typedef", "union", "unsigned" and "void". 910 (2) Only unsigned constants may be used as size specifications for 911 arrays. If an identifier is used, it must have been declared 912 previously as an unsigned constant in a "const" definition. 914 (3) Constant and type identifiers within the scope of a specification 915 are in the same name space and must be declared uniquely within this 916 scope. 918 (4) Similarly, variable names must be unique within the scope of 919 struct and union declarations. Nested struct and union declarations 920 create new scopes. 922 (5) The discriminant of a union must be of a type that evaluates to 923 an integer. That is, "int", "unsigned int", "bool", an enumerated 924 type or any typedefed type that evaluates to one of these is legal. 925 Also, the case values must be one of the legal values of the 926 discriminant. Finally, a case value may not be specified more than 927 once within the scope of a union declaration. 929 7. AN EXAMPLE OF AN XDR DATA DESCRIPTION 931 Here is a short XDR data description of a thing called a "file", 932 which might be used to transfer files from one machine to another. 934 const MAXUSERNAME = 32; /* max length of a user name */ 935 const MAXFILELEN = 65535; /* max length of a file */ 936 const MAXNAMELEN = 255; /* max length of a file name */ 938 /* 939 * Types of files: 940 */ 941 enum filekind { 942 TEXT = 0, /* ascii data */ 943 DATA = 1, /* raw data */ 944 EXEC = 2 /* executable */ 945 }; 947 /* 948 * File information, per kind of file: 949 */ 950 union filetype switch (filekind kind) { 951 case TEXT: 952 void; /* no extra information */ 953 case DATA: 954 string creator; /* data creator */ 955 case EXEC: 957 string interpretor; /* program interpretor */ 958 }; 960 /* 961 * A complete file: 962 */ 963 struct file { 964 string filename; /* name of file */ 965 filetype type; /* info about file */ 966 string owner; /* owner of file */ 967 opaque data; /* file data */ 968 }; 970 Suppose now that there is a user named "john" who wants to store his 971 lisp program "sillyprog" that contains just the data "(quit)". His 972 file would be encoded as follows: 974 OFFSET HEX BYTES ASCII COMMENTS 975 ------ --------- ----- -------- 976 0 00 00 00 09 .... -- length of filename = 9 977 4 73 69 6c 6c sill -- filename characters 978 8 79 70 72 6f ypro -- ... and more characters ... 979 12 67 00 00 00 g... -- ... and 3 zero-bytes of fill 980 16 00 00 00 02 .... -- filekind is EXEC = 2 981 20 00 00 00 04 .... -- length of interpretor = 4 982 24 6c 69 73 70 lisp -- interpretor characters 983 28 00 00 00 04 .... -- length of owner = 4 984 32 6a 6f 68 6e john -- owner characters 985 36 00 00 00 06 .... -- length of file data = 6 986 40 28 71 75 69 (qui -- file data bytes ... 987 44 74 29 00 00 t).. -- ... and 2 zero-bytes of fill 989 8. Security Considerations 991 Security issues are not discussed in this memo. 993 9. IANA Considerations 995 It is possible, if not likely, that new data types will 996 be added to XDR in the future. The process for adding 997 new types is via a standards track RFC and not 998 registration of new types with IANA. Standards track RFCs 999 that update or replace this document should be 1000 documented as such in the RFC Editor's database of 1001 RFCs. 1003 10. TRADEMARKS AND OWNERS 1005 SUN WORKSTATION Sun Microsystems, Inc. 1006 VAX Hewlett-Packard Company 1007 IBM-PC International Business Machines Corporation 1008 Cray Cray Inc. 1009 NFS Sun Microsystems, Inc. 1010 Ethernet Xerox Corporation. 1011 Motorola 68000 Motorola, Inc. 1012 IBM 370 International Business Machines Corporation 1014 11. ANSI/IEEE Standard 754-1985 1016 The definition of NaNs, signed zero and infinity, and denormalized 1017 numbers from [IEEE] is reproduced here for convenience. The 1018 definitions for quadruple-precision floating point numbers are 1019 analogs of those for single and double-precision floating point 1020 numbers, and are defined in [IEEE]. 1022 In the following, 'S' stands for the sign bit, 'E' for the exponent, 1023 and 'F' for the fractional part. The symbol 'u' stands for an 1024 undefined bit (0 or 1). 1026 For single-precision floating point numbers: 1028 Type S (1 bit) E (8 bits) F (23 bits) 1029 ---- --------- ---------- ----------- 1030 signalling NaN u 255 (max) .0uuuuu---u 1031 (with at least 1032 one 1 bit) 1033 quiet NaN u 255 (max) .1uuuuu---u 1035 negative infinity 1 255 (max) .000000---0 1037 positive infinity 0 255 (max) .000000---0 1039 negative zero 1 0 .000000---0 1041 positive zero 0 0 .000000---0 1043 For double-precision floating point numbers: 1045 Type S (1 bit) E (11 bits) F (52 bits) 1046 ---- --------- ----------- ----------- 1047 signalling NaN u 2047 (max) .0uuuuu---u 1048 (with at least 1049 one 1 bit) 1050 quiet NaN u 2047 (max) .1uuuuu---u 1051 negative infinity 1 2047 (max) .000000---0 1053 positive infinity 0 2047 (max) .000000---0 1055 negative zero 1 0 .000000---0 1057 positive zero 0 0 .000000---0 1059 For quadruple-precision floating point numbers: 1061 Type S (1 bit) E (15 bits) F (112 bits) 1062 ---- --------- ----------- ------------ 1063 signalling NaN u 32767 (max) .0uuuuu---u 1064 (with at least 1065 one 1 bit) 1066 quiet NaN u 32767 (max) .1uuuuu---u 1068 negative infinity 1 32767 (max) .000000---0 1070 positive infinity 0 32767 (max) .000000---0 1072 negative zero 1 0 .000000---0 1074 positive zero 0 0 .000000---0 1076 Subnormal numbers are represented as follows: 1078 Precision Exponent Value 1079 --------- -------- ----- 1080 Single 0 (-1)**S * 2**(-126) * 0.F 1082 Double 0 (-1)**S * 2**(-1022) * 0.F 1084 Quadruple 0 (-1)**S * 2**(-16382) * 0.F 1086 12. NORMATIVE REFERENCES 1088 [IEEE] "IEEE Standard for Binary Floating-Point Arithmetic", 1089 ANSI/IEEE Standard 754-1985, Institute of Electrical and 1090 Electronics Engineers, August 1985. 1092 13. INFORMATIVE REFERENCES 1094 [KERN] Brian W. Kernighan & Dennis M. Ritchie, "The C Programming 1095 Language", Bell Laboratories, Murray Hill, New Jersey, 1978. 1097 [COHE] Danny Cohen, "On Holy Wars and a Plea for Peace", IEEE 1098 Computer, October 1981. 1100 [COUR] "Courier: The Remote Procedure Call Protocol", XEROX 1101 Corporation, XSIS 038112, December 1981. 1103 [SPAR] "The SPARC Architecture Manual: Version 8", Prentice Hall, 1104 ISBN 0-13-825001-4. 1106 [HPRE] "HP Precision Architecture Handbook", June 1987, 5954-9906. 1108 14. Editor's Address 1110 Mike Eisler 1111 5765 Chase Point Circle 1112 Colorado Springs, CO 80919 1113 USA 1115 Phone: 719-599-9026 1116 EMail: mike@eisler.com 1118 15. Acknowledgements 1120 Bob Lyon was Sun's visible force behind ONC RPC in the 1980s. Sun 1121 Microsystems, Inc. is listed as the author of RFC1014, which RFC1832 1122 was heavily derived from. Raj Srinivasan in turn edited RFC1014 into 1123 RFC1832. Raj and the rest of the old ONC RPC working group produced 1124 RFC1832 from which this document is derived. Mike Eisler and Bill 1125 Janssen submitted the implementation reports for this standard. Kevin 1126 Coffman and Benny Halevy reviewed this document and gave feedback. 1127 Bryan Olson pointed out several errors in RFC1832 which are corrected 1128 in this document. 1130 16. IPR Notices 1132 The IETF takes no position regarding the validity or scope of any 1133 intellectual property or other rights that might be claimed to 1134 pertain to the implementation or use of the technology described in 1135 this document or the extent to which any license under such rights 1136 might or might not be available; neither does it represent that it 1137 has made any effort to identify any such rights. Information on the 1138 IETF's procedures with respect to rights in standards-track and 1139 standards-related documentation can be found in BCP-11. Copies of 1140 claims of rights made available for publication and any assurances of 1141 licenses to be made available, or the result of an attempt made to 1142 obtain a general license or permission for the use of such 1143 proprietary rights by implementors or users of this specification can 1144 be obtained from the IETF Secretariat. 1146 The IETF invites any interested party to bring to its attention any 1147 copyrights, patents or patent applications, or other proprietary 1148 rights which may cover technology that may be required to practice 1149 this standard. Please address the information to the IETF Executive 1150 Director. 1152 17. Copyright Notice 1154 Copyright (C) The Internet Society (2004). This document is subject 1155 to the rights, licenses and restrictions contained in BCP 78, and 1156 except as set forth therein, the authors retain all their rights. 1158 This document and the information contained herein are provided on an 1159 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1160 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1161 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1162 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1163 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1164 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.