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