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