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