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