3eaa8dd4c37c0eda73c75f28d035a28534d1168c
[dwarf-doc.git] / dwarf5 / latexdoc / typeentries.tex
1 \chapter{Type Entries}
2 \label{chap:typeentries}
3 This section presents the debugging information entries
4 that describe program types: base types, modified types and
5 user\dash defined types.
6
7 If the scope of the declaration of a named type begins after
8 \hypertarget{chap:DWATstartscopetypedeclaration}
9 the low pc value for the scope most closely enclosing the
10 declaration, the declaration may have a 
11 \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope}
12 attribute as described for objects in 
13 Section \refersec{chap:dataobjectentries}.
14
15 \section{Base Type Entries}
16 \label{chap:basetypeentries}
17
18 \textit{A base type is a data type that is not defined in terms of
19 other data types. Each programming language has a set of base
20 types that are considered to be built into that language.}
21
22 A base type is represented by a debugging information entry
23 with the tag 
24 \livetarg{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}.
25
26 A \addtoindex{base type entry}
27 has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is
28 a null\dash terminated string containing the name of the base type
29 as recognized by the programming language of the compilation
30 unit containing the base type entry.
31
32 A base type entry has a \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} attribute describing
33 how the base type is encoded and is to be interpreted. The
34 value of this attribute is an integer constant. The set of
35 values and their meanings for the \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} attribute
36 is given in 
37 Figure \refersec{fig:encodingattributevalues}
38 and following text.  
39
40 A base type entry
41 may have a \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute
42 \addtoindexx{endianity attribute}
43 as described in 
44 Section \refersec{chap:dataobjectentries}. 
45 If omitted, the encoding assumes the representation that
46 is the default for the target architecture.
47
48 A base type entry has 
49 \hypertarget{chap:DWATbytesizedataobjectordatatypesize}
50 either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute
51 \hypertarget{chap:DWATbitsizebasetypebitsize}
52 or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute 
53 \addtoindex{bit size attribute}
54 whose integer constant value
55 (see Section \refersec{chap:byteandbitsizes}) 
56 is the amount of storage needed to hold
57 a value of the type.
58
59 \textit{For example, the 
60 \addtoindex{C} type int on a machine that uses 32\dash bit
61 integers is represented by a base type entry with a name
62 attribute whose value is “int”, an encoding attribute
63 whose value is \livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed} and a byte size attribute whose
64 value is 4.}
65
66 If the value of an object of the given type does not fully
67 occupy the storage described by a byte size attribute,
68 \hypertarget{chap:DWATdatabitoffsetbasetypebitlocation}
69 the base type entry may also have 
70 \addtoindexx{bit size attribute}
71
72 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and a
73 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} attribute, 
74 both of whose values are
75 integer constant values (
76 see Section \refersec{chap:staticanddynamicvaluesofattributes}). 
77 The bit size
78 attribute describes the actual size in bits used to represent
79 values of the given type. The data bit offset attribute is the
80 offset in bits from the beginning of the containing storage to
81 the beginning of the value. Bits that are part of the offset
82 are padding. The data bit offset uses the bit numbering and
83 direction conventions that are appropriate to the current
84 language on the
85 target system to locate the beginning of the storage and
86 value. If this attribute is omitted a default data bit offset
87 of zero is assumed.
88
89 \textit{Attribute 
90 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} 
91 is 
92 \addtoindexx{bit offset attribute}
93 new in DWARF Version 4 and
94 is also used for bit field members 
95 (see Section \refersec{chap:datamemberentries}). 
96 It
97 \hypertarget{chap:DWATbitoffsetbasetypebitlocation}
98 replaces the attribute 
99 \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} 
100 when used for base
101 \addtoindexx{bit offset attribute (V3)}
102 types as defined in DWARF V3 and earlier. The earlier attribute
103 is defined in a manner suitable for bit field members on
104 big\dash endian architectures but which is wasteful for use on
105 little\dash endian architectures.}
106
107 \textit{The attribute \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} is 
108 deprecated in DWARF Version
109 4 for use in base types, but implementations may continue to
110 support its use for compatibility.}
111
112 \textit{The DWARF Version 3 definition of these attributes is as follows.}
113
114 \begin{myindentpara}{1cm}
115 \textit{A base type entry has a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute, whose value
116 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
117 is the size in bytes of the storage unit
118 used to represent an object of the given type.}
119
120 \textit{If the value of an object of the given type does not fully
121 occupy the storage unit described by the byte size attribute,
122 the base type entry may have a 
123 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute 
124 \addtoindexx{bit size attribute (V3)}
125 and a
126 \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} attribute, both of whose values 
127 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
128 are integers. The bit size attribute describes the actual
129 size in bits used to represent a value of the given type.
130 The bit offset attribute describes the offset in bits of the
131 high order bit of a value of the given type from the high
132 order bit of the storage unit used to contain that value.}
133 \end{myindentpara}
134
135 \textit{In comparing DWARF Versions 3 and 4, note that DWARF V4
136 defines the following combinations of attributes:}
137
138 \begin{itemize}
139 \item \textit{DW\-\_AT\-\_byte\-\_size}
140 \item \textit{DW\-\_AT\-\_bit\-\_size}
141 \item \textit{\livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}, \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} 
142 and optionally \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}}
143 \end{itemize}
144 DWARF V3 defines the following combinations:
145 % FIXME: the figure below interferes with the following
146 % bullet list, which looks horrible as a result.
147 \begin{itemize}
148 \item \textit{DW\-\_AT\-\_byte\-\_size}
149 \item \textit{\livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}, \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset}}
150 \end{itemize}
151
152 \begin{figure}[!here]
153 \centering
154 \begin{tabular}{lp{9cm}}
155 Name&Meaning\\ \hline
156 \livetarg{chap:DWATEaddress}{DW\-\_ATE\-\_address} &  linear machine address (for
157   segmented addresses see
158   Section \refersec{chap:segmentedaddresses}) \\
159 \livetarg{chap:DWATEboolean}{DW\-\_ATE\-\_boolean}& true or false \\
160
161 \livetarg{chap:DWATEcomplexfloat}{DW\-\_ATE\-\_complex\-\_float}& complex binary floating\dash point number \\
162 \livetarg{chap:DWATEfloat}{DW\-\_ATE\-\_float} & binary floating\dash point number \\
163 \livetarg{chap:DWATEimaginaryfloat}{DW\-\_ATE\-\_imaginary\-\_float}& imaginary binary floating\dash point number \\
164 \livetarg{chap:DWATEsigned}{DW\-\_ATE\-\_signed}& signed binary integer \\
165 \livetarg{chap:DWATEsignedchar}{DW\-\_ATE\-\_signed\-\_char}& signed character \\
166 \livetarg{chap:DWATEunsigned}{DW\-\_ATE\-\_unsigned} & unsigned binary integer \\
167 \livetarg{chap:DWATEunsignedchar}{DW\-\_ATE\-\_unsigned\-\_char} & unsigned character \\
168 \livetarg{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal}  & packed decimal \\
169 \livetarg{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string}& numeric string \\
170 \livetarg{chap:DWATEedited}{DW\-\_ATE\-\_edited} & edited string \\
171 \livetarg{chap:DWATEsignedfixed}{DW\-\_ATE\-\_signed\-\_fixed} & signed fixed\dash point scaled integer \\
172 \livetarg{chap:DWATEunsignedfixed}{DW\-\_ATE\-\_unsigned\-\_fixed}& unsigned fixed\dash point scaled integer \\
173 \livetarg{chap:DWATEdecimalfloat}{DW\-\_ATE\-\_decimal\-\_float} & decimal floating\dash point number \\ 
174 \livetarg{chap:DWATEUTF}{DW\-\_ATE\-\_UTF} & Unicode character \\
175 \end{tabular}
176 \caption{Encoding attribute values}
177 \label{fig:encodingattributevalues}
178 \end{figure}
179
180 \textit{The \livelink{chap:DWATEdecimalfloat}{DW\-\_ATE\-\_decimal\-\_float} encoding is intended for
181 floating\dash point representations that have a power\dash of\dash ten
182 exponent, such as that specified in IEEE 754R.}
183
184 \textit{The \livelink{chap:DWATEUTF}{DW\-\_ATE\-\_UTF} encoding is intended for Unicode string
185 encodings (see the Universal Character Set standard,
186 ISO/IEC 10646\dash 1:1993). For example, the 
187 \addtoindex{C++} type char16\_t is
188 represented by a base type entry with a name attribute whose
189 value is “char16\_t”, an encoding attribute whose value
190 is \livelink{chap:DWATEUTF}{DW\-\_ATE\-\_UTF} and a byte size attribute whose value is 2.}
191
192 The 
193 \livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal} 
194 and 
195 \livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} 
196 base types
197 represent packed and unpacked decimal string numeric data
198 types, respectively, either of which may be either signed
199 or unsigned. 
200 \hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}
201 These 
202 \hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}
203 base types are used in combination with
204 \livelink{chap:DWATdecimalsign}{DW\-\_AT\-\_decimal\-\_sign}, 
205 \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count} and 
206 \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale}
207 attributes.
208
209 A \livelink{chap:DWATdecimalsign}{DW\-\_AT\-\_decimal\-\_sign} attribute is an integer constant that
210 conveys the representation of the sign of the decimal type
211 (see Figure \refersec{fig:decimalsignattributevalues}). 
212 Its integer constant value is interpreted to
213 mean that the type has a leading overpunch, trailing overpunch,
214 leading separate or trailing separate sign representation or,
215 alternatively, no sign at all.
216
217 The 
218 \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count}
219 attribute is an integer constant
220 value that represents the number of digits in an instance of
221 the type.
222
223 \hypertarget{chap:DWATdecimalscaledecimalscalefactor}
224 The \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attribute is an integer constant value
225 that represents the exponent of the base ten scale factor to
226 be applied to an instance of the type. A scale of zero puts the
227 decimal point immediately to the right of the least significant
228 digit. Positive scale moves the decimal point to the right
229 and implies that additional zero digits on the right are not
230 stored in an instance of the type. Negative scale moves the
231 decimal point to the left; if the absolute value of the scale
232 is larger than the digit count, this implies additional zero
233 digits on the left are not stored in an instance of the type.
234
235 The \livelink{chap:DWATEedited}{DW\-\_ATE\-\_edited}
236 base 
237 \hypertarget{chap:DWATpicturestringpicturestringfornumericstringtype}
238 type is used to represent an edited
239 numeric or alphanumeric data type. It is used in combination
240 with an \livelink{chap:DWATpicturestring}{DW\-\_AT\-\_picture\-\_string} attribute whose value is a 
241 null\dash terminated string containing the target\dash dependent picture
242 string associated with the type.
243
244 If the edited base type entry describes an edited numeric
245 data type, the edited type entry has a \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count} and a
246 \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attribute. These attributes have the same
247 interpretation as described for the \livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal} and
248 \livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} base types. If the edited type entry
249 describes an edited alphanumeric data type, the edited type
250 entry does not have these attributes.
251
252
253 \textit{The presence or absence of the \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count} and
254 \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attributes allows a debugger to easily
255 distinguish edited numeric from edited alphanumeric, although
256 in principle the digit count and scale are derivable by
257 interpreting the picture string.}
258
259 The \livelink{chap:DWATEsignedfixed}{DW\-\_ATE\-\_signed\-\_fixed} and \livelink{chap:DWATEunsignedfixed}{DW\-\_ATE\-\_unsigned\-\_fixed} entries
260 describe signed and unsigned fixed\dash point binary data types,
261 respectively.
262
263 The fixed binary type entries have a \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count}
264 attribute with the same interpretation as described for the
265 \livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal} and \livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} base types.
266
267 For a data type with a decimal scale factor, the fixed binary
268 type entry has a \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attribute with the same
269 interpretation as described for the \livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal}
270 and \livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} base types.
271
272 \hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}
273 For a data type with a binary scale factor, the fixed
274 \addtoindexx{binary scale attribute}
275 binary type entry has a \livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute. The
276 \livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute is an integer constant value
277 that represents the exponent of the base two scale factor to
278 be applied to an instance of the type.  Zero scale puts the
279 binary point immediately to the right of the least significant
280 bit. Positive scale moves the binary point to the right and
281 implies that additional zero bits on the right are not stored
282 in an instance of the type. Negative scale moves the binary
283 point to the left; if the absolute value of the scale is
284 larger than the number of bits, this implies additional zero
285 bits on the left are not stored in an instance of the type.
286
287 For 
288 \hypertarget{chap:DWATsmallscalefactorforfixedpointtype}
289 a data type with a non\dash decimal and non\dash binary scale factor,
290 the fixed binary type entry has a 
291 \livelink{chap:DWATsmall}{DW\-\_AT\-\_small} attribute which
292 references a 
293 \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant} entry. The scale factor value
294 is interpreted in accordance with the value defined by the
295 \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant} entry. The value represented is the product
296 of the integer value in memory and the associated constant
297 entry for the type.
298
299 \textit{The \livelink{chap:DWATsmall}{DW\-\_AT\-\_small} attribute 
300 is defined with the \addtoindex{Ada} small
301 attribute in mind.}
302
303 \begin{figure}[here]
304 \centering
305 \begin{tabular}{lp{9cm}}
306 Name&Meaning\\ \hline
307 \livetarg{chap:DWDSunsigned}{DW\-\_DS\-\_unsigned} &  unsigned \\
308 \livetarg{chap:DWDSleadingoverpunch}{DW\-\_DS\-\_leading\-\_overpunch} & Sign is encoded in the most significant digit in a target\dash dependent  manner \\
309 \livetarg{chap:DWDStrailingoverpunch}{DW\-\_DS\-\_trailing\-\_overpunch} & Sign is encoded in the least significant digit in a target\dash dependent manner \\
310 \livetarg{chap:DWDSleadingseparate}{DW\-\_DS\-\_leading\-\_separate} 
311 & Decimal type: Sign is a ``+'' or ``-'' character 
312 to the left of the most significant digit. \\
313 \livetarg{chap:DWDStrailingseparate}{DW\-\_DS\-\_trailing\-\_separate} 
314 & Decimal type: Sign is a ``+'' or ``-'' character 
315 to the right of the least significant digit. \\
316 &Packed decimal type: Least significant nibble contains
317 a target\dash dependent value
318 indicating positive or negative. \\
319 \end{tabular}
320 \caption{Decimal sign attribute values}
321 \label{fig:decimalsignattributevalues}
322 \end{figure}
323
324 \section{Unspecified Type Entries}
325 \label{chap:unspecifiedtypeentries}
326 Some languages have constructs in which a type 
327 may be left unspecified or the absence of a type
328 \addtoindex{unspecified type entry}
329 may be explicitly indicated.
330
331 An unspecified (implicit, unknown, ambiguous or nonexistent)
332 type is represented by a debugging information entry with
333 the tag \livetarg{chap:DWTAGunspecifiedtype}{DW\-\_TAG\-\_unspecified\-\_type}. 
334 If a name has been given
335 to the type, then the corresponding unspecified type entry
336 has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null\dash terminated
337 string containing the name as it appears in the source program.
338
339 The interpretation of this debugging information entry is
340 intentionally left flexible to allow it to be interpreted
341 appropriately in different languages. For example, in 
342 \addtoindex{C} and \addtoindex{C++}
343 the language implementation can provide an unspecified type
344 entry with the name “void” which can be referenced by the
345 type attribute of pointer types and typedef declarations for
346 'void' (see 
347 % FIXME: the following reference was wrong in DW4 so DavidA guessed
348 % the intent.
349 Sections \refersec{chap:unspecifiedtypeentries} and 
350 %The following reference was valid, so the following is probably correct.
351 Section \refersec{chap:typedefentries}, 
352 respectively). As another
353 example, in \addtoindex{Ada} such an unspecified type entry can be referred
354 to by the type attribute of an access type where the denoted
355 type is incomplete (the name is declared as a type but the
356 definition is deferred to a separate compilation unit). Type
357 Modifier Entries
358
359 A base or user\dash defined type may be modified in different ways
360 in different languages. A type modifier is represented in
361 DWARF by a debugging information entry with one of the tags
362 given in 
363 Figure \refersec{fig:typemodifiertags}.
364
365
366 If a name has been given to the modified type in the source
367 program, then the corresponding modified type entry has
368 a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null-terminated
369 string containing the modified type name as it appears in
370 the source program.
371
372 Each of the type modifier entries has a 
373 \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute,
374 whose value is a reference to a debugging information entry
375 describing a base type, a user-defined type or another type
376 modifier.
377
378 A modified type entry describing a pointer or reference
379 type (using \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}, \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type} or
380 \livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type}) 
381 % Another instance of no-good-place-to-put-index entry.
382 may
383 \addtoindexx{address class!attribute} 
384 have 
385 \hypertarget{chap:DWATadressclasspointerorreferencetypes}
386
387 \livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
388 attribute to describe how objects having the given pointer
389 or reference type ought to be dereferenced.
390
391 A modified type entry describing a shared qualified type
392 (using \livelink{chap:DWTAGsharedtype}{DW\-\_TAG\-\_shared\-\_type}) may have a \livelink{chap:DWATcount}{DW\-\_AT\-\_count} attribute
393 whose value is a constant expressing the blocksize of the
394 type. If no count attribute is present, then the “infinite”
395 blocksize is assumed.
396
397 When multiple type modifiers are chained together to modify
398 a base or user-defined type, the tree ordering reflects the
399 semantics of the applicable lanuage rather than the textual
400 order in the source presentation.
401
402 \begin{figure}[here]
403 \centering
404 \begin{tabular}{lp{9cm}}
405 Name&Meaning\\ \hline
406 \livetarg{chap:DWTAGconsttype}{DW\-\_TAG\-\_const\-\_type} &  C or C++ const qualified type \addtoindexx{C} \addtoindexx{C++} \\
407 \livetarg{chap:DWTAGpackedtype}{DW\-\_TAG\-\_packed\-\_type}& Pascal or Ada packed type \addtoindexx{Ada} \addtoindexx{Pascal} \\
408 \livetarg{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type} & Pointer to an object of the type being modified \\
409 \livetarg{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type}& C++ (lvalue) reference to an object of the type 
410 being modified \\
411 \livetarg{chap:DWTAGrestricttype}{DW\-\_TAG\-\_restrict\-\_type}&C restrict qualified type \\
412 \livetarg{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type} & C++ rvalue reference to an object of the type
413 being modified \\
414 \livetarg{chap:DWTAGsharedtype}{DW\-\_TAG\-\_shared\-\_type}&UPC shared qualified type \\
415 \livetarg{chap:DWTAGvolatiletype}{DW\-\_TAG\-\_volatile\-\_type}&C or C++ volatile qualified type \\
416 \end{tabular}
417 \caption{Type modifier tags}
418 \label{fig:typemodifiertags}
419 \end{figure}
420
421 % The following prevents splitting the examples up.
422 % FIXME perhaps there is a better way. We could box the verbatim, 
423 % see memman.pdf on verbatims.
424 \clearpage
425 \textit{As examples of how tye modifiers are ordered, take the following C
426 declarations:}
427
428 \begin{verbatim}
429 const unsigned char * volatile p;
430     which represents a volatile pointer to a constant
431     character. This is encoded in DWARF as:
432         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}(p) -->
433             \livelink{chap:DWTAGvolatiletype}{DW\-\_TAG\-\_volatile\-\_type} -->
434                 \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type} -->
435                     \livelink{chap:DWTAGconsttype}{DW\-\_TAG\-\_const\-\_type} -->
436                         \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}(unsigned char)
437
438 volatile unsigned char * const restrict p;
439     on the other hand, represents a restricted constant
440     pointer to a volatile character. This is encoded as:
441         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}(p) -->
442             \livelink{chap:DWTAGrestricttype}{DW\-\_TAG\-\_restrict\-\_type} -->
443                 \livelink{chap:DWTAGconsttype}{DW\-\_TAG\-\_const\-\_type} -->
444                     \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type} -->
445                         \livelink{chap:DWTAGvolatiletype}{DW\-\_TAG\-\_volatile\-\_type} -->
446                             \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}(unsigned char)
447
448 \end{verbatim}
449
450 \section{Typedef Entries}
451 \label{chap:typedefentries}
452 A named type that is defined in terms of another type
453 definition is represented by a debugging information entry with
454 the tag \livetarg{chap:DWTAGtypedef}{DW\-\_TAG\-\_typedef}. 
455 The typedef entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name}
456 attribute whose value is a null-terminated string containing
457 the name of the typedef as it appears in the source program.
458
459 The typedef entry may also contain a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute whose
460 value is a reference to the type named by the typedef. If
461 the debugging information entry for a typedef represents
462 a declaration of the type that is not also a definition,
463 it does not contain a type attribute.
464
465 \textit{Depending on the language, a named type that is defined in
466 terms of another type may be called a type alias, a subtype,
467 a constrained type and other terms. A type name declared with
468 no defining details may be termed an incomplete, forward
469 or hidden type. While the DWARF \livelink{chap:DWTAGtypedef}{DW\-\_TAG\-\_typedef} entry was
470 originally inspired by the like named construct in 
471 \addtoindex{C} and \addtoindex{C++},
472 it is broadly suitable for similar constructs (by whatever
473 source syntax) in other languages.}
474
475 \section{Array Type Entries}
476 \label{chap:arraytypeentries}
477
478 Many languages share the concept of an ``array,'' which is
479 \addtoindexx{array type entry}
480 a table of components of identical type.
481
482 An array type is represented by a debugging information entry
483 with the tag \livetarg{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}. 
484 If a name has been 
485 given to
486 \addtoindexx{array!declaration of type}
487 the array type in the source program, then the corresponding
488 array type entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a
489 null-terminated string containing the array type name as it
490 appears in the source program.
491
492 The 
493 \hypertarget{chap:DWATorderingarrayrowcolumnordering}
494 array type entry describing a multidimensional array may
495 \addtoindexx{array!element ordering}
496 have a \livelink{chap:DWATordering}{DW\-\_AT\-\_ordering} attribute whose integer constant value is
497 interpreted to mean either row-major or column-major ordering
498 of array elements. The set of values and their meanings
499 for the ordering attribute are listed in 
500 Figure \refersec{fig:arrayordering}. 
501 If no
502 ordering attribute is present, the default ordering for the
503 source language (which is indicated by the \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language}
504 attribute of the enclosing compilation unit entry) is assumed.
505
506 \begin{figure}[here]
507 \autorows[0pt]{c}{1}{l}{
508 \livetarg{chap:DWORDcolmajor}{DW\-\_ORD\-\_col\-\_major},
509 \livetarg{chap:DWORDrowmajor}{DW\-\_ORD\-\_row\-\_major}
510 }
511 \caption{Array ordering}\label{fig:arrayordering}
512 \end{figure}
513
514 The ordering attribute may optionally appear on one-dimensional
515 arrays; it will be ignored.
516
517 An array type entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} 
518 \addtoindexx{array!element type}
519 attribute describing
520 the type of each element of the array.
521
522 If the amount of storage allocated to hold each element of an
523 object of the given array type is different from the amount
524 of storage that is normally allocated to hold an individual
525 \hypertarget{chap:DWATbitstridearrayelementstrideofarraytype}
526 object of the 
527 \hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}
528 indicated element type, then the array type
529 \addtoindexx{bit stride attribute}
530 entry has either a 
531 \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} 
532 or 
533 \addtoindexx{byte stride attribute}
534 a \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}
535 attribute, 
536 \addtoindexx{bit stride attribute}
537 whose value 
538 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
539 is the size of each
540 element of the array.
541
542 The array type entry may have either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} or a
543 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute 
544 (see Section \refersec{chap:byteandbitsizes}), 
545 whose value is the
546 amount of storage needed to hold an instance of the array type.
547
548 \textit{If the size of the array can be determined statically at
549 compile time, this value can usually be computed by multiplying
550 the number of array elements by the size of each element.}
551
552
553 Each array dimension is described by a debugging information
554 entry with either the tag \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type} or the tag
555 \livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type}. These entries are children of the
556 array type entry and are ordered to reflect the appearance of
557 the dimensions in the source program (i.e., leftmost dimension
558 first, next to leftmost second, and so on).
559
560 In languages, such as C, in which there is no concept of
561 a “multidimensional array”, an array of arrays may
562 be represented by a debugging information entry for a
563 multidimensional array.
564
565 Other attributes especially applicable to arrays are
566 \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated}, 
567 \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} and 
568 \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location},
569 which are described in 
570 Section \refersec{chap:dynamictypeproperties}. 
571 For relevant examples,
572 see also 
573 Appendix \refersec{app:fortran90example}.
574
575 \section{ Structure, Union, Class and Interface Type Entries}
576 \label{chap:structureunionclassandinterfacetypeentries}
577
578 \textit{The languages 
579 \addtoindex{C}, 
580 \addtoindex{C++}, and 
581 \addtoindex{Pascal}, among others, allow the
582 programmer to define types that are collections of related
583 components. In \addtoindex{C} and \addtoindex{C++}, these collections are called
584 “structures.” In \addtoindex{Pascal}, they are called “records.”
585 The components may be of different types. The components are
586 called “members” in \addtoindex{C} and 
587 \addtoindex{C++}, and “fields” in \addtoindex{Pascal}.}
588
589 \textit{The components of these collections each exist in their
590 own space in computer memory. The components of a C or C++
591 “union” all coexist in the same memory.}
592
593 \textit{\addtoindex{Pascal} and 
594 other languages have a “discriminated union,”
595 also called a “variant record.” Here, selection of a
596 number of alternative substructures (“variants”) is based
597 on the value of a component that is not part of any of those
598 substructures (the “discriminant”).}
599
600 \textit{\addtoindex{C++} and 
601 \addtoindex{Java} have the notion of ``class'', which is in some
602 ways similar to a structure. A class may have “member
603 functions” which are subroutines that are within the scope
604 of a class or structure.}
605
606 \textit{The \addtoindex{C++} notion of 
607 structure is more general than in \addtoindex{C}, being
608 equivalent to a class with minor differences. Accordingly,
609 in the following discussion statements about 
610 \addtoindex{C++} classes may
611 be understood to apply to \addtoindex{C++} structures as well.}
612
613 \subsection{Structure, Union and Class Type Entries}
614 \label{chap:structureunionandclasstypeentries}
615
616
617 Structure, union, and class types are represented by debugging
618 information entries with 
619 the tags \livetarg{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type},
620 \livetarg{chap:DWTAGuniontype}{DW\-\_TAG\-\_union\-\_type}, 
621 and \livetarg{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type},
622 respectively. If a name has been given to the structure,
623 union, or class in the source program, then the corresponding
624 structure type, union type, or class type entry has a
625 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null\dash terminated string
626 containing the type name as it appears in the source program.
627
628 The members of a structure, union, or class are represented
629 by debugging information entries that are owned by the
630 corresponding structure type, union type, or class type entry
631 and appear in the same order as the corresponding declarations
632 in the source program.
633
634 A structure type, union type or class type entry may have
635 either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute 
636 \hypertarget{chap:DWATbitsizedatamemberbitsize}
637 (see Section \refersec{chap:byteandbitsizes}), 
638 whose value is the amount of storage needed
639 to hold an instance of the structure, union or class type,
640 including any padding.  An incomplete structure, union or
641 class type is represented by a structure, union or class
642 entry that does not have a byte size attribute and that has
643 a \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute.
644
645 If the complete declaration of a type has been placed in
646 \hypertarget{chap:DWATsignaturetypesignature}
647 a separate type unit 
648 (see Section \refersec{chap:separatetypeunitentries}), 
649 an incomplete
650 declaration of that type in the compilation unit may provide
651 the unique 64\dash bit signature of the type using a \livelink{chap:DWATsignature}{DW\-\_AT\-\_signature}
652 attribute.
653
654 If a structure, union or class entry represents the definition
655 of a structure, class or union member corresponding to a prior
656 incomplete structure, class or union, the entry may have a
657 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute whose value is a reference to
658 the debugging information entry representing that incomplete
659 declaration.
660
661 Structure, union and class entries containing the
662 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute do not need to duplicate
663 information provided by the declaration entry referenced by the
664 specification attribute.  In particular, such entries do not
665 need to contain an attribute for the name of the structure,
666 class or union they represent if such information is already
667 provided in the declaration.
668
669 \textit{For \addtoindex{C} and \addtoindex{C++}, 
670 data member declarations occurring within
671 the declaration of a structure, union or class type are
672 considered to be “definitions” of those members, with
673 the exception of “static” data members, whose definitions
674 appear outside of the declaration of the enclosing structure,
675 union or class type. Function member declarations appearing
676 within a structure, union or class type declaration are
677 definitions only if the body of the function also appears
678 within the type declaration.}
679
680 If the definition for a given member of the structure, union
681 or class does not appear within the body of the declaration,
682 that member also has a debugging information entry describing
683 its definition. That latter entry has a \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification}
684 attribute referencing the debugging information entry
685 owned by the body of the structure, union or class entry and
686 representing a non\dash defining declaration of the data, function
687 or type member. The referenced entry will not have information
688 about the location of that member (low and high pc attributes
689 for function members, location descriptions for data members)
690 and will have a \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute.
691
692 \textit{Consider a nested class whose 
693 definition occurs outside of the containing class definition, as in:}
694
695 \begin{lstlisting}
696 struct A {
697     struct B;
698 };
699 struct A::B { ... };
700 \end{lstlisting}
701
702 \textit{The two different structs can be described in 
703 different compilation units to 
704 facilitate DWARF space compression 
705 (see Appendix \refersec{app:usingcompilationunits}).}
706
707 \subsection{Interface Type Entries}
708 \label{chap:interfacetypeentries}
709
710 \textit{The \addtoindex{Java} language defines ``interface'' types. 
711 An interface
712 in Java is similar to a \addtoindex{C++} or 
713 \addtoindex{Java} class with only abstract
714 methods and constant data members.}
715
716 Interface types are represented by debugging information
717 entries with the 
718 tag \livetarg{chap:DWTAGinterfacetype}{DW\-\_TAG\-\_interface\-\_type}.
719
720 An interface type entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose
721 value is a null-terminated string containing the type name
722 as it appears in the source program.
723
724 The members of an interface are represented by debugging
725 information entries that are owned by the interface type
726 entry and that appear in the same order as the corresponding
727 declarations in the source program.
728
729 \subsection{Derived or Extended Structs, Classes and Interfaces}
730 \label{chap:derivedorextendedstructsclasesandinterfaces}
731
732 \textit{In \addtoindex{C++}, a class (or struct) may be ``derived from'' or be a
733 ``subclass of'' another class. In Java, an interface may ``extend''
734 one or more other interfaces, and a class may ``extend'' another
735 class and/or ``implement'' one or more interfaces. All of these
736 relationships may be described using the following. Note that
737 in Java, the distinction between extends and implements is
738 implied by the entities at the two ends of the relationship.}
739
740 A class type or interface type entry that describes a
741 derived, extended or implementing class or interface owns
742 debugging information entries describing each of the classes
743 or interfaces it is derived from, extending or implementing,
744 respectively, ordered as they were in the source program. Each
745 such entry has the 
746 tag \livetarg{chap:DWTAGinheritance}{DW\-\_TAG\-\_inheritance}.
747
748 An inheritance entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute whose value is
749 a reference to the debugging information entry describing the
750 class or interface from which the parent class or structure
751 of the inheritance entry is derived, extended or implementing.
752
753 An inheritance entry for a class that derives from or extends
754 \hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}
755 another class or struct also has a 
756 \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}
757 attribute, whose value describes the location of the beginning
758 of the inherited type relative to the beginning address of the
759 derived class. If that value is a constant, it is the offset
760 in bytes from the beginning of the class to the beginning of
761 the inherited type. Otherwise, the value must be a location
762 description. In this latter case, the beginning address of
763 the derived class is pushed on the expression stack before
764 the location description is evaluated and the result of the
765 evaluation is the location of the inherited type.
766
767 \textit{The interpretation of the value of this attribute for
768 inherited types is the same as the interpretation for data
769 members 
770 (see Section \refersec{chap:datamemberentries}).  }
771
772 An inheritance entry 
773 \hypertarget{chap:DWATaccessibilitycppinheritedmembers}
774 may 
775 \addtoindexx{accessibility attribute}
776 have a
777 \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
778 attribute. If no accessibility attribute
779 is present, private access is assumed for an entry of a class
780 and public access is assumed for an entry of an interface,
781 struct or union.
782
783 If 
784 \hypertarget{chap:DWATvirtualityvirtualityofbaseclass}
785 the class referenced by the inheritance entry serves
786 as a \addtoindex{C++} virtual base class, the inheritance entry has a
787 \livelink{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality} attribute.
788
789 \textit{For a \addtoindex{C++} virtual base, the data member location attribute
790 will usually consist of a non-trivial location description.}
791
792 \subsection{Access Declarations}
793 \label{chap:accessdeclarations}
794
795 \textit{In \addtoindex{C++}, a derived class may contain access declarations that
796 \addtoindex{access declaration entry}
797 change the accessibility of individual class members from the
798 overall accessibility specified by the inheritance declaration.
799 A single access declaration may refer to a set of overloaded
800 names.}
801
802 If a derived class or structure contains access declarations,
803 each such declaration may be represented by a debugging
804 information entry with the tag 
805 \livetarg{chap:DWTAGaccessdeclaration}{DW\-\_TAG\-\_access\-\_declaration}. 
806 Each
807 such entry is a child of the class or structure type entry.
808
809 An access declaration entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose
810 value is a null-terminated string representing the name used
811 in the declaration in the source program, including any class
812 or structure qualifiers.
813
814 An access declaration entry 
815 \hypertarget{chap:DWATaccessibilitycppbaseclasses}
816 also 
817 has a 
818 \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
819 attribute describing the declared accessibility of the named
820 entities.
821
822
823 \subsection{Friends}
824 \label{chap:friends}
825
826 Each ``friend'' declared by a structure, union or class
827 \hypertarget{chap:DWATfriendfriendrelationship}
828 type may be represented by a debugging information entry
829 that is a child of the structure, union or class type entry;
830 the friend entry has the 
831 tag \livetarg{chap:DWTAGfriend}{DW\-\_TAG\-\_friend}.
832
833 A friend entry has a \livelink{chap:DWATfriend}{DW\-\_AT\-\_friend} attribute, whose value is
834 a reference to the debugging information entry describing
835 the declaration of the friend.
836
837
838 \subsection{Data Member Entries}
839 \label{chap:datamemberentries}
840
841 A data member (as opposed to a member function) is
842 represented by a debugging information entry with the 
843 tag \livetarg{chap:DWTAGmember}{DW\-\_TAG\-\_member}. 
844 The member entry for a named member has
845 a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null-terminated
846 string containing the member name as it appears in the source
847 program. If the member entry describes an 
848 \addtoindex{anonymous union},
849 the
850 name attribute is omitted or consists of a single zero byte.
851
852 The data member entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute to denote
853 the type of that member.
854
855 A data member entry may 
856 \addtoindexx{accessibility attribute}
857 have a 
858 \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
859 attribute. If no accessibility attribute is present, private
860 access is assumed for an entry of a class and public access
861 is assumed for an entry of a structure, union, or interface.
862
863 A data member 
864 \hypertarget{chap:DWATmutablemutablepropertyofmemberdata}
865 entry may have a \livelink{chap:DWATmutable}{DW\-\_AT\-\_mutable} attribute,
866 which is a \livelink{chap:flag}{flag}. 
867 This attribute indicates whether the data
868 member was declared with the mutable storage class specifier.
869
870 The beginning of a data member 
871 \addtoindex{beginning of a data member} 
872 is described relative to
873 \addtoindexx{beginning of an object}
874 the beginning of the object in which it is immediately
875 contained. In general, the beginning is characterized by
876 both an address and a bit offset within the byte at that
877 address. When the storage for an entity includes all of
878 the bits in the beginning byte, the beginning bit offset is
879 defined to be zero.
880
881 Bit offsets in DWARF use the bit numbering and direction
882 conventions that are appropriate to the current language on
883 the target system.
884
885 The member entry corresponding to a data member that is
886 \hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}
887 defined 
888 \hypertarget{chap:DWATdatamemberlocationdatamemberlocation}
889 in a structure, union or class may have either a
890 \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} attribute or a \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}
891 attribute. If the beginning of the data member is the same as
892 the beginning of the containing entity then neither attribute
893 is required.
894
895 For a \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} attribute there are two cases:
896
897 \begin{enumerate}[1.]
898
899 \item If the value is an integer constant, it is the offset
900 in bytes from the beginning of the containing entity. If
901 the beginning of the containing entity has a non-zero bit
902 offset then the beginning of the member entry has that same
903 bit offset as well.
904
905 \item Otherwise, the value must be a location description. In
906 this case, the beginning of the containing entity must be byte
907 aligned. The beginning address is pushed on the DWARF stack
908 before the location description is evaluated; the result of
909 the evaluation is the base address of the member entry.
910
911 \textit{The push on the DWARF expression stack of the base address of
912 the containing construct is equivalent to execution of the
913 \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} operation 
914 (see Section \refersec{chap:stackoperations});
915 \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} therefore is not needed at the
916 beginning of a location description for a data member. The
917 result of the evaluation is a location--either an address or
918 the name of a register, not an offset to the member.}
919
920 \textit{A \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} attribute that has the form of a
921 location description is not valid for a data member contained
922 in an entity that is not byte aligned because DWARF operations
923 do not allow for manipulating or computing bit offsets.}
924
925 \end{enumerate}
926
927 For a \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} attribute, the value is an integer
928 constant 
929 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
930 that specifies the number of bits
931 from the beginning of the containing entity to the beginning
932 of the data member. This value must be greater than or equal
933 to zero, but is not limited to less than the number of bits
934 per byte.
935
936 If the size of a data member is not the same as the size
937 of the type given for the data member, the data member has
938 \addtoindexx{bit size attribute}
939 either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} 
940 or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute whose
941 integer constant value 
942 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
943 is the amount
944 of storage needed to hold the value of the data member.
945
946 \textit{\addtoindex{C} and \addtoindex{C++} 
947 \addtoindex{bit fields} 
948 typically require the use of the
949 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} and \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attributes.}
950
951 \textit{This Standard uses the following bit numbering and direction
952 conventions in examples. These conventions are for illustrative
953 purposes and other conventions may apply on particular
954 architectures.}
955
956
957 \begin{itemize}
958 \item \textit{For big\dash endian architectures, bit offsets are
959 counted from high-order to low\dash order bits within a byte (or
960 larger storage unit); in this case, the bit offset identifies
961 the high\dash order bit of the object.}
962
963 \item \textit{For little\dash endian architectures, bit offsets are
964 counted from low\dash order to high\dash order bits within a byte (or
965 larger storage unit); in this case, the bit offset identifies
966 the low\dash order bit of the object.}
967 \end{itemize}
968
969
970 \textit{In either case, the bit so identified is defined as the 
971 \addtoindexx{beginning of an object}
972 beginning of the object.}
973
974 \textit{For example, take one possible representation of the following 
975 \addtoindex{C} structure definition 
976 in both big\dash and little\dash endian byte orders:}
977
978 \begin{lstlisting}
979 struct S {
980     int j:5;
981     int k:6;
982     int m:5;
983     int n:8;
984 };
985 \end{lstlisting}
986
987 \textit{The following diagrams show the structure layout
988 and data bit offsets for example big\dash\   and little\dash endian
989 architectures, respectively. Both diagrams show a structure
990 that begins at address A and whose size is four bytes. Also,
991 high order bits are to the left and low order bits are to
992 the right.}
993
994 \textit{Big\dash Endian Data Bit Offsets:}
995
996 \begin{verbatim}
997     j:0
998     k:5
999     m:11
1000     n:16
1001
1002     Addresses increase ->
1003     |       A       |     A + 1     |    A + 2      |    A + 3      | 
1004
1005     Data bit offsets increase ->
1006     +---------------+---------------+---------------+---------------+
1007     |0     4|5         10|11      15|16           23|24           31|
1008     |   j   |     k      | m        |        n      |       <pad>   |
1009     |       |            |          |               |               | 
1010     +---------------------------------------------------------------+ 
1011 \end{verbatim}
1012
1013 \textit{Little\dash  Endian Data Bit Offsets:}
1014 \begin{verbatim}
1015     j:0
1016     k:5
1017     m:11
1018     n:16
1019                                                <- Addresses increase
1020     |       A       |     A + 1     |    A + 2      |    A + 3      | 
1021
1022                                         <-  Data bit offsets increase 
1023
1024     +---------------+---------------+---------------+---------------+
1025     |31           24|23           16|15     11|10       5|4        0|
1026     |     <pad>     |        n      |    m    |    k     |     j    |
1027     |               |               |         |          |          |
1028     +---------------------------------------------------------------+
1029
1030 \end{verbatim}
1031
1032 \textit{Note that data member bit offsets in this example are the
1033 same for both big\dash\ and little\dash endian architectures even
1034 though the fields are allocated in different directions
1035 (high\dash order to low-order versus low\dash order to high\dash order);
1036 the bit naming conventions for memory and/or registers of
1037 the target architecture may or may not make this seem natural.}
1038
1039 \textit{For a more extensive example showing nested and packed records
1040 and arrays, see 
1041 Appendix \refersec{app:pascalexample}.}
1042
1043 \textit{Attribute \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} is new in DWARF Version 4 and
1044 is also used for base types 
1045 (see Section 
1046 \refersec{chap:basetypeentries}). 
1047 It replaces the
1048 \livetarg{chap:DWATbitoffsetdatamemberbitlocation}
1049 attributes \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} and \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} when used to
1050 identify the beginning of bit field data members as defined
1051 in DWARF V3 and earlier. The earlier attributes are defined
1052 in a manner suitable for bit field members on big-endian
1053 architectures but which is either awkward or incomplete for
1054 use on little-endian architectures.  
1055 (\livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} also
1056 has other uses that are not affected by this change.)}
1057
1058 \textit{The \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}, 
1059 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and 
1060 \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset}
1061 attribute combination is deprecated for data members in DWARF
1062 Version 4, but implementations may continue to support this
1063 use for compatibility.}
1064
1065 \textit{The DWARF Version 3 definitions of these attributes are
1066 as follows.}
1067
1068 \begin{myindentpara}{1cm}
1069 \textit{If the data member entry describes a bit field, then that
1070 entry has the following attributes:}
1071
1072 \begin{itemize}
1073 \item \textit{A \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} 
1074 attribute whose value 
1075 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
1076 is the number of bytes that contain an instance of the
1077 bit field and any padding bits.}
1078
1079 \textit{The byte size attribute may be omitted if the size of the
1080 object containing the bit field can be inferred from the type
1081 attribute of the data member containing the bit field.}
1082
1083 \item \textit{A \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} 
1084 attribute 
1085 \addtoindexx{bit offset attribute (V3)}
1086 whose value 
1087 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
1088 is the number of bits to the left of the leftmost
1089 (most significant) bit of the bit field value.}
1090
1091 \item \textit{A \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} 
1092 attribute 
1093 \addtoindexx{bit size attribute (V3)}
1094 whose value 
1095 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
1096 is the number of bits occupied by the bit field value.}
1097
1098 \end{itemize}
1099
1100 \textit{The location description for a bit field calculates the address
1101 of an anonymous object containing the bit field. The address
1102 is relative to the structure, union, or class that most closely
1103 encloses the bit field declaration. The number of bytes in this
1104 anonymous object is the value of the byte size attribute of
1105 the bit field. The offset (in bits) from the most significant
1106 bit of the anonymous object to the most significant bit of
1107 the bit field is the value of the bit offset attribute.}
1108 \end{myindentpara}
1109
1110
1111 \textit{Diagrams similar to the above that show the use of the
1112 \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}, \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} attribute
1113 combination may be found in the DWARF Version 3 Standard.}
1114
1115 \textit{In comparing DWARF Versions 3 and 4, note that DWARF V4
1116 defines the following combinations of attributes:}
1117
1118 \begin{itemize}
1119 \item \textit{either \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} or
1120 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} (to specify the beginning of the
1121 data member)}
1122
1123 % FIXME: the indentation of the following line is suspect.
1124 \textit{optionally together with}
1125
1126 \item  \textit{either \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} or \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} (to
1127 specify the size of the data member)}
1128
1129 \end{itemize}
1130
1131 \textit{DWARF V3 defines the following combinations}
1132
1133 \begin{itemize}
1134 \item \textit{\livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} (to specify the beginning
1135 of the data member, except this specification is only partial
1136 in the case of a bit field) }
1137
1138 % FIXME: the indentation of the following line is suspect.
1139 \textit{optionally together with}
1140
1141 \item \textit{\livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}, \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset}
1142 (to further specify the beginning of a bit field data member
1143 as well as specify the size of the data member) }
1144 \end{itemize}
1145
1146 \subsection{Member Function Entries}
1147 \label{chap:memberfunctionentries}
1148
1149 A member function is represented by a debugging information
1150 entry with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. The member function entry
1151 may contain the same attributes and follows the same rules
1152 as non\dash member global subroutine entries 
1153 (see Section \refersec{chap:subroutineandentrypointentries}).
1154
1155
1156 \addtoindexx{accessibility attribute}
1157 member function entry may have a 
1158 \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
1159 attribute. If no accessibility attribute is present, private
1160 access is assumed for an entry of a class and public access
1161 is assumed for an entry of a structure, union or interface.
1162
1163 If 
1164 \hypertarget{chap:DWATvirtualityvirtualityoffunction}
1165 the member function entry describes a virtual function,
1166 then that entry has a 
1167 \livelink{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality} attribute.
1168
1169 If 
1170 \hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}
1171 the member function entry describes an explicit member
1172 function, then that entry has a 
1173 \livelink{chap:DWATexplicit}{DW\-\_AT\-\_explicit} attribute.
1174
1175 An 
1176 \hypertarget{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}
1177 entry for a virtual function also has a
1178 \livelink{chap:DWATvtableelemlocation}{DW\-\_AT\-\_vtable\-\_elem\-\_location} attribute whose value contains
1179 a location description yielding the address of the slot
1180 for the function within the virtual function table for the
1181 enclosing class. The address of an object of the enclosing
1182 type is pushed onto the expression stack before the location
1183 description is evaluated.
1184
1185 If 
1186 \hypertarget{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}
1187 the member function entry describes a non\dash static member
1188 function, then that entry has a \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer} attribute
1189 whose value is a reference to the formal parameter entry
1190 that corresponds to the object for which the function is
1191 called. The name attribute of that formal parameter is defined
1192 by the current language (for example, 
1193 this for \addtoindex{C++} or self
1194 for \addtoindex{Objective C} 
1195 and some other languages). That parameter
1196 also has a \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute whose value is true.
1197
1198 Conversely, if the member function entry describes a static
1199 member function, the entry does not have a \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}
1200 attribute.
1201
1202 If the member function entry describes a non\dash static member
1203 function that has a const\dash volatile qualification, then
1204 the entry describes a non\dash static member function whose
1205 object formal parameter has a type that has an equivalent
1206 const\dash volatile qualification.
1207
1208 If a subroutine entry represents the defining declaration
1209 of a member function and that definition appears outside of
1210 the body of the enclosing class declaration, the subroutine
1211 entry has a \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute, whose value is
1212 a reference to the debugging information entry representing
1213 the declaration of this function member. The referenced entry
1214 will be a child of some class (or structure) type entry.
1215
1216 Subroutine entries containing the \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification}
1217 attribute do not need to duplicate information provided
1218 by the declaration entry referenced by the specification
1219 attribute. In particular, such entries do not need to contain
1220 attributes for the name or return type of the function member
1221 whose definition they represent.
1222
1223 \subsection{Class Template Instantiations}
1224 \label{chap:classtemplateinstantiations}
1225
1226 \textit{In \addtoindex{C++} a class template is a generic definition of a class
1227 type that may be instantiated when an instance of the class
1228 is declared or defined. The generic description of the
1229 class may include both parameterized types and parameterized
1230 constant values. DWARF does not represent the generic template
1231 definition, but does represent each instantiation.}
1232
1233 A class template instantiation is represented by a
1234 debugging information entry with the tag \livelink{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type},
1235 \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} or \livelink{chap:DWTAGuniontype}{DW\-\_TAG\-\_union\-\_type}. With five
1236 exceptions, such an entry will contain the same attributes
1237 and have the same types of child entries as would an entry
1238 for a class type defined explicitly using the instantiation
1239 types and values. The exceptions are:
1240
1241 \begin{enumerate}[1.]
1242 \item Each formal parameterized type declaration appearing in the
1243 template definition is represented by a debugging information
1244 entry with the tag \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}. Each
1245 such entry may have a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is
1246 a null\dash terminated string containing the name of the formal
1247 type parameter as it appears in the source program. The
1248 template type parameter entry also has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
1249 describing the actual type by which the formal is replaced
1250 for this instantiation.
1251
1252 \item Each formal parameterized value declaration appearing in the
1253 template definition is represented by a debugging information
1254 entry with the 
1255 tag \livetarg{chap:DWTAGtemplatevalueparameter}{DW\-\_TAG\-\_template\-\_value\-\_parameter}. 
1256 Each
1257 such entry may have a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is
1258 a null\dash terminated string containing the name of the formal
1259 value parameter as it appears in the source program. 
1260 The
1261 \hypertarget{chap:DWATconstvaluetemplatevalueparameter}
1262 template value parameter entry also has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
1263 describing the type of the parameterized value. Finally,
1264 the template value parameter entry has a \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}
1265 attribute, whose value is the actual constant value of the
1266 value parameter for this instantiation as represented on the
1267 target architecture.
1268
1269 \item The class type entry and each of its child entries references
1270 a template type parameter entry in any circumstance where the
1271 source template definition references a formal parameterized
1272 type. Similarly, the class type entry and each of its child
1273 entries references a template value parameter entry in any
1274 circumstance where the source template definition references
1275 a formal parameterized value.
1276
1277 \item If the compiler has generated a special compilation unit to
1278 hold the template instantiation and that special compilation
1279 unit has a different name from the compilation unit containing
1280 the template definition, the name attribute for the debugging
1281 information entry representing the special compilation unit
1282 should be empty or omitted.
1283
1284 \item If the class type entry representing the template
1285 instantiation or any of its child entries contains declaration
1286 coordinate attributes, those attributes should refer to
1287 the source for the template definition, not to any source
1288 generated artificially by the compiler.
1289 \end{enumerate}
1290
1291
1292 \subsection{Variant Entries}
1293 \label{chap:variantentries}
1294
1295 A variant part of a structure is represented by a debugging
1296 information entry with the 
1297 tag \livetarg{chap:DWTAGvariantpart}{DW\-\_TAG\-\_variant\-\_part} and is
1298 owned by the corresponding structure type entry.
1299
1300 If the variant part has a discriminant, the discriminant is
1301 \hypertarget{chap:DWATdiscrdiscriminantofvariantpart}
1302 represented by a separate debugging information entry which
1303 is a child of the variant part entry. This entry has the form
1304 of a structure data member entry. The variant part entry will
1305 have a 
1306 \livelink{chap:DWATdiscr}{DW\-\_AT\-\_discr} attribute whose value is a reference to
1307 the member entry for the discriminant.
1308
1309 If the variant part does not have a discriminant (tag field),
1310 the variant part entry has a 
1311 \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute to represent
1312 the tag type.
1313
1314 Each variant of a particular variant part is represented by
1315 \hypertarget{chap:DWATdiscrvaluediscriminantvalue}
1316 a debugging information entry with the 
1317 tag \livetarg{chap:DWTAGvariant}{DW\-\_TAG\-\_variant}
1318 and is a child of the variant part entry. The value that
1319 selects a given variant may be represented in one of three
1320 ways. The variant entry may have a 
1321 \livelink{chap:DWATdiscrvalue}{DW\-\_AT\-\_discr\-\_value} attribute
1322 whose value represents a single case label. The value of this
1323 attribute is encoded as an LEB128 number. The number is signed
1324 if the tag type for the variant part containing this variant
1325 is a signed type. The number is unsigned if the tag type is
1326 an unsigned type.
1327
1328 Alternatively, 
1329 \hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}
1330 the variant entry may contain a 
1331 \livelink{chap:DWATdiscrlist}{DW\-\_AT\-\_discr\-\_list}
1332 attribute, whose value represents a list of discriminant
1333 values. This list is represented by any of the 
1334 \livelink{chap:block}{block} forms and
1335 may contain a mixture of case labels and label ranges. Each
1336 item on the list is prefixed with a discriminant value
1337 descriptor that determines whether the list item represents
1338 a single label or a label range. A single case label is
1339 represented as an LEB128 number as defined above for the
1340 \livelink{chap:DWATdiscrvalue}{DW\-\_AT\-\_discr\-\_value} attribute. A label range is represented by
1341 two LEB128 numbers, the low value of the range followed by the
1342 high value. Both values follow the rules for signedness just
1343 described. The discriminant value descriptor is an integer
1344 constant that may have one of the values given in 
1345 Figure \refersec{fig:discriminantdescriptorvalues}.
1346
1347 \begin{figure}[here]
1348 \autorows[0pt]{c}{1}{l}{
1349 \addtoindex{DW\-\_DSC\-\_label},
1350 \addtoindex{DW\-\_DSC\-\_range}
1351 }
1352 \caption{Discriminant descriptor values}\label{fig:discriminantdescriptorvalues}
1353 \end{figure}
1354
1355 If a variant entry has neither a \livelink{chap:DWATdiscrvalue}{DW\-\_AT\-\_discr\-\_value}
1356 attribute nor a \livelink{chap:DWATdiscrlist}{DW\-\_AT\-\_discr\-\_list} attribute, or if it has
1357 a \livelink{chap:DWATdiscrlist}{DW\-\_AT\-\_discr\-\_list} attribute with 0 size, the variant is a
1358 default variant.
1359
1360 The components selected by a particular variant are represented
1361 by debugging information entries owned by the corresponding
1362 variant entry and appear in the same order as the corresponding
1363 declarations in the source program.
1364
1365 \section{Condition Entries}
1366 \label{chap:conditionentries}
1367
1368 \textit{COBOL has the notion of a ``level\dash 88 condition'' that
1369 associates a data item, called the conditional variable, with
1370 a set of one or more constant values and/or value ranges.
1371 Semantically, the condition is ‛true’ if the conditional
1372 variable's value matches any of the described constants,
1373 and the condition is ‛false’ otherwise.}
1374
1375 The \livetarg{chap:DWTAGcondition}{DW\-\_TAG\-\_condition} debugging information entry
1376 describes a
1377 logical condition that tests whether a given data item’s
1378 value matches one of a set of constant values. If a name
1379 has been given to the condition, the condition entry has a
1380 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null\dash terminated string
1381 giving the condition name as it appears in the source program.
1382
1383 The condition entry's parent entry describes the conditional
1384 variable; normally this will be a \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable},
1385 \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} or \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter} entry. If the parent
1386 entry has an array type, the condition can test any individual
1387 element, but not the array as a whole. The condition entry
1388 implicitly specifies a “comparison type” that is the
1389 type of an array element if the parent has an array type;
1390 otherwise it is the type of the parent entry.
1391
1392 The condition entry owns \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant} and/or
1393 \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type} entries that describe the constant
1394 values associated with the condition. If any child entry has
1395 a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, that attribute should describe a type
1396 compatible with the comparison type (according to the source
1397 language); otherwise the child’s type is the same as the
1398 comparison type.
1399
1400 \textit{For conditional variables with alphanumeric types, COBOL
1401 permits a source program to provide ranges of alphanumeric
1402 constants in the condition. Normally a subrange type entry
1403 does not describe ranges of strings; however, this can be
1404 represented using bounds attributes that are references to
1405 constant entries describing strings. A subrange type entry may
1406 refer to constant entries that are siblings of the subrange
1407 type entry.}
1408
1409
1410 \section{Enumeration Type Entries}
1411 \label{chap:enumerationtypeentries}
1412
1413 \textit{An “enumeration type” is a scalar that can assume one of
1414 a fixed number of symbolic values.}
1415
1416 An enumeration type is represented by a debugging information
1417 entry with the tag 
1418 \livetarg{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type}.
1419
1420 If a name has been given to the enumeration type in the source
1421 program, then the corresponding enumeration type entry has
1422 a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null\dash terminated
1423 string containing the enumeration type name as it appears
1424 in the source program. This entry also has a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}
1425 attribute whose integer constant value is the number of bytes
1426 required to hold an instance of the enumeration.
1427
1428 The enumeration type entry may have a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
1429 which refers to the underlying data type used to implement
1430 the enumeration.
1431
1432 If an enumeration type has type safe semantics such that
1433
1434 \begin{enumerate}[1.]
1435 \item Enumerators are contained in the scope of the enumeration type, and/or
1436
1437 \item Enumerators are not implicitly converted to another type
1438 \end{enumerate}
1439
1440 then the enumeration type entry may have a \livelink{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}
1441 attribute, which is a \livelink{chap:flag}{flag}. 
1442 In a language that offers only
1443 one kind of enumeration declaration, this attribute is not
1444 required.
1445
1446 \textit{In \addtoindex{C} or \addtoindex{C++}, 
1447 the underlying type will be the appropriate
1448 integral type determined by the compiler from the properties of
1449 \hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}
1450 the enumeration literal values. A \addtoindex{C++} type declaration written
1451 using enum class declares a strongly typed enumeration and
1452 is represented using \livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type} in combination
1453 with \livelink{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}.}
1454
1455 Each enumeration literal is represented by a debugging
1456 information entry with the 
1457 tag \livetarg{chap:DWTAGenumerator}{DW\-\_TAG\-\_enumerator}. 
1458 Each
1459 such entry is a child of the enumeration type entry, and the
1460 enumerator entries appear in the same order as the declarations
1461 of the enumeration literals in the source program.
1462
1463 Each enumerator entry has a 
1464 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose
1465 value is a null\dash terminated string containing the name of the
1466 \hypertarget{chap:DWATconstvalueenumerationliteralvalue}
1467 enumeration literal as it appears in the source program. 
1468 Each enumerator entry also has a 
1469 \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute,
1470 whose value is the actual numeric value of the enumerator as
1471 represented on the target system.
1472
1473
1474 If the enumeration type occurs as the description of a
1475 dimension of an array type, and the stride for that dimension
1476 \hypertarget{chap:DWATbytestrideenumerationstridedimensionofarraytype}
1477 is different than what would otherwise be determined, then
1478 \hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}
1479 the enumeration type entry has either a \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride}
1480 or \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute 
1481 \addtoindexx{bit stride attribute}
1482 which specifies the separation
1483 between successive elements along the dimension as described
1484 in 
1485 Section \refersec{chap:visibilityofdeclarations}. 
1486 The value of the 
1487 \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute
1488 \addtoindexx{bit stride attribute}
1489 is interpreted as bits and the value of 
1490 \addtoindexx{byte stride attribute}
1491 the 
1492 \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride}
1493 attribute is interpreted as bytes.
1494
1495
1496 \section{Subroutine Type Entries}
1497 \label{chap:subroutinetypeentries}
1498
1499 It is possible in \addtoindex{C}
1500 to declare pointers to subroutines
1501 that return a value of a specific type. In both 
1502 \addtoindex{C} and \addtoindex{C++},
1503 it is possible to declare pointers to subroutines that not
1504 only return a value of a specific type, but accept only
1505 arguments of specific types. The type of such pointers would
1506 be described with a ``pointer to'' modifier applied to a
1507 user\dash defined type.
1508
1509 A subroutine type is represented by a debugging information
1510 entry with the 
1511 tag \livetarg{chap:DWTAGsubroutinetype}{DW\-\_TAG\-\_subroutine\-\_type}. 
1512 If a name has
1513 been given to the subroutine type in the source program,
1514 then the corresponding subroutine type entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name}
1515 attribute whose value is a null\dash terminated string containing
1516 the subroutine type name as it appears in the source program.
1517
1518 If the subroutine type describes a function that returns
1519 a value, then the subroutine type entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type}
1520 attribute to denote the type returned by the subroutine. If
1521 the types of the arguments are necessary to describe the
1522 subroutine type, then the corresponding subroutine type
1523 entry owns debugging information entries that describe the
1524 arguments. These debugging information entries appear in the
1525 order that the corresponding argument types appear in the
1526 source program.
1527
1528 In \addtoindex{C} there 
1529 is a difference between the types of functions
1530 declared using function prototype style declarations and
1531 those declared using non\dash prototype declarations.
1532
1533
1534 \hypertarget{chap:DWATprototypedsubroutineprototype}
1535 subroutine entry declared with a function prototype style
1536 declaration may have a 
1537 \livelink{chap:DWATprototyped}{DW\-\_AT\-\_prototyped} attribute, which is
1538 a \livelink{chap:flag}{flag}.
1539
1540 Each debugging information entry owned by a subroutine
1541 type entry has a tag whose value has one of two possible
1542 interpretations:
1543
1544 \begin{enumerate}[1.]
1545 \item The formal parameters of a parameter list (that have a
1546 specific type) are represented by a debugging information entry
1547 with the tag \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}. Each formal parameter
1548 entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute that refers to the type of
1549 the formal parameter.
1550
1551 \item The unspecified parameters of a variable parameter list
1552 \addtoindexx{unspecified parameters entry}
1553 are 
1554 \addtoindexx{... parameters|see{unspecified parameters entry}}
1555 represented by a debugging information entry with the
1556 tag \livelink{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters}.
1557 \end{enumerate}
1558
1559
1560
1561 \section{String Type Entries}
1562 \label{chap:stringtypeentries}
1563
1564
1565 A ``string'' is a sequence of characters that have specific
1566 semantics and operations that separate them from arrays of
1567 characters. Fortran is one of the languages that has a string
1568 type. Note that ``string'' in this context refers to a target
1569 machine concept, not the class string as used in this document
1570 (except for the name attribute).
1571
1572 A string type is represented by a debugging information entry
1573 with the tag \livetarg{chap:DWTAGstringtype}{DW\-\_TAG\-\_string\-\_type}. 
1574 If a name has been given to
1575 the string type in the source program, then the corresponding
1576 string type entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is
1577 a null\dash terminated string containing the string type name as
1578 it appears in the source program.
1579
1580 The 
1581 \hypertarget{chap:DWATstringlengthstringlengthofstringtype}
1582 string type entry may have a 
1583 \livelink{chap:DWATstringlength}{DW\-\_AT\-\_string\-\_length} attribute
1584 whose value is a location description yielding the location
1585 where the length of the string is stored in the program. The
1586 string type entry may also have a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute
1587 or \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute, whose value 
1588 (see Section \refersec{chap:byteandbitsizes}) 
1589 is the size of the data to be retrieved from the location
1590 referenced by the string length attribute. If no (byte or bit)
1591 size attribute is present, the size of the data to be retrieved
1592 is the same as the size of an address on the target machine.
1593
1594 If no string length attribute is present, the string type
1595 entry may have a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute or \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}
1596 attribute, whose value 
1597 (see Section \refersec{chap:byteandbitsizes}) 
1598 is the amount of
1599 storage needed to hold a value of the string type.
1600
1601
1602 \section{Set Type Entries}
1603 \label{chap:settypeentries}
1604
1605 \textit{Pascal provides the concept of a “set,” which represents
1606 a group of values of ordinal type.}
1607
1608 A set is represented by a debugging information entry with
1609 the tag \livetarg{chap:DWTAGsettype}{DW\-\_TAG\-\_set\-\_type}. 
1610 If a name has been given to the
1611 set type, then the set type entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
1612 whose value is a null\dash terminated string containing the
1613 set type name as it appears in the source program.
1614
1615 The set type entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute to denote the
1616 type of an element of the set.
1617
1618 If the amount of storage allocated to hold each element of an
1619 object of the given set type is different from the amount of
1620 storage that is normally allocated to hold an individual object
1621 of the indicated element type, then the set type entry has
1622 either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute, or \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute
1623 whose value (see Section \refersec{chap:byteandbitsizes}) is
1624 the amount of storage needed to hold a value of the set type.
1625
1626
1627 \section{Subrange Type Entries}
1628 \label{chap:subrangetypeentries}
1629
1630 \textit{Several languages support the concept of a ``subrange''
1631 type object. These objects can represent a subset of the
1632 values that an object of the basis type for the subrange can
1633 represent. Subrange type entries may also be used to represent
1634 the bounds of array dimensions.}
1635
1636 A subrange type is represented by a debugging information
1637 entry with the 
1638 tag \livetarg{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}. 
1639 If a name has been
1640 given to the subrange type, then the subrange type entry
1641 has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null\dash terminated
1642 string containing the subrange type name as it appears in
1643 the source program.
1644
1645 The subrange entry may have a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute to describe
1646 the type of object, called the basis type, of whose values
1647 this subrange is a subset.
1648
1649 If the amount of storage allocated to hold each element of an
1650 object of the given subrange type is different from the amount
1651 of storage that is normally allocated to hold an individual
1652 object of the indicated element type, then the subrange
1653 type entry has a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute or \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}
1654 attribute, whose value 
1655 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1656 is the amount of
1657 storage needed to hold a value of the subrange type.
1658
1659 The 
1660 \hypertarget{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}
1661 subrange entry may have a \livelink{chap:DWATthreadsscaled}{DW\-\_AT\-\_threads\-\_scaled} attribute,
1662 which is a \livelink{chap:flag}{flag}. 
1663 If present, this attribute indicates whether
1664 this subrange represents a UPC array bound which is scaled
1665 by the runtime THREADS value (the number of UPC threads in
1666 this execution of the program).
1667
1668 \textit{This allows the representation of a UPC shared array such as}
1669
1670 \begin{lstlisting}
1671 int shared foo[34*THREADS][10][20];
1672 \end{lstlisting}
1673
1674 The 
1675 \hypertarget{chap:DWATlowerboundlowerboundofsubrange}
1676 subrange 
1677 \hypertarget{chap:DWATupperboundupperboundofsubrange}
1678 entry may have the attributes 
1679 \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}
1680 and \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound} to specify, respectively, the lower
1681 and upper bound values of the subrange. The \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}
1682 attribute 
1683 \hypertarget{chap:DWATcountelementsofsubrangetype}
1684 may be replaced by a 
1685 \livelink{chap:DWATcount}{DW\-\_AT\-\_count} attribute, whose
1686 value describes the number of elements in the subrange rather
1687 than the value of the last element. The value of each of
1688 these attributes is determined as described in 
1689 Section \refersec{chap:staticanddynamicvaluesofattributes}.
1690
1691 If the lower bound value is missing, the value is assumed to
1692 be a language\dash dependent default constant. The default lower
1693 bound is 0 for 
1694 \addtoindex{C}, \addtoindex{C++}, 
1695 \addtoindex{D}, 
1696 \addtoindex{Java}, 
1697 \addtoindex{Objective C}, 
1698 \addtoindex{Objective C++},
1699 \addtoindex{Python}, and 
1700 \addtoindex{UPC}. 
1701 The default lower bound is 1 for 
1702 \addtoindex{Ada}, \addtoindex{COBOL},
1703 \addtoindex{Fortran}, 
1704 \addtoindex{Modula}\dash 2, 
1705 \addtoindex{Pascal} and 
1706 \addtoindex{PL/I}.
1707
1708 \textit{No other default lower bound values are currently defined.}
1709
1710 If the upper bound and count are missing, then the upper bound value is 
1711 \textit{unknown}.
1712
1713 If the subrange entry has no type attribute describing the
1714 basis type, the basis type is assumed to be the same as
1715 the object described by the lower bound attribute (if it
1716 references an object). If there is no lower bound attribute,
1717 or that attribute does not reference an object, the basis type
1718 is the type of the upper bound or count attribute (if either
1719 of them references an object). If there is no upper bound or
1720 count attribute, or neither references an object, the type is
1721 assumed to be the same type, in the source language of the
1722 compilation unit containing the subrange entry, as a signed
1723 integer with the same size as an address on the target machine.
1724
1725 If the subrange type occurs as the description of a dimension
1726 of an array type, and the stride for that dimension is
1727 \hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}
1728 different than what would otherwise be determined, then
1729 \hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}
1730 the subrange type entry has either 
1731 \addtoindexx{byte stride attribute}
1732
1733 \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} or
1734 \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute 
1735 \addtoindexx{bit stride attribute}
1736 which specifies the separation
1737 between successive elements along the dimension as described
1738 in 
1739 Section \refersec{chap:byteandbitsizes}.
1740
1741 \textit{Note that the stride can be negative.}
1742
1743 \section{Pointer to Member Type Entries}
1744 \label{chap:pointertomembertypeentries}
1745
1746 \textit{In \addtoindex{C++}, a pointer to a data or function member of a class or
1747 structure is a unique type.}
1748
1749 A debugging information entry representing the type of an
1750 object that is a pointer to a structure or class member has
1751 the tag \livetarg{chap:DWTAGptrtomembertype}{DW\-\_TAG\-\_ptr\-\_to\-\_member\-\_type}.
1752
1753 If the pointer to member type has a name, the pointer to
1754 member entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is a
1755 null\dash terminated string containing the type name as it appears
1756 in the source program.
1757
1758 The pointer to member entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute to
1759 describe the type of the class or structure member to which
1760 objects of this type may point.
1761
1762 The pointer to member entry also 
1763 \hypertarget{chap:DWATcontainingtypecontainingtypeofpointertomembertype}
1764 has a 
1765 \livelink{chap:DWATcontainingtype}{DW\-\_AT\-\_containing\-\_type}
1766 attribute, whose value is a reference to a debugging
1767 information entry for the class or structure to whose members
1768 objects of this type may point.
1769
1770 The 
1771 \hypertarget{chap:DWATuselocationmemberlocationforpointertomembertype}
1772 pointer to member entry has a 
1773 \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} attribute
1774 whose value is a location description that computes the
1775 address of the member of the class to which the pointer to
1776 member entry points.
1777
1778 \textit{The method used to find the address of a given member of a
1779 class or structure is common to any instance of that class
1780 or structure and to any instance of the pointer or member
1781 type. The method is thus associated with the type entry,
1782 rather than with each instance of the type.}
1783
1784 The \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} description is used in conjunction
1785 with the location descriptions for a particular object of the
1786 given pointer to member type and for a particular structure or
1787 class instance. The \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} attribute expects two
1788 values to be 
1789 \addtoindexi{pushed}{address!implicit push for member operator}
1790 onto the DWARF expression stack before
1791 the \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} description is evaluated. The first
1792 value 
1793 \addtoindexi{pushed}{address!implicit push for member operator}
1794 is the value of the pointer to member object
1795 itself. The second value 
1796 \addtoindexi{pushed}{address!implicit push for member operator} 
1797 is the base address of the
1798 entire structure or union instance containing the member
1799 whose address is being calculated.
1800
1801 \textit{For an expression such as}
1802
1803 \begin{lstlisting}
1804     object.*mbr_ptr
1805 \end{lstlisting}
1806 % FIXME: object and mbr\_ptr should be distinguished from italic. See DW4.
1807 \textit{where mbr\_ptr has some pointer to member type, a debugger should:}
1808
1809 \textit{1. Push the value of mbr\_ptr onto the DWARF expression stack.}
1810
1811 \textit{2. Push the base address of object onto the DWARF expression stack.}
1812
1813 \textit{3. Evaluate the \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} description 
1814 given in the type of mbr\_ptr.}
1815
1816 \section{File Type Entries}
1817 \label{chap:filetypeentries}
1818
1819 \textit{Some languages, such as Pascal, provide a data type to represent 
1820 files.}
1821
1822 A file type is represented by a debugging information entry
1823 with the 
1824 \livetarg{chap:DWTAGfiletype}{DW\-\_TAG\-\_file\-\_type}. 
1825 If the file type has a name,
1826 the file type entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value
1827 is a null\dash terminated string containing the type name as it
1828 appears in the source program.
1829
1830 The file type entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute describing
1831 the type of the objects contained in the file.
1832
1833 The file type entry also 
1834 \addtoindexx{byte size}
1835 has 
1836 \addtoindexx{bit size}
1837
1838 \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} or
1839 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute, whose value 
1840 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1841 is the amount of storage need to hold a value of the file type.
1842
1843 \section{Dynamic Type Properties}
1844 \label{chap:dynamictypeproperties}
1845 \subsection{Data Location}
1846 \label{chap:datalocation}
1847
1848 \textit{Some languages may represent objects using descriptors to hold
1849 information, including a location and/or run\dash time parameters,
1850 about the data that represents the value for that object.}
1851
1852 \hypertarget{chap:DWATdatalocationindirectiontoactualdata}
1853 The \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} 
1854 attribute may be used with any
1855 type that provides one or more levels of hidden indirection
1856 and/or run\dash time parameters in its representation. Its value
1857 is a location description. The result of evaluating this
1858 description yields the location of the data for an object.
1859 When this attribute is omitted, the address of the data is
1860 the same as the address of the object.
1861
1862 \textit{This location description will typically begin with
1863 \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} 
1864 which loads the address of the
1865 object which can then serve as a descriptor in subsequent
1866 calculation. For an example using 
1867 \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} 
1868 for a Fortran 90 array, see 
1869 Appendix \refersec{app:fortran90example}.}
1870
1871 \subsection{Allocation and Association Status}
1872 \label{chap:allocationandassociationstatus}
1873
1874 \textit{Some languages, such as Fortran 90, provide types whose values
1875 may be dynamically allocated or associated with a variable
1876 under explicit program control.}
1877
1878 \hypertarget{chap:DWATallocatedallocationstatusoftypes}
1879 The 
1880 \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated} 
1881 attribute 
1882 \addtoindexx{allocated attribute}
1883 may optionally be used with any
1884 type for which objects of the type can be explicitly allocated
1885 and deallocated. The presence of the attribute indicates that
1886 objects of the type are allocatable and deallocatable. The
1887 integer value of the attribute (see below) specifies whether
1888 an object of the type is 
1889 currently allocated or not.
1890
1891 \hypertarget{chap:DWATassociatedassociationstatusoftypes}
1892 The 
1893 \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} attribute 
1894 may 
1895 \addtoindexx{associated attribute}
1896 optionally be used with
1897 any type for which objects of the type can be dynamically
1898 associated with other objects. The presence of the attribute
1899 indicates that objects of the type can be associated. The
1900 integer value of the attribute (see below) indicates whether
1901 an object of the type is currently associated or not.
1902
1903 While these attributes are defined specifically with Fortran
1904 90 ALLOCATABLE and POINTER types in mind, usage is not limited
1905 to just that language.
1906
1907 The value of these attributes is determined as described in
1908 Section \refersec{chap:staticanddynamicvaluesofattributes}.
1909
1910 A non\dash zero value is interpreted as allocated or associated,
1911 and zero is interpreted as not allocated or not associated.
1912
1913 \textit{For \addtoindex{Fortran} 90, 
1914 if the \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} 
1915 attribute is present,
1916 the type has the POINTER property where either the parent
1917 variable is never associated with a dynamic object or the
1918 implementation does not track whether the associated object
1919 is static or dynamic. If the \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated} attribute is
1920 present and the \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} attribute is not, the type
1921 has the ALLOCATABLE property. If both attributes are present,
1922 then the type should be assumed to have the POINTER property
1923 (and not ALLOCATABLE); the \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated} attribute may then
1924 be used to indicate that the association status of the object
1925 resulted from execution of an ALLOCATE statement rather than
1926 pointer assignment.}
1927
1928 \textit{For examples using 
1929 \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated} for \addtoindex{Ada} and 
1930 \addtoindex{Fortran} 90
1931 arrays, 
1932 see Appendix \refersec{app:aggregateexamples}.}
1933
1934
1935
1936 \section{Template Alias Entries}
1937 \label{chap:templatealiasentries}
1938
1939 A type named using a template alias is represented
1940 by a debugging information entry with the tag
1941 \livetarg{chap:DWTAGtemplatealias}{DW\-\_TAG\-\_template\-\_alias}. 
1942 The template alias entry has a
1943 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null\dash terminated string
1944 containing the name of the template alias as it appears in
1945 the source program. The template alias entry also contains a
1946 \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute whose value is a reference to the type
1947 named by the template alias. The template alias entry has
1948 the following child entries:
1949
1950 \begin{enumerate}[1.]
1951 \item Each formal parameterized type declaration appearing
1952 in the template alias declaration is represented
1953 by a debugging information entry with the tag
1954 \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}. Each such entry may have
1955 a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is a null\dash terminated
1956 string containing the name of the formal type parameter as it
1957 appears in the source program. The template type parameter
1958 entry also has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute describing the actual
1959 type by which the formal is replaced for this instantiation.
1960
1961 \item Each formal parameterized value declaration
1962 appearing in the template alias declaration is
1963 represented by a debugging information entry with the tag
1964 \livelink{chap:DWTAGtemplatevalueparameter}{DW\-\_TAG\-\_template\-\_value\-\_parameter}. Each such entry may have
1965 a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is a null\dash terminated
1966 string containing the name of the formal value parameter
1967 as it appears in the source program. The template value
1968 parameter entry also has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute describing
1969 the type of the parameterized value. Finally, the template
1970 value parameter entry has a \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute, whose
1971 value is the actual constant value of the value parameter for
1972 this instantiation as represented on the target architecture.
1973 \end{enumerate}
1974