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