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