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