37d24dbd34002bcba56137e353692e829fc4b288
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
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.
9
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}.
20
21 \subsection[Normal and Partial CU Entries]{Normal and Partial Compilation Unit Entries}
22 \label{chap:normalandpartialcompilationunitentries}
23
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
28 entry with the 
29 tag \livetarg{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}.
30
31 In a simple normal compilation, a single compilation unit with
32 the tag 
33 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} represents a complete object file
34 and the tag 
35 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} is not used. 
36 In a compilation
37 employing the DWARF space compression and duplicate elimination
38 techniques from 
39 Appendix \refersec{app:usingcompilationunits}, 
40 multiple compilation units using
41 the tags 
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.
45
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
57 in some cases.}
58
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}).
67
68
69 Compilation unit entries may have the following 
70 attributes:
71
72 \begin{enumerate}[1]
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}
76 attributes 
77 \addtoindexx{low PC attribute}
78 or 
79 \addtoindexx{ranges attribute}
80
81 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
82 \addtoindexx{ranges attribute}
83 whose values encode 
84 \addtoindexx{discontiguous address ranges|see{non-contiguous address ranges}}
85 the
86 contiguous or 
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 
91 may also
92 be specified 
93 in combination 
94 \addtoindexx{ranges attribute}
95 with 
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}).
103
104 \item A \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute 
105 \addtoindexx{name attribute}
106 whose value is a null\dash terminated
107 string 
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.
111
112 \item A \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} attribute 
113 \addtoindexx{language attribute}
114 whose constant value is an
115 \hypertarget{chap:DWATlanguageprogramminglanguage}
116 integer code 
117 \addtoindexx{language attribute}
118 indicating the source language of the compilation
119 unit. The set of language names and their meanings are given
120 in 
121 Figure \refersec{fig:languagenames}.
122
123 \begin{figure}[here]
124 \centering
125 \caption{Language names}
126 \label{fig:languagenames}
127 \begin{tabular}{ll}
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.& \\
150 \end{tabular}
151 \end{figure}
152
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}).
162
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}).
174
175 \item  A 
176 \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir} 
177 attribute 
178 \hypertarget{chap:DWATcompdircompilationdirectory}
179 whose value is a
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.
183
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.
192
193
194 \item  A \livelink{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case} 
195 attribute 
196 \addtoindexx{identifier case attribute}
197 whose integer
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 
202 is given in Figure
203 \refersec{fig:identifiercasecodes}.
204
205 \begin{figure}[here]
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}
211 }
212 \caption{Identifier case codes}\label{fig:identifiercasecodes}
213 \end{figure}
214
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.
223
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
229 lookups.
230
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
236 lookups.
237
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
241 access those names.
242
243 \item A \livelink{chap:DWATbasetypes}{DW\-\_AT\-\_base\-\_types} attribute whose value is a reference.
244
245
246 This 
247 \hypertarget{chap:DWATbasetypesprimitivedatatypesofcompilationunit}
248 attribute 
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}).
255
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}
262 correctly.
263
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}).
270
271
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.
280
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
287 a program.}
288
289 \end{enumerate}
290
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.
296
297
298 \subsection{Imported Unit Entries}
299 \label{chap:importedunitentries}
300 The 
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}
308 a
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.
313
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
318 compilation unit.
319
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.
328
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.
335
336 A type unit entry may have a 
337 \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} attribute, 
338 whose
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}.
343
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.
350
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.
358
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.
364
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.
373
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
377 those entities.}
378
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
386 entry containing a 
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).}
394
395 A module is represented by a debugging information entry
396 with the 
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.
401
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.
407
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} 
411 pair 
412 \addtoindexx{high PC attribute}
413 of 
414 \addtoindexx{low PC attribute}
415 attributes or a 
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}
423 It may also
424 \addtoindexx{entry pc attribute!for module initialization}
425 have a 
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}).
429
430 If 
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.
438
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.}
447
448 A namespace is represented by a debugging information entry
449 with the 
450 tag \livetarg{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}. 
451 A namespace extension is
452 \hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}
453 represented by a 
454 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} entry 
455 with 
456 \addtoindexx{extension attribute}
457
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.)
470
471 Namespace and namespace extension entries may own 
472 \addtoindexx{namespace extension entry}
473 other
474 \addtoindexx{namespace declaration entry}
475 debugging information entries describing program entities
476 whose declarations occur in the namespace.
477
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.}
482
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.
493
494 \textit{The \addtoindex{C++} \addtoindex{global namespace}
495 (the 
496 \addtoindexx{global namespace|see{namespace (C++), global}}
497 namespace 
498 \addtoindexx{namespace (C++)!global}
499 referred to by
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.}
505
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).
512 }
513
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.
523 }
524
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,
530 for example, 
531 \addtoindexx{namespace (C++)!std}
532 is large and will probably be referenced in
533 every \addtoindex{C++} compilation unit.
534 }
535
536 \textit{For a \addtoindex{C++} namespace example, 
537 see Appendix \refersec{app:namespaceexample}.
538 }
539
540
541
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
547 given another name.
548 }
549
550 An 
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}. 
555 When 
556 \hypertarget{chap:DWATimportimporteddeclaration}
557 an overloaded entity
558 is imported, there is one imported declaration entry for
559 each overloading. 
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
565 is being imported.
566
567 An imported declaration may also have a 
568 \livelink{chap:DWATname}{DW\-\_AT\-\_name}
569 attribute
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.
578
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.
584
585 \textit{A \addtoindex{C++} namespace alias may be represented by an imported
586 \hypertarget{chap:DWATimportnamespacealias}
587 declaration entry 
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.
594 }
595
596 \textit{A \addtoindex{C++} using declaration may be represented by one or more
597 \hypertarget{chap:DWATimportnamespaceusingdeclaration}
598 imported 
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).
608 }
609
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.
618 }
619
620 \subsection{Imported Module Entries}
621 \label{chap:importedmoduleentries}
622
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.
626 }
627
628 An imported module declaration is represented by a debugging
629 information entry with 
630 \addtoindexx{imported module attribute}
631 the 
632 \addtoindexx{imported module entry}
633 tag \livetarg{chap:DWTAGimportedmodule}{DW\-\_TAG\-\_imported\-\_module}.
634 An
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.
642
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.
650
651 \textit{A \addtoindex{C++} using directive 
652 may be represented by an 
653 \addtoindexx{namespace (C++)!using directive}
654 imported module
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.
659 }
660
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
667 being imported.
668 }
669
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.
675 }
676
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}.
680 }
681
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
686 }
687 \begin{lstlisting}
688 module A
689 integer X, Y, Z
690 end module
691
692 module B
693 use A
694 end module
695
696 module C
697 use B, only Q => X
698 end module
699 \end{lstlisting}
700
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.
704
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}
708 for an example.
709
710
711 \section{Subroutine and Entry Point Entries}
712 \label{chap:subroutineandentrypointentries}
713
714 The following tags exist to describe 
715 debugging information entries 
716 \addtoindexx{function entry|see{subroutine entry}}
717 for 
718 \addtoindexx{subroutine entry}
719 subroutines and entry
720 % FIXME: is entry point entry the right index 'entry'?
721 \addtoindexx{entry point entry}
722 points:
723
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. \\
730 \end{tabular}
731
732 \subsection{General Subroutine and Entry Point Information}
733 \label{chap:generalsubroutineandentrypointinformation}
734
735 It may also have a \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute as
736 described in Section \refersec{chap:linkagenames}.
737
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}
744
745 \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute,
746 which is a \livelink{chap:flag}{flag}.
747
748 \textit{Additional attributes for functions that are members of a
749 class or structure are described in 
750 Section \refersec{chap:memberfunctionentries}.
751 }
752
753
754 \hypertarget{chap:DWATmainsubprogrammainorstartingsubprogram}
755 subroutine entry 
756 may contain a 
757 \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}
758 attribute 
759 \addtoindexx{main subprogram attribute}
760 which is 
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 
764 \nolink{flag},
765 any one of them may be the starting subroutine of the program.
766
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
769 a program.
770 }
771
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.
777 }
778
779 A subroutine entry may 
780 \hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}
781 contain a 
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}.
786
787 \begin{figure}[here]
788 \autorows[0pt]{c}{1}{l}{
789 \addtoindex{DW\-\_CC\-\_normal},
790 \addtoindex{DW\-\_CC\-\_program},
791 \addtoindex{DW\-\_CC\-\_nocall},
792 }
793 \caption{Calling convention codes}\label{fig:callingconventioncodes}
794 \end{figure}
795
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.
803
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}.
812
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.
819 }
820
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.
825 }
826
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}.
831
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
839 as \addtoindex{C} 
840 where functions support recursion by default.
841 }
842
843 A subprogram entry 
844 \hypertarget{chap:DWATelementalelementalpropertyofasubroutine}
845 may have 
846 \addtoindexx{elemental attribute}
847
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
852 or property.
853
854
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.
861
862
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
869 or property.
870
871
872
873 \subsection{Subroutine and Entry Point Return Types}
874 \label{chap:subroutineandentrypointreturntypes}
875
876 If 
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.
881
882 \textit{Debugging information entries for 
883 \addtoindex{C} void functions should
884 not have an attribute for the return type.  }
885
886
887 \subsection{Subroutine and Entry Point Locations}
888 \label{chap:subroutineandentrypointlocations}
889
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}
893 whose 
894 \addtoindexx{high PC attribute}
895 values 
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}).
901
902
903 \hypertarget{chap:DWATentrypcentryaddressofsubprogram}
904 subroutine entry may also have 
905 \addtoindexx{entry pc attribute!for subroutine}
906
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}).
911
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
914 for the entry point.
915
916 \textit{While the 
917 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute 
918 \addtoindexx{entry pc attribute!for subroutine}
919 might 
920 also seem appropriate
921 for this purpose, historically the 
922 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute
923 was used before the 
924 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} was introduced (in
925 \addtoindex{DWARF Version 3}). 
926 There is insufficient reason to change this.}
927
928
929 Subroutines 
930 and 
931 entry
932 \addtoindexx{address class!attribute}
933 points 
934 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}
935 may also have 
936 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} 
937 and
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.
942
943 A subroutine entry representing a subroutine declaration
944 that is not also a definition does not have code address or
945 range attributes.
946
947
948 \subsection{Declarations Owned by Subroutines and Entry Points} 
949 \label{chap:declarationsownedbysubroutinesandentrypoints}
950
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
957 source program.
958
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.}
964
965 The unspecified parameters of a variable parameter list are
966 represented by a debugging information entry\addtoindexx{unspecified parameters entry}
967 with the tag
968 \livetarg{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters}.
969
970 The entry for a subroutine that includes 
971 \addtoindexx{Fortran!common block}
972
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}. 
979 The
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}).
986
987 \subsection{Low-Level Information}
988 \label{chap:lowlevelinformation}
989
990
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.
997
998
999 \hypertarget{chap:DWATframebasesubroutineframebaseaddress}
1000 subroutine or entry point entry may also have 
1001 \addtoindexx{frame base attribute}
1002 a
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.
1013
1014 \textit{The use of one of the \livelink{chap:DWOPreg}{DW\-\_OP\-\_reg}~\textless~n~\textgreater 
1015 operations in this
1016 context is equivalent to using 
1017 \livelink{chap:DWOPbreg}{DW\-\_OP\-\_breg}~\textless~n~\textgreater(0) 
1018 but more
1019 compact. However, these are not equivalent in general.}
1020
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:}
1025
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.}
1033
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.
1039 \end{enumerate}
1040
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.}
1046
1047 If 
1048 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}
1049
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.
1057
1058 In the context of supporting nested subroutines, the
1059 \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute value should obey the following
1060 constraints:
1061
1062 \begin{enumerate}[1.]
1063 \item It should compute a value that does not change during the
1064 life of the procedure, and
1065
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.)
1070 \end{enumerate}
1071
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.}
1078
1079
1080
1081 \subsection{Types Thrown by Exceptions}
1082 \label{chap:typesthrownbyexceptions}
1083
1084 \textit{In \addtoindex{C++} a subroutine may declare a set of types which
1085 it may validly throw.}
1086
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}
1092 the tag
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.
1099
1100 \subsection{Function Template Instantiations}
1101 \label{chap:functiontemplateinstantiations}
1102
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.}
1107
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:
1114
1115 \begin{enumerate}[1.]
1116 \item Each formal parameterized type declaration appearing in the
1117 template definition is represented by a debugging information
1118 entry with the 
1119 tag \livetarg{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}. 
1120 Each
1121 such entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, 
1122 \addtoindexx{name attribute}
1123 whose value is a
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.
1130
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.
1134
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
1140 or omitted.
1141
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.
1147 \end{enumerate}
1148
1149
1150
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
1154 tag 
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}
1161 a
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}.
1165
1166 \begin{figure}[here]
1167 \centering
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 \\
1179 \end{tabular}
1180 \end{figure}
1181
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}.}
1187
1188
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
1194 that contains the 
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
1199 that contains 
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}
1203 is known as 
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
1215 instance tree.
1216
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.
1221
1222 \textit{For example, in \addtoindex{C++} the context might be a namespace
1223 declaration or a class declaration.}
1224
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.}
1228
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}
1241 attributes 
1242 \addtoindexx{location attribute!and abstract instance}
1243 typically 
1244 \addtoindexx{ranges attribute!and abstract instance}
1245 should 
1246 \addtoindexx{high PC attribute!and abstract instance}
1247 be 
1248 \addtoindexx{low PC attribute!and abstract instance}
1249 omitted; 
1250 however, 
1251 \addtoindexx{return address attribute!and abstract instance}
1252 this 
1253 \addtoindexx{segment attribute!and abstract instance}
1254 list
1255 \addtoindexx{start scope attribute!and abstract instance}
1256 is not exhaustive.
1257
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.}
1264
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.
1274
1275 \paragraph{Concrete Inlined Instances}
1276 \label{chap:concreteinlinedinstances}
1277
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.
1284
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 
1288 of 
1289 \addtoindexx{high PC attribute}
1290 attributes 
1291 \addtoindexx{low PC attribute}
1292 or 
1293 \addtoindexx{ranges attribute}
1294
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}). 
1300 An
1301 \hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}
1302 inlined subroutine entry may 
1303 \addtoindexx{inlined subprogram entry!in concrete instance}
1304 also 
1305 \addtoindexx{inlined subprogram entry}
1306 contain 
1307 \addtoindexx{entry pc attribute!for inlined subprogram}
1308
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}).
1313
1314 % Positions of the 3 targets here is a bit arbitrary.
1315 An inlined 
1316 \hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}
1317 subroutine 
1318 \hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}
1319 entry 
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, 
1323 each of whose
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}).
1332
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.
1336
1337 An inlined subroutine entry 
1338 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}
1339 may have a 
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.
1349
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.}
1356
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
1361 the tag 
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.
1373
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.}
1377
1378 Each concrete inlined instance tree is uniquely associated
1379 with one (and only one) abstract instance tree.
1380
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.}
1385
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}
1394 has a 
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.
1400
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 
1405 of that
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
1410 origin attribute.
1411
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}).
1422
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:
1427
1428 \begin{enumerate}[1.]
1429 \item An entry in the concrete instance tree may be omitted if
1430 it contains only a 
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.
1441
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.
1456
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.
1469
1470 \end{enumerate}
1471
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.''
1479
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.}
1484
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}
1493 instance 
1494 \hypertarget{chap:DWATabstractoriginoutoflineinstance}
1495 makes use of 
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
1500 tree).
1501
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:
1506
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}).
1512
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.
1518
1519 \end{enumerate}
1520
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.
1526
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
1533 nested subroutine.
1534
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:
1540
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
1547 instance tree.
1548
1549 \item Any abstract instance tree for a nested subroutine is
1550 always omitted within the concrete instance tree for an
1551 outer subroutine.
1552
1553 \item  A concrete instance tree for a nested subroutine is
1554 always omitted within the abstract instance tree for an
1555 outer subroutine.
1556
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
1560 to the rules in 
1561 Sections \refersec{chap:concreteinlinedinstances} or 
1562 \refersec{chap:outoflineinstancesofinlinedsubroutines}
1563 , respectively,
1564 and without regard to the fact that it is within an outer
1565 concrete instance tree.
1566 \end{enumerate}
1567
1568 See Appendix \refersec{app:inliningexamples} 
1569 for discussion and examples.
1570
1571 \subsection{Trampolines}
1572 \label{chap:trampolines}
1573
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.}
1579
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.)
1587
1588 The value of the trampoline attribute may be represented
1589 using any of the following forms, which are listed in order
1590 of preference:
1591
1592 \begin{itemize}
1593 \item If the value is of class reference, then the value
1594 specifies the debugging information entry of the target
1595 subprogram.
1596
1597 \item If the value is of class address, then the value is
1598 the relocated address of the target subprogram.
1599
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.
1603
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.
1607 \end{itemize}
1608
1609
1610 The target subprogram may itself be a trampoline. (A sequence
1611 of trampolines necessarily ends with a non\dash trampoline
1612 subprogram.)
1613
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
1620 vectors.}
1621
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. }
1626
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. }
1632
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. }
1636
1637
1638
1639 \section{Lexical Block Entries}
1640 \label{chap:lexicalblockentries}
1641
1642 \textit{A 
1643 lexical \livetargi{chap:lexicalblock}{block}{lexical block} 
1644 is 
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.}
1651
1652 % We do not need to link to the preceeding paragraph.
1653 A lexical \nolink{block} is represented by a debugging information
1654 entry with the 
1655 tag \livetarg{chap:DWTAGlexicalblock}{DW\-\_TAG\-\_lexical\-\_block}.
1656
1657 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry} 
1658 entry
1659 may have 
1660 either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
1661 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of 
1662 attributes 
1663 \addtoindexx{high PC attribute}
1664 or 
1665 \addtoindexx{low PC attribute}
1666
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}).
1673
1674 If a name has been given to the 
1675 lexical \livelink{chap:lexicalblock}{block} 
1676 in the source
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} 
1683 as it appears in
1684 the source program.
1685
1686 \textit{This is not the same as a \addtoindex{C} or 
1687 \addtoindex{C++} label (see below).}
1688
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}. 
1692 There is
1693 one such debugging information entry for each local declaration
1694 of an identifier or inner lexical \livelink{chap:lexicalblock}{block}.
1695
1696 \section{Label Entries}
1697 \label{chap:labelentries}
1698
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''
1701 statements.
1702
1703 A label is represented by a debugging information entry with
1704 \addtoindexx{label entry}
1705 the 
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
1710 the source program.
1711
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.
1720
1721
1722 \section{With Statement Entries}
1723 \label{chap:withstatemententries}
1724
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
1731 record variable.}
1732
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}.
1736
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}
1741 or 
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}).
1749
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
1756 the with statement.
1757
1758 \section{Try and Catch Block Entries}
1759 \label{chap:tryandcatchblockentries}
1760
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
1769 can handle.}
1770
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}.
1777
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}
1783 or 
1784 \addtoindexx{low PC attribute}
1785 a
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}
1791 (see Section
1792 \refersec{chap:codeaddressesandranges}).
1793
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}. 
1798
1799 This child entry has one of 
1800 \addtoindexx{formal parameter entry!in catch block}
1801 the 
1802 \addtoindexx{unspecified parameters entry!in catch block}
1803 tags
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.
1807
1808 The siblings immediately following 
1809 a try \livelink{chap:tryblock}{block} entry are its
1810 corresponding catch \livelink{chap:catchblock}{block} entries.
1811
1812
1813
1814
1815
1816
1817