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 integer constant. The set of
42 values and their meanings for the
43 \livelink{chap:DWATencoding}{DW\_AT\_encoding} attribute
45 Table \refersec{tab:encodingattributevalues}
49 may have a \livelink{chap:DWATendianity}{DW\_AT\_endianity} attribute
50 \addtoindexx{endianity attribute}
52 Section \refersec{chap:dataobjectentries}.
53 If omitted, the encoding assumes the representation that
54 is the default for the target architecture.
57 \hypertarget{chap:DWATbytesizedataobjectordatatypesize}
58 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute
59 \hypertarget{chap:DWATbitsizebasetypebitsize}
60 or a \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
61 \addtoindex{bit size attribute}
62 whose integer constant value
63 (see Section \refersec{chap:byteandbitsizes})
64 is the amount of storage needed to hold
68 \textit{For example, the
69 \addtoindex{C} type int on a machine that uses 32\dash bit
70 integers is represented by a base type entry with a name
71 attribute whose value is \doublequote{int}, an encoding attribute
72 whose value is \livelink{chap:DWATEsigned}{DW\_ATE\_signed}
73 and a byte size attribute whose value is 4.}
75 If the value of an object of the given type does not fully
76 occupy the storage described by a byte size attribute,
77 \hypertarget{chap:DWATdatabitoffsetbasetypebitlocation}
78 the base type entry may also have
79 \addtoindexx{bit size attribute}
81 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and a
82 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} attribute,
84 \addtoindexx{data bit offset attribute}
86 integer constant values (
87 see Section \refersec{chap:staticanddynamicvaluesofattributes}).
89 attribute describes the actual size in bits used to represent
90 values of the given type. The data bit offset attribute is the
91 offset in bits from the beginning of the containing storage to
92 the beginning of the value. Bits that are part of the offset
93 are padding. The data bit offset uses the bit numbering and
94 direction conventions that are appropriate to the current
96 target system to locate the beginning of the storage and
97 value. If this attribute is omitted a default data bit offset
101 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
103 \addtoindexx{bit offset attribute}
105 \addtoindexx{data bit offset attribute}
107 \addtoindex{DWARF Version 4} and
108 is also used for bit field members
109 (see Section \refersec{chap:datamemberentries}).
111 \hypertarget{chap:DWATbitoffsetbasetypebitlocation}
112 replaces the attribute
113 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
115 \addtoindexx{bit offset attribute (V3)}
116 types as defined in DWARF V3 and earlier. The earlier attribute
117 is defined in a manner suitable for bit field members on
118 big\dash endian architectures but which is wasteful for use on
119 little\dash endian architectures.}
121 \textit{The attribute \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} is
123 \addtoindex{DWARF Version 4}
124 for use in base types, but implementations may continue to
125 support its use for compatibility.}
128 \addtoindex{DWARF Version 3}
129 definition of these attributes is as follows.}
130 \begin{myindentpara}{1cm}
131 \textit{A base type entry has a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
132 attribute, whose value
133 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
134 is the size in bytes of the storage unit
135 used to represent an object of the given type.}
137 \textit{If the value of an object of the given type does not fully
138 occupy the storage unit described by the byte size attribute,
139 the base type entry may have a
140 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
141 \addtoindexx{bit size attribute (V3)}
143 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} attribute, both of whose values
144 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
145 are integers. The bit size attribute describes the actual
146 size in bits used to represent a value of the given type.
147 The bit offset attribute describes the offset in bits of the
148 high order bit of a value of the given type from the high
149 order bit of the storage unit used to contain that value.}
155 \addtoindexx{DWARF Version 3}
157 \addtoindexx{DWARF Version 4} and 4, note that DWARF V4
158 defines the following combinations of attributes:}
161 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}}
162 \item \textit{\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}}
163 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
164 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
165 and optionally \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}}
167 \textit{DWARF V3 defines the following combinations:}
168 \addtoindexx{DWARF Version 3}
169 % FIXME: the figure below interferes with the following
170 % bullet list, which looks horrible as a result.
172 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}}
173 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
174 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
175 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}}
179 \caption{Encoding attribute values}
180 \label{tab:encodingattributevalues}
182 \begin{tabular}{l|p{8cm}}
184 Name&Meaning\\ \hline
185 \livetarg{chap:DWATEaddress}{DW\_ATE\_address} & linear machine address (for segmented\break
187 Section \refersec{chap:segmentedaddresses}) \\
188 \livetarg{chap:DWATEboolean}{DW\_ATE\_boolean}& true or false \\
190 \livetarg{chap:DWATEcomplexfloat}{DW\_ATE\_complex\_float}& complex binary
191 floating\dash point number \\
192 \livetarg{chap:DWATEfloat}{DW\_ATE\_float} & binary floating\dash point number \\
193 \livetarg{chap:DWATEimaginaryfloat}{DW\_ATE\_imaginary\_float}& imaginary binary
194 floating\dash point number \\
195 \livetarg{chap:DWATEsigned}{DW\_ATE\_signed}& signed binary integer \\
196 \livetarg{chap:DWATEsignedchar}{DW\_ATE\_signed\_char}& signed character \\
197 \livetarg{chap:DWATEunsigned}{DW\_ATE\_unsigned} & unsigned binary integer \\
198 \livetarg{chap:DWATEunsignedchar}{DW\_ATE\_unsigned\_char} & unsigned character \\
199 \livetarg{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} & packed decimal \\
200 \livetarg{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string}& numeric string \\
201 \livetarg{chap:DWATEedited}{DW\_ATE\_edited} & edited string \\
202 \livetarg{chap:DWATEsignedfixed}{DW\_ATE\_signed\_fixed} & signed fixed\dash point scaled integer \\
203 \livetarg{chap:DWATEunsignedfixed}{DW\_ATE\_unsigned\_fixed}& unsigned fixed\dash point scaled integer \\
204 \livetarg{chap:DWATEdecimalfloat}{DW\_ATE\_decimal\_float} & decimal floating\dash point number \\
205 \livetarg{chap:DWATEUTF}{DW\_ATE\_UTF} & \addtoindex{Unicode} character \\
210 \textit{The \livelink{chap:DWATEdecimalfloat}{DW\_ATE\_decimal\_float} encoding is intended for
211 floating\dash point representations that have a power\dash of\dash ten
212 exponent, such as that specified in IEEE 754R.}
214 \textit{The \livelink{chap:DWATEUTF}{DW\_ATE\_UTF} encoding is intended for \addtoindex{Unicode}
215 string encodings (see the Universal Character Set standard,
216 ISO/IEC 10646\dash 1:1993). For example, the
217 \addtoindex{C++} type char16\_t is
218 represented by a base type entry with a name attribute whose
219 value is \doublequote{char16\_t}, an encoding attribute whose value
220 is \livelink{chap:DWATEUTF}{DW\_ATE\_UTF} and a byte size attribute whose value is 2.}
223 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal}
225 \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string}
227 represent packed and unpacked decimal string numeric data
228 types, respectively, either of which may be
230 \addtoindexx{decimal scale attribute}
232 \addtoindexx{decimal sign attribute}
234 \addtoindexx{digit count attribute}
236 \hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}
238 \hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}
239 base types are used in combination with
240 \livelink{chap:DWATdecimalsign}{DW\_AT\_decimal\_sign},
241 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and
242 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale}
245 A \livelink{chap:DWATdecimalsign}{DW\_AT\_decimal\_sign} attribute
246 \addtoindexx{decimal sign attribute}
247 is an integer constant that
248 conveys the representation of the sign of the decimal type
249 (see Figure \refersec{tab:decimalsignattributevalues}).
250 Its integer constant value is interpreted to
251 mean that the type has a leading overpunch, trailing overpunch,
252 leading separate or trailing separate sign representation or,
253 alternatively, no sign at all.
256 \caption{Decimal sign attribute values}
257 \label{tab:decimalsignattributevalues}
259 \begin{tabular}{l|p{9cm}}
263 \livetarg{chap:DWDSunsigned}{DW\_DS\_unsigned} & Unsigned \\
264 \livetarg{chap:DWDSleadingoverpunch}{DW\_DS\_leading\_overpunch} & Sign
265 is encoded in the most significant digit in a target\dash dependent manner \\
266 \livetarg{chap:DWDStrailingoverpunch}{DW\_DS\_trailing\_overpunch} & Sign
267 is encoded in the least significant digit in a target\dash dependent manner \\
268 \livetarg{chap:DWDSleadingseparate}{DW\_DS\_leading\_separate}
269 & Decimal type: Sign is a ``+'' or ``-'' character
270 to the left of the most significant digit. \\
271 \livetarg{chap:DWDStrailingseparate}{DW\_DS\_trailing\_separate}
272 & Decimal type: Sign is a ``+'' or ``-'' character
273 to the right of the least significant digit. \\
274 &Packed decimal type: Least significant nibble contains
275 a target\dash dependent value
276 indicating positive or negative. \\
282 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count}
284 \addtoindexx{digit count attribute}
285 is an integer constant
286 value that represents the number of digits in an instance of
289 \hypertarget{chap:DWATdecimalscaledecimalscalefactor}
290 The \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale}
292 \addtoindexx{decimal scale attribute}
293 is an integer constant value
294 that represents the exponent of the base ten scale factor to
295 be applied to an instance of the type. A scale of zero puts the
296 decimal point immediately to the right of the least significant
297 digit. Positive scale moves the decimal point to the right
298 and implies that additional zero digits on the right are not
299 stored in an instance of the type. Negative scale moves the
300 decimal point to the left; if the absolute value of the scale
301 is larger than the digit count, this implies additional zero
302 digits on the left are not stored in an instance of the type.
304 The \livelink{chap:DWATEedited}{DW\_ATE\_edited}
306 \hypertarget{chap:DWATpicturestringpicturestringfornumericstringtype}
307 type is used to represent an edited
308 numeric or alphanumeric data type. It is used in combination
309 with an \livelink{chap:DWATpicturestring}{DW\_AT\_picture\_string} attribute whose value is a
310 null\dash terminated string containing the target\dash dependent picture
311 string associated with the type.
313 If the edited base type entry describes an edited numeric
314 data type, the edited type entry has a \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and a
315 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attribute.
316 \addtoindexx{decimal scale attribute}
317 These attributes have the same
318 interpretation as described for the
319 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} and
320 \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base
321 types. If the edited type entry
322 describes an edited alphanumeric data type, the edited type
323 entry does not have these attributes.
326 \textit{The presence or absence of the \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count} and
327 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attributes
328 \addtoindexx{decimal scale attribute}
329 allows a debugger to easily
330 distinguish edited numeric from edited alphanumeric, although
331 in principle the digit count and scale are derivable by
332 interpreting the picture string.}
334 The \livelink{chap:DWATEsignedfixed}{DW\_ATE\_signed\_fixed} and \livelink{chap:DWATEunsignedfixed}{DW\_ATE\_unsigned\_fixed} entries
335 describe signed and unsigned fixed\dash point binary data types,
338 The fixed binary type entries have
339 \addtoindexx{digit count attribute}
341 \livelink{chap:DWATdigitcount}{DW\_AT\_digit\_count}
342 attribute with the same interpretation as described for the
343 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} and \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base types.
345 For a data type with a decimal scale factor, the fixed binary
347 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attribute
348 \addtoindexx{decimal scale attribute}
350 interpretation as described for the
351 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal}
352 and \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base types.
354 \hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}
355 For a data type with a binary scale factor, the fixed
356 \addtoindexx{binary scale attribute}
357 binary type entry has a
358 \livelink{chap:DWATbinaryscale}{DW\_AT\_binary\_scale} attribute.
360 \livelink{chap:DWATbinaryscale}{DW\_AT\_binary\_scale} attribute
361 is an integer constant value
362 that represents the exponent of the base two scale factor to
363 be applied to an instance of the type. Zero scale puts the
364 binary point immediately to the right of the least significant
365 bit. Positive scale moves the binary point to the right and
366 implies that additional zero bits on the right are not stored
367 in an instance of the type. Negative scale moves the binary
368 point to the left; if the absolute value of the scale is
369 larger than the number of bits, this implies additional zero
370 bits on the left are not stored in an instance of the type.
373 \hypertarget{chap:DWATsmallscalefactorforfixedpointtype}
374 a data type with a non\dash decimal and non\dash binary scale factor,
375 the fixed binary type entry has a
376 \livelink{chap:DWATsmall}{DW\_AT\_small} attribute which
377 \addtoindexx{small attribute}
379 \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} entry. The scale factor value
380 is interpreted in accordance with the value defined by the
381 \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} entry. The value represented is the product
382 of the integer value in memory and the associated constant
385 \textit{The \livelink{chap:DWATsmall}{DW\_AT\_small} attribute
386 is defined with the \addtoindex{Ada} small
389 \section{Unspecified Type Entries}
390 \label{chap:unspecifiedtypeentries}
391 \addtoindexx{unspecified type entry}
392 \addtoindexx{void type|see{unspecified type entry}}
393 Some languages have constructs in which a type
394 may be left unspecified or the absence of a type
395 may be explicitly indicated.
397 An unspecified (implicit, unknown, ambiguous or nonexistent)
398 type is represented by a debugging information entry with
399 the tag \livetarg{chap:DWTAGunspecifiedtype}{DW\_TAG\_unspecified\_type}.
400 If a name has been given
401 to the type, then the corresponding unspecified type entry
402 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
403 \addtoindexx{name attribute}
405 a null\dash terminated
406 string containing the name as it appears in the source program.
408 The interpretation of this debugging information entry is
409 intentionally left flexible to allow it to be interpreted
410 appropriately in different languages. For example, in
411 \addtoindex{C} and \addtoindex{C++}
412 the language implementation can provide an unspecified type
413 entry with the name \doublequote{void} which can be referenced by the
414 type attribute of pointer types and typedef declarations for
416 % FIXME: the following reference was wrong in DW4 so DavidA guessed
418 Sections \refersec{chap:unspecifiedtypeentries} and
419 %The following reference was valid, so the following is probably correct.
420 Section \refersec{chap:typedefentries},
421 respectively). As another
422 example, in \addtoindex{Ada} such an unspecified type entry can be referred
423 to by the type attribute of an access type where the denoted
424 \addtoindexx{incomplete type (Ada)}
425 type is incomplete (the name is declared as a type but the
426 definition is deferred to a separate compilation unit).
428 \section{Type Modifier Entries}
429 \label{chap:typemodifierentries}
430 \addtoindexx{type modifier entry}
432 A base or user\dash defined type may be modified in different ways
433 in different languages. A type modifier is represented in
434 DWARF by a debugging information entry with one of the tags
435 given in Table \refersec{tab:typemodifiertags}.
436 \addtoindexx{type modifier|see{constant type entry}}
437 \addtoindexx{type modifier|see{reference type entry}}
438 \addtoindexx{type modifier|see{restricted type entry}}
439 \addtoindexx{type modifier|see{packed type entry}}
440 \addtoindexx{type modifier|see{pointer type entry}}
441 \addtoindexx{type modifier|see{shared type entry}}
442 \addtoindexx{type modifier|see{volatile type entry}}
444 If a name has been given to the modified type in the source
445 program, then the corresponding modified type entry has
446 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
447 \addtoindexx{name attribute}
448 whose value is a null\dash terminated
449 string containing the modified type name as it appears in
452 Each of the type modifier entries has
453 \addtoindexx{type attribute}
455 \livelink{chap:DWATtype}{DW\_AT\_type} attribute,
456 whose value is a reference to a debugging information entry
457 describing a base type, a user-defined type or another type
460 A modified type entry describing a
461 \addtoindexx{pointer type entry}
462 pointer or \addtoindex{reference type}
463 (using \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type},
464 \livelink{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type} or
465 \livelink{chap:DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type})
466 % Another instance of no-good-place-to-put-index entry.
468 \addtoindexx{address class!attribute}
470 \hypertarget{chap:DWATadressclasspointerorreferencetypes}
472 \livelink{chap:DWATaddressclass}{DW\_AT\_address\_class}
473 attribute to describe how objects having the given pointer
474 or reference type ought to be dereferenced.
476 A modified type entry describing a shared qualified type
477 (using \livelink{chap:DWTAGsharedtype}{DW\_TAG\_shared\_type}) may have a
478 \livelink{chap:DWATcount}{DW\_AT\_count} attribute
479 \addtoindexx{count attribute}
480 whose value is a constant expressing the (explicit or implied) blocksize specified for the
481 type in the source. If no count attribute is present, then the \doublequote{infinite}
482 blocksize is assumed.
484 When multiple type modifiers are chained together to modify
485 a base or user-defined type, the tree ordering reflects the
487 \addtoindexx{reference type entry, lvalue|see{reference type entry}}
489 \addtoindexx{reference type entry, rvalue|see{rvalue reference type entry}}
491 \addtoindexx{parameter|see{macro formal parameter list}}
493 \addtoindexx{parameter|see{\textit{this} parameter}}
495 \addtoindexx{parameter|see{variable parameter attribute}}
497 \addtoindexx{parameter|see{optional parameter attribute}}
499 \addtoindexx{parameter|see{unspecified parameters entry}}
501 \addtoindexx{parameter|see{template value parameter entry}}
503 \addtoindexx{parameter|see{template type parameter entry}}
505 \addtoindexx{parameter|see{formal parameter entry}}
509 \caption{Type modifier tags}
510 \label{tab:typemodifiertags}
512 \begin{tabular}{l|p{9cm}}
514 Name&Meaning\\ \hline
515 \livetarg{chap:DWTAGconsttype}{DW\_TAG\_const\_type} & C or C++ const qualified type
516 \addtoindexx{const qualified type entry} \addtoindexx{C} \addtoindexx{C++} \\
517 \livetarg{chap:DWTAGpackedtype}{DW\_TAG\_packed\_type}& \addtoindex{Pascal} or Ada packed type\addtoindexx{packed type entry}
518 \addtoindexx{packed qualified type entry} \addtoindexx{Ada} \addtoindexx{Pascal} \\
519 \livetarg{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} & Pointer to an object of
520 the type being modified \addtoindexx{pointer qualified type entry} \\
521 \livetarg{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type}& C++ (lvalue) reference
522 to an object of the type
523 \addtoindexx{reference type entry}
525 \addtoindexx{reference qualified type entry} \\
526 \livetarg{chap:DWTAGrestricttype}{DW\_TAG\_restrict\_type}& \addtoindex{C}
528 \addtoindexx{restricted type entry}
530 \addtoindexx{restrict qualified type} \\
531 \livetarg{chap:DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type} & C++
532 \addtoindexx{rvalue reference type entry}
534 \addtoindexx{restricted type entry}
535 reference to an object of the type being modified
536 \addtoindexx{rvalue reference qualified type entry} \\
537 \livetarg{chap:DWTAGsharedtype}{DW\_TAG\_shared\_type}&\addtoindex{UPC} shared qualified type
538 \addtoindexx{shared qualified type entry} \\
539 \livetarg{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type}&C or C++ volatile qualified type
540 \addtoindex{volatile qualified type entry} \\
545 %The following clearpage prevents splitting the example across pages.
546 \textit{As examples of how type modifiers are ordered, consider the following
547 \addtoindex{C} declarations:}
548 \begin{lstlisting}[numbers=none]
549 const unsigned char * volatile p;
551 \textit{which represents a volatile pointer to a constant
552 character. This is encoded in DWARF as:}
556 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}(p) -->
557 \livelink{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type} -->
558 \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} -->
559 \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type} -->
560 \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}(unsigned char)
565 \textit{On the other hand}
566 \begin{lstlisting}[numbers=none]
567 volatile unsigned char * const restrict p;
569 \textit{represents a restricted constant
570 pointer to a volatile character. This is encoded as:}
574 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}(p) -->
575 \livelink{chap:DWTAGrestricttype}{DW\_TAG\_restrict\_type} -->
576 \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type} -->
577 \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} -->
578 \livelink{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type} -->
579 \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}(unsigned char)
583 \section{Typedef Entries}
584 \label{chap:typedefentries}
585 A named type that is defined in terms of another type
586 definition is represented by a debugging information entry with
587 \addtoindexx{typedef entry}
588 the tag \livetarg{chap:DWTAGtypedef}{DW\_TAG\_typedef}.
589 The typedef entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
590 \addtoindexx{name attribute}
591 whose value is a null\dash terminated string containing
592 the name of the typedef as it appears in the source program.
594 The typedef entry may also contain
595 \addtoindexx{type attribute}
597 \livelink{chap:DWATtype}{DW\_AT\_type} attribute whose
598 value is a reference to the type named by the typedef. If
599 the debugging information entry for a typedef represents
600 a declaration of the type that is not also a definition,
601 it does not contain a type attribute.
603 \textit{Depending on the language, a named type that is defined in
604 terms of another type may be called a type alias, a subtype,
605 a constrained type and other terms. A type name declared with
606 no defining details may be termed an
607 \addtoindexx{incomplete type}
608 incomplete, forward or hidden type.
609 While the DWARF \livelink{chap:DWTAGtypedef}{DW\_TAG\_typedef} entry was
610 originally inspired by the like named construct in
611 \addtoindex{C} and \addtoindex{C++},
612 it is broadly suitable for similar constructs (by whatever
613 source syntax) in other languages.}
615 \section{Array Type Entries}
616 \label{chap:arraytypeentries}
618 \textit{Many languages share the concept of an ``array,'' which is
619 \addtoindexx{array type entry}
620 a table of components of identical type.}
622 An array type is represented by a debugging information entry
623 with the tag \livetarg{chap:DWTAGarraytype}{DW\_TAG\_array\_type}.
624 If a name has been given to
625 \addtoindexx{array!declaration of type}
626 the array type in the source program, then the corresponding
627 array type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
628 \addtoindexx{name attribute}
630 null\dash terminated string containing the array type name as it
631 appears in the source program.
634 \hypertarget{chap:DWATorderingarrayrowcolumnordering}
635 array type entry describing a multidimensional array may
636 \addtoindexx{array!element ordering}
637 have a \livelink{chap:DWATordering}{DW\_AT\_ordering} attribute whose integer constant value is
638 interpreted to mean either row-major or column-major ordering
639 of array elements. The set of values and their meanings
640 for the ordering attribute are listed in
641 Table \refersec{tab:arrayordering}.
643 ordering attribute is present, the default ordering for the
644 source language (which is indicated by the
645 \livelink{chap:DWATlanguage}{DW\_AT\_language}
647 \addtoindexx{language attribute}
648 of the enclosing compilation unit entry) is assumed.
650 \begin{simplenametable}[1.6in]{Array ordering}{tab:arrayordering}
651 \livetarg{chap:DWORDcolmajor}{DW\_ORD\_col\_major} \\
652 \livetarg{chap:DWORDrowmajor}{DW\_ORD\_row\_major} \\
653 \end{simplenametable}
655 The ordering attribute may optionally appear on one-dimensional
656 arrays; it will be ignored.
658 An array type entry has
659 \addtoindexx{type attribute}
660 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
662 \addtoindexx{array!element type}
663 the type of each element of the array.
665 If the amount of storage allocated to hold each element of an
666 object of the given array type is different from the amount
667 \addtoindexx{stride attribute|see{bit stride attribute or byte stride attribute}}
668 of storage that is normally allocated to hold an individual
669 \hypertarget{chap:DWATbitstridearrayelementstrideofarraytype}
671 \hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}
672 indicated element type, then the array type
673 \addtoindexx{bit stride attribute}
675 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
677 \addtoindexx{byte stride attribute}
678 a \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride}
680 \addtoindexx{bit stride attribute}
682 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
684 element of the array.
686 The array type entry may have either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or a
687 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
688 (see Section \refersec{chap:byteandbitsizes}),
690 amount of storage needed to hold an instance of the array type.
692 \textit{If the size of the array can be determined statically at
693 compile time, this value can usually be computed by multiplying
694 the number of array elements by the size of each element.}
697 Each array dimension is described by a debugging information
698 entry with either the
699 \addtoindexx{subrange type entry!as array dimension}
700 tag \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type} or the
701 \addtoindexx{enumeration type entry!as array dimension}
703 \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}. These entries are
705 array type entry and are ordered to reflect the appearance of
706 the dimensions in the source program (i.e., leftmost dimension
707 first, next to leftmost second, and so on).
709 \textit{In languages, such as C, in which there is no concept of
710 a \doublequote{multidimensional array}, an array of arrays may
711 be represented by a debugging information entry for a
712 multidimensional array.}
714 Other attributes especially applicable to arrays are
715 \livelink{chap:DWATallocated}{DW\_AT\_allocated},
716 \livelink{chap:DWATassociated}{DW\_AT\_associated} and
717 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location},
718 which are described in
719 Section \refersec{chap:dynamictypeproperties}.
720 For relevant examples, see also Appendix \refersec{app:fortran90example}.
722 \section{ Structure, Union, Class and Interface Type Entries}
723 \label{chap:structureunionclassandinterfacetypeentries}
725 \textit{The languages
727 \addtoindex{C++}, and
728 \addtoindex{Pascal}, among others, allow the
729 programmer to define types that are collections of related
730 \addtoindexx{structure type entry}
732 In \addtoindex{C} and \addtoindex{C++}, these collections are called
733 \doublequote{structures.}
734 In \addtoindex{Pascal}, they are called \doublequote{records.}
735 The components may be of different types. The components are
736 called \doublequote{members} in \addtoindex{C} and
737 \addtoindex{C++}, and \doublequote{fields} in \addtoindex{Pascal}.}
739 \textit{The components of these collections each exist in their
740 own space in computer memory. The components of a C or C++
741 \doublequote{union} all coexist in the same memory.}
743 \textit{\addtoindex{Pascal} and
744 other languages have a \doublequote{discriminated union,}
745 \addtoindex{discriminated union|see {variant entry}}
746 also called a \doublequote{variant record.} Here, selection of a
747 number of alternative substructures (\doublequote{variants}) is based
748 on the value of a component that is not part of any of those
749 substructures (the \doublequote{discriminant}).}
751 \textit{\addtoindex{C++} and
752 \addtoindex{Java} have the notion of ``class'', which is in some
753 ways similar to a structure. A class may have \doublequote{member
754 functions} which are subroutines that are within the scope
755 of a class or structure.}
757 \textit{The \addtoindex{C++} notion of
758 structure is more general than in \addtoindex{C}, being
759 equivalent to a class with minor differences. Accordingly,
760 in the following discussion statements about
761 \addtoindex{C++} classes may
762 be understood to apply to \addtoindex{C++} structures as well.}
764 \subsection{Structure, Union and Class Type Entries}
765 \label{chap:structureunionandclasstypeentries}
768 Structure, union, and class types are represented by debugging
769 \addtoindexx{structure type entry}
771 \addtoindexx{union type entry}
773 \addtoindexx{class type entry}
775 \livetarg{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type},
776 \livetarg{chap:DWTAGuniontype}{DW\_TAG\_union\_type},
777 and \livetarg{chap:DWTAGclasstype}{DW\_TAG\_class\_type},
778 respectively. If a name has been given to the structure,
779 union, or class in the source program, then the corresponding
780 structure type, union type, or class type entry has a
781 \livelink{chap:DWATname}{DW\_AT\_name} attribute
782 \addtoindexx{name attribute}
783 whose value is a null\dash terminated string
784 containing the type name as it appears in the source program.
786 The members of a structure, union, or class are represented
787 by debugging information entries that are owned by the
788 corresponding structure type, union type, or class type entry
789 and appear in the same order as the corresponding declarations
790 in the source program.
792 A structure type, union type or class type entry may have
793 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or a
794 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
795 \hypertarget{chap:DWATbitsizedatamemberbitsize}
796 (see Section \refersec{chap:byteandbitsizes}),
797 whose value is the amount of storage needed
798 to hold an instance of the structure, union or class type,
799 including any padding.
801 An incomplete structure, union or class type
802 \addtoindexx{incomplete structure/union/class}
804 \addtoindexx{incomplete type}
805 represented by a structure, union or class
806 entry that does not have a byte size attribute and that has
807 \addtoindexx{declaration attribute}
808 a \livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute.
810 If the complete declaration of a type has been placed in
811 \hypertarget{chap:DWATsignaturetypesignature}
812 a separate \addtoindex{type unit}
813 (see Section \refersec{chap:separatetypeunitentries}),
814 an incomplete declaration
815 \addtoindexx{incomplete type}
816 of that type in the compilation unit may provide
817 the unique 64\dash bit signature of the type using
818 \addtoindexx{type signature}
819 a \livelink{chap:DWATsignature}{DW\_AT\_signature}
822 If a structure, union or class entry represents the definition
823 of a structure, class or union member corresponding to a prior
824 incomplete structure, class or union, the entry may have a
825 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
826 \addtoindexx{specification attribute}
827 whose value is a reference to
828 the debugging information entry representing that incomplete
831 Structure, union and class entries containing the
832 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
833 \addtoindexx{specification attribute}
834 do not need to duplicate
835 information provided by the declaration entry referenced by the
836 specification attribute. In particular, such entries do not
837 need to contain an attribute for the name of the structure,
838 class or union they represent if such information is already
839 provided in the declaration.
841 \textit{For \addtoindex{C} and \addtoindex{C++},
843 \addtoindexx{data member|see {member entry (data)}}
844 member declarations occurring within
845 the declaration of a structure, union or class type are
846 considered to be \doublequote{definitions} of those members, with
847 the exception of \doublequote{static} data members, whose definitions
848 appear outside of the declaration of the enclosing structure,
849 union or class type. Function member declarations appearing
850 within a structure, union or class type declaration are
851 definitions only if the body of the function also appears
852 within the type declaration.}
854 If the definition for a given member of the structure, union
855 or class does not appear within the body of the declaration,
856 that member also has a debugging information entry describing
857 its definition. That latter entry has a
858 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
859 \addtoindexx{specification attribute}
860 referencing the debugging information entry
861 owned by the body of the structure, union or class entry and
862 representing a non\dash defining declaration of the data, function
863 or type member. The referenced entry will not have information
864 about the location of that member (low and high pc attributes
865 for function members, location descriptions for data members)
866 and will have a \livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute.
869 \textit{Consider a nested class whose
870 definition occurs outside of the containing class definition, as in:}
872 \begin{lstlisting}[numbers=none]
879 \textit{The two different structs can be described in
880 different compilation units to
881 facilitate DWARF space compression
882 (see Appendix \refersec{app:usingcompilationunits}).}
884 \subsection{Interface Type Entries}
885 \label{chap:interfacetypeentries}
887 \textit{The \addtoindex{Java} language defines ``interface'' types.
889 \addtoindex{interface type entry}
890 in \addtoindex{Java} is similar to a \addtoindex{C++} or
891 \addtoindex{Java} class with only abstract
892 methods and constant data members.}
895 \addtoindexx{interface type entry}
896 are represented by debugging information
898 tag \livetarg{chap:DWTAGinterfacetype}{DW\_TAG\_interface\_type}.
900 An interface type entry has
901 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
902 \addtoindexx{name attribute}
904 value is a null\dash terminated string containing the type name
905 as it appears in the source program.
907 The members of an interface are represented by debugging
908 information entries that are owned by the interface type
909 entry and that appear in the same order as the corresponding
910 declarations in the source program.
912 \subsection{Derived or Extended Structs, Classes and Interfaces}
913 \label{chap:derivedorextendedstructsclasesandinterfaces}
915 \textit{In \addtoindex{C++}, a class (or struct)
917 \addtoindexx{derived type (C++)|see{inheritance entry}}
918 be ``derived from'' or be a
919 ``subclass of'' another class.
920 In \addtoindex{Java}, an interface may ``extend''
921 \addtoindexx{extended type (Java)|see{inheritance entry}}
923 \addtoindexx{implementing type (Java)|see{inheritance entry}}
924 or more other interfaces, and a class may ``extend'' another
925 class and/or ``implement'' one or more interfaces. All of these
926 relationships may be described using the following. Note that
927 in \addtoindex{Java},
928 the distinction between extends and implements is
929 implied by the entities at the two ends of the relationship.}
931 A class type or interface type entry that describes a
932 derived, extended or implementing class or interface owns
933 \addtoindexx{implementing type (Java)|see{inheritance entry}}
934 debugging information entries describing each of the classes
935 or interfaces it is derived from, extending or implementing,
936 respectively, ordered as they were in the source program. Each
938 \addtoindexx{inheritance entry}
940 tag \livetarg{chap:DWTAGinheritance}{DW\_TAG\_inheritance}.
943 \addtoindexx{type attribute}
945 \addtoindexx{inheritance entry}
947 \livelink{chap:DWATtype}{DW\_AT\_type} attribute whose value is
948 a reference to the debugging information entry describing the
949 class or interface from which the parent class or structure
950 of the inheritance entry is derived, extended or implementing.
953 \addtoindexx{inheritance entry}
954 for a class that derives from or extends
955 \hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}
956 another class or struct also has
957 \addtoindexx{data member location attribute}
959 \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
960 attribute, whose value describes the location of the beginning
961 of the inherited type relative to the beginning address of the
962 derived class. If that value is a constant, it is the offset
963 in bytes from the beginning of the class to the beginning of
964 the inherited type. Otherwise, the value must be a location
965 description. In this latter case, the beginning address of
966 the derived class is pushed on the expression stack before
967 the \addtoindex{location description}
968 is evaluated and the result of the
969 evaluation is the location of the inherited type.
971 \textit{The interpretation of the value of this attribute for
972 inherited types is the same as the interpretation for data
974 (see Section \referfol{chap:datamemberentries}). }
977 \addtoindexx{inheritance entry}
979 \hypertarget{chap:DWATaccessibilitycppinheritedmembers}
981 \addtoindexx{accessibility attribute}
983 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
985 If no accessibility attribute
986 is present, private access is assumed for an entry of a class
987 and public access is assumed for an entry of an interface,
991 \hypertarget{chap:DWATvirtualityvirtualityofbaseclass}
992 the class referenced by the
993 \addtoindexx{inheritance entry}
994 inheritance entry serves
995 as a \addtoindex{C++} virtual base class, the inheritance entry has a
996 \livelink{chap:DWATvirtuality}{DW\_AT\_virtuality} attribute.
998 \textit{For a \addtoindex{C++} virtual base, the
999 \addtoindex{data member location attribute}
1000 will usually consist of a non-trivial
1001 \addtoindex{location description}.}
1003 \subsection{Access Declarations}
1004 \label{chap:accessdeclarations}
1006 \textit{In \addtoindex{C++}, a derived class may contain access declarations that
1007 \addtoindexx{access declaration entry}
1008 change the accessibility of individual class members from the
1009 overall accessibility specified by the inheritance declaration.
1010 A single access declaration may refer to a set of overloaded
1013 If a derived class or structure contains access declarations,
1014 each such declaration may be represented by a debugging
1015 information entry with the tag
1016 \livetarg{chap:DWTAGaccessdeclaration}{DW\_TAG\_access\_declaration}.
1018 such entry is a child of the class or structure type entry.
1020 An access declaration entry has
1021 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1022 \addtoindexx{name attribute}
1024 value is a null\dash terminated string representing the name used
1025 in the declaration in the source program, including any class
1026 or structure qualifiers.
1028 An access declaration entry
1029 \hypertarget{chap:DWATaccessibilitycppbaseclasses}
1032 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1033 attribute describing the declared accessibility of the named
1038 \subsection{Friends}
1039 \label{chap:friends}
1042 \addtoindexx{friend entry}
1043 declared by a structure, union or class
1044 \hypertarget{chap:DWATfriendfriendrelationship}
1045 type may be represented by a debugging information entry
1046 that is a child of the structure, union or class type entry;
1047 the friend entry has the
1048 tag \livetarg{chap:DWTAGfriend}{DW\_TAG\_friend}.
1051 \addtoindexx{friend attribute}
1052 a \livelink{chap:DWATfriend}{DW\_AT\_friend} attribute, whose value is
1053 a reference to the debugging information entry describing
1054 the declaration of the friend.
1057 \subsection{Data Member Entries}
1058 \label{chap:datamemberentries}
1060 A data member (as opposed to a member function) is
1061 represented by a debugging information entry with the
1062 tag \livetarg{chap:DWTAGmember}{DW\_TAG\_member}.
1064 \addtoindexx{member entry (data)}
1065 member entry for a named member has
1066 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1067 \addtoindexx{name attribute}
1068 whose value is a null\dash terminated
1069 string containing the member name as it appears in the source
1070 program. If the member entry describes an
1071 \addtoindex{anonymous union},
1072 the name attribute is omitted or the value of the attribute
1073 consists of a single zero byte.
1075 The data member entry has
1076 \addtoindexx{type attribute}
1078 \livelink{chap:DWATtype}{DW\_AT\_type} attribute to denote
1079 \addtoindexx{member entry (data)}
1080 the type of that member.
1082 A data member entry may
1083 \addtoindexx{accessibility attribute}
1085 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1086 attribute. If no accessibility attribute is present, private
1087 access is assumed for an entry of a class and public access
1088 is assumed for an entry of a structure, union, or interface.
1091 \hypertarget{chap:DWATmutablemutablepropertyofmemberdata}
1093 \addtoindexx{member entry (data)}
1095 \addtoindexx{mutable attribute}
1096 have a \livelink{chap:DWATmutable}{DW\_AT\_mutable} attribute,
1097 which is a \livelink{chap:flag}{flag}.
1098 This attribute indicates whether the data
1099 member was declared with the mutable storage class specifier.
1101 The beginning of a data member
1102 \addtoindexx{beginning of a data member}
1103 is described relative to
1104 \addtoindexx{beginning of an object}
1105 the beginning of the object in which it is immediately
1106 contained. In general, the beginning is characterized by
1107 both an address and a bit offset within the byte at that
1108 address. When the storage for an entity includes all of
1109 the bits in the beginning byte, the beginning bit offset is
1112 Bit offsets in DWARF use the bit numbering and direction
1113 conventions that are appropriate to the current language on
1117 \addtoindexx{member entry (data)}
1118 corresponding to a data member that is
1119 \hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}
1121 \hypertarget{chap:DWATdatamemberlocationdatamemberlocation}
1122 in a structure, union or class may have either
1123 \addtoindexx{data member location attribute}
1125 \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} attribute or a
1126 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1127 attribute. If the beginning of the data member is the same as
1128 the beginning of the containing entity then neither attribute
1132 For a \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} attribute
1133 \addtoindexx{data member location attribute}
1134 there are two cases:
1135 \begin{enumerate}[1. ]
1136 \item If the value is an integer constant, it is the offset
1137 in bytes from the beginning of the containing entity. If
1138 the beginning of the containing entity has a non-zero bit
1139 offset then the beginning of the member entry has that same
1142 \item Otherwise, the value must be a \addtoindex{location description}.
1144 this case, the beginning of the containing entity must be byte
1145 aligned. The beginning address is pushed on the DWARF stack
1146 before the \addtoindex{location} description is evaluated; the result of
1147 the evaluation is the base address of the member entry.
1149 \textit{The push on the DWARF expression stack of the base address of
1150 the containing construct is equivalent to execution of the
1151 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address} operation
1152 (see Section \refersec{chap:stackoperations});
1153 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address} therefore
1154 is not needed at the
1155 beginning of a \addtoindex{location description} for a data member.
1157 result of the evaluation is a location--either an address or
1158 the name of a register, not an offset to the member.}
1160 \textit{A \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
1162 \addtoindexx{data member location attribute}
1163 that has the form of a
1164 \addtoindex{location description} is not valid for a data member contained
1165 in an entity that is not byte aligned because DWARF operations
1166 do not allow for manipulating or computing bit offsets.}
1170 For a \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} attribute,
1171 the value is an integer constant
1172 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1173 that specifies the number of bits
1174 from the beginning of the containing entity to the beginning
1175 of the data member. This value must be greater than or equal
1176 to zero, but is not limited to less than the number of bits
1179 If the size of a data member is not the same as the size
1180 of the type given for the data member, the data member has
1181 \addtoindexx{bit size attribute}
1182 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1183 or a \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute whose
1184 integer constant value
1185 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1187 of storage needed to hold the value of the data member.
1189 \textit{Bit fields in \addtoindex{C} and \addtoindex{C++}
1191 \addtoindexx{bit fields}
1193 \addtoindexx{data bit offset}
1195 \addtoindexx{data bit size}
1197 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} and
1198 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attributes.}
1201 \textit{This Standard uses the following bit numbering and direction
1202 conventions in examples. These conventions are for illustrative
1203 purposes and other conventions may apply on particular
1206 \item \textit{For big\dash endian architectures, bit offsets are
1207 counted from high-order to low\dash order bits within a byte (or
1208 larger storage unit); in this case, the bit offset identifies
1209 the high\dash order bit of the object.}
1211 \item \textit{For little\dash endian architectures, bit offsets are
1212 counted from low\dash order to high\dash order bits within a byte (or
1213 larger storage unit); in this case, the bit offset identifies
1214 the low\dash order bit of the object.}
1218 \textit{In either case, the bit so identified is defined as the
1219 \addtoindexx{beginning of an object}
1220 beginning of the object.}
1222 \textit{For example, take one possible representation of the following
1223 \addtoindex{C} structure definition
1224 in both big\dash and little\dash endian byte orders:}
1235 \textit{Figures \referfol{fig:bigendiandatabitoffsets} and
1236 \refersec{fig:littleendiandatabitoffsets}
1237 show the structure layout
1238 and data bit offsets for example big\dash\ and little\dash endian
1239 architectures, respectively. Both diagrams show a structure
1240 that begins at address A and whose size is four bytes. Also,
1241 high order bits are to the left and low order bits are to
1251 Addresses increase ->
1252 | A | A + 1 | A + 2 | A + 3 |
1254 Data bit offsets increase ->
1255 +---------------+---------------+---------------+---------------+
1256 |0 4|5 10|11 15|16 23|24 31|
1257 | j | k | m | n | <pad> |
1259 +---------------------------------------------------------------+
1261 \caption{Big-endian data bit offsets}
1262 \label{fig:bigendiandatabitoffsets}
1271 <- Addresses increase
1272 | A | A + 1 | A + 2 | A + 3 |
1274 <- Data bit offsets increase
1275 +---------------+---------------+---------------+---------------+
1276 |31 24|23 16|15 11|10 5|4 0|
1277 | <pad> | n | m | k | j |
1279 +---------------------------------------------------------------+
1281 \caption{Little-endian data bit offsets}
1282 \label{fig:littleendiandatabitoffsets}
1285 \textit{Note that data member bit offsets in this example are the
1286 same for both big\dash\ and little\dash endian architectures even
1287 though the fields are allocated in different directions
1288 (high\dash order to low-order versus low\dash order to high\dash order);
1289 the bit naming conventions for memory and/or registers of
1290 the target architecture may or may not make this seem natural.}
1292 \textit{For a more extensive example showing nested and packed records
1294 Appendix \refersec{app:pascalexample}.}
1296 \textit{Attribute \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1298 \addtoindex{DWARF Version 4}
1299 and is also used for base types
1301 \refersec{chap:basetypeentries}).
1303 \livetarg{chap:DWATbitoffsetdatamemberbitlocation}
1304 attributes \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} and
1305 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} when used to
1306 identify the beginning of bit field data members as defined
1307 in DWARF V3 and earlier. The earlier attributes are defined
1308 in a manner suitable for bit field members on big-endian
1309 architectures but which is either awkward or incomplete for
1310 use on little-endian architectures.
1311 (\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} also
1312 has other uses that are not affected by this change.)}
1314 \textit{The \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
1315 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
1316 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
1317 attribute combination is deprecated for data members in DWARF
1318 Version 4, but implementations may continue to support this
1319 use for compatibility.}
1322 \addtoindex{DWARF Version 3}
1323 definitions of these attributes are
1325 \begin{myindentpara}{1cm}
1326 \textit{If the data member entry describes a bit field, then that
1327 entry has the following attributes:}
1330 \item \textit{A \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1331 attribute whose value
1332 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1333 is the number of bytes that contain an instance of the
1334 bit field and any padding bits.}
1336 \textit{The byte size attribute may be omitted if the size of the
1337 object containing the bit field can be inferred from the type
1338 attribute of the data member containing the bit field.}
1340 \item \textit{A \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
1342 \addtoindexx{bit offset attribute (V3)}
1344 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1345 is the number of bits to the left of the leftmost
1346 (most significant) bit of the bit field value.}
1348 \item \textit{A \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
1350 \addtoindexx{bit size attribute (V3)}
1352 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1353 is the number of bits occupied by the bit field value.}
1358 \addtoindex{location description} for a bit field calculates the address
1359 of an anonymous object containing the bit field. The address
1360 is relative to the structure, union, or class that most closely
1361 encloses the bit field declaration. The number of bytes in this
1362 anonymous object is the value of the byte size attribute of
1363 the bit field. The offset (in bits) from the most significant
1364 bit of the anonymous object to the most significant bit of
1365 the bit field is the value of the bit offset attribute.}
1369 \textit{Diagrams similar to the above that show the use of the
1370 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
1371 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
1372 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} attribute
1373 combination may be found in the
1374 \addtoindex{DWARF Version 3} Standard.}
1376 \textit{In comparing
1378 \addtoindexx{DWARF Version 3}
1380 \addtoindexx{DWARF Version 4}
1381 4, note that DWARF V4
1382 defines the following combinations of attributes:}
1385 \item \textit{either \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
1387 \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}
1388 (to specify the beginning of the data member)}
1390 % FIXME: the indentation of the following line is suspect.
1391 \textit{optionally together with}
1393 \item \textit{either \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or
1394 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} (to
1395 specify the size of the data member)}
1399 \textit{DWARF V3 defines the following combinations}
1402 \item \textit{\livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}
1403 (to specify the beginning
1404 of the data member, except this specification is only partial
1405 in the case of a bit field) }
1407 % FIXME: the indentation of the following line is suspect.
1408 \textit{optionally together with}
1410 \item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
1411 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and
1412 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
1413 (to further specify the beginning of a bit field data member
1414 as well as specify the size of the data member) }
1417 \subsection{Member Function Entries}
1418 \label{chap:memberfunctionentries}
1420 A member function is represented by a
1421 \addtoindexx{member function entry}
1422 debugging information entry
1424 \addtoindexx{subprogram entry!as member function}
1425 tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}.
1426 The member function entry
1427 may contain the same attributes and follows the same rules
1428 as non\dash member global subroutine entries
1429 (see Section \refersec{chap:subroutineandentrypointentries}).
1432 \addtoindexx{accessibility attribute}
1433 member function entry may have a
1434 \livelink{chap:DWATaccessibility}{DW\_AT\_accessibility}
1435 attribute. If no accessibility attribute is present, private
1436 access is assumed for an entry of a class and public access
1437 is assumed for an entry of a structure, union or interface.
1440 \hypertarget{chap:DWATvirtualityvirtualityoffunction}
1441 the member function entry describes a virtual function,
1442 then that entry has a
1443 \livelink{chap:DWATvirtuality}{DW\_AT\_virtuality} attribute.
1446 \hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}
1447 the member function entry describes an explicit member
1448 function, then that entry has
1449 \addtoindexx{explicit attribute}
1451 \livelink{chap:DWATexplicit}{DW\_AT\_explicit} attribute.
1454 \hypertarget{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}
1455 entry for a virtual function also has a
1456 \livelink{chap:DWATvtableelemlocation}{DW\_AT\_vtable\_elem\_location}
1457 \addtoindexi{attribute}{vtable element location attribute} whose value contains
1458 a \addtoindex{location description}
1459 yielding the address of the slot
1460 for the function within the virtual function table for the
1461 enclosing class. The address of an object of the enclosing
1462 type is pushed onto the expression stack before the location
1463 description is evaluated.
1466 \hypertarget{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}
1467 the member function entry describes a non\dash static member
1468 \addtoindexx{this pointer attribute|see{object pointer attribute}}
1469 function, then that entry
1470 \addtoindexx{self pointer attribute|see{object pointer attribute}}
1472 \addtoindexx{object pointer attribute}
1473 a \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}
1475 whose value is a reference to the formal parameter entry
1476 that corresponds to the object for which the function is
1477 called. The name attribute of that formal parameter is defined
1478 by the current language (for example,
1479 this for \addtoindex{C++} or self
1480 for \addtoindex{Objective C}
1481 and some other languages). That parameter
1482 also has a \livelink{chap:DWATartificial}{DW\_AT\_artificial} attribute whose value is true.
1484 Conversely, if the member function entry describes a static
1485 member function, the entry does not have
1486 \addtoindexx{object pointer attribute}
1488 \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}
1491 If the member function entry describes a non\dash static member
1492 function that has a const\dash volatile qualification, then
1493 the entry describes a non\dash static member function whose
1494 object formal parameter has a type that has an equivalent
1495 const\dash volatile qualification.
1497 If a subroutine entry represents the defining declaration
1498 of a member function and that definition appears outside of
1499 the body of the enclosing class declaration, the subroutine
1501 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute,
1502 \addtoindexx{specification attribute}
1504 a reference to the debugging information entry representing
1505 the declaration of this function member. The referenced entry
1506 will be a child of some class (or structure) type entry.
1508 Subroutine entries containing the
1509 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute
1510 \addtoindexx{specification attribute}
1511 do not need to duplicate information provided
1512 by the declaration entry referenced by the specification
1513 attribute. In particular, such entries do not need to contain
1514 attributes for the name or return type of the function member
1515 whose definition they represent.
1517 \subsection{Class Template Instantiations}
1518 \label{chap:classtemplateinstantiations}
1520 \textit{In \addtoindex{C++} a class template is a generic definition of a class
1521 type that may be instantiated when an instance of the class
1522 is declared or defined. The generic description of the
1523 class may include both parameterized types and parameterized
1524 constant values. DWARF does not represent the generic template
1525 definition, but does represent each instantiation.}
1527 A class template instantiation is represented by a
1528 debugging information entry with the tag \livelink{chap:DWTAGclasstype}{DW\_TAG\_class\_type},
1529 \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type} or
1530 \livelink{chap:DWTAGuniontype}{DW\_TAG\_union\_type}. With five
1531 exceptions, such an entry will contain the same attributes
1532 and have the same types of child entries as would an entry
1533 for a class type defined explicitly using the instantiation
1534 types and values. The exceptions are:
1536 \begin{enumerate}[1. ]
1537 \item Each formal parameterized type declaration appearing in the
1538 template definition is represented by a debugging information
1540 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}. Each
1541 such entry may have a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1542 \addtoindexx{name attribute}
1544 a null\dash terminated string containing the name of the formal
1545 type parameter as it appears in the source program. The
1546 template type parameter entry also has
1547 \addtoindexx{type attribute}
1549 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1550 describing the actual type by which the formal is replaced
1551 for this instantiation.
1553 \item Each formal parameterized value declaration appearing in the
1554 template definition is represented by a
1555 debugging information entry with the
1556 \addtoindexx{template value parameter entry}
1557 tag \livetarg{chap:DWTAGtemplatevalueparameter}{DW\_TAG\_template\_value\_parameter}.
1559 such entry may have a
1560 \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1561 \addtoindexx{name attribute}
1563 a null\dash terminated string containing the name of the formal
1564 value parameter as it appears in the source program.
1566 \hypertarget{chap:DWATconstvaluetemplatevalueparameter}
1567 template value parameter entry
1568 \addtoindexx{template value parameter entry}
1570 \addtoindexx{type attribute}
1572 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1573 describing the type of the parameterized value. Finally,
1574 the template value parameter entry has a
1575 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}
1576 attribute, whose value is the actual constant value of the
1577 value parameter for this instantiation as represented on the
1578 target architecture.
1581 \item The class type entry and each of its child entries references
1582 a \addtoindex{template type parameter entry} in any circumstance where the
1583 source template definition references a formal parameterized
1585 Similarly, the class type entry and each of its child
1586 entries references a template value parameter entry in any
1587 circumstance where the source template definition references
1588 a formal parameterized value.
1590 \item If the compiler has generated a special compilation unit to
1592 \addtoindexx{template instantiation!and special compilation unit}
1593 template instantiation and that special compilation
1594 unit has a different name from the compilation unit containing
1595 the template definition, the name attribute for the debugging
1596 information entry representing the special compilation unit
1597 should be empty or omitted.
1600 \item If the class type entry representing the template
1601 instantiation or any of its child entries contains declaration
1602 coordinate attributes, those attributes should refer to
1603 the source for the template definition, not to any source
1604 generated artificially by the compiler.
1608 \subsection{Variant Entries}
1609 \label{chap:variantentries}
1611 A variant part of a structure is represented by a debugging
1612 information entry\addtoindexx{variant part entry} with the
1613 tag \livetarg{chap:DWTAGvariantpart}{DW\_TAG\_variant\_part} and is
1614 owned by the corresponding structure type entry.
1616 If the variant part has a discriminant, the discriminant is
1617 \hypertarget{chap:DWATdiscrdiscriminantofvariantpart}
1619 \addtoindexx{discriminant (entry)}
1620 separate debugging information entry which
1621 is a child of the variant part entry. This entry has the form
1623 \addtoindexx{member entry (data)!as discriminant}
1624 structure data member entry. The variant part entry will
1625 \addtoindexx{discriminant attribute}
1627 \livelink{chap:DWATdiscr}{DW\_AT\_discr} attribute
1628 whose value is a reference to
1629 the member entry for the discriminant.
1631 If the variant part does not have a discriminant (tag field),
1632 the variant part entry has
1633 \addtoindexx{type attribute}
1635 \livelink{chap:DWATtype}{DW\_AT\_type} attribute to represent
1638 Each variant of a particular variant part is represented by
1639 \hypertarget{chap:DWATdiscrvaluediscriminantvalue}
1640 a debugging information entry\addtoindexx{variant entry} with the
1641 tag \livetarg{chap:DWTAGvariant}{DW\_TAG\_variant}
1642 and is a child of the variant part entry. The value that
1643 selects a given variant may be represented in one of three
1644 ways. The variant entry may have a
1645 \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value} attribute
1646 whose value represents a single case label. The value of this
1647 attribute is encoded as an LEB128 number. The number is signed
1648 if the tag type for the variant part containing this variant
1649 is a signed type. The number is unsigned if the tag type is
1653 \hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}
1654 the variant entry may contain
1655 \addtoindexx{discriminant list attribute}
1657 \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list}
1658 attribute, whose value represents a list of discriminant
1659 values. This list is represented by any of the
1660 \livelink{chap:block}{block} forms and
1661 may contain a mixture of case labels and label ranges. Each
1662 item on the list is prefixed with a discriminant value
1663 descriptor that determines whether the list item represents
1664 a single label or a label range. A single case label is
1665 represented as an LEB128 number as defined above for
1666 \addtoindexx{discriminant value attribute}
1668 \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value}
1669 attribute. A label range is represented by
1670 two LEB128 numbers, the low value of the range followed by the
1671 high value. Both values follow the rules for signedness just
1672 described. The discriminant value descriptor is an integer
1673 constant that may have one of the values given in
1674 Table \refersec{tab:discriminantdescriptorvalues}.
1676 \begin{simplenametable}[1.4in]{Discriminant descriptor values}{tab:discriminantdescriptorvalues}
1677 \addtoindex{DW\_DSC\_label} \\
1678 \addtoindex{DW\_DSC\_range} \\
1679 \end{simplenametable}
1681 If a variant entry has neither a \livelink{chap:DWATdiscrvalue}{DW\_AT\_discr\_value}
1682 attribute nor a \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list} attribute, or if it has
1683 a \livelink{chap:DWATdiscrlist}{DW\_AT\_discr\_list} attribute with 0 size, the variant is a
1686 The components selected by a particular variant are represented
1687 by debugging information entries owned by the corresponding
1688 variant entry and appear in the same order as the corresponding
1689 declarations in the source program.
1691 \section{Condition Entries}
1692 \label{chap:conditionentries}
1694 \textit{COBOL has the notion of
1695 \addtoindexx{level-88 condition, COBOL}
1696 a ``level\dash 88 condition'' that
1697 associates a data item, called the conditional variable, with
1698 a set of one or more constant values and/or value ranges.
1699 Semantically, the condition is \textquoteleft true\textquoteright if the conditional
1700 variable's value matches any of the described constants,
1701 and the condition is \textquoteleft false\textquoteright otherwise.}
1703 The \livetarg{chap:DWTAGcondition}{DW\_TAG\_condition}
1704 debugging information entry\addtoindexx{condition entry}
1706 logical condition that tests whether a given data item\textquoteright s
1707 value matches one of a set of constant values. If a name
1708 has been given to the condition, the condition entry has a
1709 \livelink{chap:DWATname}{DW\_AT\_name} attribute
1710 \addtoindexx{name attribute}
1711 whose value is a null\dash terminated string
1712 giving the condition name as it appears in the source program.
1714 The condition entry's parent entry describes the conditional
1715 variable; normally this will be a \livelink{chap:DWTAGvariable}{DW\_TAG\_variable},
1716 \livelink{chap:DWTAGmember}{DW\_TAG\_member} or
1717 \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter} entry.
1719 \addtoindexx{formal parameter entry}
1721 entry has an array type, the condition can test any individual
1722 element, but not the array as a whole. The condition entry
1723 implicitly specifies a \doublequote{comparison type} that is the
1724 type of an array element if the parent has an array type;
1725 otherwise it is the type of the parent entry.
1727 The condition entry owns \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} and/or
1728 \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type} entries that describe the constant
1729 values associated with the condition. If any child entry
1730 \addtoindexx{type attribute}
1732 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute,
1733 that attribute should describe a type
1734 compatible with the comparison type (according to the source
1735 language); otherwise the child\textquoteright s type is the same as the
1738 \textit{For conditional variables with alphanumeric types, COBOL
1739 permits a source program to provide ranges of alphanumeric
1740 constants in the condition. Normally a subrange type entry
1741 does not describe ranges of strings; however, this can be
1742 represented using bounds attributes that are references to
1743 constant entries describing strings. A subrange type entry may
1744 refer to constant entries that are siblings of the subrange
1748 \section{Enumeration Type Entries}
1749 \label{chap:enumerationtypeentries}
1751 \textit{An \doublequote{enumeration type} is a scalar that can assume one of
1752 a fixed number of symbolic values.}
1754 An enumeration type is represented by a debugging information
1756 \livetarg{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}.
1758 If a name has been given to the enumeration type in the source
1759 program, then the corresponding enumeration type entry has
1760 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1761 \addtoindexx{name attribute}
1762 whose value is a null\dash terminated
1763 string containing the enumeration type name as it appears
1764 in the source program. This entry also has a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
1765 attribute whose integer constant value is the number of bytes
1766 required to hold an instance of the enumeration.
1768 The \addtoindex{enumeration type entry}
1770 \addtoindexx{type attribute}
1771 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1772 which refers to the underlying data type used to implement
1775 If an enumeration type has type safe
1776 \addtoindexx{type safe enumeration types}
1779 \begin{enumerate}[1. ]
1780 \item Enumerators are contained in the scope of the enumeration type, and/or
1782 \item Enumerators are not implicitly converted to another type
1785 then the \addtoindex{enumeration type entry} may
1786 \addtoindexx{enum class|see{type-safe enumeration}}
1787 have a \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}
1788 attribute, which is a \livelink{chap:flag}{flag}.
1789 In a language that offers only
1790 one kind of enumeration declaration, this attribute is not
1793 \textit{In \addtoindex{C} or \addtoindex{C++},
1794 the underlying type will be the appropriate
1795 integral type determined by the compiler from the properties of
1796 \hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}
1797 the enumeration literal values.
1798 A \addtoindex{C++} type declaration written
1799 using enum class declares a strongly typed enumeration and
1800 is represented using \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}
1801 in combination with \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}.}
1803 Each enumeration literal is represented by a debugging
1804 \addtoindexx{enumeration literal|see{enumeration entry}}
1805 information entry with the
1806 tag \livetarg{chap:DWTAGenumerator}{DW\_TAG\_enumerator}.
1808 such entry is a child of the
1809 \addtoindex{enumeration type entry}, and the
1810 enumerator entries appear in the same order as the declarations
1811 of the enumeration literals in the source program.
1813 Each \addtoindex{enumerator entry} has a
1814 \livelink{chap:DWATname}{DW\_AT\_name} attribute, whose
1815 \addtoindexx{name attribute}
1816 value is a null\dash terminated string containing the name of the
1817 \hypertarget{chap:DWATconstvalueenumerationliteralvalue}
1818 enumeration literal as it appears in the source program.
1819 Each enumerator entry also has a
1820 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value} attribute,
1821 whose value is the actual numeric value of the enumerator as
1822 represented on the target system.
1825 If the enumeration type occurs as the description of a
1826 \addtoindexx{enumeration type endry!as array dimension}
1827 dimension of an array type, and the stride for that dimension
1828 \hypertarget{chap:DWATbytestrideenumerationstridedimensionofarraytype}
1829 is different than what would otherwise be determined, then
1830 \hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}
1831 the enumeration type entry has either a
1832 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
1833 or \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
1834 \addtoindexx{bit stride attribute}
1835 which specifies the separation
1836 between successive elements along the dimension as described
1838 Section \refersec{chap:visibilityofdeclarations}.
1840 \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
1841 \addtoindexx{bit stride attribute}
1842 is interpreted as bits and the value of
1843 \addtoindexx{byte stride attribute}
1845 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}
1846 attribute is interpreted as bytes.
1849 \section{Subroutine Type Entries}
1850 \label{chap:subroutinetypeentries}
1852 \textit{It is possible in \addtoindex{C}
1853 to declare pointers to subroutines
1854 that return a value of a specific type. In both
1855 \addtoindex{C} and \addtoindex{C++},
1856 it is possible to declare pointers to subroutines that not
1857 only return a value of a specific type, but accept only
1858 arguments of specific types. The type of such pointers would
1859 be described with a ``pointer to'' modifier applied to a
1860 user\dash defined type.}
1862 A subroutine type is represented by a debugging information
1864 \addtoindexx{subroutine type entry}
1865 tag \livetarg{chap:DWTAGsubroutinetype}{DW\_TAG\_subroutine\_type}.
1867 been given to the subroutine type in the source program,
1868 then the corresponding subroutine type entry has
1869 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1870 \addtoindexx{name attribute}
1871 whose value is a null\dash terminated string containing
1872 the subroutine type name as it appears in the source program.
1874 If the subroutine type describes a function that returns
1875 a value, then the subroutine type entry has
1876 \addtoindexx{type attribute}
1877 a \livelink{chap:DWATtype}{DW\_AT\_type}
1878 attribute to denote the type returned by the subroutine. If
1879 the types of the arguments are necessary to describe the
1880 subroutine type, then the corresponding subroutine type
1881 entry owns debugging information entries that describe the
1882 arguments. These debugging information entries appear in the
1883 order that the corresponding argument types appear in the
1886 \textit{In \addtoindex{C} there
1887 is a difference between the types of functions
1888 declared using function prototype style declarations and
1889 those declared using non\dash prototype declarations.}
1892 \hypertarget{chap:DWATprototypedsubroutineprototype}
1893 subroutine entry declared with a function prototype style
1894 declaration may have
1895 \addtoindexx{prototyped attribute}
1897 \livelink{chap:DWATprototyped}{DW\_AT\_prototyped} attribute, which is
1898 a \livelink{chap:flag}{flag}.
1900 Each debugging information entry owned by a subroutine
1901 type entry has a tag whose value has one of two possible
1904 \begin{enumerate}[1. ]
1905 \item The formal parameters of a parameter list (that have a
1906 specific type) are represented by a debugging information entry
1907 with the tag \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}.
1908 Each formal parameter
1910 \addtoindexx{type attribute}
1911 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute that refers to the type of
1912 the formal parameter.
1914 \item The unspecified parameters of a variable parameter list
1915 \addtoindexx{unspecified parameters entry}
1917 \addtoindexx{... parameters|see{unspecified parameters entry}}
1918 represented by a debugging information entry with the
1919 tag \livelink{chap:DWTAGunspecifiedparameters}{DW\_TAG\_unspecified\_parameters}.
1924 \section{String Type Entries}
1925 \label{chap:stringtypeentries}
1927 \textit{A ``string'' is a sequence of characters that have specific
1928 \addtoindexx{string type entry}
1929 semantics and operations that separate them from arrays of
1931 \addtoindex{Fortran} is one of the languages that has a string
1932 type. Note that ``string'' in this context refers to a target
1933 machine concept, not the class string as used in this document
1934 (except for the name attribute).}
1936 A string type is represented by a debugging information entry
1937 with the tag \livetarg{chap:DWTAGstringtype}{DW\_TAG\_string\_type}.
1938 If a name has been given to
1939 the string type in the source program, then the corresponding
1940 string type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1941 \addtoindexx{name attribute}
1943 a null\dash terminated string containing the string type name as
1944 it appears in the source program.
1947 \hypertarget{chap:DWATstringlengthstringlengthofstringtype}
1948 string type entry may have a
1949 \livelink{chap:DWATstringlength}{DW\_AT\_string\_length} attribute
1951 \addtoindexx{string length attribute}
1953 \addtoindex{location description} yielding the location
1954 where the length of the string is stored in the program. The
1955 string type entry may also have a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute
1956 or \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute, whose value
1957 (see Section \refersec{chap:byteandbitsizes})
1958 is the size of the data to be retrieved from the location
1959 referenced by the string length attribute. If no (byte or bit)
1960 size attribute is present, the size of the data to be retrieved
1962 \addtoindex{size of an address} on the target machine.
1964 If no string length attribute is present, the string type
1965 entry may have a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or
1966 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
1967 attribute, whose value
1968 (see Section \refersec{chap:byteandbitsizes})
1970 storage needed to hold a value of the string type.
1973 \section{Set Type Entries}
1974 \label{chap:settypeentries}
1976 \textit{\addtoindex{Pascal} provides the concept of a \doublequote{set,} which represents
1977 a group of values of ordinal type.}
1979 A set is represented by a debugging information entry with
1980 the tag \livetarg{chap:DWTAGsettype}{DW\_TAG\_set\_type}.
1981 \addtoindexx{set type entry}
1982 If a name has been given to the
1983 set type, then the set type entry has
1984 a \livelink{chap:DWATname}{DW\_AT\_name} attribute
1985 \addtoindexx{name attribute}
1986 whose value is a null\dash terminated string containing the
1987 set type name as it appears in the source program.
1989 The set type entry has
1990 \addtoindexx{type attribute}
1991 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to denote the
1992 type of an element of the set.
1994 If the amount of storage allocated to hold each element of an
1995 object of the given set type is different from the amount of
1996 storage that is normally allocated to hold an individual object
1997 of the indicated element type, then the set type entry has
1998 either a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute, or
1999 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute
2000 whose value (see Section \refersec{chap:byteandbitsizes}) is
2001 the amount of storage needed to hold a value of the set type.
2004 \section{Subrange Type Entries}
2005 \label{chap:subrangetypeentries}
2007 \textit{Several languages support the concept of a ``subrange''
2008 type object. These objects can represent a subset of the
2009 values that an object of the basis type for the subrange can
2011 Subrange type entries may also be used to represent
2012 the bounds of array dimensions.}
2014 A subrange type is represented by a debugging information
2016 \addtoindexx{subrange type entry}
2017 tag \livetarg{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}.
2019 given to the subrange type, then the subrange type entry
2020 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
2021 \addtoindexx{name attribute}
2022 whose value is a null\dash terminated
2023 string containing the subrange type name as it appears in
2026 The subrange entry may have
2027 \addtoindexx{type attribute}
2028 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to describe
2029 the type of object, called the basis type, of whose values
2030 this subrange is a subset.
2032 If the amount of storage allocated to hold each element of an
2033 object of the given subrange type is different from the amount
2034 of storage that is normally allocated to hold an individual
2035 object of the indicated element type, then the subrange
2037 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or
2038 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
2039 attribute, whose value
2040 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
2042 storage needed to hold a value of the subrange type.
2045 \hypertarget{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}
2046 subrange entry may have
2047 \addtoindexx{threads scaled attribute}
2049 \livelink{chap:DWATthreadsscaled}{DW\_AT\_threads\_scaled} attribute,
2050 which is a \livelink{chap:flag}{flag}.
2051 If present, this attribute indicates whether
2052 this subrange represents a \addtoindex{UPC} array bound which is scaled
2053 by the runtime THREADS value (the number of UPC threads in
2054 this execution of the program).
2056 \textit{This allows the representation of a \addtoindex{UPC} shared array such as}
2058 \begin{lstlisting}[numbers=none]
2059 int shared foo[34*THREADS][10][20];
2063 \hypertarget{chap:DWATlowerboundlowerboundofsubrange}
2065 \hypertarget{chap:DWATupperboundupperboundofsubrange}
2066 entry may have the attributes
2067 \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}
2068 \addtoindexx{lower bound attribute}
2069 and \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}
2070 \addtoindexx{upper bound attribute} to specify, respectively, the lower
2071 and upper bound values of the subrange. The
2072 \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}
2074 \hypertarget{chap:DWATcountelementsofsubrangetype}
2076 % FIXME: The following matches DWARF4: odd as there is no default count.
2077 \addtoindexx{count attribute!default}
2079 \addtoindexx{count attribute}
2081 \livelink{chap:DWATcount}{DW\_AT\_count} attribute,
2083 value describes the number of elements in the subrange rather
2084 than the value of the last element. The value of each of
2085 these attributes is determined as described in
2086 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2088 If the lower bound value is missing, the value is assumed to
2089 be a language\dash dependent default constant.
2090 \addtoindexx{lower bound attribute!default}
2091 The default lower bound is 0 for
2092 \addtoindex{C}, \addtoindex{C++},
2095 \addtoindex{Objective C},
2096 \addtoindex{Objective C++},
2097 \addtoindex{Python}, and
2099 The default lower bound is 1 for
2100 \addtoindex{Ada}, \addtoindex{COBOL},
2101 \addtoindex{Fortran},
2102 \addtoindex{Modula-2},
2103 \addtoindex{Pascal} and
2106 \textit{No other default lower bound values are currently defined.}
2108 If the upper bound and count are missing, then the upper bound value is
2109 \textit{unknown}.\addtoindexx{upper bound attribute!default unknown}
2111 If the subrange entry has no type attribute describing the
2112 basis type, the basis type is assumed to be the same as
2113 the object described by the lower bound attribute (if it
2114 references an object). If there is no lower bound attribute,
2115 or that attribute does not reference an object, the basis type
2116 is the type of the upper bound or \addtoindex{count attribute}
2118 of them references an object). If there is no upper bound or
2119 count attribute, or neither references an object, the type is
2120 assumed to be the same type, in the source language of the
2121 compilation unit containing the subrange entry, as a signed
2122 integer with the same size as an address on the target machine.
2124 If the subrange type occurs as the description of a dimension
2125 of an array type, and the stride for that dimension is
2126 \hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}
2127 different than what would otherwise be determined, then
2128 \hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}
2129 the subrange type entry has either
2130 \addtoindexx{byte stride attribute}
2132 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride} or
2133 \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride} attribute
2134 \addtoindexx{bit stride attribute}
2135 which specifies the separation
2136 between successive elements along the dimension as described
2138 Section \refersec{chap:byteandbitsizes}.
2140 \textit{Note that the stride can be negative.}
2142 \section{Pointer to Member Type Entries}
2143 \label{chap:pointertomembertypeentries}
2145 \textit{In \addtoindex{C++}, a
2146 pointer to a data or function member of a class or
2147 structure is a unique type.}
2149 A debugging information entry representing the type of an
2150 object that is a pointer to a structure or class member has
2151 the tag \livetarg{chap:DWTAGptrtomembertype}{DW\_TAG\_ptr\_to\_member\_type}.
2153 If the \addtoindex{pointer to member type} has a name, the
2154 \addtoindexx{pointer to member type entry}
2155 pointer to member entry has a
2156 \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2157 \addtoindexx{name attribute}
2159 null\dash terminated string containing the type name as it appears
2160 in the source program.
2162 The \addtoindex{pointer to member} entry
2164 \addtoindexx{type attribute}
2165 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute to
2166 describe the type of the class or structure member to which
2167 objects of this type may point.
2169 The \addtoindex{pointer to member} entry also
2170 \hypertarget{chap:DWATcontainingtypecontainingtypeofpointertomembertype}
2172 \livelink{chap:DWATcontainingtype}{DW\_AT\_containing\_type}
2173 attribute, whose value is a reference to a debugging
2174 information entry for the class or structure to whose members
2175 objects of this type may point.
2178 \hypertarget{chap:DWATuselocationmemberlocationforpointertomembertype}
2180 \addtoindex{pointer to member entry}
2182 \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} attribute
2183 \addtoindexx{use location attribute}
2185 \addtoindex{location description} that computes the
2186 address of the member of the class to which the pointer to
2187 member entry points.
2189 \textit{The method used to find the address of a given member of a
2190 class or structure is common to any instance of that class
2191 or structure and to any instance of the pointer or member
2192 type. The method is thus associated with the type entry,
2193 rather than with each instance of the type.}
2195 The \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description is used in conjunction
2196 with the location descriptions for a particular object of the
2197 given \addtoindex{pointer to member type} and for a particular structure or
2198 class instance. The \livelink{chap:DWATuselocation}{DW\_AT\_use\_location}
2199 attribute expects two values to be
2200 \addtoindexi{pushed}{address!implicit push for member operator}
2201 onto the DWARF expression stack before
2202 the \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description is evaluated.
2204 \addtoindexi{pushed}{address!implicit push for member operator}
2205 is the value of the \addtoindex{pointer to member} object
2206 itself. The second value
2207 \addtoindexi{pushed}{address!implicit push for member operator}
2208 is the base address of the
2209 entire structure or union instance containing the member
2210 whose address is being calculated.
2212 \textit{For an expression such as}
2214 \begin{lstlisting}[numbers=none]
2217 % FIXME: object and mbr\_ptr should be distinguished from italic. See DW4.
2218 \textit{where mbr\_ptr has some \addtoindex{pointer to member type}, a debugger should:}
2220 \textit{1. Push the value of mbr\_ptr onto the DWARF expression stack.}
2222 \textit{2. Push the base address of object onto the DWARF expression stack.}
2224 \textit{3. Evaluate the \livelink{chap:DWATuselocation}{DW\_AT\_use\_location} description
2225 given in the type of mbr\_ptr.}
2227 \section{File Type Entries}
2228 \label{chap:filetypeentries}
2230 \textit{Some languages, such as \addtoindex{Pascal},
2231 provide a data type to represent
2234 A file type is represented by a debugging information entry
2236 \addtoindexx{file type entry}
2238 \livetarg{chap:DWTAGfiletype}{DW\_TAG\_file\_type}.
2239 If the file type has a name,
2240 the file type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2241 \addtoindexx{name attribute}
2243 is a null\dash terminated string containing the type name as it
2244 appears in the source program.
2246 The file type entry has
2247 \addtoindexx{type attribute}
2248 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute describing
2249 the type of the objects contained in the file.
2251 The file type entry also
2252 \addtoindexx{byte size}
2254 \addtoindexx{bit size}
2256 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or
2257 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute, whose value
2258 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
2259 is the amount of storage need to hold a value of the file type.
2261 \section{Dynamic Type Properties}
2262 \label{chap:dynamictypeproperties}
2263 \subsection{Data Location}
2264 \label{chap:datalocation}
2266 \textit{Some languages may represent objects using descriptors to hold
2267 information, including a location and/or run\dash time parameters,
2268 about the data that represents the value for that object.}
2270 \hypertarget{chap:DWATdatalocationindirectiontoactualdata}
2271 The \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
2272 attribute may be used with any
2273 \addtoindexx{data location attribute}
2274 type that provides one or more levels of
2275 \addtoindexx{hidden indirection|see{data location attribute}}
2277 and/or run\dash time parameters in its representation. Its value
2278 is a \addtoindex{location description}.
2279 The result of evaluating this
2280 description yields the location of the data for an object.
2281 When this attribute is omitted, the address of the data is
2282 the same as the address of the object.
2284 \textit{This location description will typically begin with
2285 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
2286 which loads the address of the
2287 object which can then serve as a descriptor in subsequent
2288 calculation. For an example using
2289 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
2290 for a \addtoindex{Fortran 90 array}, see
2291 Appendix \refersec{app:fortran90example}.}
2293 \subsection{Allocation and Association Status}
2294 \label{chap:allocationandassociationstatus}
2296 \textit{Some languages, such as \addtoindex{Fortran 90},
2297 provide types whose values
2298 may be dynamically allocated or associated with a variable
2299 under explicit program control.}
2301 \hypertarget{chap:DWATallocatedallocationstatusoftypes}
2303 \livelink{chap:DWATallocated}{DW\_AT\_allocated}
2305 \addtoindexx{allocated attribute}
2306 may optionally be used with any
2307 type for which objects of the type can be explicitly allocated
2308 and deallocated. The presence of the attribute indicates that
2309 objects of the type are allocatable and deallocatable. The
2310 integer value of the attribute (see below) specifies whether
2311 an object of the type is
2312 currently allocated or not.
2314 \hypertarget{chap:DWATassociatedassociationstatusoftypes}
2316 \livelink{chap:DWATassociated}{DW\_AT\_associated} attribute
2318 \addtoindexx{associated attribute}
2319 optionally be used with
2320 any type for which objects of the type can be dynamically
2321 associated with other objects. The presence of the attribute
2322 indicates that objects of the type can be associated. The
2323 integer value of the attribute (see below) indicates whether
2324 an object of the type is currently associated or not.
2326 \textit{While these attributes are defined specifically with
2327 \addtoindex{Fortran 90} ALLOCATABLE and POINTER types
2328 in mind, usage is not limited
2329 to just that language.}
2331 The value of these attributes is determined as described in
2332 Section \refersec{chap:staticanddynamicvaluesofattributes}.
2334 A non\dash zero value is interpreted as allocated or associated,
2335 and zero is interpreted as not allocated or not associated.
2337 \textit{For \addtoindex{Fortran 90},
2338 if the \livelink{chap:DWATassociated}{DW\_AT\_associated}
2339 attribute is present,
2340 the type has the POINTER property where either the parent
2341 variable is never associated with a dynamic object or the
2342 implementation does not track whether the associated object
2343 is static or dynamic. If the \livelink{chap:DWATallocated}{DW\_AT\_allocated} attribute is
2344 present and the \livelink{chap:DWATassociated}{DW\_AT\_associated} attribute is not, the type
2345 has the ALLOCATABLE property. If both attributes are present,
2346 then the type should be assumed to have the POINTER property
2347 (and not ALLOCATABLE); the \livelink{chap:DWATallocated}{DW\_AT\_allocated} attribute may then
2348 be used to indicate that the association status of the object
2349 resulted from execution of an ALLOCATE statement rather than
2350 pointer assignment.}
2352 \textit{For examples using
2353 \livelink{chap:DWATallocated}{DW\_AT\_allocated} for \addtoindex{Ada} and
2354 \addtoindex{Fortran 90}
2356 see Appendix \refersec{app:aggregateexamples}.}
2360 \section{Template Alias Entries}
2361 \label{chap:templatealiasentries}
2363 A type named using a template alias is represented
2364 by a debugging information entry
2365 \addtoindexx{template alias entry}
2367 \livetarg{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}.
2368 The template alias entry has a
2369 \livelink{chap:DWATname}{DW\_AT\_name} attribute
2370 \addtoindexx{name attribute}
2371 whose value is a null\dash terminated string
2372 containing the name of the template alias as it appears in
2373 the source program. The template alias entry also contains
2374 \addtoindexx{type attribute}
2376 \livelink{chap:DWATtype}{DW\_AT\_type} attribute
2377 whose value is a reference to the type
2378 named by the template alias.
2381 The template alias entry has the following child entries:
2382 \begin{enumerate}[1. ]
2383 \item Each formal parameterized type declaration appearing
2384 in the template alias declaration is represented
2385 by a debugging information entry with the tag
2386 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}.
2387 Each such entry may have
2388 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2389 \addtoindexx{name attribute}
2390 whose value is a null\dash terminated
2391 string containing the name of the formal type parameter as it
2392 appears in the source program. The template type parameter
2394 \addtoindexx{type attribute}
2395 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
2396 describing the actual
2397 type by which the formal is replaced for this instantiation.
2399 \item Each formal parameterized value declaration
2400 appearing in the template alias declaration is
2401 represented by a debugging information entry with the tag
2402 \livelink{chap:DWTAGtemplatevalueparameter}{DW\_TAG\_template\_value\_parameter}.
2403 Each such entry may have
2404 a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
2405 \addtoindexx{name attribute}
2406 whose value is a null\dash terminated
2407 string containing the name of the formal value parameter
2408 as it appears in the source program. The template value
2409 parameter entry also has
2410 \addtoindexx{type attribute}
2411 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute describing
2412 the type of the parameterized value. Finally, the template
2413 value parameter entry has a \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}
2414 attribute, whose value is the actual constant value of the value parameter for
2415 this instantiation as represented on the target architecture.