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