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 \addtoindex{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 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} 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. The earlier attribute
118 is defined in a manner suitable for bit field members on
119 big\dash endian architectures but which is wasteful for use on
120 little\dash endian architectures.}
122 \textit{The attribute \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} is
124 \addtoindex{DWARF Version 4}
125 for use in base types, but implementations may continue to
126 support its use for compatibility.}
129 \addtoindex{DWARF Version 3}
130 definition of these attributes is as follows.}
131 \begin{myindentpara}{1cm}
132 \textit{A base type entry has a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
133 attribute, whose value
134 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
135 is the size in bytes of the storage unit
136 used to represent an object of the given type.}
138 \textit{If the value of an object of the given type does not fully
139 occupy the storage unit described by the byte size attribute,
140 the base type entry may have a
141 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
142 \addtoindexx{bit size attribute (V3)}
144 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} attribute, both of whose values
145 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
146 are integers. The bit size attribute describes the actual
147 size in bits used to represent a value of the given type.
148 The bit offset attribute describes the offset in bits of the
149 high order bit of a value of the given type from the high
150 order bit of the storage unit used to contain that value.}
156 \addtoindexx{DWARF Version 3}
158 \addtoindexx{DWARF Version 4} and 4, note that DWARF V4
159 defines the following combinations of attributes:}
162 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}}
163 \item \textit{\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}}
164 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
165 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
166 and optionally \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}}
168 \textit{DWARF V3 defines the following combinations:}
169 \addtoindexx{DWARF Version 3}
170 % FIXME: the figure below interferes with the following
171 % bullet list, which looks horrible as a result.
173 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}}
174 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
175 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
176 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}}
180 \caption{Encoding attribute values}
181 \label{tab:encodingattributevalues}
183 \begin{tabular}{l|p{8cm}}
185 Name&Meaning\\ \hline
186 \livetarg{chap:DWATEaddress}{DW\_ATE\_address} & linear machine address (for segmented\break
188 Section \refersec{chap:segmentedaddresses}) \\
189 \livetarg{chap:DWATEboolean}{DW\_ATE\_boolean}& true or false \\
191 \livetarg{chap:DWATEcomplexfloat}{DW\_ATE\_complex\_float}& complex binary
192 floating\dash point number \\
193 \livetarg{chap:DWATEfloat}{DW\_ATE\_float} & binary floating\dash point number \\
194 \livetarg{chap:DWATEimaginaryfloat}{DW\_ATE\_imaginary\_float}& imaginary binary
195 floating\dash point number \\
196 \livetarg{chap:DWATEsigned}{DW\_ATE\_signed}& signed binary integer \\
197 \livetarg{chap:DWATEsignedchar}{DW\_ATE\_signed\_char}& signed character \\
198 \livetarg{chap:DWATEunsigned}{DW\_ATE\_unsigned} & unsigned binary integer \\
199 \livetarg{chap:DWATEunsignedchar}{DW\_ATE\_unsigned\_char} & unsigned character \\
200 \livetarg{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} & packed decimal \\
201 \livetarg{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string}& numeric string \\
202 \livetarg{chap:DWATEedited}{DW\_ATE\_edited} & edited string \\
203 \livetarg{chap:DWATEsignedfixed}{DW\_ATE\_signed\_fixed} & signed fixed\dash point scaled integer \\
204 \livetarg{chap:DWATEunsignedfixed}{DW\_ATE\_unsigned\_fixed}& unsigned fixed\dash point scaled integer \\
205 \livetarg{chap:DWATEdecimalfloat}{DW\_ATE\_decimal\_float} & decimal floating\dash point number \\
206 \livetarg{chap:DWATEUTF}{DW\_ATE\_UTF} & \addtoindex{Unicode} character \\
211 \textit{The \livelink{chap:DWATEdecimalfloat}{DW\_ATE\_decimal\_float} encoding is intended for
212 floating\dash point representations that have a power\dash of\dash ten
213 exponent, such as that specified in IEEE 754R.}
215 \textit{The \livelink{chap:DWATEUTF}{DW\_ATE\_UTF} encoding is intended for \addtoindex{Unicode}
216 string encodings (see the Universal Character Set standard,
217 ISO/IEC 10646\dash 1:1993). For example, the
218 \addtoindex{C++} type char16\_t is
219 represented by a base type entry with a name attribute whose
220 value is \doublequote{char16\_t}, an encoding attribute whose value
221 is \livelink{chap:DWATEUTF}{DW\_ATE\_UTF} and a byte size attribute whose value is 2.}
224 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal}
226 \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string}
228 represent packed and unpacked decimal string numeric data
229 types, respectively, either of which may be
231 \addtoindexx{decimal scale attribute}
233 \addtoindexx{decimal sign attribute}
235 \addtoindexx{digit count attribute}
237 \hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}
239 \hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}
240 base types are used in combination with
241 \livelink{chap:DWATdecimalsign}{DW\_AT\_decimal\_sign},
242 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and
243 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale}
246 A \livelink{chap:DWATdecimalsign}{DW\_AT\_decimal\_sign} attribute
247 \addtoindexx{decimal sign attribute}
248 is an \livelink{chap:classconstant}{integer constant} that
249 conveys the representation of the sign of the decimal type
250 (see Figure \refersec{tab:decimalsignattributevalues}).
251 Its \livelink{chap:classconstant}{integer constant} value is interpreted to
252 mean that the type has a leading overpunch, trailing overpunch,
253 leading separate or trailing separate sign representation or,
254 alternatively, no sign at all.
257 \caption{Decimal sign attribute values}
258 \label{tab:decimalsignattributevalues}
260 \begin{tabular}{l|p{9cm}}
264 \livetarg{chap:DWDSunsigned}{DW\_DS\_unsigned} & Unsigned \\
265 \livetarg{chap:DWDSleadingoverpunch}{DW\_DS\_leading\_overpunch} & Sign
266 is encoded in the most significant digit in a target\dash dependent manner \\
267 \livetarg{chap:DWDStrailingoverpunch}{DW\_DS\_trailing\_overpunch} & Sign
268 is encoded in the least significant digit in a target\dash dependent manner \\
269 \livetarg{chap:DWDSleadingseparate}{DW\_DS\_leading\_separate}
270 & Decimal type: Sign is a ``+'' or ``-'' character
271 to the left of the most significant digit. \\
272 \livetarg{chap:DWDStrailingseparate}{DW\_DS\_trailing\_separate}
273 & Decimal type: Sign is a ``+'' or ``-'' character
274 to the right of the least significant digit. \\
275 &Packed decimal type: Least significant nibble contains
276 a target\dash dependent value
277 indicating positive or negative. \\
283 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count}
285 \addtoindexx{digit count attribute}
286 is an \livelink{chap:classconstant}{integer constant}
287 value that represents the number of digits in an instance of
290 \hypertarget{chap:DWATdecimalscaledecimalscalefactor}
291 The \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale}
293 \addtoindexx{decimal scale attribute}
294 is an integer constant value
295 that represents the exponent of the base ten scale factor to
296 be applied to an instance of the type. A scale of zero puts the
297 decimal point immediately to the right of the least significant
298 digit. Positive scale moves the decimal point to the right
299 and implies that additional zero digits on the right are not
300 stored in an instance of the type. Negative scale moves the
301 decimal point to the left; if the absolute value of the scale
302 is larger than the digit count, this implies additional zero
303 digits on the left are not stored in an instance of the type.
305 The \livelink{chap:DWATEedited}{DW\_ATE\_edited}
307 \hypertarget{chap:DWATpicturestringpicturestringfornumericstringtype}
308 type is used to represent an edited
309 numeric or alphanumeric data type. It is used in combination
310 with an \livelink{chap:DWATpicturestring}{DW\_AT\_picture\_string} attribute whose value is a
311 null\dash terminated string containing the target\dash dependent picture
312 string associated with the type.
314 If the edited base type entry describes an edited numeric
315 data type, the edited type entry has a \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and a
316 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attribute.
317 \addtoindexx{decimal scale attribute}
318 These attributes have the same
319 interpretation as described for the
320 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} and
321 \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base
322 types. If the edited type entry
323 describes an edited alphanumeric data type, the edited type
324 entry does not have these attributes.
327 \textit{The presence or absence of the \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and
328 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attributes
329 \addtoindexx{decimal scale attribute}
330 allows a debugger to easily
331 distinguish edited numeric from edited alphanumeric, although
332 in principle the digit count and scale are derivable by
333 interpreting the picture string.}
335 The \livelink{chap:DWATEsignedfixed}{DW\_ATE\_signed\_fixed} and \livelink{chap:DWATEunsignedfixed}{DW\_ATE\_unsigned\_fixed} entries
336 describe signed and unsigned fixed\dash point binary data types,
339 The fixed binary type entries have
340 \addtoindexx{digit count attribute}
342 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count}
343 attribute with the same interpretation as described for the
344 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} and \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base types.
346 For a data type with a decimal scale factor, the fixed binary
348 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attribute
349 \addtoindexx{decimal scale attribute}
351 interpretation as described for the
352 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal}
353 and \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base types.
355 \hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}
356 For a data type with a binary scale factor, the fixed
357 \addtoindexx{binary scale attribute}
358 binary type entry has a
359 \livelink{chap:DWATbinaryscale}{DW\_AT\_binary\_scale} attribute.
361 \livelink{chap:DWATbinaryscale}{DW\_AT\_binary\_scale} attribute
362 is an \livelink{chap:classconstant}{integer constant} value
363 that represents the exponent of the base two scale factor to
364 be applied to an instance of the type. Zero scale puts the
365 binary point immediately to the right of the least significant
366 bit. Positive scale moves the binary point to the right and
367 implies that additional zero bits on the right are not stored
368 in an instance of the type. Negative scale moves the binary
369 point to the left; if the absolute value of the scale is
370 larger than the number of bits, this implies additional zero
371 bits on the left are not stored in an instance of the type.
374 \hypertarget{chap:DWATsmallscalefactorforfixedpointtype}
375 a data type with a non\dash decimal and non\dash binary scale factor,
376 the fixed binary type entry has a
377 \livelink{chap:DWATsmall}{DW\_AT\_small} attribute which
378 \addtoindexx{small attribute}
380 \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} entry. The scale factor value
381 is interpreted in accordance with the value defined by the
382 \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} entry. The value represented is the product
383 of the integer value in memory and the associated constant
386 \textit{The \livelink{chap:DWATsmall}{DW\_AT\_small} attribute
387 is defined with the \addtoindex{Ada} small
390 \section{Unspecified Type Entries}
391 \label{chap:unspecifiedtypeentries}
392 \addtoindexx{unspecified type entry}
393 \addtoindexx{void type|see{unspecified type entry}}
394 Some languages have constructs in which a type
395 may be left unspecified or the absence of a type
396 may be explicitly indicated.
398 An unspecified (implicit, unknown, ambiguous or nonexistent)
399 type is represented by a debugging information entry with
400 the tag \livetarg{chap:DWTAGunspecifiedtype}{DW\_TAG\_unspecified\_type}.
401 If a name has been given
402 to the type, then the corresponding unspecified type entry
403 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
404 \addtoindexx{name attribute}
406 a null\dash terminated
407 string containing the name as it appears in the source program.
409 The interpretation of this debugging information entry is
410 intentionally left flexible to allow it to be interpreted
411 appropriately in different languages. For example, in
412 \addtoindex{C} and \addtoindex{C++}
413 the language implementation can provide an unspecified type
414 entry with the name \doublequote{void} which can be referenced by the
415 type attribute of pointer types and typedef declarations for
417 % FIXME: the following reference was wrong in DW4 so DavidA guessed
419 Sections \refersec{chap:unspecifiedtypeentries} and
420 %The following reference was valid, so the following is probably correct.
421 Section \refersec{chap:typedefentries},
422 respectively). As another
423 example, in \addtoindex{Ada} such an unspecified type entry can be referred
424 to by the type attribute of an access type where the denoted
425 \addtoindexx{incomplete type (Ada)}
426 type is incomplete (the name is declared as a type but the
427 definition is deferred to a separate compilation unit).
429 \section{Type Modifier Entries}
430 \label{chap:typemodifierentries}
431 \addtoindexx{type modifier entry}
433 A base or user\dash defined type may be modified in different ways
434 in different languages. A type modifier is represented in
435 DWARF by a debugging information entry with one of the tags
436 given in Table \refersec{tab:typemodifiertags}.
437 \addtoindexx{type modifier|see{constant type entry}}
438 \addtoindexx{type modifier|see{reference type entry}}
439 \addtoindexx{type modifier|see{restricted type entry}}
440 \addtoindexx{type modifier|see{packed type entry}}
441 \addtoindexx{type modifier|see{pointer type entry}}
442 \addtoindexx{type modifier|see{shared type entry}}
443 \addtoindexx{type modifier|see{volatile type entry}}
445 If a name has been given to the modified type in the source
446 program, then the corresponding modified type entry has
447 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
448 \addtoindexx{name attribute}
449 whose value is a null\dash terminated
450 string containing the modified type name as it appears in
453 Each of the type modifier entries has
454 \addtoindexx{type attribute}
456 \livelink{chap:DWATtype}{DW\_AT\_type} attribute,
457 whose value is a \livelink{chap:classreference}{reference}
458 to a debugging information entry
459 describing a base type, a user-defined type or another type
462 A modified type entry describing a
463 \addtoindexx{pointer type entry}
464 pointer or \addtoindex{reference type}
465 (using \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type},
466 \livelink{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type} or
467 \livelink{chap:DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type})
468 % Another instance of no-good-place-to-put-index entry.
470 \addtoindexx{address class!attribute}
472 \hypertarget{chap:DWATadressclasspointerorreferencetypes}
474 \livelink{chap:DWATaddressclass}{DW\_AT\_address\_class}
475 attribute to describe how objects having the given pointer
476 or reference type ought to be dereferenced.
478 A modified type entry describing a shared qualified type
479 (using \livelink{chap:DWTAGsharedtype}{DW\_TAG\_shared\_type}) may have a
480 \livelink{chap:DWATcount}{DW\_AT\_count} attribute
481 \addtoindexx{count attribute}
482 whose value is a constant expressing the (explicit or implied) blocksize specified for the
483 type in the source. If no count attribute is present, then the \doublequote{infinite}
484 blocksize is assumed.
486 When multiple type modifiers are chained together to modify
487 a base or user-defined type, the tree ordering reflects the
489 \addtoindexx{reference type entry, lvalue|see{reference type entry}}
491 \addtoindexx{reference type entry, rvalue|see{rvalue reference type entry}}
493 \addtoindexx{parameter|see{macro formal parameter list}}
495 \addtoindexx{parameter|see{\textit{this} parameter}}
497 \addtoindexx{parameter|see{variable parameter attribute}}
499 \addtoindexx{parameter|see{optional parameter attribute}}
501 \addtoindexx{parameter|see{unspecified parameters entry}}
503 \addtoindexx{parameter|see{template value parameter entry}}
505 \addtoindexx{parameter|see{template type parameter entry}}
507 \addtoindexx{parameter|see{formal parameter entry}}
511 \caption{Type modifier tags}
512 \label{tab:typemodifiertags}
514 \begin{tabular}{l|p{9cm}}
516 Name&Meaning\\ \hline
517 \livetarg{chap:DWTAGconsttype}{DW\_TAG\_const\_type} & C or C++ const qualified type
518 \addtoindexx{const qualified type entry} \addtoindexx{C} \addtoindexx{C++} \\
519 \livetarg{chap:DWTAGpackedtype}{DW\_TAG\_packed\_type}& \addtoindex{Pascal} or Ada packed type\addtoindexx{packed type entry}
520 \addtoindexx{packed qualified type entry} \addtoindexx{Ada} \addtoindexx{Pascal} \\
521 \livetarg{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} & Pointer to an object of
522 the type being modified \addtoindexx{pointer qualified type entry} \\
523 \livetarg{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type}& C++ (lvalue) reference
524 to an object of the type
525 \addtoindexx{reference type entry}
527 \addtoindexx{reference qualified type entry} \\
528 \livetarg{chap:DWTAGrestricttype}{DW\_TAG\_restrict\_type}& \addtoindex{C}
530 \addtoindexx{restricted type entry}
532 \addtoindexx{restrict qualified type} \\
533 \livetarg{chap:DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type} & C++
534 \addtoindexx{rvalue reference type entry}
536 \addtoindexx{restricted type entry}
537 reference to an object of the type being modified
538 \addtoindexx{rvalue reference qualified type entry} \\
539 \livetarg{chap:DWTAGsharedtype}{DW\_TAG\_shared\_type}&\addtoindex{UPC} shared qualified type
540 \addtoindexx{shared qualified type entry} \\
541 \livetarg{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type}&C or C++ volatile qualified type
542 \addtoindex{volatile qualified type entry} \\
547 %The following clearpage prevents splitting the example across pages.
548 \textit{As examples of how type modifiers are ordered, consider the following
549 \addtoindex{C} declarations:}
550 \begin{lstlisting}[numbers=none]
551 const unsigned char * volatile p;
553 \textit{which represents a volatile pointer to a constant
554 character. This is encoded in DWARF as:}
558 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}(p) -->
559 \livelink{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type} -->
560 \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} -->
561 \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type} -->
562 \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}(unsigned char)
567 \textit{On the other hand}
568 \begin{lstlisting}[numbers=none]
569 volatile unsigned char * const restrict p;
571 \textit{represents a restricted constant
572 pointer to a volatile character. This is encoded as:}
576 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}(p) -->
577 \livelink{chap:DWTAGrestricttype}{DW\_TAG\_restrict\_type} -->
578 \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type} -->
579 \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} -->
580 \livelink{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type} -->
581 \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}(unsigned char)
585 \section{Typedef Entries}
586 \label{chap:typedefentries}
587 A named type that is defined in terms of another type
588 definition is represented by a debugging information entry with
589 \addtoindexx{typedef entry}
590 the tag \livetarg{chap:DWTAGtypedef}{DW\_TAG\_typedef}.
591 The typedef entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
592 \addtoindexx{name attribute}
593 whose value is a null\dash terminated string containing
594 the name of the typedef as it appears in the source program.
596 The typedef entry may also contain
597 \addtoindexx{type attribute}
599 \livelink{chap:DWATtype}{DW\_AT\_type} attribute whose
600 value is a \livelink{chap:classreference}{reference}
601 to the type named by the typedef. If
602 the debugging information entry for a typedef represents
603 a declaration of the type that is not also a definition,
604 it does not contain a type attribute.
606 \textit{Depending on the language, a named type that is defined in
607 terms of another type may be called a type alias, a subtype,
608 a constrained type and other terms. A type name declared with
609 no defining details may be termed an
610 \addtoindexx{incomplete type}
611 incomplete, forward or hidden type.
612 While the DWARF \livelink{chap:DWTAGtypedef}{DW\_TAG\_typedef} entry was
613 originally inspired by the like named construct in
614 \addtoindex{C} and \addtoindex{C++},
615 it is broadly suitable for similar constructs (by whatever
616 source syntax) in other languages.}
618 \section{Array Type Entries}
619 \label{chap:arraytypeentries}
621 \textit{Many languages share the concept of an ``array,'' which is
622 \addtoindexx{array type entry}
623 a table of components of identical type.}
625 An array type is represented by a debugging information entry
626 with the tag \livetarg{chap:DWTAGarraytype}{DW\_TAG\_array\_type}.
627 If a name has been given to
628 \addtoindexx{array!declaration of type}
629 the array type in the source program, then the corresponding
630 array type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
631 \addtoindexx{name attribute}
633 null\dash terminated string containing the array type name as it
634 appears in the source program.
637 \hypertarget{chap:DWATorderingarrayrowcolumnordering}
638 array type entry describing a multidimensional array may
639 \addtoindexx{array!element ordering}
640 have a \livelink{chap:DWATordering}{DW\_AT\_ordering} attribute whose
641 \livelink{chap:classconstant}{integer constant} value is
642 interpreted to mean either row-major or column-major ordering
643 of array elements. The set of values and their meanings
644 for the ordering attribute are listed in
645 Table \refersec{tab:arrayordering}.
647 ordering attribute is present, the default ordering for the
648 source language (which is indicated by the
649 \livelink{chap:DWATlanguage}{DW\_AT\_language}
651 \addtoindexx{language attribute}
652 of the enclosing compilation unit entry) is assumed.
654 \begin{simplenametable}[1.6in]{Array ordering}{tab:arrayordering}
655 \livetarg{chap:DWORDcolmajor}{DW\_ORD\_col\_major} \\
656 \livetarg{chap:DWORDrowmajor}{DW\_ORD\_row\_major} \\
657 \end{simplenametable}
659 The ordering attribute may optionally appear on one-dimensional
660 arrays; it will be ignored.
662 An array type entry has
663 \addtoindexx{type attribute}
664 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
666 \addtoindexx{array!element type}
667 the type of each element of the array.
669 If the amount of storage allocated to hold each element of an
670 object of the given array type is different from the amount
671 \addtoindexx{stride attribute|see{bit stride attribute or byte stride attribute}}
672 of storage that is normally allocated to hold an individual
673 \hypertarget{chap:DWATbitstridearrayelementstrideofarraytype}
675 \hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}
676 indicated element type, then the array type
677 \addtoindexx{bit stride attribute}
679 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
681 \addtoindexx{byte stride attribute}
682 a \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride}
684 \addtoindexx{bit stride attribute}
686 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
688 element of the array.
690 The array type entry may have either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or a
691 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
692 (see Section \refersec{chap:byteandbitsizes}),
694 amount of storage needed to hold an instance of the array type.
696 \textit{If the size of the array can be determined statically at
697 compile time, this value can usually be computed by multiplying
698 the number of array elements by the size of each element.}
701 Each array dimension is described by a debugging information
702 entry with either the
703 \addtoindexx{subrange type entry!as array dimension}
704 tag \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type} or the
705 \addtoindexx{enumeration type entry!as array dimension}
707 \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}. These entries are
709 array type entry and are ordered to reflect the appearance of
710 the dimensions in the source program (i.e., leftmost dimension
711 first, next to leftmost second, and so on).
713 \textit{In languages, such as C, in which there is no concept of
714 a \doublequote{multidimensional array}, an array of arrays may
715 be represented by a debugging information entry for a
716 multidimensional array.}
719 Other attributes especially applicable to arrays are
720 \livelink{chap:DWATallocated}{DW\_AT\_allocated},
721 \livelink{chap:DWATassociated}{DW\_AT\_associated} and
722 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location},
723 which are described in
724 Section \refersec{chap:dynamictypeproperties}.
725 For relevant examples, see also Appendix \refersec{app:fortran90example}.
727 \section{ Structure, Union, Class and Interface Type Entries}
728 \label{chap:structureunionclassandinterfacetypeentries}
730 \textit{The languages
732 \addtoindex{C++}, and
733 \addtoindex{Pascal}, among others, allow the
734 programmer to define types that are collections of related
735 \addtoindexx{structure type entry}
737 In \addtoindex{C} and \addtoindex{C++}, these collections are called
738 \doublequote{structures.}
739 In \addtoindex{Pascal}, they are called \doublequote{records.}
740 The components may be of different types. The components are
741 called \doublequote{members} in \addtoindex{C} and
742 \addtoindex{C++}, and \doublequote{fields} in \addtoindex{Pascal}.}
744 \textit{The components of these collections each exist in their
745 own space in computer memory. The components of a C or C++
746 \doublequote{union} all coexist in the same memory.}
748 \textit{\addtoindex{Pascal} and
749 other languages have a \doublequote{discriminated union,}
750 \addtoindex{discriminated union|see {variant entry}}
751 also called a \doublequote{variant record.} Here, selection of a
752 number of alternative substructures (\doublequote{variants}) is based
753 on the value of a component that is not part of any of those
754 substructures (the \doublequote{discriminant}).}
756 \textit{\addtoindex{C++} and
757 \addtoindex{Java} have the notion of ``class'', which is in some
758 ways similar to a structure. A class may have \doublequote{member
759 functions} which are subroutines that are within the scope
760 of a class or structure.}
762 \textit{The \addtoindex{C++} notion of
763 structure is more general than in \addtoindex{C}, being
764 equivalent to a class with minor differences. Accordingly,
765 in the following discussion statements about
766 \addtoindex{C++} classes may
767 be understood to apply to \addtoindex{C++} structures as well.}
769 \subsection{Structure, Union and Class Type Entries}
770 \label{chap:structureunionandclasstypeentries}
773 Structure, union, and class types are represented by debugging
774 \addtoindexx{structure type entry}
776 \addtoindexx{union type entry}
778 \addtoindexx{class type entry}
780 \livetarg{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type},
781 \livetarg{chap:DWTAGuniontype}{DW\_TAG\_union\_type},
782 and \livetarg{chap:DWTAGclasstype}{DW\_TAG\_class\_type},
783 respectively. If a name has been given to the structure,
784 union, or class in the source program, then the corresponding
785 structure type, union type, or class type entry has a
786 \livelink{chap:DWATname}{DW\_AT\_name} attribute
787 \addtoindexx{name attribute}
788 whose value is a null\dash terminated string
789 containing the type name as it appears in the source program.
791 The members of a structure, union, or class are represented
792 by debugging information entries that are owned by the
793 corresponding structure type, union type, or class type entry
794 and appear in the same order as the corresponding declarations
795 in the source program.
797 A structure type, union type or class type entry may have
798 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or a
799 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
800 \hypertarget{chap:DWATbitsizedatamemberbitsize}
801 (see Section \refersec{chap:byteandbitsizes}),
802 whose value is the amount of storage needed
803 to hold an instance of the structure, union or class type,
804 including any padding.
806 An incomplete structure, union or class type
807 \addtoindexx{incomplete structure/union/class}
809 \addtoindexx{incomplete type}
810 represented by a structure, union or class
811 entry that does not have a byte size attribute and that has
812 \addtoindexx{declaration attribute}
813 a \livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute.
815 If the complete declaration of a type has been placed in
816 \hypertarget{chap:DWATsignaturetypesignature}
817 a separate \addtoindex{type unit}
818 (see Section \refersec{chap:separatetypeunitentries}),
819 an incomplete declaration
820 \addtoindexx{incomplete type}
821 of that type in the compilation unit may provide
822 the unique 64\dash bit signature of the type using
823 \addtoindexx{type signature}
824 a \livelink{chap:DWATsignature}{DW\_AT\_signature}
827 If a structure, union or class entry represents the definition
828 of a structure, class or union member corresponding to a prior
829 incomplete structure, class or union, the entry may have a
830 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
831 \addtoindexx{specification attribute}
832 whose value is a \livelink{chap:classreference}{reference} to
833 the debugging information entry representing that incomplete
836 Structure, union and class entries containing the
837 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
838 \addtoindexx{specification attribute}
839 do not need to duplicate
840 information provided by the declaration entry referenced by the
841 specification attribute. In particular, such entries do not
842 need to contain an attribute for the name of the structure,
843 class or union they represent if such information is already
844 provided in the declaration.
846 \textit{For \addtoindex{C} and \addtoindex{C++},
848 \addtoindexx{data member|see {member entry (data)}}
849 member declarations occurring within
850 the declaration of a structure, union or class type are
851 considered to be \doublequote{definitions} of those members, with
852 the exception of \doublequote{static} data members, whose definitions
853 appear outside of the declaration of the enclosing structure,
854 union or class type. Function member declarations appearing
855 within a structure, union or class type declaration are
856 definitions only if the body of the function also appears
857 within the type declaration.}
859 If the definition for a given member of the structure, union
860 or class does not appear within the body of the declaration,
861 that member also has a debugging information entry describing
862 its definition. That latter entry has a
863 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
864 \addtoindexx{specification attribute}
865 referencing the debugging information entry
866 owned by the body of the structure, union or class entry and
867 representing a non\dash defining declaration of the data, function
868 or type member. The referenced entry will not have information
869 about the location of that member (low and high pc attributes
870 for function members, location descriptions for data members)
871 and will have a \livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute.
874 \textit{Consider a nested class whose
875 definition occurs outside of the containing class definition, as in:}
877 \begin{lstlisting}[numbers=none]
884 \textit{The two different structs can be described in
885 different compilation units to
886 facilitate DWARF space compression
887 (see Appendix \refersec{app:usingcompilationunits}).}
889 \subsection{Interface Type Entries}
890 \label{chap:interfacetypeentries}
892 \textit{The \addtoindex{Java} language defines ``interface'' types.
894 \addtoindex{interface type entry}
895 in \addtoindex{Java} is similar to a \addtoindex{C++} or
896 \addtoindex{Java} class with only abstract
897 methods and constant data members.}
900 \addtoindexx{interface type entry}
901 are represented by debugging information
903 tag \livetarg{chap:DWTAGinterfacetype}{DW\_TAG\_interface\_type}.
905 An interface type entry has
906 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
907 \addtoindexx{name attribute}
909 value is a null\dash terminated string containing the type name
910 as it appears in the source program.
912 The members of an interface are represented by debugging
913 information entries that are owned by the interface type
914 entry and that appear in the same order as the corresponding
915 declarations in the source program.
917 \subsection{Derived or Extended Structs, Classes and Interfaces}
918 \label{chap:derivedorextendedstructsclasesandinterfaces}
920 \textit{In \addtoindex{C++}, a class (or struct)
922 \addtoindexx{derived type (C++)|see{inheritance entry}}
923 be ``derived from'' or be a
924 ``subclass of'' another class.
925 In \addtoindex{Java}, an interface may ``extend''
926 \addtoindexx{extended type (Java)|see{inheritance entry}}
928 \addtoindexx{implementing type (Java)|see{inheritance entry}}
929 or more other interfaces, and a class may ``extend'' another
930 class and/or ``implement'' one or more interfaces. All of these
931 relationships may be described using the following. Note that
932 in \addtoindex{Java},
933 the distinction between extends and implements is
934 implied by the entities at the two ends of the relationship.}
936 A class type or interface type entry that describes a
937 derived, extended or implementing class or interface owns
938 \addtoindexx{implementing type (Java)|see{inheritance entry}}
939 debugging information entries describing each of the classes
940 or interfaces it is derived from, extending or implementing,
941 respectively, ordered as they were in the source program. Each
943 \addtoindexx{inheritance entry}
945 tag \livetarg{chap:DWTAGinheritance}{DW\_TAG\_inheritance}.
948 \addtoindexx{type attribute}
950 \addtoindexx{inheritance entry}
952 \livelink{chap:DWATtype}{DW\_AT\_type} attribute whose value is
953 a reference to the debugging information entry describing the
954 class or interface from which the parent class or structure
955 of the inheritance entry is derived, extended or implementing.
958 \addtoindexx{inheritance entry}
959 for a class that derives from or extends
960 \hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}
961 another class or struct also has
962 \addtoindexx{data member location attribute}
964 \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
965 attribute, whose value describes the location of the beginning
966 of the inherited type relative to the beginning address of the
967 derived class. If that value is a constant, it is the offset
968 in bytes from the beginning of the class to the beginning of
969 the inherited type. Otherwise, the value must be a location
970 description. In this latter case, the beginning address of
971 the derived class is pushed on the expression stack before
972 the \addtoindex{location description}
973 is evaluated and the result of the
974 evaluation is the location of the inherited type.
976 \textit{The interpretation of the value of this attribute for
977 inherited types is the same as the interpretation for data
979 (see Section \referfol{chap:datamemberentries}). }
982 \addtoindexx{inheritance entry}
984 \hypertarget{chap:DWATaccessibilitycppinheritedmembers}
986 \addtoindexx{accessibility attribute}
988 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
990 If no accessibility attribute
991 is present, private access is assumed for an entry of a class
992 and public access is assumed for an entry of an interface,
996 \hypertarget{chap:DWATvirtualityvirtualityofbaseclass}
997 the class referenced by the
998 \addtoindexx{inheritance entry}
999 inheritance entry serves
1000 as a \addtoindex{C++} virtual base class, the inheritance entry has a
1001 \livelink{chap:DWATvirtuality}{DW\_AT\_virtuality} attribute.
1003 \textit{For a \addtoindex{C++} virtual base, the
1004 \addtoindex{data member location attribute}
1005 will usually consist of a non-trivial
1006 \addtoindex{location description}.}
1008 \subsection{Access Declarations}
1009 \label{chap:accessdeclarations}
1011 \textit{In \addtoindex{C++}, a derived class may contain access declarations that
1012 \addtoindexx{access declaration entry}
1013 change the accessibility of individual class members from the
1014 overall accessibility specified by the inheritance declaration.
1015 A single access declaration may refer to a set of overloaded
1018 If a derived class or structure contains access declarations,
1019 each such declaration may be represented by a debugging
1020 information entry with the tag
1021 \livetarg{chap:DWTAGaccessdeclaration}{DW\_TAG\_access\_declaration}.
1023 such entry is a child of the class or structure type entry.
1025 An access declaration entry has
1026 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1027 \addtoindexx{name attribute}
1029 value is a null\dash terminated string representing the name used
1030 in the declaration in the source program, including any class
1031 or structure qualifiers.
1033 An access declaration entry
1034 \hypertarget{chap:DWATaccessibilitycppbaseclasses}
1037 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1038 attribute describing the declared accessibility of the named
1043 \subsection{Friends}
1044 \label{chap:friends}
1047 \addtoindexx{friend entry}
1048 declared by a structure, union or class
1049 \hypertarget{chap:DWATfriendfriendrelationship}
1050 type may be represented by a debugging information entry
1051 that is a child of the structure, union or class type entry;
1052 the friend entry has the
1053 tag \livetarg{chap:DWTAGfriend}{DW\_TAG\_friend}.
1056 \addtoindexx{friend attribute}
1057 a \livelink{chap:DWATfriend}{DW\_AT\_friend} attribute, whose value is
1058 a reference to the debugging information entry describing
1059 the declaration of the friend.
1062 \subsection{Data Member Entries}
1063 \label{chap:datamemberentries}
1065 A data member (as opposed to a member function) is
1066 represented by a debugging information entry with the
1067 tag \livetarg{chap:DWTAGmember}{DW\_TAG\_member}.
1069 \addtoindexx{member entry (data)}
1070 member entry for a named member has
1071 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1072 \addtoindexx{name attribute}
1073 whose value is a null\dash terminated
1074 string containing the member name as it appears in the source
1075 program. If the member entry describes an
1076 \addtoindex{anonymous union},
1077 the name attribute is omitted or the value of the attribute
1078 consists of a single zero byte.
1080 The data member entry has
1081 \addtoindexx{type attribute}
1083 \livelink{chap:DWATtype}{DW\_AT\_type} attribute to denote
1084 \addtoindexx{member entry (data)}
1085 the type of that member.
1087 A data member entry may
1088 \addtoindexx{accessibility attribute}
1090 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1091 attribute. If no accessibility attribute is present, private
1092 access is assumed for an entry of a class and public access
1093 is assumed for an entry of a structure, union, or interface.
1096 \hypertarget{chap:DWATmutablemutablepropertyofmemberdata}
1098 \addtoindexx{member entry (data)}
1100 \addtoindexx{mutable attribute}
1101 have a \livelink{chap:DWATmutable}{DW\_AT\_mutable} attribute,
1102 which is a \livelink{chap:classflag}{flag}.
1103 This attribute indicates whether the data
1104 member was declared with the mutable storage class specifier.
1106 The beginning of a data member
1107 \addtoindexx{beginning of a data member}
1108 is described relative to
1109 \addtoindexx{beginning of an object}
1110 the beginning of the object in which it is immediately
1111 contained. In general, the beginning is characterized by
1112 both an address and a bit offset within the byte at that
1113 address. When the storage for an entity includes all of
1114 the bits in the beginning byte, the beginning bit offset is
1117 Bit offsets in DWARF use the bit numbering and direction
1118 conventions that are appropriate to the current language on
1122 \addtoindexx{member entry (data)}
1123 corresponding to a data member that is
1124 \hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}
1126 \hypertarget{chap:DWATdatamemberlocationdatamemberlocation}
1127 in a structure, union or class may have either
1128 \addtoindexx{data member location attribute}
1130 \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} attribute or a
1131 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1132 attribute. If the beginning of the data member is the same as
1133 the beginning of the containing entity then neither attribute
1137 For a \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} attribute
1138 \addtoindexx{data member location attribute}
1139 there are two cases:
1140 \begin{enumerate}[1. ]
1141 \item If the value is an \livelink{chap:classconstant}{integer constant},
1143 in bytes from the beginning of the containing entity. If
1144 the beginning of the containing entity has a non-zero bit
1145 offset then the beginning of the member entry has that same
1148 \item Otherwise, the value must be a \addtoindex{location description}.
1150 this case, the beginning of the containing entity must be byte
1151 aligned. The beginning address is pushed on the DWARF stack
1152 before the \addtoindex{location} description is evaluated; the result of
1153 the evaluation is the base address of the member entry.
1155 \textit{The push on the DWARF expression stack of the base address of
1156 the containing construct is equivalent to execution of the
1157 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address} operation
1158 (see Section \refersec{chap:stackoperations});
1159 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address} therefore
1160 is not needed at the
1161 beginning of a \addtoindex{location description} for a data member.
1163 result of the evaluation is a location--either an address or
1164 the name of a register, not an offset to the member.}
1166 \textit{A \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
1168 \addtoindexx{data member location attribute}
1169 that has the form of a
1170 \addtoindex{location description} is not valid for a data member contained
1171 in an entity that is not byte aligned because DWARF operations
1172 do not allow for manipulating or computing bit offsets.}
1176 For a \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} attribute,
1177 the value is an \livelink{chap:classconstant}{integer constant}
1178 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1179 that specifies the number of bits
1180 from the beginning of the containing entity to the beginning
1181 of the data member. This value must be greater than or equal
1182 to zero, but is not limited to less than the number of bits
1185 If the size of a data member is not the same as the size
1186 of the type given for the data member, the data member has
1187 \addtoindexx{bit size attribute}
1188 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1189 or a \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute whose
1190 \livelink{chap:classconstant}{integer constant} value
1191 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1193 of storage needed to hold the value of the data member.
1195 \textit{Bit fields in \addtoindex{C} and \addtoindex{C++}
1197 \addtoindexx{bit fields}
1199 \addtoindexx{data bit offset}
1201 \addtoindexx{data bit size}
1203 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} and
1204 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attributes.}
1207 \textit{This Standard uses the following bit numbering and direction
1208 conventions in examples. These conventions are for illustrative
1209 purposes and other conventions may apply on particular
1212 \item \textit{For big\dash endian architectures, bit offsets are
1213 counted from high-order to low\dash order bits within a byte (or
1214 larger storage unit); in this case, the bit offset identifies
1215 the high\dash order bit of the object.}
1217 \item \textit{For little\dash endian architectures, bit offsets are
1218 counted from low\dash order to high\dash order bits within a byte (or
1219 larger storage unit); in this case, the bit offset identifies
1220 the low\dash order bit of the object.}
1224 \textit{In either case, the bit so identified is defined as the
1225 \addtoindexx{beginning of an object}
1226 beginning of the object.}
1228 \textit{For example, take one possible representation of the following
1229 \addtoindex{C} structure definition
1230 in both big\dash and little\dash endian byte orders:}
1241 \textit{Figures \referfol{fig:bigendiandatabitoffsets} and
1242 \refersec{fig:littleendiandatabitoffsets}
1243 show the structure layout
1244 and data bit offsets for example big\dash\ and little\dash endian
1245 architectures, respectively. Both diagrams show a structure
1246 that begins at address A and whose size is four bytes. Also,
1247 high order bits are to the left and low order bits are to
1257 Addresses increase ->
1258 | A | A + 1 | A + 2 | A + 3 |
1260 Data bit offsets increase ->
1261 +---------------+---------------+---------------+---------------+
1262 |0 4|5 10|11 15|16 23|24 31|
1263 | j | k | m | n | <pad> |
1265 +---------------------------------------------------------------+
1267 \caption{Big-endian data bit offsets}
1268 \label{fig:bigendiandatabitoffsets}
1277 <- Addresses increase
1278 | A | A + 1 | A + 2 | A + 3 |
1280 <- Data bit offsets increase
1281 +---------------+---------------+---------------+---------------+
1282 |31 24|23 16|15 11|10 5|4 0|
1283 | <pad> | n | m | k | j |
1285 +---------------------------------------------------------------+
1287 \caption{Little-endian data bit offsets}
1288 \label{fig:littleendiandatabitoffsets}
1291 \textit{Note that data member bit offsets in this example are the
1292 same for both big\dash\ and little\dash endian architectures even
1293 though the fields are allocated in different directions
1294 (high\dash order to low-order versus low\dash order to high\dash order);
1295 the bit naming conventions for memory and/or registers of
1296 the target architecture may or may not make this seem natural.}
1298 \textit{For a more extensive example showing nested and packed records
1300 Appendix \refersec{app:pascalexample}.}
1302 \textit{Attribute \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1304 \addtoindex{DWARF Version 4}
1305 and is also used for base types
1307 \refersec{chap:basetypeentries}).
1309 \livetarg{chap:DWATbitoffsetdatamemberbitlocation}{}
1310 attributes \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} and
1311 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} when used to
1312 identify the beginning of bit field data members as defined
1313 in DWARF V3 and earlier. The earlier attributes are defined
1314 in a manner suitable for bit field members on big-endian
1315 architectures but which is either awkward or incomplete for
1316 use on little-endian architectures.
1317 (\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} also
1318 has other uses that are not affected by this change.)}
1320 \textit{The \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
1321 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
1322 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
1323 attribute combination is deprecated for data members in DWARF
1324 Version 4, but implementations may continue to support this
1325 use for compatibility.}
1328 \addtoindex{DWARF Version 3}
1329 definitions of these attributes are
1331 \begin{myindentpara}{1cm}
1332 \textit{If the data member entry describes a bit field, then that
1333 entry has the following attributes:}
1336 \item \textit{A \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1337 attribute whose value
1338 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1339 is the number of bytes that contain an instance of the
1340 bit field and any padding bits.}
1342 \textit{The byte size attribute may be omitted if the size of the
1343 object containing the bit field can be inferred from the type
1344 attribute of the data member containing the bit field.}
1346 \item \textit{A \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
1348 \addtoindexx{bit offset attribute (V3)}
1350 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1351 is the number of bits to the left of the leftmost
1352 (most significant) bit of the bit field value.}
1354 \item \textit{A \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
1356 \addtoindexx{bit size attribute (V3)}
1358 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1359 is the number of bits occupied by the bit field value.}
1364 \addtoindex{location description} for a bit field calculates the address
1365 of an anonymous object containing the bit field. The address
1366 is relative to the structure, union, or class that most closely
1367 encloses the bit field declaration. The number of bytes in this
1368 anonymous object is the value of the byte size attribute of
1369 the bit field. The offset (in bits) from the most significant
1370 bit of the anonymous object to the most significant bit of
1371 the bit field is the value of the bit offset attribute.}
1375 \textit{Diagrams similar to the above that show the use of the
1376 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
1377 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
1378 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} attribute
1379 combination may be found in the
1380 \addtoindex{DWARF Version 3} Standard.}
1382 \textit{In comparing
1384 \addtoindexx{DWARF Version 3}
1386 \addtoindexx{DWARF Version 4}
1387 4, note that DWARF V4
1388 defines the following combinations of attributes:}
1391 \item \textit{either \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
1393 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1394 (to specify the beginning of the data member)}
1396 % FIXME: the indentation of the following line is suspect.
1397 \textit{optionally together with}
1399 \item \textit{either \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or
1400 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} (to
1401 specify the size of the data member)}
1405 \textit{DWARF V3 defines the following combinations}
1408 \item \textit{\livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
1409 (to specify the beginning
1410 of the data member, except this specification is only partial
1411 in the case of a bit field) }
1413 % FIXME: the indentation of the following line is suspect.
1414 \textit{optionally together with}
1416 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
1417 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
1418 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
1419 (to further specify the beginning of a bit field data member
1420 as well as specify the size of the data member) }
1423 \subsection{Member Function Entries}
1424 \label{chap:memberfunctionentries}
1426 A member function is represented by a
1427 \addtoindexx{member function entry}
1428 debugging information entry
1430 \addtoindexx{subprogram entry!as member function}
1431 tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}.
1432 The member function entry
1433 may contain the same attributes and follows the same rules
1434 as non\dash member global subroutine entries
1435 (see Section \refersec{chap:subroutineandentrypointentries}).
1438 \addtoindexx{accessibility attribute}
1439 member function entry may have a
1440 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1441 attribute. If no accessibility attribute is present, private
1442 access is assumed for an entry of a class and public access
1443 is assumed for an entry of a structure, union or interface.
1446 \hypertarget{chap:DWATvirtualityvirtualityoffunction}
1447 the member function entry describes a virtual function,
1448 then that entry has a
1449 \livelink{chap:DWATvirtuality}{DW\_AT\_virtuality} attribute.
1452 \hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}
1453 the member function entry describes an explicit member
1454 function, then that entry has
1455 \addtoindexx{explicit attribute}
1457 \livelink{chap:DWATexplicit}{DW\_AT\_explicit} attribute.
1460 \hypertarget{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}
1461 entry for a virtual function also has a
1462 \livelink{chap:DWATvtableelemlocation}{DW\_AT\_vtable\_elem\_location}
1463 \addtoindexi{attribute}{vtable element location attribute} whose value contains
1464 a \addtoindex{location description}
1465 yielding the address of the slot
1466 for the function within the virtual function table for the
1467 enclosing class. The address of an object of the enclosing
1468 type is pushed onto the expression stack before the location
1469 description is evaluated.
1472 \hypertarget{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}
1473 the member function entry describes a non\dash static member
1474 \addtoindexx{this pointer attribute|see{object pointer attribute}}
1475 function, then that entry
1476 \addtoindexx{self pointer attribute|see{object pointer attribute}}
1478 \addtoindexx{object pointer attribute}
1479 a \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}
1481 whose value is a \livelink{chap:classreference}{reference}
1482 to the formal parameter entry
1483 that corresponds to the object for which the function is
1484 called. The name attribute of that formal parameter is defined
1485 by the current language (for example,
1486 this for \addtoindex{C++} or self
1487 for \addtoindex{Objective C}
1488 and some other languages). That parameter
1489 also has a \livelink{chap:DWATartificial}{DW\_AT\_artificial} attribute whose value is true.
1491 Conversely, if the member function entry describes a static
1492 member function, the entry does not have
1493 \addtoindexx{object pointer attribute}
1495 \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}
1498 If the member function entry describes a non\dash static member
1499 function that has a const\dash volatile qualification, then
1500 the entry describes a non\dash static member function whose
1501 object formal parameter has a type that has an equivalent
1502 const\dash volatile qualification.
1504 If a subroutine entry represents the defining declaration
1505 of a member function and that definition appears outside of
1506 the body of the enclosing class declaration, the subroutine
1508 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute,
1509 \addtoindexx{specification attribute}
1511 a reference to the debugging information entry representing
1512 the declaration of this function member. The referenced entry
1513 will be a child of some class (or structure) type entry.
1515 Subroutine entries containing the
1516 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
1517 \addtoindexx{specification attribute}
1518 do not need to duplicate information provided
1519 by the declaration entry referenced by the specification
1520 attribute. In particular, such entries do not need to contain
1521 attributes for the name or return type of the function member
1522 whose definition they represent.
1524 \subsection{Class Template Instantiations}
1525 \label{chap:classtemplateinstantiations}
1527 \textit{In \addtoindex{C++} a class template is a generic definition of a class
1528 type that may be instantiated when an instance of the class
1529 is declared or defined. The generic description of the
1530 class may include both parameterized types and parameterized
1531 constant values. DWARF does not represent the generic template
1532 definition, but does represent each instantiation.}
1534 A class template instantiation is represented by a
1535 debugging information entry with the tag \livelink{chap:DWTAGclasstype}{DW\_TAG\_class\_type},
1536 \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type} or
1537 \livelink{chap:DWTAGuniontype}{DW\_TAG\_union\_type}. With five
1538 exceptions, such an entry will contain the same attributes
1539 and have the same types of child entries as would an entry
1540 for a class type defined explicitly using the instantiation
1541 types and values. The exceptions are:
1543 \begin{enumerate}[1. ]
1544 \item Each formal parameterized type declaration appearing in the
1545 template definition is represented by a debugging information
1547 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}. Each
1548 such entry may have a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1549 \addtoindexx{name attribute}
1551 a null\dash terminated string containing the name of the formal
1552 type parameter as it appears in the source program. The
1553 template type parameter entry also has
1554 \addtoindexx{type attribute}
1556 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1557 describing the actual type by which the formal is replaced
1558 for this instantiation.
1560 \item Each formal parameterized value declaration appearing in the
1561 template definition is represented by a
1562 debugging information entry with the
1563 \addtoindexx{template value parameter entry}
1564 tag \livetarg{chap:DWTAGtemplatevalueparameter}{DW\_TAG\_template\_value\_parameter}.
1566 such entry may have a
1567 \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1568 \addtoindexx{name attribute}
1570 a null\dash terminated string containing the name of the formal
1571 value parameter as it appears in the source program.
1573 \hypertarget{chap:DWATconstvaluetemplatevalueparameter}
1574 template value parameter entry
1575 \addtoindexx{template value parameter entry}
1577 \addtoindexx{type attribute}
1579 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1580 describing the type of the parameterized value. Finally,
1581 the template value parameter entry has a
1582 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}
1583 attribute, whose value is the actual constant value of the
1584 value parameter for this instantiation as represented on the
1585 target architecture.
1588 \item The class type entry and each of its child entries references
1589 a \addtoindex{template type parameter entry} in any circumstance where the
1590 source template definition references a formal parameterized
1592 Similarly, the class type entry and each of its child
1593 entries references a template value parameter entry in any
1594 circumstance where the source template definition references
1595 a formal parameterized value.
1597 \item If the compiler has generated a special compilation unit to
1599 \addtoindexx{template instantiation!and special compilation unit}
1600 template instantiation and that special compilation
1601 unit has a different name from the compilation unit containing
1602 the template definition, the name attribute for the debugging
1603 information entry representing the special compilation unit
1604 should be empty or omitted.
1607 \item If the class type entry representing the template
1608 instantiation or any of its child entries contains declaration
1609 coordinate attributes, those attributes should refer to
1610 the source for the template definition, not to any source
1611 generated artificially by the compiler.
1615 \subsection{Variant Entries}
1616 \label{chap:variantentries}
1618 A variant part of a structure is represented by a debugging
1619 information entry\addtoindexx{variant part entry} with the
1620 tag \livetarg{chap:DWTAGvariantpart}{DW\_TAG\_variant\_part} and is
1621 owned by the corresponding structure type entry.
1623 If the variant part has a discriminant, the discriminant is
1624 \hypertarget{chap:DWATdiscrdiscriminantofvariantpart}
1626 \addtoindexx{discriminant (entry)}
1627 separate debugging information entry which
1628 is a child of the variant part entry. This entry has the form
1630 \addtoindexx{member entry (data)!as discriminant}
1631 structure data member entry. The variant part entry will
1632 \addtoindexx{discriminant attribute}
1634 \livelink{chap:DWATdiscr}{DW\_AT\_discr} attribute
1635 whose value is a \livelink{chap:classreference}{reference} to
1636 the member entry for the discriminant.
1638 If the variant part does not have a discriminant (tag field),
1639 the variant part entry has
1640 \addtoindexx{type attribute}
1642 \livelink{chap:DWATtype}{DW\_AT\_type} attribute to represent
1645 Each variant of a particular variant part is represented by
1646 \hypertarget{chap:DWATdiscrvaluediscriminantvalue}
1647 a debugging information entry\addtoindexx{variant entry} with the
1648 tag \livetarg{chap:DWTAGvariant}{DW\_TAG\_variant}
1649 and is a child of the variant part entry. The value that
1650 selects a given variant may be represented in one of three
1651 ways. The variant entry may have a
1652 \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value} attribute
1653 whose value represents a single case label. The value of this
1654 attribute is encoded as an LEB128 number. The number is signed
1655 if the tag type for the variant part containing this variant
1656 is a signed type. The number is unsigned if the tag type is
1661 \hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}
1662 the variant entry may contain
1663 \addtoindexx{discriminant list attribute}
1665 \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list}
1666 attribute, whose value represents a list of discriminant
1667 values. This list is represented by any of the
1668 \livelink{chap:classblock}{block} forms and
1669 may contain a mixture of case labels and label ranges. Each
1670 item on the list is prefixed with a discriminant value
1671 descriptor that determines whether the list item represents
1672 a single label or a label range. A single case label is
1673 represented as an LEB128 number as defined above for
1674 \addtoindexx{discriminant value attribute}
1676 \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value}
1677 attribute. A label range is represented by
1678 two LEB128 numbers, the low value of the range followed by the
1679 high value. Both values follow the rules for signedness just
1680 described. The discriminant value descriptor is an integer
1681 constant that may have one of the values given in
1682 Table \refersec{tab:discriminantdescriptorvalues}.
1684 \begin{simplenametable}[1.4in]{Discriminant descriptor values}{tab:discriminantdescriptorvalues}
1685 \livetarg{chap:DWDSClabel}{DW\_DSC\_label} \\
1686 \livetarg{chap:DWDSCrange}{DW\_DSC\_range} \\
1687 \end{simplenametable}
1689 If a variant entry has neither a \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value}
1690 attribute nor a \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list} attribute, or if it has
1691 a \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list} attribute with 0 size, the variant is a
1694 The components selected by a particular variant are represented
1695 by debugging information entries owned by the corresponding
1696 variant entry and appear in the same order as the corresponding
1697 declarations in the source program.
1699 \section{Condition Entries}
1700 \label{chap:conditionentries}
1702 \textit{COBOL has the notion of
1703 \addtoindexx{level-88 condition, COBOL}
1704 a ``level\dash 88 condition'' that
1705 associates a data item, called the conditional variable, with
1706 a set of one or more constant values and/or value ranges.
1707 Semantically, the condition is \textquoteleft true\textquoteright if the conditional
1708 variable's value matches any of the described constants,
1709 and the condition is \textquoteleft false\textquoteright otherwise.}
1711 The \livetarg{chap:DWTAGcondition}{DW\_TAG\_condition}
1712 debugging information entry\addtoindexx{condition entry}
1714 logical condition that tests whether a given data item\textquoteright s
1715 value matches one of a set of constant values. If a name
1716 has been given to the condition, the condition entry has a
1717 \livelink{chap:DWATname}{DW\_AT\_name} attribute
1718 \addtoindexx{name attribute}
1719 whose value is a null\dash terminated string
1720 giving the condition name as it appears in the source program.
1722 The condition entry's parent entry describes the conditional
1723 variable; normally this will be a \livelink{chap:DWTAGvariable}{DW\_TAG\_variable},
1724 \livelink{chap:DWTAGmember}{DW\_TAG\_member} or
1725 \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter} entry.
1727 \addtoindexx{formal parameter entry}
1729 entry has an array type, the condition can test any individual
1730 element, but not the array as a whole. The condition entry
1731 implicitly specifies a \doublequote{comparison type} that is the
1732 type of an array element if the parent has an array type;
1733 otherwise it is the type of the parent entry.
1735 The condition entry owns \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} and/or
1736 \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type} entries that describe the constant
1737 values associated with the condition. If any child entry
1738 \addtoindexx{type attribute}
1740 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute,
1741 that attribute should describe a type
1742 compatible with the comparison type (according to the source
1743 language); otherwise the child\textquoteright s type is the same as the
1746 \textit{For conditional variables with alphanumeric types, COBOL
1747 permits a source program to provide ranges of alphanumeric
1748 constants in the condition. Normally a subrange type entry
1749 does not describe ranges of strings; however, this can be
1750 represented using bounds attributes that are references to
1751 constant entries describing strings. A subrange type entry may
1752 refer to constant entries that are siblings of the subrange
1756 \section{Enumeration Type Entries}
1757 \label{chap:enumerationtypeentries}
1759 \textit{An \doublequote{enumeration type} is a scalar that can assume one of
1760 a fixed number of symbolic values.}
1762 An enumeration type is represented by a debugging information
1764 \livetarg{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}.
1766 If a name has been given to the enumeration type in the source
1767 program, then the corresponding enumeration type entry has
1768 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1769 \addtoindexx{name attribute}
1770 whose value is a null\dash terminated
1771 string containing the enumeration type name as it appears
1772 in the source program. This entry also has a
1773 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1774 attribute whose \livelink{chap:classconstant}{integer constant}
1775 value is the number of bytes
1776 required to hold an instance of the enumeration.
1778 The \addtoindex{enumeration type entry}
1780 \addtoindexx{type attribute}
1781 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1782 which refers to the underlying data type used to implement
1785 If an enumeration type has type safe
1786 \addtoindexx{type safe enumeration types}
1789 \begin{enumerate}[1. ]
1790 \item Enumerators are contained in the scope of the enumeration type, and/or
1792 \item Enumerators are not implicitly converted to another type
1795 then the \addtoindex{enumeration type entry} may
1796 \addtoindexx{enum class|see{type-safe enumeration}}
1797 have a \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}
1798 attribute, which is a \livelink{chap:classflag}{flag}.
1799 In a language that offers only
1800 one kind of enumeration declaration, this attribute is not
1803 \textit{In \addtoindex{C} or \addtoindex{C++},
1804 the underlying type will be the appropriate
1805 integral type determined by the compiler from the properties of
1806 \hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}
1807 the enumeration literal values.
1808 A \addtoindex{C++} type declaration written
1809 using enum class declares a strongly typed enumeration and
1810 is represented using \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}
1811 in combination with \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}.}
1813 Each enumeration literal is represented by a debugging
1814 \addtoindexx{enumeration literal|see{enumeration entry}}
1815 information entry with the
1816 tag \livetarg{chap:DWTAGenumerator}{DW\_TAG\_enumerator}.
1818 such entry is a child of the
1819 \addtoindex{enumeration type entry}, and the
1820 enumerator entries appear in the same order as the declarations
1821 of the enumeration literals in the source program.
1823 Each \addtoindex{enumerator entry} has a
1824 \livelink{chap:DWATname}{DW\_AT\_name} attribute, whose
1825 \addtoindexx{name attribute}
1826 value is a null\dash terminated string containing the name of the
1827 \hypertarget{chap:DWATconstvalueenumerationliteralvalue}
1828 enumeration literal as it appears in the source program.
1829 Each enumerator entry also has a
1830 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value} attribute,
1831 whose value is the actual numeric value of the enumerator as
1832 represented on the target system.
1835 If the enumeration type occurs as the description of a
1836 \addtoindexx{enumeration type endry!as array dimension}
1837 dimension of an array type, and the stride for that dimension
1838 \hypertarget{chap:DWATbytestrideenumerationstridedimensionofarraytype}
1839 is different than what would otherwise be determined, then
1840 \hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}
1841 the enumeration type entry has either a
1842 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
1843 or \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
1844 \addtoindexx{bit stride attribute}
1845 which specifies the separation
1846 between successive elements along the dimension as described
1848 Section \refersec{chap:visibilityofdeclarations}.
1850 \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
1851 \addtoindexx{bit stride attribute}
1852 is interpreted as bits and the value of
1853 \addtoindexx{byte stride attribute}
1855 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
1856 attribute is interpreted as bytes.
1859 \section{Subroutine Type Entries}
1860 \label{chap:subroutinetypeentries}
1862 \textit{It is possible in \addtoindex{C}
1863 to declare pointers to subroutines
1864 that return a value of a specific type. In both
1865 \addtoindex{C} and \addtoindex{C++},
1866 it is possible to declare pointers to subroutines that not
1867 only return a value of a specific type, but accept only
1868 arguments of specific types. The type of such pointers would
1869 be described with a ``pointer to'' modifier applied to a
1870 user\dash defined type.}
1872 A subroutine type is represented by a debugging information
1874 \addtoindexx{subroutine type entry}
1875 tag \livetarg{chap:DWTAGsubroutinetype}{DW\_TAG\_subroutine\_type}.
1877 been given to the subroutine type in the source program,
1878 then the corresponding subroutine type entry has
1879 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1880 \addtoindexx{name attribute}
1881 whose value is a null\dash terminated string containing
1882 the subroutine type name as it appears in the source program.
1884 If the subroutine type describes a function that returns
1885 a value, then the subroutine type entry has
1886 \addtoindexx{type attribute}
1887 a \livelink{chap:DWATtype}{DW\_AT\_type}
1888 attribute to denote the type returned by the subroutine. If
1889 the types of the arguments are necessary to describe the
1890 subroutine type, then the corresponding subroutine type
1891 entry owns debugging information entries that describe the
1892 arguments. These debugging information entries appear in the
1893 order that the corresponding argument types appear in the
1896 \textit{In \addtoindex{C} there
1897 is a difference between the types of functions
1898 declared using function prototype style declarations and
1899 those declared using non\dash prototype declarations.}
1902 \hypertarget{chap:DWATprototypedsubroutineprototype}
1903 subroutine entry declared with a function prototype style
1904 declaration may have
1905 \addtoindexx{prototyped attribute}
1907 \livelink{chap:DWATprototyped}{DW\_AT\_prototyped} attribute, which is
1908 a \livelink{chap:classflag}{flag}.
1910 Each debugging information entry owned by a subroutine
1911 type entry correspond to either a formal parameter or the sequence of
1912 unspecified parameters of the subprogram type:
1914 \begin{enumerate}[1. ]
1915 \item A formal parameter of a parameter list (that has a
1916 specific type) is represented by a debugging information entry
1917 with the tag \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}.
1918 Each formal parameter
1920 \addtoindexx{type attribute}
1921 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute that refers to the type of
1922 the formal parameter.
1924 \item The unspecified parameters of a variable parameter list
1925 \addtoindexx{unspecified parameters entry}
1927 \addtoindexx{\texttt{...} parameters|see{unspecified parameters entry}}
1928 represented by a debugging information entry with the
1929 tag \livelink{chap:DWTAGunspecifiedparameters}{DW\_TAG\_unspecified\_parameters}.
1934 \section{String Type Entries}
1935 \label{chap:classstringtypeentries}
1937 \textit{A ``string'' is a sequence of characters that have specific
1938 \addtoindexx{string type entry}
1939 semantics and operations that separate them from arrays of
1941 \addtoindex{Fortran} is one of the languages that has a string
1942 type. Note that ``string'' in this context refers to a target
1943 machine concept, not the class string as used in this document
1944 (except for the name attribute).}
1946 A string type is represented by a debugging information entry
1947 with the tag \livetarg{chap:DWTAGstringtype}{DW\_TAG\_string\_type}.
1948 If a name has been given to
1949 the string type in the source program, then the corresponding
1950 string type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1951 \addtoindexx{name attribute}
1953 a null\dash terminated string containing the string type name as
1954 it appears in the source program.
1957 \hypertarget{chap:DWATstringlengthstringlengthofstringtype}
1958 string type entry may have a
1959 \livelink{chap:DWATstringlength}{DW\_AT\_string\_length} attribute
1961 \addtoindexx{string length attribute}
1963 \addtoindex{location description} yielding the location
1964 where the length of the string is stored in the program. The
1965 string type entry may also have a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute
1966 or \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute, whose value
1967 (see Section \refersec{chap:byteandbitsizes})
1968 is the size of the data to be retrieved from the location
1969 referenced by the string length attribute. If no (byte or bit)
1970 size attribute is present, the size of the data to be retrieved
1972 \addtoindex{size of an address} on the target machine.
1975 If no string length attribute is present, the string type
1976 entry may have a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or
1977 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
1978 attribute, whose value
1979 (see Section \refersec{chap:byteandbitsizes})
1981 storage needed to hold a value of the string type.
1984 \section{Set Type Entries}
1985 \label{chap:settypeentries}
1987 \textit{\addtoindex{Pascal} provides the concept of a \doublequote{set,} which represents
1988 a group of values of ordinal type.}
1990 A set is represented by a debugging information entry with
1991 the tag \livetarg{chap:DWTAGsettype}{DW\_TAG\_set\_type}.
1992 \addtoindexx{set type entry}
1993 If a name has been given to the
1994 set type, then the set type entry has
1995 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1996 \addtoindexx{name attribute}
1997 whose value is a null\dash terminated string containing the
1998 set type name as it appears in the source program.
2000 The set type entry has
2001 \addtoindexx{type attribute}
2002 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to denote the
2003 type of an element of the set.
2005 If the amount of storage allocated to hold each element of an
2006 object of the given set type is different from the amount of
2007 storage that is normally allocated to hold an individual object
2008 of the indicated element type, then the set type entry has
2009 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute, or
2010 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
2011 whose value (see Section \refersec{chap:byteandbitsizes}) is
2012 the amount of storage needed to hold a value of the set type.
2015 \section{Subrange Type Entries}
2016 \label{chap:subrangetypeentries}
2018 \textit{Several languages support the concept of a ``subrange''
2019 type object. These objects can represent a subset of the
2020 values that an object of the basis type for the subrange can
2022 Subrange type entries may also be used to represent
2023 the bounds of array dimensions.}
2025 A subrange type is represented by a debugging information
2027 \addtoindexx{subrange type entry}
2028 tag \livetarg{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}.
2030 given to the subrange type, then the subrange type entry
2031 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
2032 \addtoindexx{name attribute}
2033 whose value is a null\dash terminated
2034 string containing the subrange type name as it appears in
2037 The subrange entry may have
2038 \addtoindexx{type attribute}
2039 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to describe
2040 the type of object, called the basis type, of whose values
2041 this subrange is a subset.
2043 If the amount of storage allocated to hold each element of an
2044 object of the given subrange type is different from the amount
2045 of storage that is normally allocated to hold an individual
2046 object of the indicated element type, then the subrange
2048 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or
2049 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
2050 attribute, whose value
2051 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
2053 storage needed to hold a value of the subrange type.
2056 \hypertarget{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}
2057 subrange entry may have
2058 \addtoindexx{threads scaled attribute}
2060 \livelink{chap:DWATthreadsscaled}{DW\_AT\_threads\_scaled} attribute,
2061 which is a \livelink{chap:classflag}{flag}.
2062 If present, this attribute indicates whether
2063 this subrange represents a \addtoindex{UPC} array bound which is scaled
2064 by the runtime THREADS value (the number of UPC threads in
2065 this execution of the program).
2067 \textit{This allows the representation of a \addtoindex{UPC} shared array such as}
2069 \begin{lstlisting}[numbers=none]
2070 int shared foo[34*THREADS][10][20];
2074 \hypertarget{chap:DWATlowerboundlowerboundofsubrange}
2076 \hypertarget{chap:DWATupperboundupperboundofsubrange}
2077 entry may have the attributes
2078 \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}
2079 \addtoindexx{lower bound attribute}
2080 and \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}
2081 \addtoindexx{upper bound attribute} to specify, respectively, the lower
2082 and upper bound values of the subrange. The
2083 \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}
2085 \hypertarget{chap:DWATcountelementsofsubrangetype}
2087 % FIXME: The following matches DWARF4: odd as there is no default count.
2088 \addtoindexx{count attribute!default}
2090 \addtoindexx{count attribute}
2092 \livelink{chap:DWATcount}{DW\_AT\_count} attribute,
2094 value describes the number of elements in the subrange rather
2095 than the value of the last element. The value of each of
2096 these attributes is determined as described in
2097 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2099 If the lower bound value is missing, the value is assumed to
2100 be a language\dash dependent default constant.
2101 \addtoindexx{lower bound attribute!default}
2102 The default lower bound is 0 for
2103 \addtoindex{C}, \addtoindex{C++},
2106 \addtoindex{Objective C},
2107 \addtoindex{Objective C++},
2108 \addtoindex{Python}, and
2110 The default lower bound is 1 for
2111 \addtoindex{Ada}, \addtoindex{COBOL},
2112 \addtoindex{Fortran},
2113 \addtoindex{Modula-2},
2114 \addtoindex{Pascal} and
2117 \textit{No other default lower bound values are currently defined.}
2119 If the upper bound and count are missing, then the upper bound value is
2120 \textit{unknown}.\addtoindexx{upper bound attribute!default unknown}
2122 If the subrange entry has no type attribute describing the
2123 basis type, the basis type is determined as follows:
2124 \begin{enumerate}[1. ]
2126 If there is a lower bound attribute that references an object,
2127 the basis type is assumed to be the same as the type of that object.
2129 Otherwise, if there is an upper bound or count attribute that references
2130 an object, the basis type is assumed to be the same as the type of that object.
2132 Otherwise, the type is
2133 assumed to be the same type, in the source language of the
2134 compilation unit containing the subrange entry, as a signed
2135 integer with the same size as an address on the target machine.
2138 If the subrange type occurs as the description of a dimension
2139 of an array type, and the stride for that dimension is
2140 \hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}
2141 different than what would otherwise be determined, then
2142 \hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}
2143 the subrange type entry has either
2144 \addtoindexx{byte stride attribute}
2146 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride} or
2147 \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
2148 \addtoindexx{bit stride attribute}
2149 which specifies the separation
2150 between successive elements along the dimension as described
2152 Section \refersec{chap:byteandbitsizes}.
2154 \textit{Note that the stride can be negative.}
2156 \section{Pointer to Member Type Entries}
2157 \label{chap:pointertomembertypeentries}
2159 \textit{In \addtoindex{C++}, a
2160 pointer to a data or function member of a class or
2161 structure is a unique type.}
2163 A debugging information entry representing the type of an
2164 object that is a pointer to a structure or class member has
2165 the tag \livetarg{chap:DWTAGptrtomembertype}{DW\_TAG\_ptr\_to\_member\_type}.
2167 If the \addtoindex{pointer to member type} has a name, the
2168 \addtoindexx{pointer to member type entry}
2169 pointer to member entry has a
2170 \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2171 \addtoindexx{name attribute}
2173 null\dash terminated string containing the type name as it appears
2174 in the source program.
2176 The \addtoindex{pointer to member} entry
2178 \addtoindexx{type attribute}
2179 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to
2180 describe the type of the class or structure member to which
2181 objects of this type may point.
2183 The \addtoindex{pointer to member} entry also
2184 \hypertarget{chap:DWATcontainingtypecontainingtypeofpointertomembertype}
2186 \livelink{chap:DWATcontainingtype}{DW\_AT\_containing\_type}
2187 attribute, whose value is a \livelink{chap:classreference}{reference} to a debugging
2188 information entry for the class or structure to whose members
2189 objects of this type may point.
2191 The \addtoindex{pointer to member entry}
2192 \hypertarget{chap:DWATuselocationmemberlocationforpointertomembertype}
2194 \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} attribute
2195 \addtoindexx{use location attribute}
2197 \addtoindex{location description} that computes the
2198 address of the member of the class to which the pointer to
2199 member entry points.
2201 \textit{The method used to find the address of a given member of a
2202 class or structure is common to any instance of that class
2203 or structure and to any instance of the pointer or member
2204 type. The method is thus associated with the type entry,
2205 rather than with each instance of the type.}
2207 The \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description is used in conjunction
2208 with the location descriptions for a particular object of the
2209 given \addtoindex{pointer to member type} and for a particular structure or
2210 class instance. The \livelink{chap:DWATuselocation}{DW\_AT\_use\_location}
2211 attribute expects two values to be
2212 \addtoindexi{pushed}{address!implicit push for member operator}
2213 onto the DWARF expression stack before
2214 the \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description is evaluated.
2216 \addtoindexi{pushed}{address!implicit push for member operator}
2217 is the value of the \addtoindex{pointer to member} object
2218 itself. The second value
2219 \addtoindexi{pushed}{address!implicit push for member operator}
2220 is the base address of the
2221 entire structure or union instance containing the member
2222 whose address is being calculated.
2225 \textit{For an expression such as}
2227 \begin{lstlisting}[numbers=none]
2230 % FIXME: object and mbr\_ptr should be distinguished from italic. See DW4.
2231 \textit{where mbr\_ptr has some \addtoindex{pointer to member type}, a debugger should:}
2233 \textit{1. Push the value of mbr\_ptr onto the DWARF expression stack.}
2235 \textit{2. Push the base address of object onto the DWARF expression stack.}
2237 \textit{3. Evaluate the \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description
2238 given in the type of mbr\_ptr.}
2240 \section{File Type Entries}
2241 \label{chap:filetypeentries}
2243 \textit{Some languages, such as \addtoindex{Pascal},
2244 provide a data type to represent
2247 A file type is represented by a debugging information entry
2249 \addtoindexx{file type entry}
2251 \livetarg{chap:DWTAGfiletype}{DW\_TAG\_file\_type}.
2252 If the file type has a name,
2253 the file type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2254 \addtoindexx{name attribute}
2256 is a null\dash terminated string containing the type name as it
2257 appears in the source program.
2259 The file type entry has
2260 \addtoindexx{type attribute}
2261 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute describing
2262 the type of the objects contained in the file.
2264 The file type entry also
2265 \addtoindexx{byte size}
2267 \addtoindexx{bit size}
2269 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or
2270 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute, whose value
2271 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
2272 is the amount of storage need to hold a value of the file type.
2274 \section{Dynamic Type Properties}
2275 \label{chap:dynamictypeproperties}
2276 \subsection{Data Location}
2277 \label{chap:datalocation}
2279 \textit{Some languages may represent objects using descriptors to hold
2280 information, including a location and/or run\dash time parameters,
2281 about the data that represents the value for that object.}
2283 \hypertarget{chap:DWATdatalocationindirectiontoactualdata}
2284 The \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
2285 attribute may be used with any
2286 \addtoindexx{data location attribute}
2287 type that provides one or more levels of
2288 \addtoindexx{hidden indirection|see{data location attribute}}
2290 and/or run\dash time parameters in its representation. Its value
2291 is a \addtoindex{location description}.
2292 The result of evaluating this
2293 description yields the location of the data for an object.
2294 When this attribute is omitted, the address of the data is
2295 the same as the address of the object.
2298 \textit{This location description will typically begin with
2299 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
2300 which loads the address of the
2301 object which can then serve as a descriptor in subsequent
2302 calculation. For an example using
2303 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
2304 for a \addtoindex{Fortran 90 array}, see
2305 Appendix \refersec{app:fortran90example}.}
2307 \subsection{Allocation and Association Status}
2308 \label{chap:allocationandassociationstatus}
2310 \textit{Some languages, such as \addtoindex{Fortran 90},
2311 provide types whose values
2312 may be dynamically allocated or associated with a variable
2313 under explicit program control.}
2315 \hypertarget{chap:DWATallocatedallocationstatusoftypes}
2317 \livelink{chap:DWATallocated}{DW\_AT\_allocated}
2319 \addtoindexx{allocated attribute}
2320 may optionally be used with any
2321 type for which objects of the type can be explicitly allocated
2322 and deallocated. The presence of the attribute indicates that
2323 objects of the type are allocatable and deallocatable. The
2324 integer value of the attribute (see below) specifies whether
2325 an object of the type is
2326 currently allocated or not.
2328 \hypertarget{chap:DWATassociatedassociationstatusoftypes}
2330 \livelink{chap:DWATassociated}{DW\_AT\_associated} attribute
2332 \addtoindexx{associated attribute}
2333 optionally be used with
2334 any type for which objects of the type can be dynamically
2335 associated with other objects. The presence of the attribute
2336 indicates that objects of the type can be associated. The
2337 integer value of the attribute (see below) indicates whether
2338 an object of the type is currently associated or not.
2340 \textit{While these attributes are defined specifically with
2341 \addtoindex{Fortran 90} ALLOCATABLE and POINTER types
2342 in mind, usage is not limited
2343 to just that language.}
2345 The value of these attributes is determined as described in
2346 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2348 A non\dash zero value is interpreted as allocated or associated,
2349 and zero is interpreted as not allocated or not associated.
2351 \textit{For \addtoindex{Fortran 90},
2352 if the \livelink{chap:DWATassociated}{DW\_AT\_associated}
2353 attribute is present,
2354 the type has the POINTER property where either the parent
2355 variable is never associated with a dynamic object or the
2356 implementation does not track whether the associated object
2357 is static or dynamic. If the \livelink{chap:DWATallocated}{DW\_AT\_allocated} attribute is
2358 present and the \livelink{chap:DWATassociated}{DW\_AT\_associated} attribute is not, the type
2359 has the ALLOCATABLE property. If both attributes are present,
2360 then the type should be assumed to have the POINTER property
2361 (and not ALLOCATABLE); the \livelink{chap:DWATallocated}{DW\_AT\_allocated} attribute may then
2362 be used to indicate that the association status of the object
2363 resulted from execution of an ALLOCATE statement rather than
2364 pointer assignment.}
2366 \textit{For examples using
2367 \livelink{chap:DWATallocated}{DW\_AT\_allocated} for \addtoindex{Ada} and
2368 \addtoindex{Fortran 90}
2370 see Appendix \refersec{app:aggregateexamples}.}
2374 \section{Template Alias Entries}
2375 \label{chap:templatealiasentries}
2377 A type named using a template alias is represented
2378 by a debugging information entry
2379 \addtoindexx{template alias entry}
2381 \livetarg{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}.
2382 The template alias entry has a
2383 \livelink{chap:DWATname}{DW\_AT\_name} attribute
2384 \addtoindexx{name attribute}
2385 whose value is a null\dash terminated string
2386 containing the name of the template alias as it appears in
2387 the source program. The template alias entry also contains
2388 \addtoindexx{type attribute}
2390 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
2391 whose value is a \livelink{chap:classreference}{reference}
2392 to the type named by the template alias.
2395 The template alias entry has the following child entries:
2396 \begin{enumerate}[1. ]
2397 \item Each formal parameterized type declaration appearing
2398 in the template alias declaration is represented
2399 by a debugging information entry with the tag
2400 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}.
2401 Each such entry may have
2402 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2403 \addtoindexx{name attribute}
2404 whose value is a null\dash terminated
2405 string containing the name of the formal type parameter as it
2406 appears in the source program. The template type parameter
2408 \addtoindexx{type attribute}
2409 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
2410 describing the actual
2411 type by which the formal is replaced for this instantiation.
2413 \item Each formal parameterized value declaration
2414 appearing in the template alias declaration is
2415 represented by a debugging information entry with the tag
2416 \livelink{chap:DWTAGtemplatevalueparameter}{DW\_TAG\_template\_value\_parameter}.
2417 Each such entry may have
2418 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2419 \addtoindexx{name attribute}
2420 whose value is a null\dash terminated
2421 string containing the name of the formal value parameter
2422 as it appears in the source program. The template value
2423 parameter entry also has
2424 \addtoindexx{type attribute}
2425 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute describing
2426 the type of the parameterized value. Finally, the template
2427 value parameter entry has a \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}
2428 attribute, whose value is the actual constant value of the value parameter for
2429 this instantiation as represented on the target architecture.