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.
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 \livelink{chap:DWATstartscope}{DW\_AT\_start\_scope}
12 attribute as described for objects in
13 Section \refersec{chap:dataobjectentries}.
15 \section{Base Type Entries}
16 \label{chap:basetypeentries}
18 \textit{A base type is a data type that is not defined in terms of
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.}
24 A base type is represented by a debugging information entry
26 \livetarg{chap:DWTAGbasetype}{DW\_TAG\_base\_type}.
28 A \addtoindex{base type entry}
29 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
31 \addtoindexx{name attribute}
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.
38 \addtoindexx{encoding attribute}
39 a \livelink{chap:DWATencoding}{DW\_AT\_encoding} 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 \livelink{chap:DWATencoding}{DW\_AT\_encoding} attribute
46 Table \refersec{tab:encodingattributevalues}
50 may have a \livelink{chap:DWATendianity}{DW\_AT\_endianity} attribute
51 \addtoindexx{endianity attribute}
53 Section \refersec{chap:dataobjectentries}.
54 If omitted, the encoding assumes the representation that
55 is the default for the target architecture.
58 \hypertarget{chap:DWATbytesizedataobjectordatatypesize}
59 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute
60 \hypertarget{chap:DWATbitsizebasetypebitsize}
61 or a \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} 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
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 \livelink{chap:DWATEsigned}{DW\_ATE\_signed}
74 and a byte size attribute whose value is 4.}
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}
82 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and a
83 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} attribute,
85 \addtoindexx{data bit offset attribute}
87 \livelink{chap:classconstant}{integer constant} values
88 (see Section \refersec{chap:staticanddynamicvaluesofattributes}).
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
97 target system to locate the beginning of the storage and
98 value. If this attribute is omitted a default data bit offset
102 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
104 \addtoindexx{bit offset attribute}
106 \addtoindexx{data bit offset attribute}
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}).
112 \hypertarget{chap:DWATbitoffsetbasetypebitlocation}
113 replaces the attribute
114 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
116 \addtoindexx{bit offset attribute (V3)}
117 types as defined in DWARF V3 and earlier.
118 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
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.}
124 \caption{Encoding attribute values}
125 \label{tab:encodingattributevalues}
127 \begin{tabular}{l|p{8cm}}
129 Name&Meaning\\ \hline
130 \livetarg{chap:DWATEaddress}{DW\_ATE\_address} & linear machine address (for segmented\break
132 Section \refersec{chap:segmentedaddresses}) \\
133 \livetarg{chap:DWATEboolean}{DW\_ATE\_boolean}& true or false \\
135 \livetarg{chap:DWATEcomplexfloat}{DW\_ATE\_complex\_float}& complex binary
136 floating\dash point number \\
137 \livetarg{chap:DWATEfloat}{DW\_ATE\_float} & binary floating\dash point number \\
138 \livetarg{chap:DWATEimaginaryfloat}{DW\_ATE\_imaginary\_float}& imaginary binary
139 floating\dash point number \\
140 \livetarg{chap:DWATEsigned}{DW\_ATE\_signed}& signed binary integer \\
141 \livetarg{chap:DWATEsignedchar}{DW\_ATE\_signed\_char}& signed character \\
142 \livetarg{chap:DWATEunsigned}{DW\_ATE\_unsigned} & unsigned binary integer \\
143 \livetarg{chap:DWATEunsignedchar}{DW\_ATE\_unsigned\_char} & unsigned character \\
144 \livetarg{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} & packed decimal \\
145 \livetarg{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string}& numeric string \\
146 \livetarg{chap:DWATEedited}{DW\_ATE\_edited} & edited string \\
147 \livetarg{chap:DWATEsignedfixed}{DW\_ATE\_signed\_fixed} & signed fixed\dash point scaled integer \\
148 \livetarg{chap:DWATEunsignedfixed}{DW\_ATE\_unsigned\_fixed}& unsigned fixed\dash point scaled integer \\
149 \livetarg{chap:DWATEdecimalfloat}{DW\_ATE\_decimal\_float} & decimal floating\dash point number \\
150 \livetarg{chap:DWATEUTF}{DW\_ATE\_UTF} & \addtoindex{Unicode} character \\
155 \textit{The \livelink{chap:DWATEdecimalfloat}{DW\_ATE\_decimal\_float} 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.}
159 \textit{The \livelink{chap:DWATEUTF}{DW\_ATE\_UTF} 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 \livelink{chap:DWATEUTF}{DW\_ATE\_UTF} and a byte size attribute whose value is 2.}
168 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal}
170 \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string}
172 represent packed and unpacked decimal string numeric data
173 types, respectively, either of which may be
175 \addtoindexx{decimal scale attribute}
177 \addtoindexx{decimal sign attribute}
179 \addtoindexx{digit count attribute}
181 \hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}
183 \hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}
184 base types are used in combination with
185 \livelink{chap:DWATdecimalsign}{DW\_AT\_decimal\_sign},
186 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and
187 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale}
191 A \livelink{chap:DWATdecimalsign}{DW\_AT\_decimal\_sign} 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.
202 \caption{Decimal sign attribute values}
203 \label{tab:decimalsignattributevalues}
205 \begin{tabular}{l|p{9cm}}
209 \livetarg{chap:DWDSunsigned}{DW\_DS\_unsigned} & Unsigned \\
210 \livetarg{chap:DWDSleadingoverpunch}{DW\_DS\_leading\_overpunch} & Sign
211 is encoded in the most significant digit in a target\dash dependent manner \\
212 \livetarg{chap:DWDStrailingoverpunch}{DW\_DS\_trailing\_overpunch} & Sign
213 is encoded in the least significant digit in a target\dash dependent manner \\
214 \livetarg{chap:DWDSleadingseparate}{DW\_DS\_leading\_separate}
215 & Decimal type: Sign is a \doublequote{+} or \doublequote{-} character
216 to the left of the most significant digit. \\
217 \livetarg{chap:DWDStrailingseparate}{DW\_DS\_trailing\_separate}
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. \\
228 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count}
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
235 \hypertarget{chap:DWATdecimalscaledecimalscalefactor}
236 The \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale}
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.
250 The \livelink{chap:DWATEedited}{DW\_ATE\_edited}
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 \livelink{chap:DWATpicturestring}{DW\_AT\_picture\_string} attribute whose value is a
256 null\dash terminated string containing the target\dash dependent picture
257 string associated with the type.
259 If the edited base type entry describes an edited numeric
260 data type, the edited type entry has a \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and a
261 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attribute.
262 \addtoindexx{decimal scale attribute}
263 These attributes have the same
264 interpretation as described for the
265 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} and
266 \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} 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.
272 \textit{The presence or absence of the \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and
273 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} 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.}
280 The \livelink{chap:DWATEsignedfixed}{DW\_ATE\_signed\_fixed} and \livelink{chap:DWATEunsignedfixed}{DW\_ATE\_unsigned\_fixed} entries
281 describe signed and unsigned fixed\dash point binary data types,
284 The fixed binary type entries have
285 \addtoindexx{digit count attribute}
287 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count}
288 attribute with the same interpretation as described for the
289 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} and \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base types.
292 For a data type with a decimal scale factor, the fixed binary
294 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attribute
295 \addtoindexx{decimal scale attribute}
297 interpretation as described for the
298 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal}
299 and \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base types.
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 \livelink{chap:DWATbinaryscale}{DW\_AT\_binary\_scale} attribute.
307 \livelink{chap:DWATbinaryscale}{DW\_AT\_binary\_scale} 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.
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 \livelink{chap:DWATsmall}{DW\_AT\_small} attribute which
324 \addtoindexx{small attribute}
326 \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} entry. The scale factor value
327 is interpreted in accordance with the value defined by the
328 \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} entry. The value represented is the product
329 of the integer value in memory and the associated constant
332 \textit{The \livelink{chap:DWATsmall}{DW\_AT\_small} attribute
333 is defined with the \addtoindex{Ada} \texttt{small}
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.
344 An unspecified (implicit, unknown, ambiguous or nonexistent)
345 type is represented by a debugging information entry with
346 the tag \livetarg{chap:DWTAGunspecifiedtype}{DW\_TAG\_unspecified\_type}.
347 If a name has been given
348 to the type, then the corresponding unspecified type entry
349 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
350 \addtoindexx{name attribute}
352 a null\dash terminated
353 string containing the name as it appears in the source program.
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
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).
373 \section{Type Modifier Entries}
374 \label{chap:typemodifierentries}
375 \addtoindexx{type modifier entry}
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{constant type entry}}
382 \addtoindexx{type modifier|see{reference type entry}}
383 \addtoindexx{type modifier|see{restricted type entry}}
384 \addtoindexx{type modifier|see{packed type entry}}
385 \addtoindexx{type modifier|see{pointer type entry}}
386 \addtoindexx{type modifier|see{shared type entry}}
387 \addtoindexx{type modifier|see{volatile type entry}}
389 If a name has been given to the modified type in the source
390 program, then the corresponding modified type entry has
391 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
392 \addtoindexx{name attribute}
393 whose value is a null\dash terminated
394 string containing the modified type name as it appears in
397 Each of the type modifier entries has
398 \addtoindexx{type attribute}
400 \livelink{chap:DWATtype}{DW\_AT\_type} attribute,
401 whose value is a \livelink{chap:classreference}{reference}
402 to a debugging information entry
403 describing a base type, a user-defined type or another type
406 A modified type entry describing a
407 \addtoindexx{pointer type entry}
408 pointer or \addtoindex{reference type}
409 (using \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type},
410 \livelink{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type} or
411 \livelink{chap:DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type})
412 % Another instance of no-good-place-to-put-index entry.
414 \addtoindexx{address class!attribute}
416 \hypertarget{chap:DWATadressclasspointerorreferencetypes}
418 \livelink{chap:DWATaddressclass}{DW\_AT\_address\_class}
419 attribute to describe how objects having the given pointer
420 or reference type ought to be dereferenced.
422 A modified type entry describing a \addtoindex{UPC} shared qualified type
423 (using \livelink{chap:DWTAGsharedtype}{DW\_TAG\_shared\_type}) may have a
424 \livelink{chap:DWATcount}{DW\_AT\_count} attribute
425 \addtoindexx{count attribute}
426 whose value is a constant expressing the (explicit or implied) blocksize specified for the
427 type in the source. If no count attribute is present, then the \doublequote{infinite}
428 blocksize is assumed.
430 When multiple type modifiers are chained together to modify
431 a base or user-defined type, the tree ordering reflects the
433 \addtoindexx{reference type entry, lvalue|see{reference type entry}}
435 \addtoindexx{reference type entry, rvalue|see{rvalue reference type entry}}
437 \addtoindexx{parameter|see{macro formal parameter list}}
439 \addtoindexx{parameter|see{\textit{this} parameter}}
441 \addtoindexx{parameter|see{variable parameter attribute}}
443 \addtoindexx{parameter|see{optional parameter attribute}}
445 \addtoindexx{parameter|see{unspecified parameters entry}}
447 \addtoindexx{parameter|see{template value parameter entry}}
449 \addtoindexx{parameter|see{template type parameter entry}}
451 \addtoindexx{parameter|see{formal parameter entry}}
455 \caption{Type modifier tags}
456 \label{tab:typemodifiertags}
458 \begin{tabular}{l|p{9cm}}
460 Name&Meaning\\ \hline
461 \livetarg{chap:DWTAGconsttype}{DW\_TAG\_const\_type} & C or C++ const qualified type
462 \addtoindexx{const qualified type entry} \addtoindexx{C} \addtoindexx{C++} \\
463 \livetarg{chap:DWTAGpackedtype}{DW\_TAG\_packed\_type}& \addtoindex{Pascal} or Ada packed type\addtoindexx{packed type entry}
464 \addtoindexx{packed qualified type entry} \addtoindexx{Ada} \addtoindexx{Pascal} \\
465 \livetarg{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} & Pointer to an object of
466 the type being modified \addtoindexx{pointer qualified type entry} \\
467 \livetarg{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type}& C++ (lvalue) reference
468 to an object of the type
469 \addtoindexx{reference type entry}
471 \addtoindexx{reference qualified type entry} \\
472 \livetarg{chap:DWTAGrestricttype}{DW\_TAG\_restrict\_type}& \addtoindex{C}
474 \addtoindexx{restricted type entry}
476 \addtoindexx{restrict qualified type} \\
477 \livetarg{chap:DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type} & C++
478 \addtoindexx{rvalue reference type entry}
480 \addtoindexx{restricted type entry}
481 reference to an object of the type being modified
482 \addtoindexx{rvalue reference qualified type entry} \\
483 \livetarg{chap:DWTAGsharedtype}{DW\_TAG\_shared\_type}&\addtoindex{UPC} shared qualified type
484 \addtoindexx{shared qualified type entry} \\
485 \livetarg{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type}&C or C++ volatile qualified type
486 \addtoindexx{volatile qualified type entry} \\
491 %The following clearpage prevents splitting the example across pages.
492 \textit{As examples of how type modifiers are ordered, consider the following
493 \addtoindex{C} declarations:}
494 \begin{lstlisting}[numbers=none]
495 const unsigned char * volatile p;
497 \textit{which represents a volatile pointer to a constant
498 character. This is encoded in DWARF as:}
502 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}(p) -->
503 \livelink{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type} -->
504 \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} -->
505 \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type} -->
506 \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}(unsigned char)
511 \textit{On the other hand}
512 \begin{lstlisting}[numbers=none]
513 volatile unsigned char * const restrict p;
515 \textit{represents a restricted constant
516 pointer to a volatile character. This is encoded as:}
520 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}(p) -->
521 \livelink{chap:DWTAGrestricttype}{DW\_TAG\_restrict\_type} -->
522 \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type} -->
523 \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} -->
524 \livelink{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type} -->
525 \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}(unsigned char)
529 \section{Typedef Entries}
530 \label{chap:typedefentries}
531 A named type that is defined in terms of another type
532 definition is represented by a debugging information entry with
533 \addtoindexx{typedef entry}
534 the tag \livetarg{chap:DWTAGtypedef}{DW\_TAG\_typedef}.
535 The typedef entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
536 \addtoindexx{name attribute}
537 whose value is a null\dash terminated string containing
538 the name of the typedef as it appears in the source program.
540 The typedef entry may also contain
541 \addtoindexx{type attribute}
543 \livelink{chap:DWATtype}{DW\_AT\_type} attribute whose
544 value is a \livelink{chap:classreference}{reference}
545 to the type named by the typedef. If
546 the debugging information entry for a typedef represents
547 a declaration of the type that is not also a definition,
548 it does not contain a type attribute.
550 \textit{Depending on the language, a named type that is defined in
551 terms of another type may be called a type alias, a subtype,
552 a constrained type and other terms. A type name declared with
553 no defining details may be termed an
554 \addtoindexx{incomplete type}
555 incomplete, forward or hidden type.
556 While the DWARF \livelink{chap:DWTAGtypedef}{DW\_TAG\_typedef} entry was
557 originally inspired by the like named construct in
558 \addtoindex{C} and \addtoindex{C++},
559 it is broadly suitable for similar constructs (by whatever
560 source syntax) in other languages.}
562 \section{Array Type Entries}
563 \label{chap:arraytypeentries}
565 \textit{Many languages share the concept of an \doublequote{array,} which is
566 \addtoindexx{array type entry}
567 a table of components of identical type.}
569 An array type is represented by a debugging information entry
570 with the tag \livetarg{chap:DWTAGarraytype}{DW\_TAG\_array\_type}.
571 If a name has been given to
572 \addtoindexx{array!declaration of type}
573 the array type in the source program, then the corresponding
574 array type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
575 \addtoindexx{name attribute}
577 null\dash terminated string containing the array type name as it
578 appears in the source program.
581 \hypertarget{chap:DWATorderingarrayrowcolumnordering}
582 array type entry describing a multidimensional array may
583 \addtoindexx{array!element ordering}
584 have a \livelink{chap:DWATordering}{DW\_AT\_ordering} attribute whose
585 \livelink{chap:classconstant}{integer constant} value is
586 interpreted to mean either row-major or column-major ordering
587 of array elements. The set of values and their meanings
588 for the ordering attribute are listed in
589 Table \refersec{tab:arrayordering}.
591 ordering attribute is present, the default ordering for the
592 source language (which is indicated by the
593 \livelink{chap:DWATlanguage}{DW\_AT\_language}
595 \addtoindexx{language attribute}
596 of the enclosing compilation unit entry) is assumed.
598 \begin{simplenametable}[1.6in]{Array ordering}{tab:arrayordering}
599 \livetarg{chap:DWORDcolmajor}{DW\_ORD\_col\_major} \\
600 \livetarg{chap:DWORDrowmajor}{DW\_ORD\_row\_major} \\
601 \end{simplenametable}
603 The ordering attribute may optionally appear on one-dimensional
604 arrays; it will be ignored.
606 An array type entry has
607 \addtoindexx{type attribute}
608 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
610 \addtoindexx{array!element type}
611 the type of each element of the array.
613 If the amount of storage allocated to hold each element of an
614 object of the given array type is different from the amount
615 \addtoindexx{stride attribute|see{bit stride attribute or byte stride attribute}}
616 of storage that is normally allocated to hold an individual
617 \hypertarget{chap:DWATbitstridearrayelementstrideofarraytype}
619 \hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}
620 indicated element type, then the array type
621 \addtoindexx{bit stride attribute}
623 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
625 \addtoindexx{byte stride attribute}
626 a \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride}
628 \addtoindexx{bit stride attribute}
630 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
632 element of the array.
634 The array type entry may have either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or a
635 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
636 (see Section \refersec{chap:byteandbitsizes}),
638 amount of storage needed to hold an instance of the array type.
640 \textit{If the size of the array can be determined statically at
641 compile time, this value can usually be computed by multiplying
642 the number of array elements by the size of each element.}
645 Each array dimension is described by a debugging information
646 entry with either the
647 \addtoindexx{subrange type entry!as array dimension}
648 tag \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type} or the
649 \addtoindexx{enumeration type entry!as array dimension}
651 \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}. These entries are
653 array type entry and are ordered to reflect the appearance of
654 the dimensions in the source program (i.e., leftmost dimension
655 first, next to leftmost second, and so on).
657 \textit{In languages that have no concept of a
658 \doublequote{multidimensional array} (for example,
659 \addtoindex{C}), an array of arrays may
660 be represented by a debugging information entry for a
661 multidimensional array.}
664 Other attributes especially applicable to arrays are
665 \livelink{chap:DWATallocated}{DW\_AT\_allocated},
666 \livelink{chap:DWATassociated}{DW\_AT\_associated} and
667 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location},
668 which are described in
669 Section \refersec{chap:dynamictypeproperties}.
670 For relevant examples, see also Appendix \refersec{app:fortran90example}.
672 \section{Coarray Type Entries}
673 \label{chap:coarraytypeentries}
674 \addtoindexx{coarray}
675 \textit{In Fortran, a \doublequote{coarray} is an array whose
676 elements are located in different processes rather than in the
677 memory of one process. The individual elements
678 of a coarray can be scalars or arrays.
679 Similar to arrays, coarrays have \doublequote{codimensions} that are
680 indexed using a \doublequote{coindex} or multiple \doublequote{coindices}.
681 \addtoindexx{codimension|see{coarray}}
682 \addtoindexx{coindex|see{coarray}}
685 A coarray type is represented by a debugging information entry
686 with the tag \livetarg{chap:DWTAGcoarraytype}{DW\_TAG\_coarray\_type}.
687 If a name has been given to the
688 coarray type in the source, then the corresponding coarray type
689 entry has a \DWATname{} attribute whose value is a null-terminated
690 string containing the array type name as it appears in the source
693 A coarray entry has one or more \DWTAGsubrangetype{} child entries,
694 one for each codimension. It also has a \DWATtype{} attribute
695 describing the type of each element of the coarray.
697 \textit{In a coarray application, the run-time number of processes in the application
698 is part of the coindex calculation. It is represented in the Fortran source by
699 a coindex which is declared with a \doublequote{*} as the upper bound. To express this
700 concept in DWARF, the \DWTAGsubrangetype{} child entry for that index has
701 only a lower bound and no upper bound.}
703 \textit{How coarray elements are located and how coindices are
704 converted to process specifications is processor-dependent.}
706 \section{Structure, Union, Class and Interface Type Entries}
707 \label{chap:structureunionclassandinterfacetypeentries}
709 \textit{The languages
711 \addtoindex{C++}, and
712 \addtoindex{Pascal}, among others, allow the
713 programmer to define types that are collections of related
714 \addtoindexx{structure type entry}
716 In \addtoindex{C} and \addtoindex{C++}, these collections are called
717 \doublequote{structures.}
718 In \addtoindex{Pascal}, they are called \doublequote{records.}
719 The components may be of different types. The components are
720 called \doublequote{members} in \addtoindex{C} and
721 \addtoindex{C++}, and \doublequote{fields} in \addtoindex{Pascal}.}
723 \textit{The components of these collections each exist in their
724 own space in computer memory. The components of a C or C++
725 \doublequote{union} all coexist in the same memory.}
727 \textit{\addtoindex{Pascal} and
728 other languages have a \doublequote{discriminated union,}
729 \addtoindexx{discriminated union|see {variant entry}}
730 also called a \doublequote{variant record.} Here, selection of a
731 number of alternative substructures (\doublequote{variants}) is based
732 on the value of a component that is not part of any of those
733 substructures (the \doublequote{discriminant}).}
735 \textit{\addtoindex{C++} and
736 \addtoindex{Java} have the notion of \doublequote{class,} which is in some
737 ways similar to a structure. A class may have \doublequote{member
738 functions} which are subroutines that are within the scope
739 of a class or structure.}
741 \textit{The \addtoindex{C++} notion of
742 structure is more general than in \addtoindex{C}, being
743 equivalent to a class with minor differences. Accordingly,
744 in the following discussion statements about
745 \addtoindex{C++} classes may
746 be understood to apply to \addtoindex{C++} structures as well.}
748 \subsection{Structure, Union and Class Type Entries}
749 \label{chap:structureunionandclasstypeentries}
752 Structure, union, and class types are represented by debugging
753 \addtoindexx{structure type entry}
755 \addtoindexx{union type entry}
757 \addtoindexx{class type entry}
759 \livetarg{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type},
760 \livetarg{chap:DWTAGuniontype}{DW\_TAG\_union\_type},
761 and \livetarg{chap:DWTAGclasstype}{DW\_TAG\_class\_type},
762 respectively. If a name has been given to the structure,
763 union, or class in the source program, then the corresponding
764 structure type, union type, or class type entry has a
765 \livelink{chap:DWATname}{DW\_AT\_name} attribute
766 \addtoindexx{name attribute}
767 whose value is a null\dash terminated string
768 containing the type name as it appears in the source program.
770 The members of a structure, union, or class are represented
771 by debugging information entries that are owned by the
772 corresponding structure type, union type, or class type entry
773 and appear in the same order as the corresponding declarations
774 in the source program.
776 A structure type, union type or class type entry may have
777 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or a
778 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
779 \hypertarget{chap:DWATbitsizedatamemberbitsize}
780 (see Section \refersec{chap:byteandbitsizes}),
781 whose value is the amount of storage needed
782 to hold an instance of the structure, union or class type,
783 including any padding.
785 An incomplete structure, union or class type
786 \addtoindexx{incomplete structure/union/class}
788 \addtoindexx{incomplete type}
789 represented by a structure, union or class
790 entry that does not have a byte size attribute and that has
791 \addtoindexx{declaration attribute}
792 a \livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute.
794 If the complete declaration of a type has been placed in
795 \hypertarget{chap:DWATsignaturetypesignature}
796 a separate \addtoindex{type unit}
797 (see Section \refersec{chap:separatetypeunitentries}),
798 an incomplete declaration
799 \addtoindexx{incomplete type}
800 of that type in the compilation unit may provide
801 the unique 64\dash bit signature of the type using
802 \addtoindexx{type signature}
803 a \livelink{chap:DWATsignature}{DW\_AT\_signature}
806 If a structure, union or class entry represents the definition
807 of a structure, union or class member corresponding to a prior
808 incomplete structure, union or class, the entry may have a
809 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
810 \addtoindexx{specification attribute}
811 whose value is a \livelink{chap:classreference}{reference} to
812 the debugging information entry representing that incomplete
815 Structure, union and class entries containing the
816 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
817 \addtoindexx{specification attribute}
818 do not need to duplicate
819 information provided by the declaration entry referenced by the
820 specification attribute. In particular, such entries do not
821 need to contain an attribute for the name of the structure,
822 union or class they represent if such information is already
823 provided in the declaration.
825 \textit{For \addtoindex{C} and \addtoindex{C++},
827 \addtoindexx{data member|see {member entry (data)}}
828 member declarations occurring within
829 the declaration of a structure, union or class type are
830 considered to be \doublequote{definitions} of those members, with
831 the exception of \doublequote{static} data members, whose definitions
832 appear outside of the declaration of the enclosing structure,
833 union or class type. Function member declarations appearing
834 within a structure, union or class type declaration are
835 definitions only if the body of the function also appears
836 within the type declaration.}
838 If the definition for a given member of the structure, union
839 or class does not appear within the body of the declaration,
840 that member also has a debugging information entry describing
841 its definition. That latter entry has a
842 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
843 \addtoindexx{specification attribute}
844 referencing the debugging information entry
845 owned by the body of the structure, union or class entry and
846 representing a non\dash defining declaration of the data, function
847 or type member. The referenced entry will not have information
848 about the location of that member (low and high pc attributes
849 for function members, location descriptions for data members)
850 and will have a \livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute.
853 \textit{Consider a nested class whose
854 definition occurs outside of the containing class definition, as in:}
856 \begin{lstlisting}[numbers=none]
863 \textit{The two different structs can be described in
864 different compilation units to
865 facilitate DWARF space compression
866 (see Appendix \refersec{app:usingcompilationunits}).}
868 \subsection{Interface Type Entries}
869 \label{chap:interfacetypeentries}
871 \textit{The \addtoindex{Java} language defines \doublequote{interface} types.
873 \addtoindexx{interface type entry}
874 in \addtoindex{Java} is similar to a \addtoindex{C++} or
875 \addtoindex{Java} class with only abstract
876 methods and constant data members.}
879 \addtoindexx{interface type entry}
880 are represented by debugging information
882 tag \livetarg{chap:DWTAGinterfacetype}{DW\_TAG\_interface\_type}.
884 An interface type entry has
885 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
886 \addtoindexx{name attribute}
888 value is a null\dash terminated string containing the type name
889 as it appears in the source program.
891 The members of an interface are represented by debugging
892 information entries that are owned by the interface type
893 entry and that appear in the same order as the corresponding
894 declarations in the source program.
896 \subsection{Derived or Extended Structs, Classes and Interfaces}
897 \label{chap:derivedorextendedstructsclasesandinterfaces}
899 \textit{In \addtoindex{C++}, a class (or struct)
901 \addtoindexx{derived type (C++)|see{inheritance entry}}
902 be \doublequote{derived from} or be a
903 \doublequote{subclass of} another class.
904 In \addtoindex{Java}, an interface may \doublequote{extend}
905 \addtoindexx{extended type (Java)|see{inheritance entry}}
907 \addtoindexx{implementing type (Java)|see{inheritance entry}}
908 or more other interfaces, and a class may \doublequote{extend} another
909 class and/or \doublequote{implement} one or more interfaces. All of these
910 relationships may be described using the following. Note that
911 in \addtoindex{Java},
912 the distinction between extends and implements is
913 implied by the entities at the two ends of the relationship.}
915 A class type or interface type entry that describes a
916 derived, extended or implementing class or interface owns
917 \addtoindexx{implementing type (Java)|see{inheritance entry}}
918 debugging information entries describing each of the classes
919 or interfaces it is derived from, extending or implementing,
920 respectively, ordered as they were in the source program. Each
922 \addtoindexx{inheritance entry}
924 tag \livetarg{chap:DWTAGinheritance}{DW\_TAG\_inheritance}.
927 \addtoindexx{type attribute}
929 \addtoindexx{inheritance entry}
931 \livelink{chap:DWATtype}{DW\_AT\_type} attribute whose value is
932 a reference to the debugging information entry describing the
933 class or interface from which the parent class or structure
934 of the inheritance entry is derived, extended or implementing.
937 \addtoindexx{inheritance entry}
938 for a class that derives from or extends
939 \hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}
940 another class or struct also has
941 \addtoindexx{data member location attribute}
943 \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
944 attribute, whose value describes the location of the beginning
945 of the inherited type relative to the beginning address of the
946 instance of the derived class. If that value is a constant, it is the offset
947 in bytes from the beginning of the class to the beginning of
948 the instance of the inherited type. Otherwise, the value must be a location
949 description. In this latter case, the beginning address of
950 the instance of the derived class is pushed on the expression stack before
951 the \addtoindex{location description}
952 is evaluated and the result of the
953 evaluation is the location of the instance of the inherited type.
955 \textit{The interpretation of the value of this attribute for
956 inherited types is the same as the interpretation for data
958 (see Section \referfol{chap:datamemberentries}). }
961 \addtoindexx{inheritance entry}
963 \hypertarget{chap:DWATaccessibilitycppinheritedmembers}
965 \addtoindexx{accessibility attribute}
967 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
969 If no accessibility attribute
970 is present, private access is assumed for an entry of a class
971 and public access is assumed for an entry of an interface,
975 \hypertarget{chap:DWATvirtualityvirtualityofbaseclass}
976 the class referenced by the
977 \addtoindexx{inheritance entry}
978 inheritance entry serves
979 as a \addtoindex{C++} virtual base class, the inheritance entry has a
980 \livelink{chap:DWATvirtuality}{DW\_AT\_virtuality} attribute.
982 \textit{For a \addtoindex{C++} virtual base, the
983 \addtoindex{data member location attribute}
984 will usually consist of a non-trivial
985 \addtoindex{location description}.}
987 \subsection{Access Declarations}
988 \label{chap:accessdeclarations}
990 \textit{In \addtoindex{C++}, a derived class may contain access declarations that
991 \addtoindexx{access declaration entry}
992 change the accessibility of individual class members from the
993 overall accessibility specified by the inheritance declaration.
994 A single access declaration may refer to a set of overloaded
997 If a derived class or structure contains access declarations,
998 each such declaration may be represented by a debugging
999 information entry with the tag
1000 \livetarg{chap:DWTAGaccessdeclaration}{DW\_TAG\_access\_declaration}.
1002 such entry is a child of the class or structure type entry.
1004 An access declaration entry has
1005 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1006 \addtoindexx{name attribute}
1008 value is a null\dash terminated string representing the name used
1009 in the declaration in the source program, including any class
1010 or structure qualifiers.
1012 An access declaration entry
1013 \hypertarget{chap:DWATaccessibilitycppbaseclasses}
1016 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1017 attribute describing the declared accessibility of the named
1022 \subsection{Friends}
1023 \label{chap:friends}
1025 Each \doublequote{friend}
1026 \addtoindexx{friend entry}
1027 declared by a structure, union or class
1028 \hypertarget{chap:DWATfriendfriendrelationship}
1029 type may be represented by a debugging information entry
1030 that is a child of the structure, union or class type entry;
1031 the friend entry has the
1032 tag \livetarg{chap:DWTAGfriend}{DW\_TAG\_friend}.
1035 \addtoindexx{friend attribute}
1036 a \livelink{chap:DWATfriend}{DW\_AT\_friend} attribute, whose value is
1037 a reference to the debugging information entry describing
1038 the declaration of the friend.
1041 \subsection{Data Member Entries}
1042 \label{chap:datamemberentries}
1044 A data member (as opposed to a member function) is
1045 represented by a debugging information entry with the
1046 tag \livetarg{chap:DWTAGmember}{DW\_TAG\_member}.
1048 \addtoindexx{member entry (data)}
1049 member entry for a named member has
1050 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1051 \addtoindexx{name attribute}
1052 whose value is a null\dash terminated
1053 string containing the member name as it appears in the source
1054 program. If the member entry describes an
1055 \addtoindex{anonymous union},
1056 the name attribute is omitted or the value of the attribute
1057 consists of a single zero byte.
1059 The data member entry has
1060 \addtoindexx{type attribute}
1062 \livelink{chap:DWATtype}{DW\_AT\_type} attribute to denote
1063 \addtoindexx{member entry (data)}
1064 the type of that member.
1066 A data member entry may
1067 \addtoindexx{accessibility attribute}
1069 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1070 attribute. If no accessibility attribute is present, private
1071 access is assumed for an entry of a class and public access
1072 is assumed for an entry of a structure, union, or interface.
1075 \hypertarget{chap:DWATmutablemutablepropertyofmemberdata}
1077 \addtoindexx{member entry (data)}
1079 \addtoindexx{mutable attribute}
1080 have a \livelink{chap:DWATmutable}{DW\_AT\_mutable} attribute,
1081 which is a \livelink{chap:classflag}{flag}.
1082 This attribute indicates whether the data
1083 member was declared with the mutable storage class specifier.
1085 The beginning of a data member
1086 \addtoindexx{beginning of a data member}
1087 is described relative to
1088 \addtoindexx{beginning of an object}
1089 the beginning of the object in which it is immediately
1090 contained. In general, the beginning is characterized by
1091 both an address and a bit offset within the byte at that
1092 address. When the storage for an entity includes all of
1093 the bits in the beginning byte, the beginning bit offset is
1096 Bit offsets in DWARF use the bit numbering and direction
1097 conventions that are appropriate to the current language on
1101 \addtoindexx{member entry (data)}
1102 corresponding to a data member that is
1103 \hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}
1105 \hypertarget{chap:DWATdatamemberlocationdatamemberlocation}
1106 in a structure, union or class may have either
1107 \addtoindexx{data member location attribute}
1109 \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} attribute or a
1110 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1111 attribute. If the beginning of the data member is the same as
1112 the beginning of the containing entity then neither attribute
1116 For a \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} attribute
1117 \addtoindexx{data member location attribute}
1118 there are two cases:
1119 \begin{enumerate}[1. ]
1120 \item If the value is an \livelink{chap:classconstant}{integer constant},
1122 in bytes from the beginning of the containing entity. If
1123 the beginning of the containing entity has a non-zero bit
1124 offset then the beginning of the member entry has that same
1127 \item Otherwise, the value must be a \addtoindex{location description}.
1129 this case, the beginning of the containing entity must be byte
1130 aligned. The beginning address is pushed on the DWARF stack
1131 before the \addtoindex{location} description is evaluated; the result of
1132 the evaluation is the base address of the member entry.
1134 \textit{The push on the DWARF expression stack of the base address of
1135 the containing construct is equivalent to execution of the
1136 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address} operation
1137 (see Section \refersec{chap:stackoperations});
1138 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address} therefore
1139 is not needed at the
1140 beginning of a \addtoindex{location description} for a data member.
1142 result of the evaluation is a location---either an address or
1143 the name of a register, not an offset to the member.}
1145 \textit{A \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
1147 \addtoindexx{data member location attribute}
1148 that has the form of a
1149 \addtoindex{location description} is not valid for a data member contained
1150 in an entity that is not byte aligned because DWARF operations
1151 do not allow for manipulating or computing bit offsets.}
1155 For a \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} attribute,
1156 the value is an \livelink{chap:classconstant}{integer constant}
1157 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1158 that specifies the number of bits
1159 from the beginning of the containing entity to the beginning
1160 of the data member. This value must be greater than or equal
1161 to zero, but is not limited to less than the number of bits
1164 If the size of a data member is not the same as the size
1165 of the type given for the data member, the data member has
1166 \addtoindexx{bit size attribute}
1167 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1168 or a \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute whose
1169 \livelink{chap:classconstant}{integer constant} value
1170 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1172 of storage needed to hold the value of the data member.
1174 \textit{Bit fields in \addtoindex{C} and \addtoindex{C++}
1176 \addtoindexx{bit fields}
1178 \addtoindexx{data bit offset}
1180 \addtoindexx{data bit size}
1182 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} and
1183 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attributes.}
1186 \textit{This Standard uses the following bit numbering and direction
1187 conventions in examples. These conventions are for illustrative
1188 purposes and other conventions may apply on particular
1191 \item \textit{For big\dash endian architectures, bit offsets are
1192 counted from high-order to low\dash order bits within a byte (or
1193 larger storage unit); in this case, the bit offset identifies
1194 the high\dash order bit of the object.}
1196 \item \textit{For little\dash endian architectures, bit offsets are
1197 counted from low\dash order to high\dash order bits within a byte (or
1198 larger storage unit); in this case, the bit offset identifies
1199 the low\dash order bit of the object.}
1203 \textit{In either case, the bit so identified is defined as the
1204 \addtoindexx{beginning of an object}
1205 beginning of the object.}
1207 \textit{For example, take one possible representation of the following
1208 \addtoindex{C} structure definition
1209 in both big\dash and little\dash endian byte orders:}
1220 \textit{Figures \referfol{fig:bigendiandatabitoffsets} and
1221 \refersec{fig:littleendiandatabitoffsets}
1222 show the structure layout
1223 and data bit offsets for example big\dash\ and little\dash endian
1224 architectures, respectively. Both diagrams show a structure
1225 that begins at address A and whose size is four bytes. Also,
1226 high order bits are to the left and low order bits are to
1238 Addresses increase ->
1239 | A | A + 1 | A + 2 | A + 3 |
1241 Data bit offsets increase ->
1242 +---------------+---------------+---------------+---------------+
1243 |0 4|5 10|11 15|16 23|24 31|
1244 | j | k | m | n | <pad> |
1246 +---------------------------------------------------------------+
1250 \caption{Big-endian data bit offsets}
1251 \label{fig:bigendiandatabitoffsets}
1262 <- Addresses increase
1263 | A + 3 | A + 2 | A + 1 | A |
1265 <- Data bit offsets increase
1266 +---------------+---------------+---------------+---------------+
1267 |31 24|23 16|15 11|10 5|4 0|
1268 | <pad> | n | m | k | j |
1270 +---------------------------------------------------------------+
1274 \caption{Little-endian data bit offsets}
1275 \label{fig:littleendiandatabitoffsets}
1278 \textit{Note that data member bit offsets in this example are the
1279 same for both big\dash\ and little\dash endian architectures even
1280 though the fields are allocated in different directions
1281 (high\dash order to low-order versus low\dash order to high\dash order);
1282 the bit naming conventions for memory and/or registers of
1283 the target architecture may or may not make this seem natural.}
1285 \textit{For a more extensive example showing nested and packed records
1287 Appendix \refersec{app:pascalexample}.}
1289 \textit{Attribute \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1291 \addtoindex{DWARF Version 4}, unchanged in \addtoindex{DWARF Version 5},
1292 and is also used for base types
1294 \refersec{chap:basetypeentries}).
1296 \livetarg{chap:DWATbitoffsetdatamemberbitlocation}{}
1297 attributes \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} and
1298 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} when used to
1299 identify the beginning of bit field data members as defined
1300 in DWARF V3 and earlier. The \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
1301 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
1302 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
1303 attribute combination is deprecated for data members in DWARF
1304 Version 4 and later. See Section 5.6.6 in the DWARF Version 4
1305 specification for a discussion of compatibility considerations.}
1307 \subsection{Member Function Entries}
1308 \label{chap:memberfunctionentries}
1310 A member function is represented by a
1311 \addtoindexx{member function entry}
1312 debugging information entry
1314 \addtoindexx{subprogram entry!as member function}
1315 tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}.
1316 The member function entry
1317 may contain the same attributes and follows the same rules
1318 as non\dash member global subroutine entries
1319 (see Section \refersec{chap:subroutineandentrypointentries}).
1322 \addtoindexx{accessibility attribute}
1323 member function entry may have a
1324 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1325 attribute. If no accessibility attribute is present, private
1326 access is assumed for an entry of a class and public access
1327 is assumed for an entry of a structure, union or interface.
1330 \hypertarget{chap:DWATvirtualityvirtualityoffunction}
1331 the member function entry describes a virtual function,
1332 then that entry has a
1333 \livelink{chap:DWATvirtuality}{DW\_AT\_virtuality} attribute.
1336 \hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}
1337 the member function entry describes an explicit member
1338 function, then that entry has
1339 \addtoindexx{explicit attribute}
1341 \livelink{chap:DWATexplicit}{DW\_AT\_explicit} attribute.
1344 \hypertarget{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}
1345 entry for a virtual function also has a
1346 \livelink{chap:DWATvtableelemlocation}{DW\_AT\_vtable\_elem\_location}
1347 \addtoindexi{attribute}{vtable element location attribute} whose value contains
1348 a \addtoindex{location description}
1349 yielding the address of the slot
1350 for the function within the virtual function table for the
1351 enclosing class. The address of an object of the enclosing
1352 type is pushed onto the expression stack before the location
1353 description is evaluated.
1356 \hypertarget{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}
1357 the member function entry describes a non\dash static member
1358 \addtoindexx{this pointer attribute|see{object pointer attribute}}
1359 function, then that entry
1360 \addtoindexx{self pointer attribute|see{object pointer attribute}}
1362 \addtoindexx{object pointer attribute}
1363 a \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}
1365 whose value is a \livelink{chap:classreference}{reference}
1366 to the formal parameter entry
1367 that corresponds to the object for which the function is
1368 called. The name attribute of that formal parameter is defined
1369 by the current language (for example,
1370 \texttt{this} for \addtoindex{C++} or \texttt{self}
1371 for \addtoindex{Objective C}
1372 and some other languages). That parameter
1373 also has a \livelink{chap:DWATartificial}{DW\_AT\_artificial} attribute whose value is true.
1375 Conversely, if the member function entry describes a static
1376 member function, the entry does not have
1377 \addtoindexx{object pointer attribute}
1379 \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}
1382 If the member function entry describes a non\dash static member
1383 function that has a const\dash volatile qualification, then
1384 the entry describes a non\dash static member function whose
1385 object formal parameter has a type that has an equivalent
1386 const\dash volatile qualification.
1388 If a subroutine entry represents the defining declaration
1389 of a member function and that definition appears outside of
1390 the body of the enclosing class declaration, the subroutine
1392 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute,
1393 \addtoindexx{specification attribute}
1395 a reference to the debugging information entry representing
1396 the declaration of this function member. The referenced entry
1397 will be a child of some class (or structure) type entry.
1399 Subroutine entries containing the
1400 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
1401 \addtoindexx{specification attribute}
1402 do not need to duplicate information provided
1403 by the declaration entry referenced by the specification
1404 attribute. In particular, such entries do not need to contain
1405 attributes for the name or return type of the function member
1406 whose definition they represent.
1409 \subsection{Class Template Instantiations}
1410 \label{chap:classtemplateinstantiations}
1412 \textit{In \addtoindex{C++} a class template is a generic definition of a class
1413 type that may be instantiated when an instance of the class
1414 is declared or defined. The generic description of the
1415 class may include both parameterized types and parameterized
1416 constant values. DWARF does not represent the generic template
1417 definition, but does represent each instantiation.}
1419 A class template instantiation is represented by a
1420 debugging information entry with the tag \livelink{chap:DWTAGclasstype}{DW\_TAG\_class\_type},
1421 \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type} or
1422 \livelink{chap:DWTAGuniontype}{DW\_TAG\_union\_type}. With five
1423 exceptions, such an entry will contain the same attributes
1424 and have the same types of child entries as would an entry
1425 for a class type defined explicitly using the instantiation
1426 types and values. The exceptions are:
1428 \begin{enumerate}[1. ]
1429 \item Each formal parameterized type declaration appearing in the
1430 template definition is represented by a debugging information
1432 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}. Each
1433 such entry may have a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1434 \addtoindexx{name attribute}
1436 a null\dash terminated string containing the name of the formal
1437 type parameter as it appears in the source program. The
1438 template type parameter entry also has
1439 \addtoindexx{type attribute}
1441 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1442 describing the actual type by which the formal is replaced
1443 for this instantiation.
1445 \item Each formal parameterized value declaration appearing in the
1446 template definition is represented by a
1447 debugging information entry with the
1448 \addtoindexx{template value parameter entry}
1449 tag \livetarg{chap:DWTAGtemplatevalueparameter}{DW\_TAG\_template\_value\_parameter}.
1451 such entry may have a
1452 \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1453 \addtoindexx{name attribute}
1455 a null\dash terminated string containing the name of the formal
1456 value parameter as it appears in the source program.
1458 \hypertarget{chap:DWATconstvaluetemplatevalueparameter}
1459 template value parameter entry
1460 \addtoindexx{template value parameter entry}
1462 \addtoindexx{type attribute}
1464 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1465 describing the type of the parameterized value. Finally,
1466 the template value parameter entry has a
1467 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}
1468 attribute, whose value is the actual constant value of the
1469 value parameter for this instantiation as represented on the
1470 target architecture.
1473 \item The class type entry and each of its child entries reference
1474 a \addtoindex{template type parameter entry} in any circumstance where the
1475 source template definition references a formal parameterized
1477 Similarly, the class type entry and each of its child
1478 entries reference a template value parameter entry in any
1479 circumstance where the source template definition references
1480 a formal parameterized value.
1483 \item If the compiler has generated a special compilation unit to
1485 \addtoindexx{template instantiation!and special compilation unit}
1486 template instantiation and that special compilation
1487 unit has a different name from the compilation unit containing
1488 the template definition, the name attribute for the debugging
1489 information entry representing the special compilation unit
1490 should be empty or omitted.
1493 \item If the class type entry representing the template
1494 instantiation or any of its child entries contains declaration
1495 coordinate attributes, those attributes should refer to
1496 the source for the template definition, not to any source
1497 generated artificially by the compiler.
1501 \subsection{Variant Entries}
1502 \label{chap:variantentries}
1504 A variant part of a structure is represented by a debugging
1505 information entry\addtoindexx{variant part entry} with the
1506 tag \livetarg{chap:DWTAGvariantpart}{DW\_TAG\_variant\_part} and is
1507 owned by the corresponding structure type entry.
1509 If the variant part has a discriminant, the discriminant is
1510 \hypertarget{chap:DWATdiscrdiscriminantofvariantpart}
1512 \addtoindexx{discriminant (entry)}
1513 separate debugging information entry which
1514 is a child of the variant part entry. This entry has the form
1516 \addtoindexx{member entry (data)!as discriminant}
1517 structure data member entry. The variant part entry will
1518 \addtoindexx{discriminant attribute}
1520 \livelink{chap:DWATdiscr}{DW\_AT\_discr} attribute
1521 whose value is a \livelink{chap:classreference}{reference} to
1522 the member entry for the discriminant.
1524 If the variant part does not have a discriminant (tag field),
1525 the variant part entry has
1526 \addtoindexx{type attribute}
1528 \livelink{chap:DWATtype}{DW\_AT\_type} attribute to represent
1531 Each variant of a particular variant part is represented by
1532 \hypertarget{chap:DWATdiscrvaluediscriminantvalue}
1533 a debugging information entry\addtoindexx{variant entry} with the
1534 tag \livetarg{chap:DWTAGvariant}{DW\_TAG\_variant}
1535 and is a child of the variant part entry. The value that
1536 selects a given variant may be represented in one of three
1537 ways. The variant entry may have a
1538 \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value} attribute
1539 whose value represents a single case label. The value of this
1540 attribute is encoded as an LEB128 number. The number is signed
1541 if the tag type for the variant part containing this variant
1542 is a signed type. The number is unsigned if the tag type is
1547 \hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}
1548 the variant entry may contain
1549 \addtoindexx{discriminant list attribute}
1551 \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list}
1552 attribute, whose value represents a list of discriminant
1553 values. This list is represented by any of the
1554 \livelink{chap:classblock}{block} forms and
1555 may contain a mixture of case labels and label ranges. Each
1556 item on the list is prefixed with a discriminant value
1557 descriptor that determines whether the list item represents
1558 a single label or a label range. A single case label is
1559 represented as an LEB128 number as defined above for
1560 \addtoindexx{discriminant value attribute}
1562 \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value}
1563 attribute. A label range is represented by
1564 two LEB128 numbers, the low value of the range followed by the
1565 high value. Both values follow the rules for signedness just
1566 described. The discriminant value descriptor is an integer
1567 constant that may have one of the values given in
1568 Table \refersec{tab:discriminantdescriptorvalues}.
1570 \begin{simplenametable}[1.4in]{Discriminant descriptor values}{tab:discriminantdescriptorvalues}
1571 \livetarg{chap:DWDSClabel}{DW\_DSC\_label} \\
1572 \livetarg{chap:DWDSCrange}{DW\_DSC\_range} \\
1573 \end{simplenametable}
1575 If a variant entry has neither a \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value}
1576 attribute nor a \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list} attribute, or if it has
1577 a \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list} attribute with 0 size, the variant is a
1580 The components selected by a particular variant are represented
1581 by debugging information entries owned by the corresponding
1582 variant entry and appear in the same order as the corresponding
1583 declarations in the source program.
1585 \section{Condition Entries}
1586 \label{chap:conditionentries}
1588 \textit{COBOL has the notion of
1589 \addtoindexx{level-88 condition, COBOL}
1590 a \doublequote{level\dash 88 condition} that
1591 associates a data item, called the conditional variable, with
1592 a set of one or more constant values and/or value ranges.
1593 % Note: the {} after \textquoteright (twice) is necessary to assure a following space separator
1594 Semantically, the condition is \textquoteleft true\textquoteright{}
1596 variable's value matches any of the described constants,
1597 and the condition is \textquoteleft false\textquoteright{} otherwise.}
1599 The \livetarg{chap:DWTAGcondition}{DW\_TAG\_condition}
1600 debugging information entry\addtoindexx{condition entry}
1602 logical condition that tests whether a given data item\textquoteright s
1603 value matches one of a set of constant values. If a name
1604 has been given to the condition, the condition entry has a
1605 \livelink{chap:DWATname}{DW\_AT\_name} attribute
1606 \addtoindexx{name attribute}
1607 whose value is a null\dash terminated string
1608 giving the condition name as it appears in the source program.
1610 The condition entry's parent entry describes the conditional
1611 variable; normally this will be a \livelink{chap:DWTAGvariable}{DW\_TAG\_variable},
1612 \livelink{chap:DWTAGmember}{DW\_TAG\_member} or
1613 \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter} entry.
1615 \addtoindexx{formal parameter entry}
1617 entry has an array type, the condition can test any individual
1618 element, but not the array as a whole. The condition entry
1619 implicitly specifies a \doublequote{comparison type} that is the
1620 type of an array element if the parent has an array type;
1621 otherwise it is the type of the parent entry.
1624 The condition entry owns \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} and/or
1625 \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type} entries that describe the constant
1626 values associated with the condition. If any child entry
1627 \addtoindexx{type attribute}
1629 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute,
1630 that attribute should describe a type
1631 compatible with the comparison type (according to the source
1632 language); otherwise the child\textquoteright s type is the same as the
1635 \textit{For conditional variables with alphanumeric types, COBOL
1636 permits a source program to provide ranges of alphanumeric
1637 constants in the condition. Normally a subrange type entry
1638 does not describe ranges of strings; however, this can be
1639 represented using bounds attributes that are references to
1640 constant entries describing strings. A subrange type entry may
1641 refer to constant entries that are siblings of the subrange
1645 \section{Enumeration Type Entries}
1646 \label{chap:enumerationtypeentries}
1648 \textit{An \doublequote{enumeration type} is a scalar that can assume one of
1649 a fixed number of symbolic values.}
1651 An enumeration type is represented by a debugging information
1653 \livetarg{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}.
1655 If a name has been given to the enumeration type in the source
1656 program, then the corresponding enumeration type entry has
1657 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1658 \addtoindexx{name attribute}
1659 whose value is a null\dash terminated
1660 string containing the enumeration type name as it appears
1661 in the source program. This entry also has a
1662 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1663 attribute whose \livelink{chap:classconstant}{integer constant}
1664 value is the number of bytes
1665 required to hold an instance of the enumeration.
1667 The \addtoindex{enumeration type entry}
1669 \addtoindexx{type attribute}
1670 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1671 which refers to the underlying data type used to implement
1674 If an enumeration type has type safe
1675 \addtoindexx{type safe enumeration types}
1678 \begin{enumerate}[1. ]
1679 \item Enumerators are contained in the scope of the enumeration type, and/or
1681 \item Enumerators are not implicitly converted to another type
1684 then the \addtoindex{enumeration type entry} may
1685 \addtoindexx{enum class|see{type-safe enumeration}}
1686 have a \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}
1687 attribute, which is a \livelink{chap:classflag}{flag}.
1688 In a language that offers only
1689 one kind of enumeration declaration, this attribute is not
1692 \textit{In \addtoindex{C} or \addtoindex{C++},
1693 the underlying type will be the appropriate
1694 integral type determined by the compiler from the properties of
1695 \hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}
1696 the enumeration literal values.
1697 A \addtoindex{C++} type declaration written
1698 using enum class declares a strongly typed enumeration and
1699 is represented using \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}
1700 in combination with \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}.}
1702 Each enumeration literal is represented by a debugging
1703 \addtoindexx{enumeration literal|see{enumeration entry}}
1704 information entry with the
1705 tag \livetarg{chap:DWTAGenumerator}{DW\_TAG\_enumerator}.
1707 such entry is a child of the
1708 \addtoindex{enumeration type entry}, and the
1709 enumerator entries appear in the same order as the declarations
1710 of the enumeration literals in the source program.
1712 Each \addtoindex{enumerator entry} has a
1713 \livelink{chap:DWATname}{DW\_AT\_name} attribute, whose
1714 \addtoindexx{name attribute}
1715 value is a null\dash terminated string containing the name of the
1716 \hypertarget{chap:DWATconstvalueenumerationliteralvalue}
1717 enumeration literal as it appears in the source program.
1718 Each enumerator entry also has a
1719 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value} attribute,
1720 whose value is the actual numeric value of the enumerator as
1721 represented on the target system.
1724 If the enumeration type occurs as the description of a
1725 \addtoindexx{enumeration type endry!as array dimension}
1726 dimension of an array type, and the stride for that dimension
1727 \hypertarget{chap:DWATbytestrideenumerationstridedimensionofarraytype}
1728 is different than what would otherwise be determined, then
1729 \hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}
1730 the enumeration type entry has either a
1731 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
1732 or \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
1733 \addtoindexx{bit stride attribute}
1734 which specifies the separation
1735 between successive elements along the dimension as described
1737 Section \refersec{chap:staticanddynamicvaluesofattributes}.
1739 \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
1740 \addtoindexx{bit stride attribute}
1741 is interpreted as bits and the value of
1742 \addtoindexx{byte stride attribute}
1744 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
1745 attribute is interpreted as bytes.
1748 \section{Subroutine Type Entries}
1749 \label{chap:subroutinetypeentries}
1751 \textit{It is possible in \addtoindex{C}
1752 to declare pointers to subroutines
1753 that return a value of a specific type. In both
1754 \addtoindex{C} and \addtoindex{C++},
1755 it is possible to declare pointers to subroutines that not
1756 only return a value of a specific type, but accept only
1757 arguments of specific types. The type of such pointers would
1758 be described with a \doublequote{pointer to} modifier applied to a
1759 user\dash defined type.}
1761 A subroutine type is represented by a debugging information
1763 \addtoindexx{subroutine type entry}
1764 tag \livetarg{chap:DWTAGsubroutinetype}{DW\_TAG\_subroutine\_type}.
1766 been given to the subroutine type in the source program,
1767 then the corresponding subroutine type entry has
1768 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1769 \addtoindexx{name attribute}
1770 whose value is a null\dash terminated string containing
1771 the subroutine type name as it appears in the source program.
1773 If the subroutine type describes a function that returns
1774 a value, then the subroutine type entry has
1775 \addtoindexx{type attribute}
1776 a \livelink{chap:DWATtype}{DW\_AT\_type}
1777 attribute to denote the type returned by the subroutine. If
1778 the types of the arguments are necessary to describe the
1779 subroutine type, then the corresponding subroutine type
1780 entry owns debugging information entries that describe the
1781 arguments. These debugging information entries appear in the
1782 order that the corresponding argument types appear in the
1785 \textit{In \addtoindex{C} there
1786 is a difference between the types of functions
1787 declared using function prototype style declarations and
1788 those declared using non\dash prototype declarations.}
1791 \hypertarget{chap:DWATprototypedsubroutineprototype}
1792 subroutine entry declared with a function prototype style
1793 declaration may have
1794 \addtoindexx{prototyped attribute}
1796 \livelink{chap:DWATprototyped}{DW\_AT\_prototyped} attribute, which is
1797 a \livelink{chap:classflag}{flag}.
1799 Each debugging information entry owned by a subroutine
1800 type entry corresponds to either a formal parameter or the sequence of
1801 unspecified parameters of the subprogram type:
1803 \begin{enumerate}[1. ]
1804 \item A formal parameter of a parameter list (that has a
1805 specific type) is represented by a debugging information entry
1806 with the tag \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}.
1807 Each formal parameter
1809 \addtoindexx{type attribute}
1810 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute that refers to the type of
1811 the formal parameter.
1813 \item The unspecified parameters of a variable parameter list
1814 \addtoindexx{unspecified parameters entry}
1816 \addtoindexx{\texttt{...} parameters|see{unspecified parameters entry}}
1817 represented by a debugging information entry with the
1818 tag \livelink{chap:DWTAGunspecifiedparameters}{DW\_TAG\_unspecified\_parameters}.
1823 \section{String Type Entries}
1824 \label{chap:stringtypeentries}
1826 \textit{A \doublequote{string} is a sequence of characters that have specific
1827 \addtoindexx{string type entry}
1828 semantics and operations that distinguish them from arrays of
1830 \addtoindex{Fortran} is one of the languages that has a string
1831 type. Note that \doublequote{string} in this context refers to a target
1832 machine concept, not the class string as used in this document
1833 (except for the name attribute).}
1835 A string type is represented by a debugging information entry
1836 with the tag \livetarg{chap:DWTAGstringtype}{DW\_TAG\_string\_type}.
1837 If a name has been given to
1838 the string type in the source program, then the corresponding
1839 string type entry has a
1840 \livelink{chap:DWATname}{DW\_AT\_name} attribute
1841 \addtoindexx{name attribute}
1843 a null\dash terminated string containing the string type name as
1844 it appears in the source program.
1847 The string type entry may have a
1848 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or
1849 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
1850 attribute, whose value
1851 (see Section \refersec{chap:byteandbitsizes})
1853 storage needed to hold a value of the string type.
1857 \hypertarget{chap:DWATstringlengthstringlengthofstringtype}
1858 string type entry may also have a
1859 \livelink{chap:DWATstringlength}{DW\_AT\_string\_length} attribute
1861 \addtoindexx{string length attribute}
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).
1870 The string type entry may also have a
1871 \livetarg{chap:DWATstringlengthbytesize}{DW\_AT\_string\_length\_byte\_size}
1873 \livetarg{chap:DWATstringlengthbitsize}{DW\_AT\_string\_length\_bit\_size} 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
1880 \addtoindex{size of an address} on the target machine.
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:
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
1894 In DWARF Version 5, \DWATbytesize{} always specifies the amount of storage
1895 allocated for objects of the string type.}
1897 \section{Set Type Entries}
1898 \label{chap:settypeentries}
1900 \textit{\addtoindex{Pascal} provides the concept of a \doublequote{set,} which represents
1901 a group of values of ordinal type.}
1903 A set is represented by a debugging information entry with
1904 the tag \livetarg{chap:DWTAGsettype}{DW\_TAG\_set\_type}.
1905 \addtoindexx{set type entry}
1906 If a name has been given to the
1907 set type, then the set type entry has
1908 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1909 \addtoindexx{name attribute}
1910 whose value is a null\dash terminated string containing the
1911 set type name as it appears in the source program.
1913 The set type entry has
1914 \addtoindexx{type attribute}
1915 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to denote the
1916 type of an element of the set.
1919 If the amount of storage allocated to hold each element of an
1920 object of the given set type is different from the amount of
1921 storage that is normally allocated to hold an individual object
1922 of the indicated element type, then the set type entry has
1923 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute, or
1924 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
1925 whose value (see Section \refersec{chap:byteandbitsizes}) is
1926 the amount of storage needed to hold a value of the set type.
1929 \section{Subrange Type Entries}
1930 \label{chap:subrangetypeentries}
1932 \textit{Several languages support the concept of a \doublequote{subrange}
1933 type object. These objects can represent a subset of the
1934 values that an object of the basis type for the subrange can
1936 Subrange type entries may also be used to represent
1937 the bounds of array dimensions.}
1939 A subrange type is represented by a debugging information
1941 \addtoindexx{subrange type entry}
1942 tag \livetarg{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}.
1944 given to the subrange type, then the subrange type entry
1945 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1946 \addtoindexx{name attribute}
1947 whose value is a null\dash terminated
1948 string containing the subrange type name as it appears in
1951 The subrange entry may have
1952 \addtoindexx{type attribute}
1953 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to describe
1954 the type of object, called the basis type, of whose values
1955 this subrange is a subset.
1957 If the amount of storage allocated to hold each element of an
1958 object of the given subrange type is different from the amount
1959 of storage that is normally allocated to hold an individual
1960 object of the indicated element type, then the subrange
1962 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or
1963 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
1964 attribute, whose value
1965 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1967 storage needed to hold a value of the subrange type.
1970 \hypertarget{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}
1971 subrange entry may have
1972 \addtoindexx{threads scaled attribute}
1974 \livelink{chap:DWATthreadsscaled}{DW\_AT\_threads\_scaled} attribute,
1975 which is a \livelink{chap:classflag}{flag}.
1976 If present, this attribute indicates whether
1977 this subrange represents a \addtoindex{UPC} array bound which is scaled
1978 by the runtime THREADS value (the number of UPC threads in
1979 this execution of the program).
1981 \textit{This allows the representation of a \addtoindex{UPC} shared array such as}
1983 \begin{lstlisting}[numbers=none]
1984 int shared foo[34*THREADS][10][20];
1988 \hypertarget{chap:DWATlowerboundlowerboundofsubrange}
1990 \hypertarget{chap:DWATupperboundupperboundofsubrange}
1991 entry may have the attributes
1992 \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}
1993 \addtoindexx{lower bound attribute}
1994 and \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}
1995 \addtoindexx{upper bound attribute} to specify, respectively, the lower
1996 and upper bound values of the subrange. The
1997 \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}
1999 \hypertarget{chap:DWATcountelementsofsubrangetype}
2001 % FIXME: The following matches DWARF4: odd as there is no default count.
2002 \addtoindexx{count attribute!default}
2004 \addtoindexx{count attribute}
2006 \livelink{chap:DWATcount}{DW\_AT\_count} attribute,
2008 value describes the number of elements in the subrange rather
2009 than the value of the last element. The value of each of
2010 these attributes is determined as described in
2011 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2013 If the lower bound value is missing, the value is assumed to
2014 be a language\dash dependent default constant.
2015 \addtoindexx{lower bound attribute!default}
2016 The default lower bound is 0 for
2017 \addtoindex{C}, \addtoindex{C++},
2020 \addtoindex{Haskell},
2022 \addtoindex{Objective C},
2023 \addtoindex{Objective C++},
2024 \addtoindex{OpenCL},
2025 \addtoindex{Python}, and
2027 The default lower bound is 1 for
2030 \addtoindex{Fortran},
2031 \addtoindex{Modula-2},
2032 \addtoindex{Modula-3},
2033 \addtoindex{Pascal} and
2036 \textit{No other default lower bound values are currently defined.}
2038 If the upper bound and count are missing, then the upper bound value is
2039 \textit{unknown}.\addtoindexx{upper bound attribute!default unknown}
2041 If the subrange entry has no type attribute describing the
2042 basis type, the basis type is determined as follows:
2043 \begin{enumerate}[1. ]
2045 If there is a lower bound attribute that references an object,
2046 the basis type is assumed to be the same as the type of that object.
2048 Otherwise, if there is an upper bound or count attribute that references
2049 an object, the basis type is assumed to be the same as the type of that object.
2051 Otherwise, the type is
2052 assumed to be the same type, in the source language of the
2053 compilation unit containing the subrange entry, as a signed
2054 integer with the same size as an address on the target machine.
2057 If the subrange type occurs as the description of a dimension
2058 of an array type, and the stride for that dimension is
2059 \hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}
2060 different than what would otherwise be determined, then
2061 \hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}
2062 the subrange type entry has either
2063 \addtoindexx{byte stride attribute}
2065 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride} or
2066 \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
2067 \addtoindexx{bit stride attribute}
2068 which specifies the separation
2069 between successive elements along the dimension as described
2071 Section \refersec{chap:byteandbitsizes}.
2073 \textit{Note that the stride can be negative.}
2075 \section{Pointer to Member Type Entries}
2076 \label{chap:pointertomembertypeentries}
2078 \textit{In \addtoindex{C++}, a
2079 pointer to a data or function member of a class or
2080 structure is a unique type.}
2082 A debugging information entry representing the type of an
2083 object that is a pointer to a structure or class member has
2084 the tag \livetarg{chap:DWTAGptrtomembertype}{DW\_TAG\_ptr\_to\_member\_type}.
2086 If the \addtoindex{pointer to member type} has a name, the
2087 \addtoindexx{pointer to member type entry}
2088 pointer to member entry has a
2089 \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2090 \addtoindexx{name attribute}
2092 null\dash terminated string containing the type name as it appears
2093 in the source program.
2095 The \addtoindex{pointer to member} entry
2097 \addtoindexx{type attribute}
2098 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to
2099 describe the type of the class or structure member to which
2100 objects of this type may point.
2102 The \addtoindexx{pointer to member} entry also
2103 \hypertarget{chap:DWATcontainingtypecontainingtypeofpointertomembertype}
2105 \livelink{chap:DWATcontainingtype}{DW\_AT\_containing\_type}
2106 attribute, whose value is a \livelink{chap:classreference}{reference} to a debugging
2107 information entry for the class or structure to whose members
2108 objects of this type may point.
2110 The \addtoindex{pointer to member entry}
2111 \hypertarget{chap:DWATuselocationmemberlocationforpointertomembertype}
2113 \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} attribute
2114 \addtoindexx{use location attribute}
2116 \addtoindex{location description} that computes the
2117 address of the member of the class to which the pointer to
2118 member entry points.
2120 \textit{The method used to find the address of a given member of a
2121 class or structure is common to any instance of that class
2122 or structure and to any instance of the pointer or member
2123 type. The method is thus associated with the type entry,
2124 rather than with each instance of the type.}
2126 The \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description is used in conjunction
2127 with the location descriptions for a particular object of the
2128 given \addtoindex{pointer to member type} and for a particular structure or
2129 class instance. The \livelink{chap:DWATuselocation}{DW\_AT\_use\_location}
2130 attribute expects two values to be
2131 \addtoindexi{pushed}{address!implicit push for member operator}
2132 onto the DWARF expression stack before
2133 the \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description is evaluated.
2135 \addtoindexi{pushed}{address!implicit push for member operator}
2136 is the value of the \addtoindex{pointer to member} object
2137 itself. The second value
2138 \addtoindexi{pushed}{address!implicit push for member operator}
2139 is the base address of the
2140 entire structure or union instance containing the member
2141 whose address is being calculated.
2144 \textit{For an expression such as}
2146 \begin{lstlisting}[numbers=none]
2149 \textit{where \texttt{mbr\_ptr} has some \addtoindex{pointer to member type}, a debugger should:}
2151 \item \textit{Push the value of \texttt{mbr\_ptr} onto the DWARF expression stack.}
2152 \item \textit{Push the base address of \texttt{object} onto the DWARF expression stack.}
2153 \item \textit{Evaluate the \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description
2154 given in the type of \texttt{mbr\_ptr}.}
2158 \section{File Type Entries}
2159 \label{chap:filetypeentries}
2161 \textit{Some languages, such as \addtoindex{Pascal},
2162 provide a data type to represent
2165 A file type is represented by a debugging information entry
2167 \addtoindexx{file type entry}
2169 \livetarg{chap:DWTAGfiletype}{DW\_TAG\_file\_type}.
2170 If the file type has a name,
2171 the file type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2172 \addtoindexx{name attribute}
2174 is a null\dash terminated string containing the type name as it
2175 appears in the source program.
2177 The file type entry has
2178 \addtoindexx{type attribute}
2179 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute describing
2180 the type of the objects contained in the file.
2182 The file type entry also
2183 \addtoindexx{byte size}
2185 \addtoindexx{bit size}
2187 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or
2188 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute, whose value
2189 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
2190 is the amount of storage need to hold a value of the file type.
2192 \section{Dynamic Type Properties}
2193 \label{chap:dynamictypeproperties}
2194 \subsection{Data Location}
2195 \label{chap:datalocation}
2197 \textit{Some languages may represent objects using descriptors to hold
2198 information, including a location and/or run\dash time parameters,
2199 about the data that represents the value for that object.}
2201 \hypertarget{chap:DWATdatalocationindirectiontoactualdata}
2202 The \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
2203 attribute may be used with any
2204 \addtoindexx{data location attribute}
2205 type that provides one or more levels of
2206 \addtoindexx{hidden indirection|see{data location attribute}}
2208 and/or run\dash time parameters in its representation. Its value
2209 is a \addtoindex{location description}.
2210 The result of evaluating this
2211 description yields the location of the data for an object.
2212 When this attribute is omitted, the address of the data is
2213 the same as the address of the object.
2216 \textit{This location description will typically begin with
2217 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
2218 which loads the address of the
2219 object which can then serve as a descriptor in subsequent
2220 calculation. For an example using
2221 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
2222 for a \addtoindex{Fortran 90 array}, see
2223 Appendix \refersec{app:fortran90example}.}
2225 \subsection{Allocation and Association Status}
2226 \label{chap:allocationandassociationstatus}
2228 \textit{Some languages, such as \addtoindex{Fortran 90},
2229 provide types whose values
2230 may be dynamically allocated or associated with a variable
2231 under explicit program control.}
2233 \hypertarget{chap:DWATallocatedallocationstatusoftypes}
2235 \livelink{chap:DWATallocated}{DW\_AT\_allocated}
2237 \addtoindexx{allocated attribute}
2238 may optionally be used with any
2239 type for which objects of the type can be explicitly allocated
2240 and deallocated. The presence of the attribute indicates that
2241 objects of the type are allocatable and deallocatable. The
2242 integer value of the attribute (see below) specifies whether
2243 an object of the type is
2244 currently allocated or not.
2246 \hypertarget{chap:DWATassociatedassociationstatusoftypes}
2248 \livelink{chap:DWATassociated}{DW\_AT\_associated} attribute
2250 \addtoindexx{associated attribute}
2251 optionally be used with
2252 any type for which objects of the type can be dynamically
2253 associated with other objects. The presence of the attribute
2254 indicates that objects of the type can be associated. The
2255 integer value of the attribute (see below) indicates whether
2256 an object of the type is currently associated or not.
2258 \textit{While these attributes are defined specifically with
2259 \addtoindex{Fortran 90} ALLOCATABLE and POINTER types
2260 in mind, usage is not limited
2261 to just that language.}
2263 The value of these attributes is determined as described in
2264 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2266 A non\dash zero value is interpreted as allocated or associated,
2267 and zero is interpreted as not allocated or not associated.
2269 \textit{For \addtoindex{Fortran 90},
2270 if the \livelink{chap:DWATassociated}{DW\_AT\_associated}
2271 attribute is present,
2272 the type has the POINTER property where either the parent
2273 variable is never associated with a dynamic object or the
2274 implementation does not track whether the associated object
2275 is static or dynamic. If the \livelink{chap:DWATallocated}{DW\_AT\_allocated} attribute is
2276 present and the \livelink{chap:DWATassociated}{DW\_AT\_associated} attribute is not, the type
2277 has the ALLOCATABLE property. If both attributes are present,
2278 then the type should be assumed to have the POINTER property
2279 (and not ALLOCATABLE); the \livelink{chap:DWATallocated}{DW\_AT\_allocated} attribute may then
2280 be used to indicate that the association status of the object
2281 resulted from execution of an ALLOCATE statement rather than
2282 pointer assignment.}
2284 \textit{For examples using
2285 \livelink{chap:DWATallocated}{DW\_AT\_allocated} for \addtoindex{Ada} and
2286 \addtoindex{Fortran 90}
2288 see Appendix \refersec{app:aggregateexamples}.}
2292 \section{Template Alias Entries}
2293 \label{chap:templatealiasentries}
2295 A type named using a template alias is represented
2296 by a debugging information entry
2297 \addtoindexx{template alias entry}
2299 \livetarg{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}.
2300 The template alias entry has a
2301 \livelink{chap:DWATname}{DW\_AT\_name} attribute
2302 \addtoindexx{name attribute}
2303 whose value is a null\dash terminated string
2304 containing the name of the template alias as it appears in
2305 the source program. The template alias entry also contains
2306 \addtoindexx{type attribute}
2308 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
2309 whose value is a \livelink{chap:classreference}{reference}
2310 to the type named by the template alias.
2313 The template alias entry has the following child entries:
2314 \begin{enumerate}[1. ]
2315 \item Each formal parameterized type declaration appearing
2316 in the template alias declaration is represented
2317 by a debugging information entry with the tag
2318 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}.
2319 Each such entry may have
2320 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2321 \addtoindexx{name attribute}
2322 whose value is a null\dash terminated
2323 string containing the name of the formal type parameter as it
2324 appears in the source program. The template type parameter
2326 \addtoindexx{type attribute}
2327 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
2328 describing the actual
2329 type by which the formal is replaced for this instantiation.
2331 \item Each formal parameterized value declaration
2332 appearing in the template alias declaration is
2333 represented by a debugging information entry with the tag
2334 \livelink{chap:DWTAGtemplatevalueparameter}{DW\_TAG\_template\_value\_parameter}.
2335 Each such entry may have
2336 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2337 \addtoindexx{name attribute}
2338 whose value is a null\dash terminated
2339 string containing the name of the formal value parameter
2340 as it appears in the source program. The template value
2341 parameter entry also has
2342 \addtoindexx{type attribute}
2343 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute describing
2344 the type of the parameterized value. Finally, the template
2345 value parameter entry has a \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}
2346 attribute, whose value is the actual constant value of the value parameter for
2347 this instantiation as represented on the target architecture.