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