1 \chapter{Program Scope Entries}
2 \label{chap:programscopeentries}
3 This section describes debugging information entries that
4 relate to different levels of program scope: compilation,
5 module, subprogram, and so on. Except for separate type
6 entries (see Section \refersec{chap:separatetypeunitentries}),
7 these entries may be thought of
8 as bounded by ranges of text addresses within the program.
10 \section{Unit Entries}
11 An object file may contain one or more compilation units,
12 of which there are three kinds: normal compilation units,
13 partial compilation units and type units. A partial compilation
14 unit is related to one or more other compilation units that
15 import it. A type unit represents a single complete type in a
16 separate unit. Either a normal compilation unit or a partial
17 compilation unit may be logically incorporated into another
18 compilation unit using an
19 \addtoindex{imported unit entry}.
21 \subsection[Normal and Partial CU Entries]{Normal and Partial Compilation Unit Entries}
22 \label{chap:normalandpartialcompilationunitentries}
24 A \addtoindex{normal compilation unit} is represented by a
25 debugging information entry with the
26 tag \livetarg{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}. A partial
27 compilation unit is represented by a debugging information
29 tag \livetarg{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}.
31 In a simple normal compilation, a single compilation unit with
33 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} represents a complete object file
35 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} is not used.
37 employing the DWARF space compression and duplicate elimination
39 Appendix \refersec{app:usingcompilationunits},
40 multiple compilation units using
42 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} and/or
43 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} are
44 used to represent portions of an object file.
46 \textit{A normal compilation unit typically represents the text and
47 data contributed to an executable by a single relocatable
48 object file. It may be derived from several source files,
49 including pre\dash processed ``include files.'' A partial
50 compilation unit typically represents a part of the text
51 and data of a relocatable object file, in a manner that can
52 potentially be shared with the results of other compilations
53 to save space. It may be derived from an ``include file'',
54 template instantiation, or other implementation\dash dependent
55 portion of a compilation. A normal compilation unit can also
56 function in a manner similar to a partial compilation unit
59 A compilation unit entry owns debugging information
60 entries that represent all or part of the declarations
61 made in the corresponding compilation. In the case of a
62 partial compilation unit, the containing scope of its owned
63 declarations is indicated by imported unit entries in one
64 or more other compilation unit entries that refer to that
65 partial compilation unit (see
66 Section \refersec{chap:importedunitentries}).
69 Compilation unit entries may have the following
73 \item Either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
74 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of
75 \addtoindexx{high PC attribute}
77 \addtoindexx{low PC attribute}
79 \addtoindexx{ranges attribute}
81 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
82 \addtoindexx{ranges attribute}
84 \addtoindexx{discontiguous address ranges|see{non-contiguous address ranges}}
87 non\dash contiguous address ranges, respectively,
88 of the machine instructions generated for the compilation
89 unit (see Section {chap:codeaddressesandranges}).
90 A \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute
94 \addtoindexx{ranges attribute}
96 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} to specify the
97 \addtoindexx{ranges attribute}
98 default base address for use in
99 \addtoindexx{location list}
100 location lists (see Section
101 \refersec{chap:locationlists}) and range lists
102 (see Section \refersec{chap:noncontiguousaddressranges}).
104 \item A \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
105 \addtoindexx{name attribute}
106 whose value is a null\dash terminated
108 \hypertarget{chap:DWATnamepathnameofcompilationsource}
109 containing the full or relative path name of the primary
110 source file from which the compilation unit was derived.
112 \item A \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} attribute
113 \addtoindexx{language attribute}
114 whose constant value is an
115 \hypertarget{chap:DWATlanguageprogramminglanguage}
117 \addtoindexx{language attribute}
118 indicating the source language of the compilation
119 unit. The set of language names and their meanings are given
121 Figure \refersec{fig:languagenames}.
125 \caption{Language names}
126 \label{fig:languagenames}
128 Language name & Meaning\\ \hline
129 \livetarg{chap:DWLANGAda83}{DW\-\_LANG\-\_Ada83} \dag&ISO \addtoindex{Ada}:1983 \addtoindexx{Ada} \\
130 \livetarg{chap:DWLANGAda95}{DW\-\_LANG\-\_Ada95} \dag&ISO Ada:1995 \addtoindexx{Ada} \\
131 \livetarg{chap:DWLANGC}{DW\-\_LANG\-\_C}&Non-standardized C, such as K\&R \\
132 \livetarg{chap:DWLANGC89}{DW\-\_LANG\-\_C89}&ISO C:1989 \\
133 \livetarg{chap:DWLANGC99}{DW\-\_LANG\-\_C99} & ISO \addtoindex{C}:1999 \\
134 \livetarg{chap:DWLANGCplusplus}{DW\-\_LANG\-\_C\-\_plus\-\_plus}&ISO \addtoindex{C++}:1998 \\
135 \livetarg{chap:DWLANGCobol74}{DW\-\_LANG\-\_Cobol74}& ISO \addtoindex{Cobol}:1974 \\
136 \livetarg{chap:DWLANGCobol85}{DW\-\_LANG\-\_Cobol85} & ISO \addtoindex{Cobol}:1985 \\
137 \livetarg{chap:DWLANGD}{DW\-\_LANG\-\_D} \dag & D \addtoindexx{D language} \\
138 \livetarg{chap:DWLANGFortran77}{DW\-\_LANG\-\_Fortran77} &ISO \addtoindex{FORTRAN} 77\\
139 \livetarg{chap:DWLANGFortran90}{DW\-\_LANG\-\_Fortran90} & ISO \addtoindex{Fortran 90}\\
140 \livetarg{chap:DWLANGFortran95}{DW\-\_LANG\-\_Fortran95} & ISO \addtoindex{Fortran 95}\\
141 \livetarg{chap:DWLANGJava}{DW\-\_LANG\-\_Java} & \addtoindex{Java}\\
142 \livetarg{chap:DWLANGModula2}{DW\-\_LANG\-\_Modula2} & ISO Modula\dash 2:1996 \addtoindexx{Modula-2}\\
143 \livetarg{chap:DWLANGObjC}{DW\-\_LANG\-\_ObjC} & \addtoindex{Objective C}\\
144 \livetarg{chap:DWLANGObjCplusplus}{DW\-\_LANG\-\_ObjC\-\_plus\-\_plus} & \addtoindex{Objective C++}\\
145 \livetarg{chap:DWLANGPascal83}{DW\-\_LANG\-\_Pascal83} & ISO \addtoindex{Pascal}:1983\\
146 \livetarg{chap:DWLANGPLI}{DW\-\_LANG\-\_PLI} \dag & ANSI \addtoindex{PL/I}:1976\\
147 \livetarg{chap:DWLANGPython}{DW\-\_LANG\-\_Python} \dag & \addtoindex{Python}\\
148 \livetarg{chap:DWLANGUPC}{DW\-\_LANG\-\_UPC} &\addtoindex{Unified Parallel C}\\ \hline
149 \dag \ \ Support for these languages is limited.& \\
153 \item A \livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list} attribute whose value is a section
154 \hypertarget{chap:DWATstmtlistlinenumberinformationforunit}
155 offset to the line number information for this compilation
156 unit. This information is placed in a separate object file
157 section from the debugging information entries themselves. The
158 value of the statement list attribute is the offset in the
159 \addtoindex{.debug\_line} section of the first byte of the line number
160 information for this compilation unit
161 (see Section \refersec{chap:linenumberinformation}).
163 \item A \livelink{chap:DWATmacroinfo}{DW\-\_AT\-\_macro\-\_info} attribute
164 \addtoindex{macro information attribute}
165 whose value is a section
166 \hypertarget{chap:DWATmacroinfomacroinformation}
167 offset to the macro information for this compilation unit.
168 This information is placed in a separate object file section
169 from the debugging information entries themselves. The
170 value of the macro information attribute is the offset in
171 the \addtoindex{.debug\_macinfo} section of the first byte of the macro
172 information for this compilation unit
173 (see Section \refersec{chap:macroinformation}).
176 \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir}
178 \hypertarget{chap:DWATcompdircompilationdirectory}
180 null\dash terminated string containing the current working directory
181 of the compilation command that produced this compilation
182 unit in whatever form makes sense for the host system.
184 \item A \livelink{chap:DWATproducer}{DW\-\_AT\-\_producer} attribute whose value is a null\dash
185 terminated string containing information about the compiler
186 \hypertarget{chap:DWATproducercompileridentification}
187 that produced the compilation unit. The actual contents of
188 the string will be specific to each producer, but should
189 begin with the name of the compiler vendor or some other
190 identifying character sequence that should avoid confusion
191 with other producer values.
194 \item A \livelink{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case}
196 \addtoindexx{identifier case attribute}
198 \hypertarget{chap:DWATidentifiercaseidentifiercaserule}
199 constant value is a code describing the treatment
200 of identifiers within this compilation unit. The
201 set of identifier case codes
203 \refersec{fig:identifiercasecodes}.
206 \autorows[0pt]{c}{1}{l}{
207 \livelink{chap:DWIDcasesensitive}{DW\-\_ID\-\_case\-\_sensitive},
208 \livelink{chap:DWIDupcase}{DW\-\_ID\-\_up\-\_case},
209 \livelink{chap:DWIDdowncase}{DW\-\_ID\-\_down\-\_case},
210 \livelink{chap:DWIDcaseinsensitive}{DW\-\_ID\-\_case\-\_insensitive}
212 \caption{Identifier case codes}\label{fig:identifiercasecodes}
215 \livetarg{chap:DWIDcasesensitive}{DW\-\_ID\-\_case\-\_sensitive} is the default for all compilation units
216 that do not have this attribute. It indicates that names given
217 as the values of \livelink{chap:DWATname}{DW\-\_AT\-\_name} attributes
218 \addtoindexx{name attribute}
219 in debugging information
220 entries for the compilation unit reflect the names as they
221 appear in the source program. The debugger should be sensitive
222 to the case of identifier names when doing identifier lookups.
224 \livetarg{chap:DWIDupcase}{DW\-\_ID\-\_up\-\_case} means that the producer of the debugging
225 information for this compilation unit converted all source
226 names to upper case. The values of the name attributes may not
227 reflect the names as they appear in the source program. The
228 debugger should convert all names to upper case when doing
231 \livetarg{chap:DWIDdowncase}{DW\-\_ID\-\_down\-\_case} means that the producer of the debugging
232 information for this compilation unit converted all source
233 names to lower case. The values of the name attributes may not
234 reflect the names as they appear in the source program. The
235 debugger should convert all names to lower case when doing
238 \livetarg{chap:DWIDcaseinsensitive}{DW\-\_ID\-\_case\-\_insensitive} means that the values of the name
239 attributes reflect the names as they appear in the source
240 program but that a case insensitive lookup should be used to
243 \item A \livelink{chap:DWATbasetypes}{DW\-\_AT\-\_base\-\_types} attribute whose value is a reference.
247 \hypertarget{chap:DWATbasetypesprimitivedatatypesofcompilationunit}
249 \addtoindexx{base types attribute}
250 points to a debugging information entry
251 representing another compilation unit. It may be used
252 to specify the compilation unit containing the base type
253 entries used by entries in the current compilation unit
254 (see Section \refersec{chap:basetypeentries}).
256 This attribute provides a consumer a way to find the definition
257 of base types for a compilation unit that does not itself
258 contain such definitions. This allows a consumer, for example,
259 to interpret a type conversion to a base type
260 % getting this link target at the right spot is tricky.
261 \hypertarget{chap:DWATuseUTF8compilationunitusesutf8strings}
264 \item A \livelink{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8} attribute,
265 which is a \livelink{chap:flag}{flag} whose
266 presence indicates that all strings (such as the names of
267 declared entities in the source program) are represented
268 using the UTF\dash 8 representation
269 (see Section \refersec{datarep:attributeencodings}).
272 \item A \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram} attribute, which is a \livelink{chap:flag}{flag}
273 \addtoindexx{main subprogram attribute}
274 whose presence indicates
275 \hypertarget{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}
276 that the compilation unit contains a
277 subprogram that has been identified as the starting function
278 of the program. If more than one compilation unit contains
279 this \nolink{flag}, any one of them may contain the starting function.
281 \textit{\addtoindex{Fortran} has a PROGRAM statement which is used
282 to specify and provide a user\dash specified name for the main
283 subroutine of a program.
284 \addtoindex{C} uses the name “main” to identify
285 the main subprogram of a program. Some other languages provide
286 similar or other means to identify the main subprogram of
291 The base address of a compilation unit is defined as the
292 value of the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute, if present; otherwise,
293 it is undefined. If the base address is undefined, then any
294 DWARF entry or structure defined in terms of the base address
295 of that compilation unit is not valid.
298 \subsection{Imported Unit Entries}
299 \label{chap:importedunitentries}
301 \hypertarget{chap:DWATimportimportedunit}
302 place where a normal or partial unit is imported is
303 represented by a debugging information entry with the
304 \addtoindexx{imported unit entry}
305 tag \livetarg{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}.
306 An imported unit entry contains
307 \addtoindexx{import attribute}
309 \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute
310 whose value is a reference to the
311 normal or partial compilation unit whose declarations logically
312 belong at the place of the imported unit entry.
314 An imported unit entry does not necessarily correspond to
315 any entity or construct in the source program. It is merely
316 “glue” used to relate a partial unit, or a compilation
317 unit used as a partial unit, to a place in some other
320 \subsection{Separate Type Unit Entries}
321 \label{chap:separatetypeunitentries}
322 An object file may contain any number of separate type
323 unit entries, each representing a single complete type
324 definition. Each type unit must be uniquely identified by
325 a 64\dash bit signature, stored as part of the type unit, which
326 can be used to reference the type definition from debugging
327 information entries in other compilation units and type units.
329 A type unit is represented by a debugging information entry
330 with the tag \livetarg{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit}.
331 A type unit entry owns debugging
332 information entries that represent the definition of a single
333 type, plus additional debugging information entries that may
334 be necessary to include as part of the definition of the type.
336 A type unit entry may have a
337 \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} attribute,
339 \addtoindexx{language attribute}
340 constant value is an integer code indicating the source
341 language used to define the type. The set of language names
342 and their meanings are given in Figure \refersec{fig:languagenames}.
344 A type unit entry for a given type T owns a debugging
345 information entry that represents a defining declaration
346 of type T. If the type is nested within enclosing types or
347 namespaces, the debugging information entry for T is nested
348 within debugging information entries describing its containers;
349 otherwise, T is a direct child of the type unit entry.
351 A type unit entry may also own additional debugging information
352 entries that represent declarations of additional types that
353 are referenced by type T and have not themselves been placed in
354 separate type units. Like T, if an additional type U is nested
355 within enclosing types or namespaces, the debugging information
356 entry for U is nested within entries describing its containers;
357 otherwise, U is a direct child of the type unit entry.
359 The containing entries for types T and U are declarations,
360 and the outermost containing entry for any given type T or
361 U is a direct child of the type unit entry. The containing
362 entries may be shared among the additional types and between
363 T and the additional types.
365 Types are not required to be placed in type units. In general,
366 only large types such as structure, class, enumeration, and
367 union types included from header files should be considered
368 for separate type units. Base types and other small types
369 are not usually worth the overhead of placement in separate
370 type units. Types that are unlikely to be replicated, such
371 as those defined in the main source file, are also better
372 left in the main compilation unit.
374 \section{Module, Namespace and Importing Entries}
375 \textit{Modules and namespaces provide a means to collect related
376 entities into a single entity and to manage the names of
379 \subsection{Module Entries}
380 \label{chap:moduleentries}
381 \textit{Several languages have the concept of a ``module.''
382 \addtoindexx{Modula-2}
383 A Modula\dash 2 definition module
384 \addtoindexx{Modula-2!definition module}
385 may be represented by a module
387 \addtoindex{declaration attribute}
388 (\livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}). A
389 \addtoindex{Fortran 90} module
390 \addtoindexx{Fortran!module (Fortran 90)}
391 may also be represented by a module entry
392 (but no declaration attribute is warranted because \addtoindex{Fortran}
393 has no concept of a corresponding module body).}
395 A module is represented by a debugging information entry
397 tag \livetarg{chap:DWTAGmodule}{DW\-\_TAG\-\_module}.
398 Module entries may own other
399 debugging information entries describing program entities
400 whose declaration scopes end at the end of the module itself.
402 If the module has a name, the module entry has a
403 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
404 \addtoindexx{name attribute}
405 whose value is a null\dash terminated string containing
406 the module name as it appears in the source program.
408 The \addtoindex{module entry} may have either a
409 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
410 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}
412 \addtoindexx{high PC attribute}
414 \addtoindexx{low PC attribute}
416 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
417 \addtoindexx{ranges attribute}
418 whose values encode the contiguous or non\dash contiguous address
419 ranges, respectively, of the machine instructions generated for
420 the module initialization code
421 (see Section \refersec{chap:codeaddressesandranges}).
422 \hypertarget{chap:DWATentrypcentryaddressofmoduleinitialization}
424 \addtoindexx{entry pc attribute!for module initialization}
426 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute whose value is the address of
427 the first executable instruction of that initialization code
428 (see Section \refersec{chap:entryaddress}).
431 \hypertarget{chap:DWATprioritymodulepriority}
432 the module has been assigned a priority, it may have a
433 \livelink{chap:DWATpriority}{DW\-\_AT\-\_priority} attribute. The value of this attribute is a
434 reference to another debugging information entry describing
435 a variable with a constant value. The value of this variable
436 is the actual constant value of the module’s priority,
437 represented as it would be on the target architecture.
439 \subsection{Namespace Entries}
440 \label{chap:namespaceentries}
441 \textit{\addtoindex{C++} has the notion of a namespace, which provides a way to
442 \addtoindexx{namespace (C++)}
443 implement name hiding, so that names of unrelated things
444 do not accidentally clash in the
445 \addtoindex{global namespace} when an
446 application is linked together.}
448 A namespace is represented by a debugging information entry
450 tag \livetarg{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}.
451 A namespace extension is
452 \hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}
454 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} entry
456 \addtoindexx{extension attribute}
458 \livelink{chap:DWATextension}{DW\-\_AT\-\_extension}
459 attribute referring to the previous extension, or if there
460 is no previous extension, to the original
461 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
462 entry. A namespace extension entry does not need to duplicate
463 information in a previous extension entry of the namespace
464 nor need it duplicate information in the original namespace
465 entry. (Thus, for a namespace with a name,
466 a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
467 \addtoindexx{name attribute}
468 need only be attached directly to the original
469 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} entry.)
471 Namespace and namespace extension entries may own
472 \addtoindexx{namespace extension entry}
474 \addtoindexx{namespace declaration entry}
475 debugging information entries describing program entities
476 whose declarations occur in the namespace.
478 \textit{For \addtoindex{C++}, such
479 owned program entities may be declarations,
480 including certain declarations that are also object or
481 function definitions.}
483 If a type, variable, or function declared in a namespace is
484 defined outside of the body of the namespace declaration,
485 that type, variable, or function definition entry has a
486 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute
487 whose value is a reference to the
488 debugging information entry representing the declaration of
489 the type, variable or function. Type, variable, or function
490 entries with a \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute do not need
491 to duplicate information provided by the declaration entry
492 referenced by the specification attribute.
494 \textit{The \addtoindex{C++} \addtoindex{global namespace}
496 \addtoindexx{global namespace|see{namespace (C++), global}}
498 \addtoindexx{namespace (C++)!global}
500 ``::f'', for example) is not explicitly represented in
501 DWARF with a namespace entry (thus mirroring the situation
502 in \addtoindex{C++} source).
503 Global items may be simply declared with no
504 reference to a namespace.}
506 \textit{The \addtoindex{C++}
507 compilation unit specific ``unnamed namespace'' may
508 \addtoindexx{namespace (C++)!unnamed}
509 be represented by a namespace entry with no name attribute in
510 the original namespace declaration entry (and therefore no name
511 attribute in any namespace extension entry of this namespace).
514 \textit{A compiler emitting namespace information may choose to
515 explicitly represent namespace extensions, or to represent the
516 final namespace declaration of a compilation unit; this is a
517 quality\dash of\dash implementation issue and no specific requirements
518 are given here. If only the final namespace is represented,
519 \addtoindexx{namespace (C++)!using declaration}
520 it is impossible for a debugger to interpret using declaration
521 references in exactly the manner defined by the
522 \addtoindex{C++} language.
525 \textit{Emitting all namespace declaration information in all
526 compilation units can result in a significant increase in the
527 size of the debug information and significant duplication of
528 information across compilation units.
529 The \addtoindex{C++} namespace std,
531 \addtoindexx{namespace (C++)!std}
532 is large and will probably be referenced in
533 every \addtoindex{C++} compilation unit.
536 \textit{For a \addtoindex{C++} namespace example,
537 see Appendix \refersec{app:namespaceexample}.
542 \subsection{Imported (or Renamed) Declaration Entries}
543 \label{chap:importedorrenameddeclarationentries}
544 \textit{Some languages support the concept of importing into or making
545 accessible in a given unit declarations made in a different
546 module or scope. An imported declaration may sometimes be
551 imported declaration is represented by one or
552 \addtoindex{imported declaration entry}
553 more debugging information entries with the
554 tag \livetarg{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}.
556 \hypertarget{chap:DWATimportimporteddeclaration}
558 is imported, there is one imported declaration entry for
560 \addtoindexx{import attribute}
561 Each imported declaration entry has a
562 \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute,
563 whose value is a reference to the
564 debugging information entry representing the declaration that
567 An imported declaration may also have a
568 \livelink{chap:DWATname}{DW\-\_AT\-\_name}
570 \addtoindexx{name attribute}
571 whose value is a null\dash terminated string containing the
572 name, as it appears in the source program, by which the
573 imported entity is to be known in the context of the imported
574 declaration entry (which may be different than the name of
575 the entity being imported). If no name is present, then the
576 name by which the entity is to be known is the same as the
577 name of the entity being imported.
579 An imported declaration entry with a name attribute may be
580 used as a general means to rename or provide an alias for
581 \addtoindexx{alias declaration|see{imported declaration entry}}
582 an entity, regardless of the context in which the importing
583 declaration or the imported entity occurs.
585 \textit{A \addtoindex{C++} namespace alias may be represented by an imported
586 \hypertarget{chap:DWATimportnamespacealias}
588 \addtoindexx{namespace (C++)!alias}
589 with a name attribute whose value is
590 a null\dash terminated string containing the alias name as it
591 appears in the source program and an import attribute whose
592 value is a reference to the applicable original namespace or
593 namespace extension entry.
596 \textit{A \addtoindex{C++} using declaration may be represented by one or more
597 \hypertarget{chap:DWATimportnamespaceusingdeclaration}
599 \addtoindexx{namespace (C++)!using declaration}
600 declaration entries. When the using declaration
601 refers to an overloaded function, there is one imported
602 declaration entry corresponding to each overloading. Each
603 imported declaration entry has no name attribute but it does
604 have an import attribute that refers to the entry for the
605 entity being imported. (\addtoindex{C++}
606 provides no means to ``rename''
607 an imported entity, other than a namespace).
610 \textit{A \addtoindex{Fortran} use statement
611 \addtoindexx{Fortran!use statement}
612 with an ``only list'' may be
613 represented by a series of imported declaration entries,
614 one (or more) for each entity that is imported. An entity
615 that is renamed in the importing context may be represented
616 by an imported declaration entry with a name attribute that
617 specifies the new local name.
620 \subsection{Imported Module Entries}
621 \label{chap:importedmoduleentries}
623 \textit{Some languages support the concept of importing into or making
624 accessible in a given unit all of the declarations contained
625 within a separate module or namespace.
628 An imported module declaration is represented by a debugging
629 information entry with
630 \addtoindexx{imported module attribute}
632 \addtoindexx{imported module entry}
633 tag \livetarg{chap:DWTAGimportedmodule}{DW\-\_TAG\-\_imported\-\_module}.
635 imported module entry contains a
636 \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute
637 \addtoindexx{import attribute}
638 whose value is a reference to the module or namespace entry
639 containing the definition and/or declaration entries for
640 the entities that are to be imported into the context of the
641 imported module entry.
643 An imported module declaration may own a set of imported
644 declaration entries, each of which refers to an entry in the
645 module whose corresponding entity is to be known in the context
646 of the imported module declaration by a name other than its
647 name in that module. Any entity in the module that is not
648 renamed in this way is known in the context of the imported
649 module entry by the same name as it is declared in the module.
651 \textit{A \addtoindex{C++} using directive
652 may be represented by an
653 \addtoindexx{namespace (C++)!using directive}
655 \hypertarget{chap:DWATimportnamespaceusingdirective}
656 entry, with an import attribute referring to the namespace
657 entry of the appropriate extension of the namespace (which
658 might be the original namespace entry) and no owned entries.
661 \textit{A \addtoindex{Fortran} use statement
662 \addtoindexx{Fortran!use statement}
663 with a “rename list” may be
664 represented by an imported module entry with an import
665 attribute referring to the module and owned entries
666 corresponding to those entities that are renamed as part of
670 \textit{A \addtoindex{Fortran} use statement
671 with neither a “rename list” nor
672 an “only list” may be represented by an imported module
673 entry with an import attribute referring to the module and
674 no owned child entries.
677 \textit{A use statement with an “only list” is represented by a
678 series of individual imported declaration entries as described
679 in Section \refersec{chap:importedorrenameddeclarationentries}.
682 \textit{A \addtoindex{Fortran} use statement for an entity in a module that is
683 itself imported by a use statement without an explicit mention
684 may be represented by an imported declaration entry that refers
685 to the original debugging information entry. For example, given
701 the imported declaration entry for Q within module C refers
702 directly to the variable declaration entry for A in module A
703 because there is no explicit representation for X in module B.
705 A similar situation arises for a \addtoindex{C++} using declaration that
706 imports an entity in terms of a namespace alias. See
707 Appendix \refersec{app:namespaceexample}
711 \section{Subroutine and Entry Point Entries}
712 \label{chap:subroutineandentrypointentries}
714 The following tags exist to describe
715 debugging information entries
716 \addtoindexx{function entry|see{subroutine entry}}
718 \addtoindexx{subroutine entry}
719 subroutines and entry
720 % FIXME: is entry point entry the right index 'entry'?
721 \addtoindexx{entry point entry}
724 \begin{tabular}{lp{9.0cm}}
725 \livetarg{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} & A subroutine or function. \\
726 \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine} & A particular inlined
727 \addtoindexx{inlined subprogram entry}
728 instance of a subroutine or function. \\
729 \livetarg{chap:DWTAGentrypoint}{DW\-\_TAG\-\_entry\-\_point} & An alternate entry point. \\
732 \subsection{General Subroutine and Entry Point Information}
733 \label{chap:generalsubroutineandentrypointinformation}
735 It may also have a \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute as
736 described in Section \refersec{chap:linkagenames}.
738 If the name of the subroutine described by an entry with the
739 tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
740 is visible outside of its containing
741 \hypertarget{chap:DWATexternalexternalsubroutine}
742 compilation unit, that entry has
743 \addtoindexx{external attribute}
745 \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute,
746 which is a \livelink{chap:flag}{flag}.
748 \textit{Additional attributes for functions that are members of a
749 class or structure are described in
750 Section \refersec{chap:memberfunctionentries}.
754 \hypertarget{chap:DWATmainsubprogrammainorstartingsubprogram}
757 \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}
759 \addtoindexx{main subprogram attribute}
761 a \livelink{chap:flag}{flag} whose presence indicates that the
762 subroutine has been identified as the starting function of
763 the program. If more than one subprogram contains this
765 any one of them may be the starting subroutine of the program.
767 \textit{\addtoindex{Fortran} has a PROGRAM statement which is used to specify
768 and provide a user\dash supplied name for the main subroutine of
772 \textit{A common debugger feature is to allow the debugger user to call
773 a subroutine within the subject program. In certain cases,
774 however, the generated code for a subroutine will not obey
775 the standard calling conventions for the target architecture
776 and will therefore not be safe to call from within a debugger.
779 A subroutine entry may
780 \hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}
782 \livelink{chap:DWATcallingconvention}{DW\-\_AT\-\_calling\-\_convention}
783 attribute, whose value is an integer constant. The set of
784 calling convention codes is given in
785 Figure \refersec{fig:callingconventioncodes}.
788 \autorows[0pt]{c}{1}{l}{
789 \addtoindex{DW\-\_CC\-\_normal},
790 \addtoindex{DW\-\_CC\-\_program},
791 \addtoindex{DW\-\_CC\-\_nocall},
793 \caption{Calling convention codes}\label{fig:callingconventioncodes}
796 If this attribute is not present, or its value is the constant
797 \livetarg{chap:DWCCnormal}{DW\-\_CC\-\_normal}, then the subroutine may be safely called by
798 obeying the ``standard'' calling conventions of the target
799 architecture. If the value of the calling convention attribute
800 is the constant \livetarg{chap:DWCCnocall}{DW\-\_CC\-\_nocall}, the subroutine does not obey
801 standard calling conventions, and it may not be safe for the
802 debugger to call this subroutine.
804 If the semantics of the language of the compilation unit
805 containing the subroutine entry distinguishes between ordinary
806 subroutines and subroutines that can serve as the ``main
807 program,'' that is, subroutines that cannot be called
808 directly according to the ordinary calling conventions,
809 then the debugging information entry for such a subroutine
810 may have a calling convention attribute whose value is the
811 constant \livetarg{chap:DWCCprogram}{DW\-\_CC\-\_program}.
813 \textit{The \livelink{chap:DWCCprogram}{DW\-\_CC\-\_program}
814 value is intended to support \addtoindex{Fortran} main
815 \addtoindexx{Fortran!main program}
816 programs which in some implementations may not be callable
817 or which must be invoked in a special way. It is not intended
818 as a way of finding the entry address for the program.
821 \textit{In \addtoindex{C}
822 there is a difference between the types of functions
823 declared using function prototype style declarations and
824 those declared using non\dash prototype declarations.
827 A subroutine entry declared with a function prototype style
828 declaration may have a
829 \livelink{chap:DWATprototyped}{DW\-\_AT\-\_prototyped} attribute, which is
830 a \livelink{chap:flag}{flag}.
832 \textit{The \addtoindex{Fortran}
833 language allows the keywords elemental, pure
834 and recursive to be included as part of the declaration of
835 a subroutine; these attributes reflect that usage. These
836 attributes are not relevant for languages that do not support
837 similar keywords or syntax. In particular, the \livelink{chap:DWATrecursive}{DW\-\_AT\-\_recursive}
838 attribute is neither needed nor appropriate in languages such
840 where functions support recursion by default.
844 \hypertarget{chap:DWATelementalelementalpropertyofasubroutine}
846 \addtoindexx{elemental attribute}
848 \livelink{chap:DWATelemental}{DW\-\_AT\-\_elemental} attribute, which
849 is a \livelink{chap:flag}{flag}.
850 The attribute indicates whether the subroutine
851 or entry point was declared with the ``elemental'' keyword
855 \hypertarget{chap:DWATpurepurepropertyofasubroutine}
856 subprogram entry may have a
857 \livelink{chap:DWATpure}{DW\-\_AT\-\_pure} attribute, which is
858 a \livelink{chap:flag}{flag}.
859 The attribute indicates whether the subroutine was
860 declared with the ``pure'' keyword or property.
863 \hypertarget{chap:DWATrecursiverecursivepropertyofasubroutine}
864 subprogram entry may have a
865 \livelink{chap:DWATrecursive}{DW\-\_AT\-\_recursive} attribute, which
866 is a \livelink{chap:flag}{flag}.
867 The attribute indicates whether the subroutine
868 or entry point was declared with the ``recursive'' keyword
873 \subsection{Subroutine and Entry Point Return Types}
874 \label{chap:subroutineandentrypointreturntypes}
877 \hypertarget{chap:DWATtypetypeofsubroutinereturn}
878 the subroutine or entry point is a function that returns a
879 value, then its debugging information entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type}
880 attribute to denote the type returned by that function.
882 \textit{Debugging information entries for
883 \addtoindex{C} void functions should
884 not have an attribute for the return type. }
887 \subsection{Subroutine and Entry Point Locations}
888 \label{chap:subroutineandentrypointlocations}
890 A subroutine entry may have either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
891 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes or a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
892 \addtoindexx{ranges attribute}
894 \addtoindexx{high PC attribute}
896 \addtoindexx{low PC attribute}
897 encode the contiguous or non\dash contiguous address
898 ranges, respectively, of the machine instructions generated
899 for the subroutine (see
900 Section \refersec{chap:codeaddressesandranges}).
903 \hypertarget{chap:DWATentrypcentryaddressofsubprogram}
904 subroutine entry may also have
905 \addtoindexx{entry pc attribute!for subroutine}
907 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute
908 whose value is the address of the first executable instruction
909 of the subroutine (see
910 Section \refersec{chap:entryaddress}).
912 An entry point has a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute whose value is the
913 relocated address of the first machine instruction generated
917 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute
918 \addtoindexx{entry pc attribute!for subroutine}
920 also seem appropriate
921 for this purpose, historically the
922 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute
924 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} was introduced (in
925 \addtoindex{DWARF Version 3}).
926 There is insufficient reason to change this.}
932 \addtoindexx{address class!attribute}
934 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}
936 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
938 \livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class} attributes,
939 as appropriate, to specify
940 which segments the code for the subroutine resides in and
941 the addressing mode to be used in calling that subroutine.
943 A subroutine entry representing a subroutine declaration
944 that is not also a definition does not have code address or
948 \subsection{Declarations Owned by Subroutines and Entry Points}
949 \label{chap:declarationsownedbysubroutinesandentrypoints}
951 The declarations enclosed by a subroutine or entry point are
952 represented by debugging information entries that are owned
953 by the subroutine or entry point entry. Entries representing
954 \addtoindexx{formal parameter}
955 the formal parameters of the subroutine or entry point appear
956 in the same order as the corresponding declarations in the
959 \textit{There is no ordering requirement for entries for declarations
960 that are children of subroutine or entry point entries but
961 that do not represent formal parameters. The formal parameter
962 entries may be interspersed with other entries used by formal
963 parameter entries, such as type entries.}
965 The unspecified parameters of a variable parameter list are
966 represented by a debugging information entry\addtoindexx{unspecified parameters entry}
968 \livetarg{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters}.
970 The entry for a subroutine that includes
971 \addtoindexx{Fortran!common block}
973 \addtoindex{Fortran} common block
974 \livelink{chap:fortrancommonblock}{common}
975 \livelink{chap:commonblockentry}{block}
976 \addtoindexx{common block|see{Fortran common block}}
977 has a child entry with the
978 tag \livetarg{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion}.
980 \hypertarget{chap:commonreferencecommonblockusage}
981 common inclusion entry has a
982 \livelink{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference} attribute
983 whose value is a reference to the debugging information entry
984 for the common \nolink{block} being included
985 (see Section \refersec{chap:commonblockentries}).
987 \subsection{Low-Level Information}
988 \label{chap:lowlevelinformation}
991 \hypertarget{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}
992 subroutine or entry point entry may have a
993 \livelink{chap:DWATreturnaddr}{DW\-\_AT\-\_return\-\_addr}
994 attribute, whose value is a location description. The location
995 calculated is the place where the return address for the
996 subroutine or entry point is stored.
999 \hypertarget{chap:DWATframebasesubroutineframebaseaddress}
1000 subroutine or entry point entry may also have
1001 \addtoindexx{frame base attribute}
1003 \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute, whose value is a location
1004 description that computes the “frame base” for the
1005 subroutine or entry point. If the location description is
1006 a simple register location description, the given register
1007 contains the frame base address. If the location description is
1008 a DWARF expression, the result of evaluating that expression
1009 is the frame base address. Finally, for a
1010 \addtoindex{location list},
1011 this interpretation applies to each location description
1012 contained in the list of \addtoindex{location list} entries.
1014 \textit{The use of one of the \livelink{chap:DWOPreg}{DW\-\_OP\-\_reg}~\textless~n~\textgreater
1016 context is equivalent to using
1017 \livelink{chap:DWOPbreg}{DW\-\_OP\-\_breg}~\textless~n~\textgreater(0)
1019 compact. However, these are not equivalent in general.}
1021 \textit{The frame base for a procedure is typically an address fixed
1022 relative to the first unit of storage allocated for the
1023 procedure’s stack frame. The \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute
1024 can be used in several ways:}
1026 \begin{enumerate}[1.]
1027 \item \textit{In procedures that need
1028 \addtoindexx{location list}
1029 location lists to locate local
1030 variables, the \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} can hold the needed location
1031 list, while all variables’ location descriptions can be
1032 simpler ones involving the frame base.}
1034 \item \textit{It can be used in resolving ``up\dash level'' addressing
1035 within nested routines.
1036 (See also \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}, below)}
1037 %The -See also- here is ok, the DW\-\_AT should be
1038 %a hyperref to the def itself, which is earlier in this document.
1041 \textit{Some languages support nested subroutines. In such languages,
1042 it is possible to reference the local variables of an
1043 outer subroutine from within an inner subroutine. The
1044 \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link} and \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attributes allow
1045 debuggers to support this same kind of referencing.}
1048 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}
1050 \addtoindexx{address!uplevel|see{static link attribute}}
1051 subroutine or entry point is nested, it may have a
1052 \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}
1053 attribute, whose value is a location
1054 description that computes the frame base of the relevant
1055 instance of the subroutine that immediately encloses the
1056 subroutine or entry point.
1058 In the context of supporting nested subroutines, the
1059 \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute value should obey the following
1062 \begin{enumerate}[1.]
1063 \item It should compute a value that does not change during the
1064 life of the procedure, and
1066 \item The computed value should be unique among instances of
1067 the same subroutine. (For typical \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} use, this
1068 means that a recursive subroutine’s stack frame must have
1069 non\dash zero size.)
1072 \textit{If a debugger is attempting to resolve an up\dash level reference
1073 to a variable, it uses the nesting structure of DWARF to
1074 determine which subroutine is the lexical parent and the
1075 \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link} value to identify the appropriate active
1076 frame of the parent. It can then attempt to find the reference
1077 within the context of the parent.}
1081 \subsection{Types Thrown by Exceptions}
1082 \label{chap:typesthrownbyexceptions}
1084 \textit{In \addtoindex{C++} a subroutine may declare a set of types which
1085 it may validly throw.}
1087 If a subroutine explicitly declares that it may throw
1088 \addtoindexx{exception thrown|see{thrown type entry}}
1089 an exception for one or more types, each such type is
1090 represented by a debugging information entry with
1091 \addtoindexx{thrown type entry}
1093 \livetarg{chap:DWTAGthrowntype}{DW\-\_TAG\-\_thrown\-\_type}.
1094 Each such entry is a child of the entry
1095 representing the subroutine that may throw this type. Each
1096 thrown type entry contains a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, whose
1097 value is a reference to an entry describing the type of the
1098 exception that may be thrown.
1100 \subsection{Function Template Instantiations}
1101 \label{chap:functiontemplateinstantiations}
1103 \textit{In \addtoindex{C++}, a function template is a generic definition of
1104 a function that is instantiated differently when called with
1105 values of different types. DWARF does not represent the generic
1106 template definition, but does represent each instantiation.}
1108 A template instantiation is represented by a debugging
1109 information entry with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. With four
1110 exceptions, such an entry will contain the same attributes and
1111 will have the same types of child entries as would an entry
1112 for a subroutine defined explicitly using the instantiation
1113 types. The exceptions are:
1115 \begin{enumerate}[1.]
1116 \item Each formal parameterized type declaration appearing in the
1117 template definition is represented by a debugging information
1119 tag \livetarg{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}.
1121 such entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
1122 \addtoindexx{name attribute}
1124 null\dash terminated string containing the name of the formal
1125 type parameter as it appears in the source program. The
1126 \addtoindexx{formal type parameter|see{template type parameter entry}}
1127 template type parameter entry also has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
1128 describing the actual type by which the formal is replaced
1129 for this instantiation.
1131 \item The subprogram entry and each of its child entries reference
1132 a template type parameter entry in any circumstance where
1133 the template definition referenced a formal parameterized type.
1135 \item If the compiler has generated a special compilation unit
1136 to hold the template instantiation and that compilation unit
1137 has a different name from the compilation unit containing
1138 the template definition, the name attribute for the debugging
1139 information entry representing that compilation unit is empty
1142 \item If the subprogram entry representing the template
1143 instantiation or any of its child entries contain declaration
1144 coordinate attributes, those attributes refer to the source
1145 for the template definition, not to any source generated
1146 artificially by the compiler for this instantiation.
1151 \subsection{Inlinable and Inlined Subroutines}
1152 A declaration or a definition of an inlinable subroutine
1153 is represented by a debugging information entry with the
1155 \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}.
1156 The entry for a subroutine that is
1157 \hypertarget{chap:DWATinlineinlinedsubroutine}
1158 explicitly declared to be available for inline expansion or
1159 that was expanded inline implicitly by the compiler has
1160 \addtoindexx{inline attribute}
1162 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is an integer constant. The
1163 set of values for the \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute is given in
1164 Figure \refersec{fig:inlinecodes}.
1166 \begin{figure}[here]
1168 \caption{Inline codes}
1169 \label{fig:inlinecodes}
1170 \begin{tabular}{lp{9cm}}
1171 Name&Meaning\\ \hline
1172 \livetarg{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined} & Not delared inline nor inlined by the
1173 compiler(equivalent to the absense of the containing
1174 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute) \\
1175 \livetarg{chap:DWINLinlined}{DW\-\_INL\-\_inlined} & Not declared inline but inlined by the compiler \\
1176 \livetarg{chap:DWINLdeclarednotinlined}{DW\-\_INL\-\_declared\-\_not\-\_inlined} & Declared inline but
1177 not inlined by the compiler \\
1178 \livetarg{chap:DWINLdeclaredinlined}{DW\-\_INL\-\_declared\-\_inlined} & Declared inline and inlined by the compiler \\
1182 \textit{In \addtoindex{C++}, a function or a constructor declared with
1183 constexpr is implicitly declared inline. The abstract inline
1184 instance (see below) is represented by a debugging information
1185 entry with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. Such an entry has a
1186 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is \livelink{chap:DWINLinlined}{DW\-\_INL\-\_inlined}.}
1189 \paragraph{Abstract Instances}
1190 \label{chap:abstractinstances}
1191 Any debugging information entry that is owned (either
1192 \hypertarget{chap:DWATinlineabstracttinstance}
1193 directly or indirectly) by a debugging information entry
1195 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute is referred to
1196 \addtoindexx{abstract instance!entry}
1197 as an ``abstract instance entry.''
1198 Any subroutine entry
1200 \addtoindexx{inline attribute}
1201 a \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is other
1202 than \livelink{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined}
1204 \addtoindexx{abstract instance!root}
1205 an ``abstract instance root.''
1206 Any set of abstract instance entries that are all
1207 children (either directly or indirectly) of some abstract
1208 instance root, together with the root itself, is known as
1209 \addtoindexx{abstract instance!tree}
1210 an ``abstract instance tree.'' However, in the case where
1211 an abstract instance tree is nested within another abstract
1212 instance tree, the entries in the
1213 \addtoindex{nested abstract instance}
1214 tree are not considered to be entries in the outer abstract
1217 Each abstract instance root is either part of a larger
1218 \addtoindexx{abstract instance!root}
1219 tree (which gives a context for the root) or uses
1220 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} to refer to the declaration in context.
1222 \textit{For example, in \addtoindex{C++} the context might be a namespace
1223 declaration or a class declaration.}
1225 \textit{Abstract instance trees are defined so that no entry is part
1226 of more than one abstract instance tree. This simplifies the
1227 following descriptions.}
1229 A debugging information entry that is a member of an abstract
1230 instance tree should not contain any attributes which describe
1231 aspects of the subroutine which vary between distinct inlined
1232 expansions or distinct out\dash of\dash line expansions. For example,
1233 \addtoindexx{entry pc attribute!and abstract instance}
1234 the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
1235 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc},
1236 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges},
1237 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc},
1238 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location},
1239 \livelink{chap:DWATreturnaddr}{DW\-\_AT\-\_return\-\_addr}, \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope}, and
1240 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment!and abstract instance}
1242 \addtoindexx{location attribute!and abstract instance}
1244 \addtoindexx{ranges attribute!and abstract instance}
1246 \addtoindexx{high PC attribute!and abstract instance}
1248 \addtoindexx{low PC attribute!and abstract instance}
1251 \addtoindexx{return address attribute!and abstract instance}
1253 \addtoindexx{segment attribute!and abstract instance}
1255 \addtoindexx{start scope attribute!and abstract instance}
1258 \textit{It would not make sense normally to put these attributes into
1259 abstract instance entries since such entries do not represent
1260 actual (concrete) instances and thus do not actually exist at
1261 run\dash time. However,
1262 see Appendix \refersec{app:inlineouteronenormalinner}
1263 for a contrary example.}
1265 The rules for the relative location of entries belonging to
1266 abstract instance trees are exactly the same as for other
1267 similar types of entries that are not abstract. Specifically,
1268 the rule that requires that an entry representing a declaration
1269 be a direct child of the entry representing the scope of the
1270 declaration applies equally to both abstract and non\dash abstract
1271 entries. Also, the ordering rules for formal parameter entries,
1272 member entries, and so on, all apply regardless of whether
1273 or not a given entry is abstract.
1275 \paragraph{Concrete Inlined Instances}
1276 \label{chap:concreteinlinedinstances}
1278 Each inline expansion of a subroutine is represented
1279 by a debugging information entry with the
1280 tag \livetarg{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}.
1281 Each such entry should be a direct
1282 child of the entry that represents the scope within which
1283 the inlining occurs.
1285 Each inlined subroutine entry may have either a
1286 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}
1287 and \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair
1289 \addtoindexx{high PC attribute}
1291 \addtoindexx{low PC attribute}
1293 \addtoindexx{ranges attribute}
1295 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges}
1296 attribute whose values encode the contiguous or non\dash contiguous
1297 address ranges, respectively, of the machine instructions
1298 generated for the inlined subroutine (see
1299 Section \refersec{chap:codeaddressesandranges}).
1301 \hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}
1302 inlined subroutine entry may
1303 \addtoindexx{inlined subprogram entry!in concrete instance}
1305 \addtoindexx{inlined subprogram entry}
1307 \addtoindexx{entry pc attribute!for inlined subprogram}
1309 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}
1310 attribute, representing the first executable instruction of
1311 the inline expansion (see
1312 Section \refersec{chap:entryaddress}).
1314 % Positions of the 3 targets here is a bit arbitrary.
1316 \hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}
1318 \hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}
1320 \hypertarget{chap:DWATcallfilefilecontaininginlinedsubroutinecall}
1321 may also have \livelink{chap:DWATcallfile}{DW\-\_AT\-\_call\-\_file},
1322 \livelink{chap:DWATcallline}{DW\-\_AT\-\_call\-\_line} and \livelink{chap:DWATcallcolumn}{DW\-\_AT\-\_call\-\_column} attributes,
1324 value is an integer constant. These attributes represent the
1325 source file, source line number, and source column number,
1326 respectively, of the first character of the statement or
1327 expression that caused the inline expansion. The call file,
1328 call line, and call column attributes are interpreted in
1329 the same way as the declaration file, declaration line, and
1330 declaration column attributes, respectively (see
1331 Section \refersec{chap:declarationcoordinates}).
1333 The call file, call line and call column coordinates do not
1334 describe the coordinates of the subroutine declaration that
1335 was inlined, rather they describe the coordinates of the call.
1337 An inlined subroutine entry
1338 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}
1340 \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}
1341 attribute, which is a \livelink{chap:flag}{flag}
1342 whose presence indicates that the
1343 subroutine has been evaluated as a compile\dash time constant. Such
1344 an entry may also have a \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute,
1345 whose value may be of any form that is appropriate for the
1346 representation of the subroutine's return value. The value of
1347 this attribute is the actual return value of the subroutine,
1348 represented as it would be on the target architecture.
1350 \textit{In \addtoindex{C++}, if a function or a constructor declared with constexpr
1351 is called with constant expressions, then the corresponding
1352 concrete inlined instance has a
1353 \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr} attribute,
1354 as well as a \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute whose value represents
1355 the actual return value of the concrete inlined instance.}
1357 Any debugging information entry that is owned (either
1358 directly or indirectly) by a debugging information entry
1359 with the tag \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine} is referred to as a
1360 ``concrete inlined instance entry.'' Any entry that has
1362 \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
1363 is known as a ``concrete inlined instance root.''
1364 Any set of concrete inlined instance
1365 entries that are all children (either directly or indirectly)
1366 of some concrete inlined instance root, together with the root
1367 itself, is known as a ``concrete inlined instance tree.''
1368 However, in the case where a concrete inlined instance tree
1369 is nested within another concrete instance tree, the entries
1370 in the \addtoindex{nested concrete inline instance} tree
1371 are not considered to
1372 be entries in the outer concrete instance tree.
1374 \textit{Concrete inlined instance trees are defined so that no entry
1375 is part of more than one concrete inlined instance tree. This
1376 simplifies later descriptions.}
1378 Each concrete inlined instance tree is uniquely associated
1379 with one (and only one) abstract instance tree.
1381 \textit{Note, however, that the reverse is not true. Any given abstract
1382 instance tree may be associated with several different concrete
1383 inlined instance trees, or may even be associated with zero
1384 concrete inlined instance trees.}
1386 Concrete inlined instance entries may omit attributes that
1387 are not specific to the concrete instance (but present in
1388 the abstract instance) and need include only attributes that
1389 are specific to the concrete instance (but omitted in the
1390 abstract instance). In place of these omitted attributes, each
1391 \hypertarget{chap:DWATabstractorigininlineinstance}
1392 concrete inlined instance entry
1393 \addtoindexx{abstract origin attribute}
1395 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
1396 attribute that may be used to obtain the missing information
1397 (indirectly) from the associated abstract instance entry. The
1398 value of the abstract origin attribute is a reference to the
1399 associated abstract instance entry.
1401 If an entry within a concrete inlined instance tree contains
1402 attributes describing the
1403 \addtoindexx{declaration coordinates!in concrete instance}
1404 declaration coordinates
1406 entry, then those attributes should refer to the file, line
1407 and column of the original declaration of the subroutine,
1408 not to the point at which it was inlined. As a consequence,
1409 they may usually be omitted from any entry that has an abstract
1412 For each pair of entries that are associated via a
1413 \addtoindexx{abstract origin attribute}
1414 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin} attribute, both members of the pair
1415 have the same tag. So, for example, an entry with the tag
1416 \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable} can only be associated with another entry
1417 that also has the tag \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}. The only exception
1418 to this rule is that the root of a concrete instance tree
1419 (which must always have the tag \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine})
1420 can only be associated with the root of its associated abstract
1421 instance tree (which must have the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}).
1423 In general, the structure and content of any given concrete
1424 inlined instance tree will be closely analogous to the
1425 structure and content of its associated abstract instance
1426 tree. There are a few exceptions:
1428 \begin{enumerate}[1.]
1429 \item An entry in the concrete instance tree may be omitted if
1431 \addtoindexx{abstract origin attribute}
1432 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin} attribute and either
1433 has no children, or its children are omitted. Such entries
1434 would provide no useful information. In C\dash like languages,
1435 such entries frequently include types, including structure,
1436 union, class, and interface types; and members of types. If any
1437 entry within a concrete inlined instance tree needs to refer
1438 to an entity declared within the scope of the relevant inlined
1439 subroutine and for which no concrete instance entry exists,
1440 the reference should refer to the abstract instance entry.
1442 \item Entries in the concrete instance tree which are associated
1443 with entries in the abstract instance tree such that neither
1444 has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
1445 \addtoindexx{name attribute}
1446 and neither is referenced by
1447 any other debugging information entry, may be omitted. This
1448 may happen for debugging information entries in the abstract
1449 instance trees that became unnecessary in the concrete instance
1450 tree because of additional information available there. For
1451 example, an anonymous variable might have been created and
1452 described in the abstract instance tree, but because of
1453 the actual parameters for a particular inlined expansion,
1454 it could be described as a constant value without the need
1455 for that separate debugging information entry.
1457 \item A concrete instance tree may contain entries which do
1458 not correspond to entries in the abstract instance tree
1459 to describe new entities that are specific to a particular
1460 inlined expansion. In that case, they will not have associated
1461 entries in the abstract instance tree, should not contain
1462 \addtoindexx{abstract origin attribute}
1463 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin} attributes, and must contain all their
1464 own attributes directly. This allows an abstract instance tree
1465 to omit debugging information entries for anonymous entities
1466 that are unlikely to be needed in most inlined expansions. In
1467 any expansion which deviates from that expectation, the
1468 entries can be described in its concrete inlined instance tree.
1472 \paragraph{Out-of-Line Instances of Inlined Subroutines}
1473 \label{chap:outoflineinstancesofinlinedsubroutines}
1474 Under some conditions, compilers may need to generate concrete
1475 executable instances of inlined subroutines other than at
1476 points where those subroutines are actually called. Such
1477 concrete instances of inlined subroutines are referred to as
1478 ``concrete out\dash of\dash line instances.''
1480 \textit{In \addtoindex{C++}, for example,
1481 taking the address of a function declared
1482 to be inline can necessitate the generation of a concrete
1483 out\dash of\dash line instance of the given function.}
1485 The DWARF representation of a concrete out\dash of\dash line instance
1486 of an inlined subroutine is essentially the same as for a
1487 concrete inlined instance of that subroutine (as described in
1488 the preceding section). The representation of such a concrete
1489 % It is critical that the hypertarget and livelink be
1490 % separated to avoid problems with latex.
1491 out\dash of\dash line
1492 \addtoindexx{abstract origin attribute}
1494 \hypertarget{chap:DWATabstractoriginoutoflineinstance}
1496 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
1497 attributes in exactly the same way as they are used for
1498 a concrete inlined instance (that is, as references to
1499 corresponding entries within the associated abstract instance
1502 The differences between the DWARF representation of a
1503 concrete out\dash of\dash line instance of a given subroutine and the
1504 representation of a concrete inlined instance of that same
1505 subroutine are as follows:
1507 \begin{enumerate}[1.]
1508 \item The root entry for a concrete out\dash of\dash line instance
1509 of a given inlined subroutine has the same tag as does its
1510 associated (abstract) inlined subroutine entry (that is, tag
1511 \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} rather than \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}).
1513 \item The root entry for a concrete out\dash of\dash line instance tree
1514 is normally owned by the same parent entry that also owns
1515 the root entry of the associated abstract instance. However,
1516 it is not required that the abstract and out\dash of\dash line instance
1517 trees be owned by the same parent entry.
1521 \paragraph{Nested Inlined Subroutines}
1522 \label{nestedinlinedsubroutines}
1523 Some languages and compilers may permit the logical nesting of
1524 a subroutine within another subroutine, and may permit either
1525 the outer or the nested subroutine, or both, to be inlined.
1527 For a non\dash inlined subroutine nested within an inlined
1528 subroutine, the nested subroutine is described normally in
1529 both the abstract and concrete inlined instance trees for
1530 the outer subroutine. All rules pertaining to the abstract
1531 and concrete instance trees for the outer subroutine apply
1532 also to the abstract and concrete instance entries for the
1535 For an inlined subroutine nested within another inlined
1536 subroutine, the following rules apply to their abstract and
1537 \addtoindexx{abstract instance!nested}
1538 \addtoindexx{concrete instance!nested}
1539 concrete instance trees:
1541 \begin{enumerate}[1.]
1542 \item The abstract instance tree for the nested subroutine is
1543 described within the abstract instance tree for the outer
1544 subroutine according to the rules in
1545 Section \refersec{chap:abstractinstances}, and
1546 without regard to the fact that it is within an outer abstract
1549 \item Any abstract instance tree for a nested subroutine is
1550 always omitted within the concrete instance tree for an
1553 \item A concrete instance tree for a nested subroutine is
1554 always omitted within the abstract instance tree for an
1557 \item The concrete instance tree for any inlined or out-of-line
1558 expansion of the nested subroutine is described within a
1559 concrete instance tree for the outer subroutine according
1561 Sections \refersec{chap:concreteinlinedinstances} or
1562 \refersec{chap:outoflineinstancesofinlinedsubroutines}
1564 and without regard to the fact that it is within an outer
1565 concrete instance tree.
1568 See Appendix \refersec{app:inliningexamples}
1569 for discussion and examples.
1571 \subsection{Trampolines}
1572 \label{chap:trampolines}
1574 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1575 \hypertarget{chap:DWATtrampolinetargetsubroutine}
1576 an intermediary in making a call to another subroutine. It may
1577 adjust parameters and/or the result (if any) as appropriate
1578 to the combined calling and called execution contexts.}
1580 A trampoline is represented by a debugging information entry
1581 with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} or \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
1582 that has a \livelink{chap:DWATtrampoline}{DW\-\_AT\-\_trampoline} attribute. The value of that
1583 attribute indicates the target subroutine of the trampoline,
1584 that is, the subroutine to which the trampoline passes
1585 control. (A trampoline entry may but need not also have a
1586 \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute.)
1588 The value of the trampoline attribute may be represented
1589 using any of the following forms, which are listed in order
1593 \item If the value is of class reference, then the value
1594 specifies the debugging information entry of the target
1597 \item If the value is of class address, then the value is
1598 the relocated address of the target subprogram.
1600 \item If the value is of class string, then the value is the
1601 (possibly mangled) \addtoindexx{mangled names}
1602 name of the target subprogram.
1604 \item If the value is of class \livelink{chap:flag}{flag}, then the value true
1605 indicates that the containing subroutine is a trampoline but
1606 that the target subroutine is not known.
1610 The target subprogram may itself be a trampoline. (A sequence
1611 of trampolines necessarily ends with a non\dash trampoline
1614 \textit{In \addtoindex{C++}, trampolines may be used
1615 to implement derived virtual
1616 member functions; such trampolines typically adjust the
1617 implicit this pointer parameter in the course of passing
1618 control. Other languages and environments may use trampolines
1619 in a manner sometimes known as transfer functions or transfer
1622 \textit{Trampolines may sometimes pass control to the target
1623 subprogram using a branch or jump instruction instead of a
1624 call instruction, thereby leaving no trace of their existence
1625 in the subsequent execution context. }
1627 \textit{This attribute helps make it feasible for a debugger to arrange
1628 that stepping into a trampoline or setting a breakpoint in
1629 a trampoline will result in stepping into or setting the
1630 breakpoint in the target subroutine instead. This helps to
1631 hide the compiler generated subprogram from the user. }
1633 \textit{If the target subroutine is not known, a debugger may choose
1634 to repeatedly step until control arrives in a new subroutine
1635 which can be assumed to be the target subroutine. }
1639 \section{Lexical Block Entries}
1640 \label{chap:lexicalblockentries}
1643 lexical \livetargi{chap:lexicalblock}{block}{lexical block}
1645 \addtoindexx{lexical block}
1646 a bracketed sequence of source statements
1647 that may contain any number of declarations. In some languages
1648 (including \addtoindex{C} and \addtoindex{C++}),
1649 \nolink{blocks} can be nested within other
1650 \nolink{blocks} to any depth.}
1652 % We do not need to link to the preceeding paragraph.
1653 A lexical \nolink{block} is represented by a debugging information
1655 tag \livetarg{chap:DWTAGlexicalblock}{DW\-\_TAG\-\_lexical\-\_block}.
1657 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry}
1660 either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
1661 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of
1663 \addtoindexx{high PC attribute}
1665 \addtoindexx{low PC attribute}
1667 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
1668 \addtoindexx{ranges attribute}
1669 whose values encode the contiguous or non-contiguous address
1670 ranges, respectively, of the machine instructions generated
1671 for the lexical \livelink{chap:lexicalblock}{block}
1672 (see Section \refersec{chap:codeaddressesandranges}).
1674 If a name has been given to the
1675 lexical \livelink{chap:lexicalblock}{block}
1677 program, then the corresponding
1678 lexical \livelink{chap:lexicalblockentry}{block} entry has a
1679 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose
1680 \addtoindexx{name attribute}
1681 value is a null\dash terminated string
1682 containing the name of the lexical \livelink{chap:lexicalblock}{block}
1686 \textit{This is not the same as a \addtoindex{C} or
1687 \addtoindex{C++} label (see below).}
1689 The lexical \livelink{chap:lexicalblockentry}{block} entry owns
1690 debugging information entries that
1691 describe the declarations within that lexical \livelink{chap:lexicalblock}{block}.
1693 one such debugging information entry for each local declaration
1694 of an identifier or inner lexical \livelink{chap:lexicalblock}{block}.
1696 \section{Label Entries}
1697 \label{chap:labelentries}
1699 A label is a way of identifying a source statement. A labeled
1700 statement is usually the target of one or more ``go to''
1703 A label is represented by a debugging information entry with
1704 \addtoindexx{label entry}
1706 tag \livetarg{chap:DWTAGlabel}{DW\-\_TAG\-\_label}.
1707 The entry for a label should be owned by
1708 the debugging information entry representing the scope within
1709 which the name of the label could be legally referenced within
1712 The label entry has a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute whose value
1713 is the relocated address of the first machine instruction
1714 generated for the statement identified by the label in
1715 the source program. The label entry also has a
1716 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
1717 \addtoindexx{name attribute}
1718 whose value is a null-terminated string containing
1719 the name of the label as it appears in the source program.
1722 \section{With Statement Entries}
1723 \label{chap:withstatemententries}
1725 \textit{Both \addtoindex{Pascal} and
1726 \addtoindexx{Modula-2}
1727 Modula\dash 2 support the concept of a ``with''
1728 statement. The with statement specifies a sequence of
1729 executable statements within which the fields of a record
1730 variable may be referenced, unqualified by the name of the
1733 A with statement is represented by a
1734 \addtoindexi{debugging information entry}{with statement entry}
1735 with the tag \livetarg{chap:DWTAGwithstmt}{DW\-\_TAG\-\_with\-\_stmt}.
1737 A with statement entry may have either a
1738 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
1739 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes
1740 \addtoindexx{high PC attribute}
1742 \addtoindexx{low PC attribute}
1743 a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
1744 \addtoindexx{ranges attribute}
1745 whose values encode the contiguous or non\dash contiguous address
1746 ranges, respectively, of the machine instructions generated
1747 for the with statement
1748 (see Section \refersec{chap:codeaddressesandranges}).
1750 The with statement entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, denoting
1751 the type of record whose fields may be referenced without full
1752 qualification within the body of the statement. It also has
1753 \addtoindexx{location attribute}
1754 a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute, describing how to find the base
1755 address of the record object referenced within the body of
1758 \section{Try and Catch Block Entries}
1759 \label{chap:tryandcatchblockentries}
1761 \textit{In \addtoindex{C++} a lexical \livelink{chap:lexicalblock}{block} may be
1762 designated as a ``catch \nolink{block}.''
1763 A catch \livetargi{chap:catchblock}{block}{catch block} is an
1764 exception handler that handles
1765 exceptions thrown by an immediately
1766 preceding ``try \livelink{chap:tryblock}{block}.''
1767 A catch \livelink{chap:catchblock}{block}
1768 designates the type of the exception that it
1771 A try \livetargi{chap:tryblock}{block}{try block} is represented
1772 by a debugging information entry
1773 with the tag \livetarg{chap:DWTAGtryblock}{DW\-\_TAG\-\_try\-\_block}.
1774 A catch \livelink{chap:catchblock}{block} is represented by
1775 a debugging information entry with
1776 the tag \livetarg{chap:DWTAGcatchblock}{DW\-\_TAG\-\_catch\-\_block}.
1778 % nolink as we have links just above and do not have a combo link for both
1779 Both try and catch \nolink{block} entries may have either a
1780 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
1781 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes
1782 \addtoindexx{high PC attribute}
1784 \addtoindexx{low PC attribute}
1786 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
1787 \addtoindexx{ranges attribute}
1788 whose values encode the contiguous
1789 or non\dash contiguous address ranges, respectively, of the
1790 machine instructions generated for the \livelink{chap:lexicalblock}{block}
1792 \refersec{chap:codeaddressesandranges}).
1794 Catch \livelink{chap:catchblock}{block} entries have at
1795 least one child entry, an
1796 entry representing the type of exception accepted by
1797 that catch \livelink{chap:catchblock}{block}.
1799 This child entry has one of
1800 \addtoindexx{formal parameter entry!in catch block}
1802 \addtoindexx{unspecified parameters entry!in catch block}
1804 \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter} or
1805 \livelink{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters},
1806 and will have the same form as other parameter entries.
1808 The siblings immediately following
1809 a try \livelink{chap:tryblock}{block} entry are its
1810 corresponding catch \livelink{chap:catchblock}{block} entries.