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