idnits 2.17.1 draft-ietf-nfsv4-rfc1832bis-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == 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 798 has weird spacing: '...onsider the ...' == Line 807 has weird spacing: '...old and rainy...' == Line 808 has weird spacing: '...old and rainy...' == Line 1143 has weird spacing: '...for the purpo...' -- 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 (February 2003) is 7734 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: 1 error (**), 0 flaws (~~), 9 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Eisler 3 Internet-Draft Editor 4 Document: draft-ietf-nfsv4-rfc1832bis-00.txt Network Appliance, Inc. 5 February 2003 7 XDR: External Data Representation Standard 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other 21 documents at any time. It is inappropriate to use Internet- 22 Drafts as reference material or to cite them other than as 23 "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 . . . . . . . . . . . . . . . . . . . 21 72 11. ANSI/IEEE Standard 754-1985 . . . . . . . . . . . . . . . . 21 73 12. NORMATIVE REFERENCES . . . . . . . . . . . . . . . . . . . 23 74 13. INFORMATIVE REFERENCES . . . . . . . . . . . . . . . . . . 23 75 14. Author's Address . . . . . . . . . . . . . . . . . . . . . 23 76 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 24 77 16. IPR Notices . . . . . . . . . . . . . . . . . . . . . . . . 24 78 17. Copyright Notice . . . . . . . . . . . . . . . . . . . . . 24 80 1. Changes from RFC1832 82 This document makes no technical changes to RFC1832 and is published 83 for the purpose 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 encodes lists of arbitrary length strings: 667 struct *stringlist { 668 string item<>; 669 stringlist next; 670 }; 672 It could have been equivalently declared as the following union: 674 union stringlist switch (bool opted) { 675 case TRUE: 676 struct { 677 string item<>; 678 stringlist next; 679 } element; 680 case FALSE: 681 void; 682 }; 684 or as a variable-length array: 686 struct stringlist<1> { 687 string item<>; 688 stringlist next; 689 }; 691 Both of these declarations obscure the intention of the stringlist 692 type, so the optional-data declaration is preferred over both of 693 them. The optional-data type also has a close correlation to how 694 recursive data structures are represented in high-level languages 695 such as Pascal or C by use of pointers. In fact, the syntax is the 696 same as that of the C language for pointers. 698 4.20. Areas for Future Enhancement 700 The XDR standard lacks representations for bit fields and bitmaps, 701 since the standard is based on bytes. Also missing are packed (or 702 binary-coded) decimals. 704 The intent of the XDR standard was not to describe every kind of data 705 that people have ever sent or will ever want to send from machine to 706 machine. Rather, it only describes the most commonly used data-types 707 of high-level languages such as Pascal or C so that applications 708 written in these languages will be able to communicate easily over 709 some medium. 711 One could imagine extensions to XDR that would let it describe almost 712 any existing protocol, such as TCP. The minimum necessary for this 713 are support for different block sizes and byte-orders. The XDR 714 discussed here could then be considered the 4-byte big-endian member 715 of a larger XDR family. 717 5. DISCUSSION 719 (1) Why use a language for describing data? What's wrong with 720 diagrams? 722 There are many advantages in using a data-description language such 723 as XDR versus using diagrams. Languages are more formal than 724 diagrams and lead to less ambiguous descriptions of data. Languages 725 are also easier to understand and allow one to think of other issues 726 instead of the low-level details of bit-encoding. Also, there is a 727 close analogy between the types of XDR and a high-level language such 728 as C or Pascal. This makes the implementation of XDR encoding and 729 decoding modules an easier task. Finally, the language specification 730 itself is an ASCII string that can be passed from machine to machine 731 to perform on-the-fly data interpretation. 733 (2) Why is there only one byte-order for an XDR unit? 735 Supporting two byte-orderings requires a higher level protocol for 736 determining in which byte-order the data is encoded. Since XDR is 737 not a protocol, this can't be done. The advantage of this, though, 738 is that data in XDR format can be written to a magnetic tape, for 739 example, and any machine will be able to interpret it, since no 740 higher level protocol is necessary for determining the byte-order. 742 (3) Why is the XDR byte-order big-endian instead of little-endian? 743 Isn't this unfair to little-endian machines such as the VAX(r), which 744 has to convert from one form to the other? 746 Yes, it is unfair, but having only one byte-order means you have to 747 be unfair to somebody. Many architectures, such as the Motorola 748 68000* and IBM 370*, support the big-endian byte-order. 750 (4) Why is the XDR unit four bytes wide? 752 There is a tradeoff in choosing the XDR unit size. Choosing a small 753 size such as two makes the encoded data small, but causes alignment 754 problems for machines that aren't aligned on these boundaries. A 755 large size such as eight means the data will be aligned on virtually 756 every machine, but causes the encoded data to grow too big. We chose 757 four as a compromise. Four is big enough to support most 758 architectures efficiently, except for rare machines such as the 759 eight-byte aligned Cray*. Four is also small enough to keep the 760 encoded data restricted to a reasonable size. 762 (5) Why must variable-length data be padded with zeros? 764 It is desirable that the same data encode into the same thing on all 765 machines, so that encoded data can be meaningfully compared or 766 checksummed. Forcing the padded bytes to be zero ensures this. 768 (6) Why is there no explicit data-typing? 770 Data-typing has a relatively high cost for what small advantages it 771 may have. One cost is the expansion of data due to the inserted type 772 fields. Another is the added cost of interpreting these type fields 773 and acting accordingly. And most protocols already know what type 774 they expect, so data-typing supplies only redundant information. 775 However, one can still get the benefits of data-typing using XDR. One 776 way is to encode two things: first a string which is the XDR data 777 description of the encoded data, and then the encoded data itself. 778 Another way is to assign a value to all the types in XDR, and then 779 define a universal type which takes this value as its discriminant 780 and for each value, describes the corresponding data type. 782 6. THE XDR LANGUAGE SPECIFICATION 784 6.1. Notational Conventions 786 This specification uses an extended Back-Naur Form notation for 787 describing the XDR language. Here is a brief description of the 788 notation: 790 (1) The characters '|', '(', ')', '[', ']', '"', and '*' are special. 791 (2) Terminal symbols are strings of any characters surrounded by 792 double quotes. (3) Non-terminal symbols are strings of non-special 793 characters. (4) Alternative items are separated by a vertical bar 794 ("|"). (5) Optional items are enclosed in brackets. (6) Items are 795 grouped together by enclosing them in parentheses. (7) A '*' 796 following an item means 0 or more occurrences of that item. 798 For example, consider the following pattern: 800 "a " "very" (", " "very")* [" cold " "and "] " rainy " 801 ("day" | "night") 803 An infinite number of strings match this pattern. A few of them are: 805 "a very rainy day" 806 "a very, very rainy day" 807 "a very cold and rainy day" 808 "a very, very, very cold and rainy night" 810 6.2. Lexical Notes 812 (1) Comments begin with '/*' and terminate with '*/'. (2) White 813 space serves to separate items and is otherwise ignored. (3) An 814 identifier is a letter followed by an optional sequence of letters, 815 digits or underbar ('_'). The case of identifiers is not ignored. 816 (4) A constant is a sequence of one or more decimal digits, 817 optionally preceded by a minus-sign ('-'). 819 6.3. Syntax Information 821 declaration: 822 type-specifier identifier 823 | type-specifier identifier "[" value "]" 824 | type-specifier identifier "<" [ value ] ">" 825 | "opaque" identifier "[" value "]" 826 | "opaque" identifier "<" [ value ] ">" 827 | "string" identifier "<" [ value ] ">" 828 | type-specifier "*" identifier 829 | "void" 831 value: 832 constant 833 | identifier 835 type-specifier: 836 [ "unsigned" ] "int" 837 | [ "unsigned" ] "hyper" 838 | "float" 839 | "double" 840 | "quadruple" 841 | "bool" 842 | enum-type-spec 843 | struct-type-spec 844 | union-type-spec 845 | identifier 847 enum-type-spec: 848 "enum" enum-body 850 enum-body: 851 "{" 852 ( identifier "=" value ) 853 ( "," identifier "=" value )* 854 "}" 856 struct-type-spec: 857 "struct" struct-body 859 struct-body: 860 "{" 861 ( declaration ";" ) 862 ( declaration ";" )* 863 "}" 865 union-type-spec: 866 "union" union-body 868 union-body: 869 "switch" "(" declaration ")" "{" 870 ( "case" value ":" declaration ";" ) 871 ( "case" value ":" declaration ";" )* 872 [ "default" ":" declaration ";" ] 873 "}" 875 constant-def: 876 "const" identifier "=" constant ";" 878 type-def: 879 "typedef" declaration ";" 880 | "enum" identifier enum-body ";" 881 | "struct" identifier struct-body ";" 882 | "union" identifier union-body ";" 884 definition: 885 type-def 886 | constant-def 888 specification: 889 definition * 891 6.4. Syntax Notes 893 (1) The following are keywords and cannot be used as identifiers: 894 "bool", "case", "const", "default", "double", "quadruple", "enum", 895 "float", "hyper", "opaque", "string", "struct", "switch", "typedef", 896 "union", "unsigned" and "void". 898 (2) Only unsigned constants may be used as size specifications for 899 arrays. If an identifier is used, it must have been declared 900 previously as an unsigned constant in a "const" definition. 902 (3) Constant and type identifiers within the scope of a specification 903 are in the same name space and must be declared uniquely within this 904 scope. 906 (4) Similarly, variable names must be unique within the scope of 907 struct and union declarations. Nested struct and union declarations 908 create new scopes. 910 (5) The discriminant of a union must be of a type that evaluates to 911 an integer. That is, "int", "unsigned int", "bool", an enumerated 912 type or any typedefed type that evaluates to one of these is legal. 913 Also, the case values must be one of the legal values of the 914 discriminant. Finally, a case value may not be specified more than 915 once within the scope of a union declaration. 917 7. AN EXAMPLE OF AN XDR DATA DESCRIPTION 919 Here is a short XDR data description of a thing called a "file", 920 which might be used to transfer files from one machine to another. 922 const MAXUSERNAME = 32; /* max length of a user name */ 923 const MAXFILELEN = 65535; /* max length of a file */ 924 const MAXNAMELEN = 255; /* max length of a file name */ 926 /* 927 * Types of files: 928 */ 929 enum filekind { 930 TEXT = 0, /* ascii data */ 931 DATA = 1, /* raw data */ 932 EXEC = 2 /* executable */ 933 }; 935 /* 936 * File information, per kind of file: 937 */ 938 union filetype switch (filekind kind) { 939 case TEXT: 940 void; /* no extra information */ 941 case DATA: 942 string creator; /* data creator */ 943 case EXEC: 944 string interpretor; /* program interpretor */ 945 }; 947 /* 948 * A complete file: 949 */ 950 struct file { 951 string filename; /* name of file */ 952 filetype type; /* info about file */ 953 string owner; /* owner of file */ 954 opaque data; /* file data */ 956 }; 958 Suppose now that there is a user named "john" who wants to store his 959 lisp program "sillyprog" that contains just the data "(quit)". His 960 file would be encoded as follows: 962 OFFSET HEX BYTES ASCII COMMENTS 963 ------ --------- ----- -------- 964 0 00 00 00 09 .... -- length of filename = 9 965 4 73 69 6c 6c sill -- filename characters 966 8 79 70 72 6f ypro -- ... and more characters ... 967 12 67 00 00 00 g... -- ... and 3 zero-bytes of fill 968 16 00 00 00 02 .... -- filekind is EXEC = 2 969 20 00 00 00 04 .... -- length of interpretor = 4 970 24 6c 69 73 70 lisp -- interpretor characters 971 28 00 00 00 04 .... -- length of owner = 4 972 32 6a 6f 68 6e john -- owner characters 973 36 00 00 00 06 .... -- length of file data = 6 974 40 28 71 75 69 (qui -- file data bytes ... 975 44 74 29 00 00 t).. -- ... and 2 zero-bytes of fill 977 8. Security Considerations 979 Security issues are not discussed in this memo. 981 9. IANA Considerations 983 There are no issues for IANA. 985 10. TRADEMARKS AND OWNERS 987 SUN WORKSTATION Sun Microsystems, Inc. 988 VAX Hewlett-Packard Company 989 IBM-PC International Business Machines Corporation 990 Cray Cray Inc. 991 NFS Sun Microsystems, Inc. 992 Ethernet Xerox Corporation. 993 Motorola 68000 Motorola, Inc. 994 IBM 370 International Business Machines Corporation 996 11. ANSI/IEEE Standard 754-1985 998 The definition of NaNs, signed zero and infinity, and denormalized 999 numbers from [IEEE] is reproduced here for convenience. The 1000 definitions for quadruple-precision floating point numbers are 1001 analogs of those for single and double-precision floating point 1002 numbers, and are defined in [IEEE]. 1004 In the following, 'S' stands for the sign bit, 'E' for the exponent, 1005 and 'F' for the fractional part. The symbol 'u' stands for an 1006 undefined bit (0 or 1). 1008 For single-precision floating point numbers: 1010 Type S (1 bit) E (8 bits) F (23 bits) 1011 ---- --------- ---------- ----------- 1012 signalling NaN u 255 (max) .0uuuuu---u 1013 (with at least 1014 one 1 bit) 1015 quiet NaN u 255 (max) .1uuuuu---u 1017 negative infinity 1 255 (max) .000000---0 1019 positive infinity 0 255 (max) .000000---0 1021 negative zero 1 0 .000000---0 1023 positive zero 0 0 .000000---0 1025 For double-precision floating point numbers: 1027 Type S (1 bit) E (11 bits) F (52 bits) 1028 ---- --------- ----------- ----------- 1029 signalling NaN u 2047 (max) .0uuuuu---u 1030 (with at least 1031 one 1 bit) 1032 quiet NaN u 2047 (max) .1uuuuu---u 1034 negative infinity 1 2047 (max) .000000---0 1036 positive infinity 0 2047 (max) .000000---0 1038 negative zero 1 0 .000000---0 1040 positive zero 0 0 .000000---0 1042 For quadruple-precision floating point numbers: 1044 Type S (1 bit) E (15 bits) F (112 bits) 1045 ---- --------- ----------- ------------ 1046 signalling NaN u 32767 (max) .0uuuuu---u 1047 (with at least 1048 one 1 bit) 1049 quiet NaN u 32767 (max) .1uuuuu---u 1050 negative infinity 1 32767 (max) .000000---0 1052 positive infinity 0 32767 (max) .000000---0 1054 negative zero 1 0 .000000---0 1056 positive zero 0 0 .000000---0 1058 Subnormal numbers are represented as follows: 1060 Precision Exponent Value 1061 --------- -------- ----- 1062 Single 0 (-1)**S * 2**(-126) * 0.F 1064 Double 0 (-1)**S * 2**(-1022) * 0.F 1066 Quadruple 0 (-1)**S * 2**(-16382) * 0.F 1068 12. NORMATIVE REFERENCES 1070 [IEEE] "IEEE Standard for Binary Floating-Point Arithmetic", 1071 ANSI/IEEE Standard 754-1985, Institute of Electrical and 1072 Electronics Engineers, August 1985. 1074 13. INFORMATIVE REFERENCES 1076 [KERN] Brian W. Kernighan & Dennis M. Ritchie, "The C Programming 1077 Language", Bell Laboratories, Murray Hill, New Jersey, 1978. 1079 [COHE] Danny Cohen, "On Holy Wars and a Plea for Peace", IEEE 1080 Computer, October 1981. 1082 [COUR] "Courier: The Remote Procedure Call Protocol", XEROX 1083 Corporation, XSIS 038112, December 1981. 1085 [SPAR] "The SPARC Architecture Manual: Version 8", Prentice Hall, 1086 ISBN 0-13-825001-4. 1088 [HPRE] "HP Precision Architecture Handbook", June 1987, 5954-9906. 1090 14. Author's Address 1092 Mike Eisler 1093 5765 Chase Point Circle 1094 Colorado Springs, CO 80919 1095 USA 1097 Phone: 719-599-9026 1098 EMail: mike@eisler.com 1100 15. Acknowledgements 1102 Bob Lyon was Sun's visible force behind ONC RPC in the 1980s. Sun 1103 Microsystems, Inc. is listed as the author of RFC1014, which RFC1832 1104 was heavily derived from. Raj Srinivasan in turn edited RFC1014 into 1105 RFC1832. Raj and the rest of the old ONC RPC working group produced 1106 RFC1832 from which this document is derived. Mike Eisler and Bill 1107 Janssen submitted the implementation reports for this standard. 1109 16. IPR Notices 1111 The IETF takes no position regarding the validity or scope of any 1112 intellectual property or other rights that might be claimed to 1113 pertain to the implementation or use of the technology described in 1114 this document or the extent to which any license under such rights 1115 might or might not be available; neither does it represent that it 1116 has made any effort to identify any such rights. Information on the 1117 IETF's procedures with respect to rights in standards-track and 1118 standards-related documentation can be found in BCP-11. Copies of 1119 claims of rights made available for publication and any assurances of 1120 licenses to be made available, or the result of an attempt made to 1121 obtain a general license or permission for the use of such 1122 proprietary rights by implementors or users of this specification can 1123 be obtained from the IETF Secretariat. 1125 The IETF invites any interested party to bring to its attention any 1126 copyrights, patents or patent applications, or other proprietary 1127 rights which may cover technology that may be required to practice 1128 this standard. Please address the information to the IETF Executive 1129 Director. 1131 17. Copyright Notice 1133 Copyright (C) The Internet Society (2003). All Rights Reserved. 1135 This document and translations of it may be copied and furnished to 1136 others, and derivative works that comment on or otherwise explain it 1137 or assist in its implementation may be prepared, copied, published 1138 and distributed, in whole or in part, without restriction of any 1139 kind, provided that the above copyright notice and this paragraph are 1140 included on all such copies and derivative works. However, this 1141 document itself may not be modified in any way, such as by removing 1142 the copyright notice or references to the Internet Society or other 1143 Internet organizations, except as needed for the purpose of 1144 developing Internet standards in which case the procedures for 1145 copyrights defined in the Internet Standards process must be 1146 followed, or as required to translate it into languages other than 1147 English. 1149 The limited permissions granted above are perpetual and will not be 1150 revoked by the Internet Society or its successors or assigns. 1152 This document and the information contained herein is provided on an 1153 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1154 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1155 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1156 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1157 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.