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