dwarf5/latexdoc/typeentries.tex

   1 \chapter{Type Entries}
   2 \label{chap:typeentries}
   3 This section presents the debugging information entries
   4 that describe program types: base types, modified types and
   5 user\dash defined types.
   6
   7 If the scope of the declaration of a named type begins after
   8 \hypertarget{chap:DWATstartscopetypedeclaration}{}
   9 the low pc value for the scope most closely enclosing the
  10 declaration, the declaration may have a
  11 \DWATstartscope{}
  12 attribute as described for objects in
  13 Section \refersec{chap:dataobjectentries}.
  14
  15 \section{Base Type Entries}
  16 \label{chap:basetypeentries}
  17
  18 \textit{A base type is a data type that is not defined in terms of
  19 other data types.
  20 \addtoindexx{fundamental type|see{base type entry}}
  21 Each programming language has a set of base
  22 types that are considered to be built into that language.}
  23
  24 A base type is represented by a debugging information entry
  25 with the tag
  26 \DWTAGbasetypeTARG.
  27
  28 A \addtoindex{base type entry}
  29 has a \DWATname{} attribute
  30 whose
  31 \addtoindexx{name attribute}
  32 value is
  33 a null\dash terminated string containing the name of the base type
  34 as recognized by the programming language of the compilation
  35 unit containing the base type entry.
  36
  37 A base type entry has
  38 \addtoindexx{encoding attribute}
  39 a \DWATencoding{} attribute describing
  40 how the base type is encoded and is to be interpreted. The
  41 value of this attribute is an
  42 \livelink{chap:classconstant}{integer constant}. The set of
  43 values and their meanings for the
  44 \DWATencoding{} attribute
  45 is given in
  46 Table \refersec{tab:encodingattributevalues}
  47 and following text.
  48
  49 A base type entry
  50 may have a \DWATendianity{} attribute
  51 \addtoindexx{endianity attribute}
  52 as described in
  53 Section \refersec{chap:dataobjectentries}.
  54 If omitted, the encoding assumes the representation that
  55 is the default for the target architecture.
  56
  57 A base type entry has
  58 \hypertarget{chap:DWATbytesizedataobjectordatatypesize}{}
  59 either a \DWATbytesize{} attribute
  60 \hypertarget{chap:DWATbitsizebasetypebitsize}{}
  61 or a \DWATbitsize{} attribute
  62 \addtoindexx{bit size attribute}
  63 whose \livelink{chap:classconstant}{integer constant} value
  64 (see Section \refersec{chap:byteandbitsizes})
  65 is the amount of storage needed to hold
  66 a value of the type.
  67
  68 \needlines{5}
  69 \textit{For example, the
  70 \addtoindex{C} type \texttt{int} on a machine that uses 32\dash bit
  71 integers is represented by a base type entry with a name
  72 attribute whose value is \doublequote{int}, an encoding attribute
  73 whose value is \DWATEsigned{}
  74 and a byte size attribute whose value is 4.}
  75
  76 If the value of an object of the given type does not fully
  77 occupy the storage described by a byte size attribute,
  78 \hypertarget{chap:DWATdatabitoffsetbasetypebitlocation}{}
  79 the base type entry may also have
  80 \addtoindexx{bit size attribute}
  81 a
  82 \DWATbitsize{} and a
  83 \DWATdatabitoffset{} attribute,
  84 both
  85 \addtoindexx{data bit offset attribute}
  86 of whose values are
  87 \livelink{chap:classconstant}{integer constant} values
  88 (see Section \refersec{chap:staticanddynamicvaluesofattributes}).
  89 The bit size
  90 attribute describes the actual size in bits used to represent
  91 values of the given type. The data bit offset attribute is the
  92 offset in bits from the beginning of the containing storage to
  93 the beginning of the value. Bits that are part of the offset
  94 are padding. The data bit offset uses the bit numbering and
  95 direction conventions that are appropriate to the current
  96 language on the
  97 target system to locate the beginning of the storage and
  98 value. If this attribute is omitted a default data bit offset
  99 of zero is assumed.
 100
 101 \textit{Attribute
 102 \DWATdatabitoffset{}
 103 is
 104 \addtoindexx{bit offset attribute}
 105 new
 106 \addtoindexx{data bit offset attribute}
 107 in
 108 \addtoindex{DWARF Version 4}, unchanged in \addtoindex{DWARF Version 5}, and
 109 is also used for bit field members
 110 (see Section \refersec{chap:datamemberentries}).
 111 It
 112 \hypertarget{chap:DWATbitoffsetbasetypebitlocation}{}
 113 replaces the attribute
 114 \DWATbitoffset{}
 115 when used for base
 116 \addtoindexx{bit offset attribute (V3)}
 117 types as defined in DWARF V3 and earlier.
 118 \DWATbitoffset{}
 119 is deprecated for use in base types in DWARF Version 4 and later.
 120 See Section 5.1 in the DWARF Version 4
 121 specification for a discussion of compatibility considerations.}
 122
 123 \begin{table}[!here]
 124 \caption{Encoding attribute values}
 125 \label{tab:encodingattributevalues}
 126 \centering
 127 \begin{tabular}{l|p{8cm}}
 128 \hline
 129 Name&Meaning\\ \hline
 130 \DWATEaddressTARG{} & linear machine address (for segmented\break
 131   addresses see
 132   Section \refersec{chap:segmentedaddresses}) \\
 133 \DWATEbooleanTARG& true or false \\
 134
 135 \DWATEcomplexfloatTARG& complex binary
 136 floating\dash point number \\
 137 \DWATEfloatTARG{} & binary floating\dash point number \\
 138 \DWATEimaginaryfloatTARG& imaginary binary
 139 floating\dash point number \\
 140 \DWATEsignedTARG& signed binary integer \\
 141 \DWATEsignedcharTARG& signed character \\
 142 \DWATEunsignedTARG{} & unsigned binary integer \\
 143 \DWATEunsignedcharTARG{} & unsigned character \\
 144 \DWATEpackeddecimalTARG{}  & packed decimal \\
 145 \DWATEnumericstringTARG& numeric string \\
 146 \DWATEeditedTARG{} & edited string \\
 147 \DWATEsignedfixedTARG{} & signed fixed\dash point scaled integer \\
 148 \DWATEunsignedfixedTARG& unsigned fixed\dash point scaled integer \\
 149 \DWATEdecimalfloatTARG{} & decimal floating\dash point number \\
 150 \DWATEUTFTARG{} & \addtoindex{Unicode} character \\
 151 \hline
 152 \end{tabular}
 153 \end{table}
 154
 155 \textit{The \DWATEdecimalfloat{} encoding is intended for
 156 floating\dash point representations that have a power\dash of\dash ten
 157 exponent, such as that specified in IEEE 754R.}
 158
 159 \textit{The \DWATEUTF{} encoding is intended for \addtoindex{Unicode}
 160 string encodings (see the Universal Character Set standard,
 161 ISO/IEC 10646\dash 1:1993). For example, the
 162 \addtoindex{C++} type char16\_t is
 163 represented by a base type entry with a name attribute whose
 164 value is \doublequote{char16\_t}, an encoding attribute whose value
 165 is \DWATEUTF{} and a byte size attribute whose value is 2.}
 166
 167 The
 168 \DWATEpackeddecimal{}
 169 and
 170 \DWATEnumericstring{}
 171 base types
 172 represent packed and unpacked decimal string numeric data
 173 types, respectively, either of which may be
 174 either
 175 \addtoindexx{decimal scale attribute}
 176 signed
 177 \addtoindexx{decimal sign attribute}
 178 or
 179 \addtoindexx{digit count attribute}
 180 unsigned.
 181 \hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}{}
 182 These
 183 \hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}{}
 184 base types are used in combination with
 185 \DWATdecimalsign,
 186 \DWATdigitcount{} and
 187 \DWATdecimalscale{}
 188 attributes.
 189
 190 \needlines{5}
 191 A \DWATdecimalsign{} attribute
 192 \addtoindexx{decimal sign attribute}
 193 is an \livelink{chap:classconstant}{integer constant} that
 194 conveys the representation of the sign of the decimal type
 195 (see Table \refersec{tab:decimalsignattributevalues}).
 196 Its \livelink{chap:classconstant}{integer constant} value is interpreted to
 197 mean that the type has a leading overpunch, trailing overpunch,
 198 leading separate or trailing separate sign representation or,
 199 alternatively, no sign at all.
 200
 201 \begin{table}[here]
 202 \caption{Decimal sign attribute values}
 203 \label{tab:decimalsignattributevalues}
 204 \centering
 205 \begin{tabular}{l|p{9cm}}
 206 \hline
 207  Name & Meaning \\
 208 \hline
 209 \DWDSunsignedTARG{} &  Unsigned \\
 210 \DWDSleadingoverpunchTARG{} & Sign
 211 is encoded in the most significant digit in a target\dash dependent  manner \\
 212 \DWDStrailingoverpunchTARG{} & Sign
 213 is encoded in the least significant digit in a target\dash dependent manner \\
 214 \DWDSleadingseparateTARG{}
 215 & Decimal type: Sign is a \doublequote{+} or \doublequote{-} character
 216 to the left of the most significant digit. \\
 217 \DWDStrailingseparateTARG{}
 218 & Decimal type: Sign is a \doublequote{+} or \doublequote{-} character
 219 to the right of the least significant digit. \\
 220 &Packed decimal type: Least significant nibble contains
 221 a target\dash dependent value
 222 indicating positive or negative. \\
 223 \hline
 224 \end{tabular}
 225 \end{table}
 226
 227 The
 228 \DWATdigitcount{}
 229 attribute
 230 \addtoindexx{digit count attribute}
 231 is an \livelink{chap:classconstant}{integer constant}
 232 value that represents the number of digits in an instance of
 233 the type.
 234
 235 \hypertarget{chap:DWATdecimalscaledecimalscalefactor}{}
 236 The \DWATdecimalscale{}
 237 attribute
 238 \addtoindexx{decimal scale attribute}
 239 is an integer constant value
 240 that represents the exponent of the base ten scale factor to
 241 be applied to an instance of the type. A scale of zero puts the
 242 decimal point immediately to the right of the least significant
 243 digit. Positive scale moves the decimal point to the right
 244 and implies that additional zero digits on the right are not
 245 stored in an instance of the type. Negative scale moves the
 246 decimal point to the left; if the absolute value of the scale
 247 is larger than the digit count, this implies additional zero
 248 digits on the left are not stored in an instance of the type.
 249
 250 The \DWATEedited{}
 251 base
 252 \hypertarget{chap:DWATpicturestringpicturestringfornumericstringtype}{}
 253 type is used to represent an edited
 254 numeric or alphanumeric data type. It is used in combination
 255 with a \DWATpicturestring{} attribute whose value is a
 256 null\dash terminated string containing the target\dash dependent picture
 257 string associated with the type.
 258
 259 If the edited base type entry describes an edited numeric
 260 data type, the edited type entry has a \DWATdigitcount{} and a
 261 \DWATdecimalscale{} attribute.
 262 \addtoindexx{decimal scale attribute}
 263 These attributes have the same
 264 interpretation as described for the
 265 \DWATEpackeddecimal{} and
 266 \DWATEnumericstring{} base
 267 types. If the edited type entry
 268 describes an edited alphanumeric data type, the edited type
 269 entry does not have these attributes.
 270
 271
 272 \textit{The presence or absence of the \DWATdigitcount{} and
 273 \DWATdecimalscale{} attributes
 274 \addtoindexx{decimal scale attribute}
 275 allows a debugger to easily
 276 distinguish edited numeric from edited alphanumeric, although
 277 in principle the digit count and scale are derivable by
 278 interpreting the picture string.}
 279
 280 The \DWATEsignedfixed{} and \DWATEunsignedfixed{} entries
 281 describe signed and unsigned fixed\dash point binary data types,
 282 respectively.
 283
 284 The fixed binary type entries have
 285 \addtoindexx{digit count attribute}
 286 a
 287 \DWATdigitcount{}
 288 attribute with the same interpretation as described for the
 289 \DWATEpackeddecimal{} and \DWATEnumericstring{} base types.
 290
 291 \needlines{4}
 292 For a data type with a decimal scale factor, the fixed binary
 293 type entry has a
 294 \DWATdecimalscale{} attribute
 295 \addtoindexx{decimal scale attribute}
 296 with the same
 297 interpretation as described for the
 298 \DWATEpackeddecimal{}
 299 and \DWATEnumericstring{} base types.
 300
 301 \hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}{}
 302 For a data type with a binary scale factor, the fixed
 303 \addtoindexx{binary scale attribute}
 304 binary type entry has a
 305 \DWATbinaryscale{} attribute.
 306 The
 307 \DWATbinaryscale{} attribute
 308 is an \livelink{chap:classconstant}{integer constant} value
 309 that represents the exponent of the base two scale factor to
 310 be applied to an instance of the type.  Zero scale puts the
 311 binary point immediately to the right of the least significant
 312 bit. Positive scale moves the binary point to the right and
 313 implies that additional zero bits on the right are not stored
 314 in an instance of the type. Negative scale moves the binary
 315 point to the left; if the absolute value of the scale is
 316 larger than the number of bits, this implies additional zero
 317 bits on the left are not stored in an instance of the type.
 318
 319 For
 320 \hypertarget{chap:DWATsmallscalefactorforfixedpointtype}{}
 321 a data type with a non\dash decimal and non\dash binary scale factor,
 322 the fixed binary type entry has a
 323 \DWATsmall{} attribute which
 324 \addtoindexx{small attribute}
 325 references a
 326 \DWTAGconstant{} entry. The scale factor value
 327 is interpreted in accordance with the value defined by the
 328 \DWTAGconstant{} entry. The value represented is the product
 329 of the integer value in memory and the associated constant
 330 entry for the type.
 331
 332 \textit{The \DWATsmall{} attribute
 333 is defined with the \addtoindex{Ada} \texttt{small}
 334 attribute in mind.}
 335
 336 \section{Unspecified Type Entries}
 337 \label{chap:unspecifiedtypeentries}
 338 \addtoindexx{unspecified type entry}
 339 \addtoindexx{void type|see{unspecified type entry}}
 340 Some languages have constructs in which a type
 341 may be left unspecified or the absence of a type
 342 may be explicitly indicated.
 343
 344 An unspecified (implicit, unknown, ambiguous or nonexistent)
 345 type is represented by a debugging information entry with
 346 the tag \DWTAGunspecifiedtypeTARG.
 347 If a name has been given
 348 to the type, then the corresponding unspecified type entry
 349 has a \DWATname{} attribute
 350 \addtoindexx{name attribute}
 351 whose value is
 352 a null\dash terminated
 353 string containing the name as it appears in the source program.
 354
 355 The interpretation of this debugging information entry is
 356 intentionally left flexible to allow it to be interpreted
 357 appropriately in different languages. For example, in
 358 \addtoindex{C} and \addtoindex{C++}
 359 the language implementation can provide an unspecified type
 360 entry with the name \doublequote{void} which can be referenced by the
 361 type attribute of pointer types and typedef declarations for
 362 'void' (see
 363 Sections \refersec{chap:typemodifierentries} and
 364 %The following reference was valid, so the following is probably correct.
 365 Section \refersec{chap:typedefentries},
 366 respectively). As another
 367 example, in \addtoindex{Ada} such an unspecified type entry can be referred
 368 to by the type attribute of an access type where the denoted
 369 \addtoindexx{incomplete type (Ada)}
 370 type is incomplete (the name is declared as a type but the
 371 definition is deferred to a separate compilation unit).
 372
 373 \section{Type Modifier Entries}
 374 \label{chap:typemodifierentries}
 375 \addtoindexx{type modifier entry}
 376
 377 A base or user\dash defined type may be modified in different ways
 378 in different languages. A type modifier is represented in
 379 DWARF by a debugging information entry with one of the tags
 380 given in Table \refersec{tab:typemodifiertags}.
 381 \addtoindexx{type modifier|see{atomic type entry}}
 382 \addtoindexx{type modifier|see{constant type entry}}
 383 \addtoindexx{type modifier|see{reference type entry}}
 384 \addtoindexx{type modifier|see{restricted type entry}}
 385 \addtoindexx{type modifier|see{packed type entry}}
 386 \addtoindexx{type modifier|see{pointer type entry}}
 387 \addtoindexx{type modifier|see{shared type entry}}
 388 \addtoindexx{type modifier|see{volatile type entry}}
 389
 390 If a name has been given to the modified type in the source
 391 program, then the corresponding modified type entry has
 392 a \DWATname{} attribute
 393 \addtoindexx{name attribute}
 394 whose value is a null\dash terminated
 395 string containing the modified type name as it appears in
 396 the source program.
 397
 398 Each of the type modifier entries has
 399 \addtoindexx{type attribute}
 400 a
 401 \DWATtype{} attribute,
 402 whose value is a \livelink{chap:classreference}{reference}
 403 to a debugging information entry
 404 describing a base type, a user-defined type or another type
 405 modifier.
 406
 407 A modified type entry describing a
 408 \addtoindexx{pointer type entry}
 409 pointer or \addtoindex{reference type}
 410 (using \DWTAGpointertype,
 411 \DWTAGreferencetype{} or
 412 \DWTAGrvaluereferencetype)
 413 % Another instance of no-good-place-to-put-index entry.
 414 may
 415 \addtoindexx{address class!attribute}
 416 have
 417 \hypertarget{chap:DWATadressclasspointerorreferencetypes}{}
 418 a
 419 \DWATaddressclass{}
 420 attribute to describe how objects having the given pointer
 421 or reference type ought to be dereferenced.
 422
 423 A modified type entry describing a \addtoindex{UPC} shared qualified type
 424 (using \DWTAGsharedtype) may have a
 425 \DWATcount{} attribute
 426 \addtoindexx{count attribute}
 427 whose value is a constant expressing the (explicit or implied) blocksize specified for the
 428 type in the source. If no count attribute is present, then the \doublequote{infinite}
 429 blocksize is assumed.
 430
 431 When multiple type modifiers are chained together to modify
 432 a base or user-defined type, the tree ordering reflects the
 433 semantics of the
 434 \addtoindexx{reference type entry, lvalue|see{reference type entry}}
 435 applicable language
 436 \addtoindexx{reference type entry, rvalue|see{rvalue reference type entry}}
 437 rather
 438 \addtoindexx{parameter|see{macro formal parameter list}}
 439 than
 440 \addtoindexx{parameter|see{\textit{this} parameter}}
 441 the
 442 \addtoindexx{parameter|see{variable parameter attribute}}
 443 textual
 444 \addtoindexx{parameter|see{optional parameter attribute}}
 445 order
 446 \addtoindexx{parameter|see{unspecified parameters entry}}
 447 in
 448 \addtoindexx{parameter|see{template value parameter entry}}
 449 the
 450 \addtoindexx{parameter|see{template type parameter entry}}
 451 source
 452 \addtoindexx{parameter|see{formal parameter entry}}
 453 presentation.
 454
 455 \begin{table}[here]
 456 \caption{Type modifier tags}
 457 \label{tab:typemodifiertags}
 458 \centering
 459 \begin{tabular}{l|p{9cm}}
 460 \hline
 461 Name&Meaning\\ \hline
 462 \DWTAGatomictypeTARG{} & C \addtoindex{\_Atomic} qualified type \\
 463 \DWTAGconsttypeTARG{} &  C or C++ const qualified type
 464 \addtoindexx{const qualified type entry} \addtoindexx{C} \addtoindexx{C++} \\
 465 \DWTAGpackedtypeTARG& \addtoindex{Pascal} or Ada packed type\addtoindexx{packed type entry}
 466 \addtoindexx{packed qualified type entry} \addtoindexx{Ada} \addtoindexx{Pascal} \\
 467 \DWTAGpointertypeTARG{} & Pointer to an object of
 468 the type being modified \addtoindexx{pointer qualified type entry} \\
 469 \DWTAGreferencetypeTARG& C++ (lvalue) reference
 470 to an object of the type
 471 \addtoindexx{reference type entry}
 472 \mbox{being} modified
 473 \addtoindexx{reference qualified type entry} \\
 474 \DWTAGrestricttypeTARG& \addtoindex{C}
 475 restrict
 476 \addtoindexx{restricted type entry}
 477 qualified type
 478 \addtoindexx{restrict qualified type} \\
 479 \DWTAGrvaluereferencetypeTARG{} & C++
 480 \addtoindexx{rvalue reference type entry}
 481 rvalue
 482 \addtoindexx{restricted type entry}
 483 reference to an object of the type \mbox{being} modified
 484 \addtoindexx{rvalue reference qualified type entry} \\
 485 \DWTAGsharedtypeTARG&\addtoindex{UPC} shared qualified type
 486 \addtoindexx{shared qualified type entry} \\
 487 \DWTAGvolatiletypeTARG&C or C++ volatile qualified type
 488 \addtoindexx{volatile qualified type entry} \\
 489 \hline
 490 \end{tabular}
 491 \end{table}
 492
 493 %The following clearpage prevents splitting the example across pages.
 494 \textit{As examples of how type modifiers are ordered, consider the following
 495 \addtoindex{C} declarations:}
 496 \begin{lstlisting}[numbers=none]
 497    const unsigned char * volatile p;
 498 \end{lstlisting}
 499 \textit{which represents a volatile pointer to a constant
 500 character. This is encoded in DWARF as:}
 501
 502 \begin{dwflisting}
 503 \begin{alltt}
 504         \DWTAGvariable(p) -->
 505             \DWTAGvolatiletype -->
 506                 \DWTAGpointertype -->
 507                     \DWTAGconsttype -->
 508                         \DWTAGbasetype(unsigned char)
 509 \end{alltt}
 510 \end{dwflisting}
 511
 512 \needlines{5}
 513 \textit{On the other hand}
 514 \begin{lstlisting}[numbers=none]
 515    volatile unsigned char * const restrict p;
 516 \end{lstlisting}
 517 \textit{represents a restricted constant
 518 pointer to a volatile character. This is encoded as:}
 519
 520 \begin{dwflisting}
 521 \begin{alltt}
 522         \DWTAGvariable(p) -->
 523             \DWTAGrestricttype -->
 524                 \DWTAGconsttype -->
 525                     \DWTAGpointertype -->
 526                         \DWTAGvolatiletype -->
 527                             \DWTAGbasetype(unsigned char)
 528 \end{alltt}
 529 \end{dwflisting}
 530
 531 \section{Typedef Entries}
 532 \label{chap:typedefentries}
 533 A named type that is defined in terms of another type
 534 definition is represented by a debugging information entry with
 535 \addtoindexx{typedef entry}
 536 the tag \DWTAGtypedefTARG.
 537 The typedef entry has a \DWATname{} attribute
 538 \addtoindexx{name attribute}
 539 whose value is a null\dash terminated string containing
 540 the name of the typedef as it appears in the source program.
 541
 542 The typedef entry may also contain
 543 \addtoindexx{type attribute}
 544 a
 545 \DWATtype{} attribute whose
 546 value is a \livelink{chap:classreference}{reference}
 547 to the type named by the typedef. If
 548 the debugging information entry for a typedef represents
 549 a declaration of the type that is not also a definition,
 550 it does not contain a type attribute.
 551
 552 \textit{Depending on the language, a named type that is defined in
 553 terms of another type may be called a type alias, a subtype,
 554 a constrained type and other terms. A type name declared with
 555 no defining details may be termed an
 556 \addtoindexx{incomplete type}
 557 incomplete, forward or hidden type.
 558 While the DWARF \DWTAGtypedef{} entry was
 559 originally inspired by the like named construct in
 560 \addtoindex{C} and \addtoindex{C++},
 561 it is broadly suitable for similar constructs (by whatever
 562 source syntax) in other languages.}
 563
 564 \section{Array Type Entries}
 565 \label{chap:arraytypeentries}
 566 \label{chap:DWTAGgenericsubrange}
 567
 568 \textit{Many languages share the concept of an \doublequote{array,} which is
 569 \addtoindexx{array type entry}
 570 a table of components of identical type.}
 571
 572 An array type is represented by a debugging information entry
 573 with the tag \DWTAGarraytypeTARG.
 574 If a name has been given to
 575 \addtoindexx{array!declaration of type}
 576 the array type in the source program, then the corresponding
 577 array type entry has a \DWATname{} attribute
 578 \addtoindexx{name attribute}
 579 whose value is a
 580 null\dash terminated string containing the array type name as it
 581 appears in the source program.
 582
 583 The
 584 \hypertarget{chap:DWATorderingarrayrowcolumnordering}{}
 585 array type entry describing a multidimensional array may
 586 \addtoindexx{array!element ordering}
 587 have a \DWATordering{} attribute whose
 588 \livelink{chap:classconstant}{integer constant} value is
 589 interpreted to mean either row-major or column-major ordering
 590 of array elements. The set of values and their meanings
 591 for the ordering attribute are listed in
 592 Table \refersec{tab:arrayordering}.
 593 If no
 594 ordering attribute is present, the default ordering for the
 595 source language (which is indicated by the
 596 \DWATlanguage{}
 597 attribute
 598 \addtoindexx{language attribute}
 599 of the enclosing compilation unit entry) is assumed.
 600
 601 \begin{simplenametable}[1.8in]{Array ordering}{tab:arrayordering}
 602 \DWORDcolmajorTARG{} \\
 603 \DWORDrowmajorTARG{} \\
 604 \end{simplenametable}
 605
 606 The ordering attribute may optionally appear on one-dimensional
 607 arrays; it will be ignored.
 608
 609 An array type entry has
 610 \addtoindexx{type attribute}
 611 a \DWATtype{} attribute
 612 describing
 613 \addtoindexx{array!element type}
 614 the type of each element of the array.
 615
 616 If the amount of storage allocated to hold each element of an
 617 object of the given array type is different from the amount
 618 \addtoindexx{stride attribute|see{bit stride attribute or byte stride attribute}}
 619 of storage that is normally allocated to hold an individual
 620 \hypertarget{chap:DWATbitstridearrayelementstrideofarraytype}{}
 621 object of the
 622 \hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}{}
 623 indicated element type, then the array type
 624 \addtoindexx{bit stride attribute}
 625 entry has either a
 626 \DWATbytestride{}
 627 or
 628 \addtoindexx{byte stride attribute}
 629 a \DWATbitstride{}
 630 attribute,
 631 \addtoindexx{bit stride attribute}
 632 whose value
 633 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
 634 is the size of each
 635 element of the array.
 636
 637 The array type entry may have either a \DWATbytesize{} or a
 638 \DWATbitsize{} attribute
 639 (see Section \refersec{chap:byteandbitsizes}),
 640 whose value is the
 641 amount of storage needed to hold an instance of the array type.
 642
 643 \textit{If the size of the array can be determined statically at
 644 compile time, this value can usually be computed by multiplying
 645 the number of array elements by the size of each element.}
 646
 647
 648 Each array dimension is described by a debugging information
 649 entry with either the
 650 \addtoindexx{subrange type entry!as array dimension}
 651 tag \DWTAGsubrangetype{} or the
 652 \addtoindexx{enumeration type entry!as array dimension}
 653 tag
 654 \DWTAGenumerationtype. These entries are
 655 children of the
 656 array type entry and are ordered to reflect the appearance of
 657 the dimensions in the source program (i.e., leftmost dimension
 658 first, next to leftmost second, and so on).
 659
 660 \textit{In languages that have no concept of a
 661 \doublequote{multidimensional array} (for example,
 662 \addtoindex{C}), an array of arrays may
 663 be represented by a debugging information entry for a
 664 multidimensional array.}
 665
 666 Alternatively, for an array with dynamic rank the array dimensions
 667 are described by a debugging information entry with the tag
 668 \DWTAGgenericsubrangeTARG.
 669 This entry has the same attributes as a
 670 \DWTAGsubrangetype{} entry; however,
 671 there is just one \DWTAGgenericsubrangeNAME{} entry and it describes all of the
 672 dimensions of the array.
 673 If \DWTAGgenericsubrangeNAME{}
 674 is used, the number of dimensions must be specified using a
 675 \DWATrank{} attribute. See also Section
 676 \refersec{chap:DWATrank}.
 677
 678
 679 \needlines{5}
 680 Other attributes especially applicable to arrays are
 681 \DWATallocated,
 682 \DWATassociated{} and
 683 \DWATdatalocation,
 684 which are described in
 685 Section \refersec{chap:dynamictypeproperties}.
 686 For relevant examples, see also Appendix \refersec{app:fortranarrayexample}.
 687
 688 \section{Coarray Type Entries}
 689 \label{chap:coarraytypeentries}
 690 \addtoindexx{coarray}
 691 \textit{In Fortran, a \doublequote{coarray} is an array whose
 692 elements are located in different processes rather than in the
 693 memory of one process. The individual elements
 694 of a coarray can be scalars or arrays.
 695 Similar to arrays, coarrays have \doublequote{codimensions} that are
 696 indexed using a \doublequote{coindex} or multiple \doublequote{coindices}.
 697 \addtoindexx{codimension|see{coarray}}
 698 \addtoindexx{coindex|see{coarray}}
 699 }
 700
 701 A coarray type is represented by a debugging information entry
 702 with the tag \DWTAGcoarraytypeTARG.
 703 If a name has been given to the
 704 coarray type in the source, then the corresponding coarray type
 705 entry has a \DWATname{} attribute whose value is a null-terminated
 706 string containing the array type name as it appears in the source
 707 program.
 708
 709 A coarray entry has one or more \DWTAGsubrangetype{} child entries,
 710 one for each codimension. It also has a \DWATtype{} attribute
 711 describing the type of each element of the coarray.
 712
 713 \textit{In a coarray application, the run-time number of processes in the application
 714 is part of the coindex calculation.  It is represented in the Fortran source by
 715 a coindex which is declared with a \doublequote{*} as the upper bound.  To express this
 716 concept in DWARF, the \DWTAGsubrangetype{} child entry for that index has
 717 only a lower bound and no upper bound.}
 718
 719 \textit{How coarray elements are located and how coindices are
 720 converted to process specifications is processor-dependent.}
 721
 722 \section{Structure, Union, Class and Interface Type Entries}
 723 \label{chap:structureunionclassandinterfacetypeentries}
 724
 725 \textit{The languages
 726 \addtoindex{C},
 727 \addtoindex{C++}, and
 728 \addtoindex{Pascal}, among others, allow the
 729 programmer to define types that are collections of related
 730 \addtoindexx{structure type entry}
 731 components.
 732 In \addtoindex{C} and \addtoindex{C++}, these collections are called
 733 \doublequote{structures.}
 734 In \addtoindex{Pascal}, they are called \doublequote{records.}
 735 The components may be of different types. The components are
 736 called \doublequote{members} in \addtoindex{C} and
 737 \addtoindex{C++}, and \doublequote{fields} in \addtoindex{Pascal}.}
 738
 739 \textit{The components of these collections each exist in their
 740 own space in computer memory. The components of a C or C++
 741 \doublequote{union} all coexist in the same memory.}
 742
 743 \textit{\addtoindex{Pascal} and
 744 other languages have a \doublequote{discriminated union,}
 745 \addtoindexx{discriminated union|see {variant entry}}
 746 also called a \doublequote{variant record.} Here, selection of a
 747 number of alternative substructures (\doublequote{variants}) is based
 748 on the value of a component that is not part of any of those
 749 substructures (the \doublequote{discriminant}).}
 750
 751 \textit{\addtoindex{C++} and
 752 \addtoindex{Java} have the notion of \doublequote{class,} which is in some
 753 ways similar to a structure. A class may have \doublequote{member
 754 functions} which are subroutines that are within the scope
 755 of a class or structure.}
 756
 757 \textit{The \addtoindex{C++} notion of
 758 structure is more general than in \addtoindex{C}, being
 759 equivalent to a class with minor differences. Accordingly,
 760 in the following discussion statements about
 761 \addtoindex{C++} classes may
 762 be understood to apply to \addtoindex{C++} structures as well.}
 763
 764 \subsection{Structure, Union and Class Type Entries}
 765 \label{chap:structureunionandclasstypeentries}
 766
 767
 768 Structure, union, and class types are represented by debugging
 769 \addtoindexx{structure type entry}
 770 information entries
 771 \addtoindexx{union type entry}
 772 with
 773 \addtoindexx{class type entry}
 774 the tags
 775 \DWTAGstructuretypeTARG,
 776 \DWTAGuniontypeTARG,
 777 and \DWTAGclasstypeTARG,
 778 respectively. If a name has been given to the structure,
 779 union, or class in the source program, then the corresponding
 780 structure type, union type, or class type entry has a
 781 \DWATname{} attribute
 782 \addtoindexx{name attribute}
 783 whose value is a null\dash terminated string
 784 containing the type name as it appears in the source program.
 785
 786 The members of a structure, union, or class are represented
 787 by debugging information entries that are owned by the
 788 corresponding structure type, union type, or class type entry
 789 and appear in the same order as the corresponding declarations
 790 in the source program.
 791
 792 A structure type, union type or class type entry may have
 793 either a \DWATbytesize{} or a
 794 \DWATbitsize{} attribute
 795 \hypertarget{chap:DWATbitsizedatamemberbitsize}{}
 796 (see Section \refersec{chap:byteandbitsizes}),
 797 whose value is the amount of storage needed
 798 to hold an instance of the structure, union or class type,
 799 including any padding.
 800
 801 An incomplete structure, union or class type
 802 \addtoindexx{incomplete structure/union/class}
 803 is
 804 \addtoindexx{incomplete type}
 805 represented by a structure, union or class
 806 entry that does not have a byte size attribute and that has
 807 \addtoindexx{declaration attribute}
 808 a \DWATdeclaration{} attribute.
 809
 810 If the complete declaration of a type has been placed in
 811 \hypertarget{chap:DWATsignaturetypesignature}{}
 812 a separate \addtoindex{type unit}
 813 (see Section \refersec{chap:separatetypeunitentries}),
 814 an incomplete declaration
 815 \addtoindexx{incomplete type}
 816 of that type in the compilation unit may provide
 817 the unique 64\dash bit signature of the type using
 818 \addtoindexx{type signature}
 819 a \DWATsignature{}
 820 attribute.
 821
 822 If a structure, union or class entry represents the definition
 823 of a structure, union or class member corresponding to a prior
 824 incomplete structure, union or class, the entry may have a
 825 \DWATspecification{} attribute
 826 \addtoindexx{specification attribute}
 827 whose value is a \livelink{chap:classreference}{reference} to
 828 the debugging information entry representing that incomplete
 829 declaration.
 830
 831 Structure, union and class entries containing the
 832 \DWATspecification{} attribute
 833 \addtoindexx{specification attribute}
 834 do not need to duplicate
 835 information provided by the declaration entry referenced by the
 836 specification attribute.  In particular, such entries do not
 837 need to contain an attribute for the name of the structure,
 838 union or class they represent if such information is already
 839 provided in the declaration.
 840
 841 \textit{For \addtoindex{C} and \addtoindex{C++},
 842 data
 843 \addtoindexx{data member|see {member entry (data)}}
 844 member declarations occurring within
 845 the declaration of a structure, union or class type are
 846 considered to be \doublequote{definitions} of those members, with
 847 the exception of \doublequote{static} data members, whose definitions
 848 appear outside of the declaration of the enclosing structure,
 849 union or class type. Function member declarations appearing
 850 within a structure, union or class type declaration are
 851 definitions only if the body of the function also appears
 852 within the type declaration.}
 853
 854 If the definition for a given member of the structure, union
 855 or class does not appear within the body of the declaration,
 856 that member also has a debugging information entry describing
 857 its definition. That latter entry has a
 858 \DWATspecification{} attribute
 859 \addtoindexx{specification attribute}
 860 referencing the debugging information entry
 861 owned by the body of the structure, union or class entry and
 862 representing a non\dash defining declaration of the data, function
 863 or type member. The referenced entry will not have information
 864 about the location of that member (low and high pc attributes
 865 for function members, location descriptions for data members)
 866 and will have a \DWATdeclaration{} attribute.
 867
 868 \needlines{5}
 869 \textit{Consider a nested class whose
 870 definition occurs outside of the containing class definition, as in:}
 871
 872 \begin{lstlisting}[numbers=none]
 873 struct A {
 874     struct B;
 875 };
 876 struct A::B { ... };
 877 \end{lstlisting}
 878
 879 \textit{The two different structs can be described in
 880 different compilation units to
 881 facilitate DWARF space compression
 882 (see Appendix \refersec{app:usingcompilationunits}).}
 883
 884 \subsection{Interface Type Entries}
 885 \label{chap:interfacetypeentries}
 886
 887 \textit{The \addtoindex{Java} language defines \doublequote{interface} types.
 888 An interface
 889 \addtoindexx{interface type entry}
 890 in \addtoindex{Java} is similar to a \addtoindex{C++} or
 891 \addtoindex{Java} class with only abstract
 892 methods and constant data members.}
 893
 894 Interface types
 895 \addtoindexx{interface type entry}
 896 are represented by debugging information
 897 entries with the
 898 tag \DWTAGinterfacetypeTARG.
 899
 900 An interface type entry has
 901 a \DWATname{} attribute,
 902 \addtoindexx{name attribute}
 903 whose
 904 value is a null\dash terminated string containing the type name
 905 as it appears in the source program.
 906
 907 The members of an interface are represented by debugging
 908 information entries that are owned by the interface type
 909 entry and that appear in the same order as the corresponding
 910 declarations in the source program.
 911
 912 \subsection{Derived or Extended Structs, Classes and Interfaces}
 913 \label{chap:derivedorextendedstructsclasesandinterfaces}
 914
 915 \textit{In \addtoindex{C++}, a class (or struct)
 916 may
 917 \addtoindexx{derived type (C++)|see{inheritance entry}}
 918 be \doublequote{derived from} or be a
 919 \doublequote{subclass of} another class.
 920 In \addtoindex{Java}, an interface may \doublequote{extend}
 921 \addtoindexx{extended type (Java)|see{inheritance entry}}
 922 one
 923 \addtoindexx{implementing type (Java)|see{inheritance entry}}
 924 or more other interfaces, and a class may \doublequote{extend} another
 925 class and/or \doublequote{implement} one or more interfaces. All of these
 926 relationships may be described using the following. Note that
 927 in \addtoindex{Java},
 928 the distinction between extends and implements is
 929 implied by the entities at the two ends of the relationship.}
 930
 931 A class type or interface type entry that describes a
 932 derived, extended or implementing class or interface owns
 933 \addtoindexx{implementing type (Java)|see{inheritance entry}}
 934 debugging information entries describing each of the classes
 935 or interfaces it is derived from, extending or implementing,
 936 respectively, ordered as they were in the source program. Each
 937 such entry has
 938 \addtoindexx{inheritance entry}
 939 the
 940 tag \DWTAGinheritanceTARG.
 941
 942 An inheritance entry
 943 \addtoindexx{type attribute}
 944 has
 945 \addtoindexx{inheritance entry}
 946 a
 947 \DWATtype{} attribute whose value is
 948 a reference to the debugging information entry describing the
 949 class or interface from which the parent class or structure
 950 of the inheritance entry is derived, extended or implementing.
 951
 952 An inheritance entry
 953 \addtoindexx{inheritance entry}
 954 for a class that derives from or extends
 955 \hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}{}
 956 another class or struct also has
 957 \addtoindexx{data member location attribute}
 958 a
 959 \DWATdatamemberlocation{}
 960 attribute, whose value describes the location of the beginning
 961 of the inherited type relative to the beginning address of the
 962 instance of the derived class. If that value is a constant, it is the offset
 963 in bytes from the beginning of the class to the beginning of
 964 the instance of the inherited type. Otherwise, the value must be a location
 965 description. In this latter case, the beginning address of
 966 the instance of the derived class is pushed on the expression stack before
 967 the \addtoindex{location description}
 968 is evaluated and the result of the
 969 evaluation is the location of the instance of the inherited type.
 970
 971 \textit{The interpretation of the value of this attribute for
 972 inherited types is the same as the interpretation for data
 973 members
 974 (see Section \referfol{chap:datamemberentries}).  }
 975
 976 An
 977 \addtoindexx{inheritance entry}
 978 inheritance entry
 979 \hypertarget{chap:DWATaccessibilitycppinheritedmembers}{}
 980 may
 981 \addtoindexx{accessibility attribute}
 982 have a
 983 \DWATaccessibility{}
 984 attribute.
 985 If no accessibility attribute
 986 is present, private access is assumed for an entry of a class
 987 and public access is assumed for an entry of an interface,
 988 struct or union.
 989
 990 If
 991 \hypertarget{chap:DWATvirtualityvirtualityofbaseclass}{}
 992 the class referenced by the
 993 \addtoindexx{inheritance entry}
 994 inheritance entry serves
 995 as a \addtoindex{C++} virtual base class, the inheritance entry has a
 996 \DWATvirtuality{} attribute.
 997
 998 \textit{For a \addtoindex{C++} virtual base, the
 999 \addtoindex{data member location attribute}
1000 will usually consist of a non-trivial
1001 \addtoindex{location description}.}
1002
1003 \subsection{Access Declarations}
1004 \label{chap:accessdeclarations}
1005
1006 \textit{In \addtoindex{C++}, a derived class may contain access declarations that
1007 \addtoindexx{access declaration entry}
1008 change the accessibility of individual class members from the
1009 overall accessibility specified by the inheritance declaration.
1010 A single access declaration may refer to a set of overloaded
1011 names.}
1012
1013 If a derived class or structure contains access declarations,
1014 each such declaration may be represented by a debugging
1015 information entry with the tag
1016 \DWTAGaccessdeclarationTARG.
1017 Each
1018 such entry is a child of the class or structure type entry.
1019
1020 An access declaration entry has
1021 a \DWATname{} attribute,
1022 \addtoindexx{name attribute}
1023 whose
1024 value is a null\dash terminated string representing the name used
1025 in the declaration in the source program, including any class
1026 or structure qualifiers.
1027
1028 An access declaration entry
1029 \hypertarget{chap:DWATaccessibilitycppbaseclasses}{}
1030 also
1031 has a
1032 \DWATaccessibility{}
1033 attribute describing the declared accessibility of the named
1034 entities.
1035
1036
1037 \needlines{6}
1038 \subsection{Friends}
1039 \label{chap:friends}
1040
1041 Each \doublequote{friend}
1042 \addtoindexx{friend entry}
1043 declared by a structure, union or class
1044 \hypertarget{chap:DWATfriendfriendrelationship}{}
1045 type may be represented by a debugging information entry
1046 that is a child of the structure, union or class type entry;
1047 the friend entry has the
1048 tag \DWTAGfriendTARG.
1049
1050 A friend entry has
1051 \addtoindexx{friend attribute}
1052 a \DWATfriend{} attribute, whose value is
1053 a reference to the debugging information entry describing
1054 the declaration of the friend.
1055
1056
1057 \subsection{Data Member Entries}
1058 \label{chap:datamemberentries}
1059
1060 A data member (as opposed to a member function) is
1061 represented by a debugging information entry with the
1062 tag \DWTAGmemberTARG.
1063 The
1064 \addtoindexx{member entry (data)}
1065 member entry for a named member has
1066 a \DWATname{} attribute
1067 \addtoindexx{name attribute}
1068 whose value is a null\dash terminated
1069 string containing the member name as it appears in the source
1070 program. If the member entry describes an
1071 \addtoindex{anonymous union},
1072 the name attribute is omitted or the value of the attribute
1073 consists of a single zero byte.
1074
1075 The data member entry has
1076 \addtoindexx{type attribute}
1077 a
1078 \DWATtype{} attribute to denote
1079 \addtoindexx{member entry (data)}
1080 the type of that member.
1081
1082 A data member entry may
1083 \addtoindexx{accessibility attribute}
1084 have a
1085 \DWATaccessibility{}
1086 attribute. If no accessibility attribute is present, private
1087 access is assumed for an entry of a class and public access
1088 is assumed for an entry of a structure, union, or interface.
1089
1090 A data member
1091 \hypertarget{chap:DWATmutablemutablepropertyofmemberdata}{}
1092 entry
1093 \addtoindexx{member entry (data)}
1094 may
1095 \addtoindexx{mutable attribute}
1096 have a \DWATmutable{} attribute,
1097 which is a \livelink{chap:classflag}{flag}.
1098 This attribute indicates whether the data
1099 member was declared with the mutable storage class specifier.
1100
1101 The beginning of a data member
1102 \addtoindexx{beginning of a data member}
1103 is described relative to
1104 \addtoindexx{beginning of an object}
1105 the beginning of the object in which it is immediately
1106 contained. In general, the beginning is characterized by
1107 both an address and a bit offset within the byte at that
1108 address. When the storage for an entity includes all of
1109 the bits in the beginning byte, the beginning bit offset is
1110 defined to be zero.
1111
1112 Bit offsets in DWARF use the bit numbering and direction
1113 conventions that are appropriate to the current language on
1114 the target system.
1115
1116 The member entry
1117 \addtoindexx{member entry (data)}
1118 corresponding to a data member that is
1119 \hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}{}
1120 defined
1121 \hypertarget{chap:DWATdatamemberlocationdatamemberlocation}{}
1122 in a structure, union or class may have either
1123 \addtoindexx{data member location attribute}
1124 a
1125 \DWATdatamemberlocation{} attribute or a
1126 \DWATdatabitoffset{}
1127 attribute. If the beginning of the data member is the same as
1128 the beginning of the containing entity then neither attribute
1129 is required.
1130
1131 \needlines{4}
1132 For a \DWATdatamemberlocation{} attribute
1133 \addtoindexx{data member location attribute}
1134 there are two cases:
1135 \begin{enumerate}[1. ]
1136 \item If the value is an \livelink{chap:classconstant}{integer constant},
1137 it is the offset
1138 in bytes from the beginning of the containing entity. If
1139 the beginning of the containing entity has a non-zero bit
1140 offset then the beginning of the member entry has that same
1141 bit offset as well.
1142
1143 \item Otherwise, the value must be a \addtoindex{location description}.
1144 In
1145 this case, the beginning of the containing entity must be byte
1146 aligned. The beginning address is pushed on the DWARF stack
1147 before the \addtoindex{location} description is evaluated; the result of
1148 the evaluation is the base address of the member entry.
1149
1150 \textit{The push on the DWARF expression stack of the base address of
1151 the containing construct is equivalent to execution of the
1152 \DWOPpushobjectaddress{} operation
1153 (see Section \refersec{chap:stackoperations});
1154 \DWOPpushobjectaddress{} therefore
1155 is not needed at the
1156 beginning of a \addtoindex{location description} for a data member.
1157 The
1158 result of the evaluation is a location---either an address or
1159 the name of a register, not an offset to the member.}
1160
1161 \textit{A \DWATdatamemberlocation{}
1162 attribute
1163 \addtoindexx{data member location attribute}
1164 that has the form of a
1165 \addtoindex{location description} is not valid for a data member contained
1166 in an entity that is not byte aligned because DWARF operations
1167 do not allow for manipulating or computing bit offsets.}
1168
1169 \end{enumerate}
1170
1171 For a \DWATdatabitoffset{} attribute,
1172 the value is an \livelink{chap:classconstant}{integer constant}
1173 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1174 that specifies the number of bits
1175 from the beginning of the containing entity to the beginning
1176 of the data member. This value must be greater than or equal
1177 to zero, but is not limited to less than the number of bits
1178 per byte.
1179
1180 If the size of a data member is not the same as the size
1181 of the type given for the data member, the data member has
1182 \addtoindexx{bit size attribute}
1183 either a \DWATbytesize{}
1184 or a \DWATbitsize{} attribute whose
1185 \livelink{chap:classconstant}{integer constant} value
1186 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1187 is the amount
1188 of storage needed to hold the value of the data member.
1189
1190 \textit{Bit fields in \addtoindex{C} and \addtoindex{C++}
1191 typically
1192 \addtoindexx{bit fields}
1193 require the use
1194 \addtoindexx{data bit offset}
1195 of
1196 \addtoindexx{data bit size}
1197 the
1198 \DWATdatabitoffset{} and
1199 \DWATbitsize{} attributes.}
1200
1201 \needlines{6}
1202 \textit{This Standard uses the following bit numbering and direction
1203 conventions in examples. These conventions are for illustrative
1204 purposes and other conventions may apply on particular
1205 architectures.}
1206 \begin{itemize}
1207 \item \textit{For big\dash endian architectures, bit offsets are
1208 counted from high-order to low\dash order bits within a byte (or
1209 larger storage unit); in this case, the bit offset identifies
1210 the high\dash order bit of the object.}
1211
1212 \item \textit{For little\dash endian architectures, bit offsets are
1213 counted from low\dash order to high\dash order bits within a byte (or
1214 larger storage unit); in this case, the bit offset identifies
1215 the low\dash order bit of the object.}
1216 \end{itemize}
1217
1218
1219 \textit{In either case, the bit so identified is defined as the
1220 \addtoindexx{beginning of an object}
1221 beginning of the object.}
1222
1223 \textit{For example, take one possible representation of the following
1224 \addtoindex{C} structure definition
1225 in both big\dash and little\dash endian byte orders:}
1226
1227 \begin{lstlisting}
1228 struct S {
1229     int j:5;
1230     int k:6;
1231     int m:5;
1232     int n:8;
1233 };
1234 \end{lstlisting}
1235
1236 \textit{Figures \referfol{fig:bigendiandatabitoffsets} and
1237 \refersec{fig:littleendiandatabitoffsets}
1238 show the structure layout
1239 and data bit offsets for example big\dash\   and little\dash endian
1240 architectures, respectively. Both diagrams show a structure
1241 that begins at address A and whose size is four bytes. Also,
1242 high order bits are to the left and low order bits are to
1243 the right.}
1244
1245 \begin{figure}[h]
1246 \begin{dwflisting}
1247 \begin{verbatim}
1248
1249     j:0
1250     k:5
1251     m:11
1252     n:16
1253
1254     Addresses increase ->
1255     |       A       |     A + 1     |    A + 2      |    A + 3      |
1256
1257     Data bit offsets increase ->
1258     +---------------+---------------+---------------+---------------+
1259     |0     4|5         10|11      15|16           23|24           31|
1260     |   j   |     k      | m        |        n      |       <pad>   |
1261     |       |            |          |               |               |
1262     +---------------------------------------------------------------+
1263
1264 \end{verbatim}
1265 \end{dwflisting}
1266 \caption{Big-endian data bit offsets}
1267 \label{fig:bigendiandatabitoffsets}
1268 \end{figure}
1269
1270 \begin{figure}[h]
1271 \begin{dwflisting}
1272 \begin{verbatim}
1273
1274     j:0
1275     k:5
1276     m:11
1277     n:16
1278                                                <- Addresses increase
1279     |     A + 3     |     A + 2     |    A + 1      |       A       |
1280
1281                                         <-  Data bit offsets increase
1282     +---------------+---------------+---------------+---------------+
1283     |31           24|23           16|15     11|10       5|4        0|
1284     |     <pad>     |        n      |    m    |    k     |     j    |
1285     |               |               |         |          |          |
1286     +---------------------------------------------------------------+
1287
1288 \end{verbatim}
1289 \end{dwflisting}
1290 \caption{Little-endian data bit offsets}
1291 \label{fig:littleendiandatabitoffsets}
1292 \end{figure}
1293
1294 \textit{Note that data member bit offsets in this example are the
1295 same for both big\dash\ and little\dash endian architectures even
1296 though the fields are allocated in different directions
1297 (high\dash order to low-order versus low\dash order to high\dash order);
1298 the bit naming conventions for memory and/or registers of
1299 the target architecture may or may not make this seem natural.}
1300
1301 \textit{For a more extensive example showing nested and packed records
1302 and arrays, see
1303 Appendix \refersec{app:pascalexample}.}
1304
1305 \textit{Attribute \DWATdatabitoffset{}
1306 is new in
1307 \addtoindex{DWARF Version 4}, unchanged in \addtoindex{DWARF Version 5},
1308 and is also used for base types
1309 (see Section
1310 \refersec{chap:basetypeentries}).
1311 It replaces the
1312 \livetarg{chap:DWATbitoffsetdatamemberbitlocation}{}
1313 attributes \DWATbitoffset{} and
1314 \DWATbytesize{} when used to
1315 identify the beginning of bit field data members as defined
1316 in DWARF V3 and earlier. The \DWATbytesize,
1317 \DWATbitsize{} and
1318 \DWATbitoffset{}
1319 attribute combination is deprecated for data members in DWARF
1320 Version 4 and later. See Section 5.6.6 in the DWARF Version 4
1321 specification for a discussion of compatibility considerations.}
1322
1323 \subsection{Member Function Entries}
1324 \label{chap:memberfunctionentries}
1325
1326 A member function is represented by a
1327 \addtoindexx{member function entry}
1328 debugging information entry
1329 with the
1330 \addtoindexx{subprogram entry!as member function}
1331 tag \DWTAGsubprogram.
1332 The member function entry
1333 may contain the same attributes and follows the same rules
1334 as non\dash member global subroutine entries
1335 (see Section \refersec{chap:subroutineandentrypointentries}).
1336
1337 \textit{In particular, if the member function entry is an
1338 instantiation of a member function template, it follows the
1339 same rules as function template instantiations (see Section
1340 \refersec{chap:functiontemplateinstantiations}).
1341 }
1342
1343 A
1344 \addtoindexx{accessibility attribute}
1345 member function entry may have a
1346 \DWATaccessibility{}
1347 attribute. If no accessibility attribute is present, private
1348 access is assumed for an entry of a class and public access
1349 is assumed for an entry of a structure, union or interface.
1350
1351 If
1352 \hypertarget{chap:DWATvirtualityvirtualityoffunction}{}
1353 the member function entry describes a virtual function,
1354 then that entry has a
1355 \DWATvirtuality{} attribute.
1356
1357 If
1358 \hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}{}
1359 the member function entry describes an explicit member
1360 function, then that entry has
1361 \addtoindexx{explicit attribute}
1362 a
1363 \DWATexplicit{} attribute.
1364
1365 An
1366 \hypertarget{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}{}
1367 entry for a virtual function also has a
1368 \DWATvtableelemlocation{}
1369 \addtoindexi{attribute}{vtable element location attribute} whose value contains
1370 a \addtoindex{location description}
1371 yielding the address of the slot
1372 for the function within the virtual function table for the
1373 enclosing class. The address of an object of the enclosing
1374 type is pushed onto the expression stack before the location
1375 description is evaluated.
1376
1377 If
1378 \hypertarget{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}{}
1379 the member function entry describes a non\dash static member
1380 \addtoindexx{this pointer attribute|see{object pointer attribute}}
1381 function, then that entry
1382 \addtoindexx{self pointer attribute|see{object pointer attribute}}
1383 has
1384 \addtoindexx{object pointer attribute}
1385 a \DWATobjectpointer{}
1386 attribute
1387 whose value is a \livelink{chap:classreference}{reference}
1388 to the formal parameter entry
1389 that corresponds to the object for which the function is
1390 called. The name attribute of that formal parameter is defined
1391 by the current language (for example,
1392 \texttt{this} for \addtoindex{C++} or \texttt{self}
1393 for \addtoindex{Objective C}
1394 and some other languages). That parameter
1395 also has a \DWATartificial{} attribute whose value is true.
1396
1397 Conversely, if the member function entry describes a static
1398 member function, the entry does not have
1399 \addtoindexx{object pointer attribute}
1400 a
1401 \DWATobjectpointer{}
1402 attribute.
1403
1404 \textit{In \addtoindex{C++}, non-static member functions can have const-volatile
1405 qualifiers, which affect the type of the first formal parameter (the
1406 \doublequote{\texttt{this}}-pointer).}
1407
1408 If the member function entry describes a non\dash static member
1409 function that has a const\dash volatile qualification, then
1410 the entry describes a non\dash static member function whose
1411 object formal parameter has a type that has an equivalent
1412 const\dash volatile qualification.
1413
1414 \textit{In \addtoindex{C++11}, non-static member functions can also have one of the
1415 ref-qualifiers, \& and \&\&. They do not change the type of the
1416 \doublequote{\texttt{this}}-pointer, but they affect the types of object values the
1417 function can be invoked on.}
1418
1419 The member function entry may have an \DWATreferenceNAME{} attribute
1420 \livetarg{chap:DWATreferenceofnonstaticmember}{}
1421 to indicate a non-static member function that can only be called on
1422 l-value objects, or the \DWATrvaluereferenceNAME{} attribute
1423 \livetarg{chap:DWATrvaluereferenceofnonstaticmember}{}
1424 to indicate that it can only be called on pr-values and x-values.
1425
1426 If a subroutine entry represents the defining declaration
1427 of a member function and that definition appears outside of
1428 the body of the enclosing class declaration, the subroutine
1429 entry has a
1430 \DWATspecification{} attribute,
1431 \addtoindexx{specification attribute}
1432 whose value is
1433 a reference to the debugging information entry representing
1434 the declaration of this function member. The referenced entry
1435 will be a child of some class (or structure) type entry.
1436
1437 Subroutine entries containing the
1438 \DWATspecification{} attribute
1439 \addtoindexx{specification attribute}
1440 do not need to duplicate information provided
1441 by the declaration entry referenced by the specification
1442 attribute. In particular, such entries do not need to contain
1443 attributes for the name or return type of the function member
1444 whose definition they represent.
1445
1446 \needlines{5}
1447 \subsection{Class Template Instantiations}
1448 \label{chap:classtemplateinstantiations}
1449
1450 \textit{In \addtoindex{C++} a class template is a generic definition of a class
1451 type that may be instantiated when an instance of the class
1452 is declared or defined. The generic description of the class may include
1453 parameterized types, parameterized compile-time constant
1454 values, and/or parameterized run-time constant addresses.
1455 DWARF does not represent the generic template
1456 definition, but does represent each instantiation.}
1457
1458 A class template instantiation is represented by a
1459 debugging information entry with the tag \DWTAGclasstype,
1460 \DWTAGstructuretype{} or
1461 \DWTAGuniontype. With the following
1462 exceptions, such an entry will contain the same attributes
1463 and have the same types of child entries as would an entry
1464 for a class type defined explicitly using the instantiation
1465 types and values. The exceptions are:
1466
1467 \begin{enumerate}[1. ]
1468 \item Template parameters are described and referenced as
1469 specified in Section \refersec{chap:templateparameters}.
1470
1471 \needlines{4}
1472 \item If the compiler has generated a special compilation unit to
1473 hold the
1474 \addtoindexx{template instantiation!and special compilation unit}
1475 template instantiation and that special compilation
1476 unit has a different name from the compilation unit containing
1477 the template definition, the name attribute for the debugging
1478 information entry representing the special compilation unit
1479 should be empty or omitted.
1480
1481 \needlines{4}
1482 \item If the class type entry representing the template
1483 instantiation or any of its child entries contains declaration
1484 coordinate attributes, those attributes should refer to
1485 the source for the template definition, not to any source
1486 generated artificially by the compiler.
1487 \end{enumerate}
1488
1489
1490 \subsection{Variant Entries}
1491 \label{chap:variantentries}
1492
1493 A variant part of a structure is represented by a debugging
1494 information entry\addtoindexx{variant part entry} with the
1495 tag \DWTAGvariantpartTARG{} and is
1496 owned by the corresponding structure type entry.
1497
1498 If the variant part has a discriminant, the discriminant is
1499 \hypertarget{chap:DWATdiscrdiscriminantofvariantpart}{}
1500 represented by a
1501 \addtoindexx{discriminant (entry)}
1502 separate debugging information entry which
1503 is a child of the variant part entry. This entry has the form
1504 of a
1505 \addtoindexx{member entry (data)!as discriminant}
1506 structure data member entry. The variant part entry will
1507 \addtoindexx{discriminant attribute}
1508 have a
1509 \DWATdiscr{} attribute
1510 whose value is a \livelink{chap:classreference}{reference} to
1511 the member entry for the discriminant.
1512
1513 If the variant part does not have a discriminant (tag field),
1514 the variant part entry has
1515 \addtoindexx{type attribute}
1516 a
1517 \DWATtype{} attribute to represent
1518 the tag type.
1519
1520 Each variant of a particular variant part is represented by
1521 \hypertarget{chap:DWATdiscrvaluediscriminantvalue}{}
1522 a debugging information entry\addtoindexx{variant entry} with the
1523 tag \DWTAGvariantTARG{}
1524 and is a child of the variant part entry. The value that
1525 selects a given variant may be represented in one of three
1526 ways. The variant entry may have a
1527 \DWATdiscrvalue{} attribute
1528 whose value represents a single case label. The value of this
1529 attribute is encoded as an LEB128 number. The number is signed
1530 if the tag type for the variant part containing this variant
1531 is a signed type. The number is unsigned if the tag type is
1532 an unsigned type.
1533
1534 \needlines{5}
1535 Alternatively,
1536 \hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}{}
1537 the variant entry may contain
1538 \addtoindexx{discriminant list attribute}
1539 a
1540 \DWATdiscrlist{}
1541 attribute, whose value represents a list of discriminant
1542 values. This list is represented by any of the
1543 \livelink{chap:classblock}{block} forms and
1544 may contain a mixture of case labels and label ranges. Each
1545 item on the list is prefixed with a discriminant value
1546 descriptor that determines whether the list item represents
1547 a single label or a label range. A single case label is
1548 represented as an LEB128 number as defined above for
1549 \addtoindexx{discriminant value attribute}
1550 the
1551 \DWATdiscrvalue{}
1552 attribute. A label range is represented by
1553 two LEB128 numbers, the low value of the range followed by the
1554 high value. Both values follow the rules for signedness just
1555 described. The discriminant value descriptor is an integer
1556 constant that may have one of the values given in
1557 Table \refersec{tab:discriminantdescriptorvalues}.
1558
1559 \begin{simplenametable}[1.4in]{Discriminant descriptor values}{tab:discriminantdescriptorvalues}
1560 \DWDSClabelTARG{} \\
1561 \DWDSCrangeTARG{} \\
1562 \end{simplenametable}
1563
1564 If a variant entry has neither a \DWATdiscrvalue{}
1565 attribute nor a \DWATdiscrlist{} attribute, or if it has
1566 a \DWATdiscrlist{} attribute with 0 size, the variant is a
1567 default variant.
1568
1569 The components selected by a particular variant are represented
1570 by debugging information entries owned by the corresponding
1571 variant entry and appear in the same order as the corresponding
1572 declarations in the source program.
1573
1574 \needlines{6}
1575 \section{Condition Entries}
1576 \label{chap:conditionentries}
1577
1578 \textit{COBOL has the notion of
1579 \addtoindexx{level-88 condition, COBOL}
1580 a \doublequote{level\dash 88 condition} that
1581 associates a data item, called the conditional variable, with
1582 a set of one or more constant values and/or value ranges.
1583 % Note: the {} after \textquoteright (twice) is necessary to assure a following space separator
1584 Semantically, the condition is \textquoteleft true\textquoteright{}
1585 if the conditional
1586 variable's value matches any of the described constants,
1587 and the condition is \textquoteleft false\textquoteright{} otherwise.}
1588
1589 The \DWTAGconditionTARG{}
1590 debugging information entry\addtoindexx{condition entry}
1591 describes a
1592 logical condition that tests whether a given data item\textquoteright s
1593 value matches one of a set of constant values. If a name
1594 has been given to the condition, the condition entry has a
1595 \DWATname{} attribute
1596 \addtoindexx{name attribute}
1597 whose value is a null\dash terminated string
1598 giving the condition name as it appears in the source program.
1599
1600 The condition entry's parent entry describes the conditional
1601 variable; normally this will be a \DWTAGvariable,
1602 \DWTAGmember{} or
1603 \DWTAGformalparameter{} entry.
1604 If
1605 \addtoindexx{formal parameter entry}
1606 the parent
1607 entry has an array type, the condition can test any individual
1608 element, but not the array as a whole. The condition entry
1609 implicitly specifies a \doublequote{comparison type} that is the
1610 type of an array element if the parent has an array type;
1611 otherwise it is the type of the parent entry.
1612
1613 \needlines{4}
1614 The condition entry owns \DWTAGconstant{} and/or
1615 \DWTAGsubrangetype{} entries that describe the constant
1616 values associated with the condition. If any child entry
1617 \addtoindexx{type attribute}
1618 has
1619 a \DWATtype{} attribute,
1620 that attribute should describe a type
1621 compatible with the comparison type (according to the source
1622 language); otherwise the child\textquoteright s type is the same as the
1623 comparison type.
1624
1625 \textit{For conditional variables with alphanumeric types, COBOL
1626 permits a source program to provide ranges of alphanumeric
1627 constants in the condition. Normally a subrange type entry
1628 does not describe ranges of strings; however, this can be
1629 represented using bounds attributes that are references to
1630 constant entries describing strings. A subrange type entry may
1631 refer to constant entries that are siblings of the subrange
1632 type entry.}
1633
1634
1635 \section{Enumeration Type Entries}
1636 \label{chap:enumerationtypeentries}
1637
1638 \textit{An \doublequote{enumeration type} is a scalar that can assume one of
1639 a fixed number of symbolic values.}
1640
1641 An enumeration type is represented by a debugging information
1642 entry with the tag
1643 \DWTAGenumerationtypeTARG.
1644
1645 If a name has been given to the enumeration type in the source
1646 program, then the corresponding enumeration type entry has
1647 a \DWATname{} attribute
1648 \addtoindexx{name attribute}
1649 whose value is a null\dash terminated
1650 string containing the enumeration type name as it appears
1651 in the source program. This entry also has a
1652 \DWATbytesize{}
1653 attribute whose \livelink{chap:classconstant}{integer constant}
1654 value is the number of bytes
1655 required to hold an instance of the enumeration.
1656
1657 The \addtoindex{enumeration type entry}
1658 may have
1659 \addtoindexx{type attribute}
1660 a \DWATtype{} attribute
1661 which refers to the underlying data type used to implement
1662 the enumeration.
1663
1664 If an enumeration type has type safe
1665 \addtoindexx{type safe enumeration types}
1666 semantics such that
1667
1668 \begin{enumerate}[1. ]
1669 \item Enumerators are contained in the scope of the enumeration type, and/or
1670
1671 \item Enumerators are not implicitly converted to another type
1672 \end{enumerate}
1673
1674 then the \addtoindex{enumeration type entry} may
1675 \addtoindexx{enum class|see{type-safe enumeration}}
1676 have a \DWATenumclass{}
1677 attribute, which is a \livelink{chap:classflag}{flag}.
1678 In a language that offers only
1679 one kind of enumeration declaration, this attribute is not
1680 required.
1681
1682 \textit{In \addtoindex{C} or \addtoindex{C++},
1683 the underlying type will be the appropriate
1684 integral type determined by the compiler from the properties of
1685 \hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}{}
1686 the enumeration literal values.
1687 A \addtoindex{C++} type declaration written
1688 using enum class declares a strongly typed enumeration and
1689 is represented using \DWTAGenumerationtype{}
1690 in combination with \DWATenumclass.}
1691
1692 Each enumeration literal is represented by a debugging
1693 \addtoindexx{enumeration literal|see{enumeration entry}}
1694 information entry with the
1695 tag \DWTAGenumeratorTARG.
1696 Each
1697 such entry is a child of the
1698 \addtoindex{enumeration type entry}, and the
1699 enumerator entries appear in the same order as the declarations
1700 of the enumeration literals in the source program.
1701
1702 Each \addtoindex{enumerator entry} has a
1703 \DWATname{} attribute, whose
1704 \addtoindexx{name attribute}
1705 value is a null\dash terminated string containing the name of the
1706 \hypertarget{chap:DWATconstvalueenumerationliteralvalue}{}
1707 enumeration literal as it appears in the source program.
1708 Each enumerator entry also has a
1709 \DWATconstvalue{} attribute,
1710 whose value is the actual numeric value of the enumerator as
1711 represented on the target system.
1712
1713
1714 If the enumeration type occurs as the description of a
1715 \addtoindexx{enumeration type endry!as array dimension}
1716 dimension of an array type, and the stride for that dimension
1717 \hypertarget{chap:DWATbytestrideenumerationstridedimensionofarraytype}{}
1718 is different than what would otherwise be determined, then
1719 \hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}{}
1720 the enumeration type entry has either a
1721 \DWATbytestride{}
1722 or \DWATbitstride{} attribute
1723 \addtoindexx{bit stride attribute}
1724 which specifies the separation
1725 between successive elements along the dimension as described
1726 in
1727 Section \refersec{chap:staticanddynamicvaluesofattributes}.
1728 The value of the
1729 \DWATbitstride{} attribute
1730 \addtoindexx{bit stride attribute}
1731 is interpreted as bits and the value of
1732 \addtoindexx{byte stride attribute}
1733 the
1734 \DWATbytestride{}
1735 attribute is interpreted as bytes.
1736
1737
1738 \section{Subroutine Type Entries}
1739 \label{chap:subroutinetypeentries}
1740
1741 \textit{It is possible in \addtoindex{C}
1742 to declare pointers to subroutines
1743 that return a value of a specific type. In both
1744 \addtoindex{C} and \addtoindex{C++},
1745 it is possible to declare pointers to subroutines that not
1746 only return a value of a specific type, but accept only
1747 arguments of specific types. The type of such pointers would
1748 be described with a \doublequote{pointer to} modifier applied to a
1749 user\dash defined type.}
1750
1751 A subroutine type is represented by a debugging information
1752 entry with the
1753 \addtoindexx{subroutine type entry}
1754 tag \DWTAGsubroutinetypeTARG.
1755 If a name has
1756 been given to the subroutine type in the source program,
1757 then the corresponding subroutine type entry has
1758 a \DWATname{} attribute
1759 \addtoindexx{name attribute}
1760 whose value is a null\dash terminated string containing
1761 the subroutine type name as it appears in the source program.
1762
1763 If the subroutine type describes a function that returns
1764 a value, then the subroutine type entry has
1765 \addtoindexx{type attribute}
1766 a \DWATtype{}
1767 attribute to denote the type returned by the subroutine. If
1768 the types of the arguments are necessary to describe the
1769 subroutine type, then the corresponding subroutine type
1770 entry owns debugging information entries that describe the
1771 arguments. These debugging information entries appear in the
1772 order that the corresponding argument types appear in the
1773 source program.
1774
1775 \textit{In \addtoindex{C} there
1776 is a difference between the types of functions
1777 declared using function prototype style declarations and
1778 those declared using non\dash prototype declarations.}
1779
1780 A
1781 \hypertarget{chap:DWATprototypedsubroutineprototype}{}
1782 subroutine entry declared with a function prototype style
1783 declaration may have
1784 \addtoindexx{prototyped attribute}
1785 a
1786 \DWATprototyped{} attribute, which is
1787 a \livelink{chap:classflag}{flag}.
1788
1789 Each debugging information entry owned by a subroutine
1790 type entry corresponds to either a formal parameter or the sequence of
1791 unspecified parameters of the subprogram type:
1792
1793 \begin{enumerate}[1. ]
1794 \item A formal parameter of a parameter list (that has a
1795 specific type) is represented by a debugging information entry
1796 with the tag \DWTAGformalparameter.
1797 Each formal parameter
1798 entry has
1799 \addtoindexx{type attribute}
1800 a \DWATtype{} attribute that refers to the type of
1801 the formal parameter.
1802
1803 \item The unspecified parameters of a variable parameter list
1804 \addtoindexx{unspecified parameters entry}
1805 are
1806 \addtoindexx{\texttt{...} parameters|see{unspecified parameters entry}}
1807 represented by a debugging information entry with the
1808 tag \DWTAGunspecifiedparameters.
1809 \end{enumerate}
1810
1811 \textit{\addtoindex{C++} const-volatile qualifiers are encoded as
1812 part of the type of the
1813 \doublequote{\texttt{this}}-pointer.
1814 \addtoindex{C++11} reference and rvalue-reference qualifiers are encoded using
1815 the \DWATreference{} and \DWATrvaluereference{} attributes, respectively.
1816 See also Section \refersec{chap:memberfunctionentries}.}
1817
1818 A subroutine type entry may have the \DWATreference{} or
1819 \DWATrvaluereference{} attribute to indicate that it describes the
1820 type of a member function with reference or rvalue-reference
1821 semantics, respectively.
1822
1823
1824 \section{String Type Entries}
1825 \label{chap:stringtypeentries}
1826
1827 \textit{A \doublequote{string} is a sequence of characters that have specific
1828 \addtoindexx{string type entry}
1829 semantics and operations that distinguish them from arrays of
1830 characters.
1831 \addtoindex{Fortran} is one of the languages that has a string
1832 type. Note that \doublequote{string} in this context refers to a target
1833 machine concept, not the class string as used in this document
1834 (except for the name attribute).}
1835
1836 A string type is represented by a debugging information entry
1837 with the tag \DWTAGstringtypeTARG.
1838 If a name has been given to
1839 the string type in the source program, then the corresponding
1840 string type entry has a
1841 \DWATname{} attribute
1842 \addtoindexx{name attribute}
1843 whose value is
1844 a null\dash terminated string containing the string type name as
1845 it appears in the source program.
1846
1847 \needlines{4}
1848 The string type entry may have a
1849 \DWATbytesize{} attribute or
1850 \DWATbitsize{}
1851 attribute, whose value
1852 (see Section \refersec{chap:byteandbitsizes})
1853 is the amount of
1854 storage needed to hold a value of the string type.
1855
1856 The
1857 \hypertarget{chap:DWATstringlengthstringlengthofstringtype}{}
1858 string type entry may also have a
1859 \DWATstringlength{} attribute
1860 whose
1861 \addtoindexx{string length attribute}
1862 value is a
1863 \addtoindex{location description} yielding the location
1864 where the length of the string is stored in the program.
1865 If the \DWATstringlength{} attribute is not present, the size
1866 of the string is assumed to be the amount of storage that is
1867 allocated for the string (as specified by the \DWATbytesize{}
1868 or \DWATbitsize{} attribute).
1869
1870 The string type entry may also have a
1871 \DWATstringlengthbytesizeTARG{}
1872 attribute or
1873 \DWATstringlengthbitsizeTARG{} attribute,
1874 \addtoindexx{string length attribute!size of length data}
1875 whose value (see Section \refersec{chap:byteandbitsizes})
1876 is the size of the data to be retrieved from the location
1877 referenced by the string length attribute. If no (byte or bit)
1878 size attribute is present, the size of the data to be retrieved
1879 is the same as the
1880 \addtoindex{size of an address} on the target machine.
1881
1882 \addtoindexx{DWARF Version 5}   % Avoid italics
1883 \textit{Prior to DWARF Version 5, the meaning of a
1884 \DWATbytesize{} attribute depends on the presence of the
1885 \DWATstringlength{} attribute:
1886 \begin{itemize}
1887 \item If \DWATstringlength{} is present, \DWATbytesize{}
1888         specifies the size of the length data to be retrieved
1889         from the location specified by the \DWATstringlength{} attribute.
1890 \item If \DWATstringlength{} is not present, \DWATbytesize{}
1891         specifies the amount of storage allocated for objects
1892         of the string type.
1893 \end{itemize}
1894 In DWARF Version 5, \DWATbytesize{} always specifies the amount of storage
1895 allocated for objects of the string type.}
1896
1897 \needlines{6}
1898 \section{Set Type Entries}
1899 \label{chap:settypeentries}
1900
1901 \textit{\addtoindex{Pascal} provides the concept of a \doublequote{set,} which represents
1902 a group of values of ordinal type.}
1903
1904 A set is represented by a debugging information entry with
1905 the tag \DWTAGsettypeTARG.
1906 \addtoindexx{set type entry}
1907 If a name has been given to the
1908 set type, then the set type entry has
1909 a \DWATname{} attribute
1910 \addtoindexx{name attribute}
1911 whose value is a null\dash terminated string containing the
1912 set type name as it appears in the source program.
1913
1914 The set type entry has
1915 \addtoindexx{type attribute}
1916 a \DWATtype{} attribute to denote the
1917 type of an element of the set.
1918
1919 \needlines{4}
1920 If the amount of storage allocated to hold each element of an
1921 object of the given set type is different from the amount of
1922 storage that is normally allocated to hold an individual object
1923 of the indicated element type, then the set type entry has
1924 either a \DWATbytesize{} attribute, or
1925 \DWATbitsize{} attribute
1926 whose value (see Section \refersec{chap:byteandbitsizes}) is
1927 the amount of storage needed to hold a value of the set type.
1928
1929
1930 \section{Subrange Type Entries}
1931 \label{chap:subrangetypeentries}
1932
1933 \textit{Several languages support the concept of a \doublequote{subrange}
1934 type object. These objects can represent a subset of the
1935 values that an object of the basis type for the subrange can
1936 represent.
1937 Subrange type entries may also be used to represent
1938 the bounds of array dimensions.}
1939
1940 A subrange type is represented by a debugging information
1941 entry with the
1942 \addtoindexx{subrange type entry}
1943 tag \DWTAGsubrangetypeTARG.
1944 If a name has been
1945 given to the subrange type, then the subrange type entry
1946 has a \DWATname{} attribute
1947 \addtoindexx{name attribute}
1948 whose value is a null\dash terminated
1949 string containing the subrange type name as it appears in
1950 the source program.
1951
1952 The tag \DWTAGgenericsubrange{} is
1953 used to describe arrays with a dynamic rank. See Section
1954 \refersec{chap:DWTAGgenericsubrange}.
1955
1956 The subrange entry may have
1957 \addtoindexx{type attribute}
1958 a \DWATtype{} attribute to describe
1959 the type of object, called the basis type, of whose values
1960 this subrange is a subset.
1961
1962 If the amount of storage allocated to hold each element of an
1963 object of the given subrange type is different from the amount
1964 of storage that is normally allocated to hold an individual
1965 object of the indicated element type, then the subrange
1966 type entry has a
1967 \DWATbytesize{} attribute or
1968 \DWATbitsize{}
1969 attribute, whose value
1970 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1971 is the amount of
1972 storage needed to hold a value of the subrange type.
1973
1974 The
1975 \hypertarget{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}{}
1976 subrange entry may have
1977 \addtoindexx{threads scaled attribute}
1978 a
1979 \DWATthreadsscaled{} attribute,
1980 which is a \livelink{chap:classflag}{flag}.
1981 If present, this attribute indicates whether
1982 this subrange represents a \addtoindex{UPC} array bound which is scaled
1983 by the runtime THREADS value (the number of UPC threads in
1984 this execution of the program).
1985
1986 \textit{This allows the representation of a \addtoindex{UPC} shared array such as}
1987
1988 \begin{lstlisting}[numbers=none]
1989 int shared foo[34*THREADS][10][20];
1990 \end{lstlisting}
1991
1992 The
1993 \hypertarget{chap:DWATlowerboundlowerboundofsubrange}{}
1994 subrange
1995 \hypertarget{chap:DWATupperboundupperboundofsubrange}{}
1996 entry may have the attributes
1997 \DWATlowerbound{}
1998 \addtoindexx{lower bound attribute}
1999 and \DWATupperbound{}
2000 \addtoindexx{upper bound attribute} to specify, respectively, the lower
2001 and upper bound values of the subrange. The
2002 \DWATupperbound{}
2003 attribute
2004 \hypertarget{chap:DWATcountelementsofsubrangetype}{}
2005 may
2006 % FIXME: The following matches DWARF4: odd as there is no default count.
2007 \addtoindexx{count attribute!default}
2008 be
2009 \addtoindexx{count attribute}
2010 replaced by a
2011 \DWATcount{} attribute,
2012 whose
2013 value describes the number of elements in the subrange rather
2014 than the value of the last element. The value of each of
2015 these attributes is determined as described in
2016 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2017
2018 If the lower bound value is missing, the value is assumed to
2019 be a language\dash dependent default constant.
2020 \addtoindexx{lower bound attribute!default}
2021 The default lower bound is 0 for
2022 \addtoindex{C}, \addtoindex{C++},
2023 \addtoindex{D},
2024 \addtoindex{Go},
2025 \addtoindex{Haskell},
2026 \addtoindex{Java},
2027 \addtoindex{Objective C},
2028 \addtoindex{Objective C++},
2029 \addtoindex{OpenCL},
2030 \addtoindex{Python}, and
2031 \addtoindex{UPC}.
2032 The default lower bound is 1 for
2033 \addtoindex{Ada},
2034 \addtoindex{COBOL},
2035 \addtoindex{Fortran},
2036 \addtoindex{Modula-2},
2037 \addtoindex{Modula-3},
2038 \addtoindex{Pascal} and
2039 \addtoindex{PL/I}.
2040
2041 \textit{No other default lower bound values are currently defined.}
2042
2043 If the upper bound and count are missing, then the upper bound value is
2044 \textit{unknown}.\addtoindexx{upper bound attribute!default unknown}
2045
2046 If the subrange entry has no type attribute describing the
2047 basis type, the basis type is determined as follows:
2048 \begin{enumerate}[1. ]
2049 \item
2050 If there is a lower bound attribute that references an object,
2051 the basis type is assumed to be the same as the type of that object.
2052 \item
2053 Otherwise, if there is an upper bound or count attribute that references
2054 an object, the basis type is assumed to be the same as the type of that object.
2055 \item
2056 Otherwise, the type is
2057 assumed to be the same type, in the source language of the
2058 compilation unit containing the subrange entry, as a signed
2059 integer with the same size as an address on the target machine.
2060 \end{enumerate}
2061
2062 If the subrange type occurs as the description of a dimension
2063 of an array type, and the stride for that dimension is
2064 \hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}{}
2065 different than what would otherwise be determined, then
2066 \hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}{}
2067 the subrange type entry has either
2068 \addtoindexx{byte stride attribute}
2069 a
2070 \DWATbytestride{} or
2071 \DWATbitstride{} attribute
2072 \addtoindexx{bit stride attribute}
2073 which specifies the separation
2074 between successive elements along the dimension as described
2075 in
2076 Section \refersec{chap:byteandbitsizes}.
2077
2078 \textit{Note that the stride can be negative.}
2079
2080 \section{Pointer to Member Type Entries}
2081 \label{chap:pointertomembertypeentries}
2082
2083 \textit{In \addtoindex{C++}, a
2084 pointer to a data or function member of a class or
2085 structure is a unique type.}
2086
2087 A debugging information entry representing the type of an
2088 object that is a pointer to a structure or class member has
2089 the tag \DWTAGptrtomembertypeTARG.
2090
2091 If the \addtoindex{pointer to member type} has a name, the
2092 \addtoindexx{pointer to member type entry}
2093 pointer to member entry has a
2094 \DWATname{} attribute,
2095 \addtoindexx{name attribute}
2096 whose value is a
2097 null\dash terminated string containing the type name as it appears
2098 in the source program.
2099
2100 The \addtoindex{pointer to member} entry
2101 has
2102 \addtoindexx{type attribute}
2103 a \DWATtype{} attribute to
2104 describe the type of the class or structure member to which
2105 objects of this type may point.
2106
2107 The \addtoindexx{pointer to member} entry also
2108 \hypertarget{chap:DWATcontainingtypecontainingtypeofpointertomembertype}{}
2109 has a
2110 \DWATcontainingtype{}
2111 attribute, whose value is a \livelink{chap:classreference}{reference} to a debugging
2112 information entry for the class or structure to whose members
2113 objects of this type may point.
2114
2115 The \addtoindex{pointer to member entry}
2116 \hypertarget{chap:DWATuselocationmemberlocationforpointertomembertype}{}
2117 has a
2118 \DWATuselocation{} attribute
2119 \addtoindexx{use location attribute}
2120 whose value is a
2121 \addtoindex{location description} that computes the
2122 address of the member of the class to which the pointer to
2123 member entry points.
2124
2125 \textit{The method used to find the address of a given member of a
2126 class or structure is common to any instance of that class
2127 or structure and to any instance of the pointer or member
2128 type. The method is thus associated with the type entry,
2129 rather than with each instance of the type.}
2130
2131 The \DWATuselocation{} description is used in conjunction
2132 with the location descriptions for a particular object of the
2133 given \addtoindex{pointer to member type} and for a particular structure or
2134 class instance. The \DWATuselocation{}
2135 attribute expects two values to be
2136 \addtoindexi{pushed}{address!implicit push for member operator}
2137 onto the DWARF expression stack before
2138 the \DWATuselocation{} description is evaluated.
2139 The first value
2140 \addtoindexi{pushed}{address!implicit push for member operator}
2141 is the value of the \addtoindex{pointer to member} object
2142 itself. The second value
2143 \addtoindexi{pushed}{address!implicit push for member operator}
2144 is the base address of the
2145 entire structure or union instance containing the member
2146 whose address is being calculated.
2147
2148 \needlines{6}
2149 \textit{For an expression such as}
2150
2151 \begin{lstlisting}[numbers=none]
2152     object.*mbr_ptr
2153 \end{lstlisting}
2154 \textit{where \texttt{mbr\_ptr} has some \addtoindex{pointer to member type}, a debugger should:}
2155 \begin{enumerate}[1. ]
2156 \item \textit{Push the value of \texttt{mbr\_ptr} onto the DWARF expression stack.}
2157 \item \textit{Push the base address of \texttt{object} onto the DWARF expression stack.}
2158 \item \textit{Evaluate the \DWATuselocation{} description
2159 given in the type of \texttt{mbr\_ptr}.}
2160 \end{enumerate}
2161
2162
2163 \section{File Type Entries}
2164 \label{chap:filetypeentries}
2165
2166 \textit{Some languages, such as \addtoindex{Pascal},
2167 provide a data type to represent
2168 files.}
2169
2170 A file type is represented by a debugging information entry
2171 with
2172 \addtoindexx{file type entry}
2173 the tag
2174 \DWTAGfiletypeTARG.
2175 If the file type has a name,
2176 the file type entry has a \DWATname{} attribute,
2177 \addtoindexx{name attribute}
2178 whose value
2179 is a null\dash terminated string containing the type name as it
2180 appears in the source program.
2181
2182 The file type entry has
2183 \addtoindexx{type attribute}
2184 a \DWATtype{} attribute describing
2185 the type of the objects contained in the file.
2186
2187 The file type entry also
2188 \addtoindexx{byte size}
2189 has
2190 \addtoindexx{bit size}
2191 a
2192 \DWATbytesize{} or
2193 \DWATbitsize{} attribute, whose value
2194 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
2195 is the amount of storage need to hold a value of the file type.
2196
2197 \section{Dynamic Type Entries and Properties}
2198
2199 \subsection{Dynamic Type Entries}
2200 \textit{Some languages such as
2201 \addtoindex{Fortran 90}, provide types whose values
2202 may be dynamically allocated or associated with a variable
2203 under explicit program control. However, unlike the related
2204 pointer type in \addtoindex{C} or
2205 \addtoindex{C++}, the indirection involved in accessing
2206 the value of the variable is generally implicit, that is, not
2207 indicated as part of program source.}
2208
2209 A dynamic type entry is used to declare a dynamic type that is
2210 \doublequote{just like} another non-dynamic type without needing to
2211 replicate the full description of that other type.
2212
2213 A dynamic type is represented by a debugging information entry
2214 with the tag \DWTAGdynamictypeTARG. If a name has been given to the
2215 dynamic type, then the dynamic type has a \DWATname{} attribute
2216 whose value is a null-terminated string containing the dynamic
2217 type name as it appears in the source.
2218
2219 A dynamic type entry has a \DWATtype{} attribute whose value is a
2220 reference to the type of the entities that are dynamically allocated.
2221
2222 A dynamic type entry also has a \DWATdatalocation, and may also
2223 have \DWATallocated{} and/or \DWATassociated{} attributes as
2224 described following (Section 5.15.1). The type referenced by the
2225 \DWATtype{} attribute must not have any of these attributes.
2226
2227 \subsection{Dynamic Type Properties}
2228 \label{chap:dynamictypeproperties}
2229 \textit{
2230 The \DWATdatalocation, \DWATallocated{} and \DWATassociated{}
2231 attributes described in this section can be used for any type, not
2232 just dynamic types.}
2233
2234 \needlines{6}
2235 \subsubsection{Data Location}
2236 \label{chap:datalocation}
2237
2238 \textit{Some languages may represent objects using descriptors to hold
2239 information, including a location and/or run\dash time parameters,
2240 about the data that represents the value for that object.}
2241
2242 \hypertarget{chap:DWATdatalocationindirectiontoactualdata}{}
2243 The \DWATdatalocation{}
2244 attribute may be used with any
2245 \addtoindexx{data location attribute}
2246 type that provides one or more levels of
2247 \addtoindexx{hidden indirection|see{data location attribute}}
2248 hidden indirection
2249 and/or run\dash time parameters in its representation. Its value
2250 is a \addtoindex{location description}.
2251 The result of evaluating this
2252 description yields the location of the data for an object.
2253 When this attribute is omitted, the address of the data is
2254 the same as the address of the object.
2255
2256 \needlines{5}
2257 \textit{This location description will typically begin with
2258 \DWOPpushobjectaddress{}
2259 which loads the address of the
2260 object which can then serve as a descriptor in subsequent
2261 calculation. For an example using
2262 \DWATdatalocation{}
2263 for a \addtoindex{Fortran 90 array}, see
2264 Appendix \refersec{app:fortranarrayexample}.}
2265
2266 \subsubsection{Allocation and Association Status}
2267 \label{chap:allocationandassociationstatus}
2268
2269 \textit{Some languages, such as \addtoindex{Fortran 90},
2270 provide types whose values
2271 may be dynamically allocated or associated with a variable
2272 under explicit program control.}
2273
2274 \hypertarget{chap:DWATallocatedallocationstatusoftypes}{}
2275 The
2276 \DWATallocated{}
2277 attribute
2278 \addtoindexx{allocated attribute}
2279 may optionally be used with any
2280 type for which objects of the type can be explicitly allocated
2281 and deallocated. The presence of the attribute indicates that
2282 objects of the type are allocatable and deallocatable. The
2283 integer value of the attribute (see below) specifies whether
2284 an object of the type is
2285 currently allocated or not.
2286
2287 \hypertarget{chap:DWATassociatedassociationstatusoftypes}{}
2288 The
2289 \DWATassociated{} attribute
2290 may
2291 \addtoindexx{associated attribute}
2292 optionally be used with
2293 any type for which objects of the type can be dynamically
2294 associated with other objects. The presence of the attribute
2295 indicates that objects of the type can be associated. The
2296 integer value of the attribute (see below) indicates whether
2297 an object of the type is currently associated or not.
2298
2299 \textit{While these attributes are defined specifically with
2300 \addtoindex{Fortran 90} ALLOCATABLE and POINTER types
2301 in mind, usage is not limited
2302 to just that language.}
2303
2304 The value of these attributes is determined as described in
2305 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2306
2307 A non\dash zero value is interpreted as allocated or associated,
2308 and zero is interpreted as not allocated or not associated.
2309
2310 \textit{For \addtoindex{Fortran 90},
2311 if the \DWATassociated{}
2312 attribute is present,
2313 the type has the POINTER property where either the parent
2314 variable is never associated with a dynamic object or the
2315 implementation does not track whether the associated object
2316 is static or dynamic. If the \DWATallocated{} attribute is
2317 present and the \DWATassociated{} attribute is not, the type
2318 has the ALLOCATABLE property. If both attributes are present,
2319 then the type should be assumed to have the POINTER property
2320 (and not ALLOCATABLE); the \DWATallocated{} attribute may then
2321 be used to indicate that the association status of the object
2322 resulted from execution of an ALLOCATE statement rather than
2323 pointer assignment.}
2324
2325 \textit{For examples using
2326 \DWATallocated{} for \addtoindex{Ada} and
2327 \addtoindex{Fortran 90}
2328 arrays,
2329 see Appendix \refersec{app:aggregateexamples}.}
2330
2331 \subsubsection{Array Rank}
2332 \label{chap:DWATrank}
2333 \addtoindexx{array!assumed-rank}
2334 \addtoindexx{assumed-rank array|see{array, assumed-rank}}
2335 \textit{The Fortran language supports \doublequote{assumed-rank arrays}. The
2336   rank (the number of dimensions) of an assumed-rank array is unknown
2337   at compile time. The Fortran runtime stores the rank in the array
2338   descriptor metadata.}
2339
2340 The presence of the
2341 \hypertarget{chap:DWATrankofdynamicarray}{\DWATrankINDX}
2342 attribute indicates that an array's rank
2343 (dimensionality) is dynamic, and therefore unknown at compile
2344 time. The value of the \DWATrankINDX{} attribute is either an integer constant
2345 or a location expression whose evaluation yields the dynamic rank.
2346
2347 The bounds of an array with dynamic rank are described using the
2348 \DWTAGgenericsubrangeTARG{} tag, which
2349 is the dynamic rank array equivalent of
2350 \DWTAGsubrangetype. The
2351 difference is that a \DWTAGgenericsubrangeINDX{} contains generic
2352 lower/upper bound and stride expressions that need to be evaluated for
2353 each dimension: Before any expression contained in a
2354 \DWTAGgenericsubrangeINDX{} can be evaluated, the dimension for which the
2355 expression should be evaluated needs to be pushed onto the stack. The
2356 expression will use it to find the offset of the respective field in
2357 the array descriptor metadata.
2358
2359 \textit{The Fortran compiler is free to choose any layout for the
2360   array descriptor. In particular, the upper and lower bounds and
2361   stride values do not need to be bundled into a structure or record,
2362   but could be laid end to end in the containing descriptor, pointed
2363   to by the descriptor, or even allocated independently of the
2364   descriptor.}
2365
2366 Dimensions are enumerated $0$ to $\mathit{rank}-1$ in a left-to-right
2367 fashion.
2368
2369 \textit{For an example in Fortran 2008, see
2370   Section~\refersec{app:assumedrankexample}.}
2371
2372
2373 \section{Template Alias Entries}
2374 \label{chap:templatealiasentries}
2375
2376 \textit{
2377 In \addtoindex{C++}, a template alias is a form of typedef that has template
2378 parameters.  DWARF does not represent the template alias definition
2379 but does represent instantiations of the alias.
2380 }
2381
2382 A type named using a template alias is represented
2383 by a debugging information entry
2384 \addtoindexx{template alias entry}
2385 with the tag
2386 \DWTAGtemplatealiasTARG.
2387 The template alias entry has a
2388 \DWATname{} attribute
2389 \addtoindexx{name attribute}
2390 whose value is a null\dash terminated string
2391 containing the name of the template alias as it appears in
2392 the source program.
2393 The template alias entry has child entries describing the template
2394 actual parameters (see Section \refersec{chap:templateparameters}).
2395