Attributes table AT_f* i* l* now has links
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
index db35d36..8be3ef5 100644 (file)
@@ -65,7 +65,8 @@ partial compilation unit (see
 Section \refersec{chap:importedunitentries}).
 
 
-Compilation unit entries may have the following attributes:
+Compilation unit entries may have the following 
+attributes:
 
 \begin{enumerate}[1]
 \item Either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of
@@ -80,10 +81,13 @@ default base address for use in location lists (see Section
 (see Section \refersec{chap:noncontiguousaddressranges}).
 
 \item A \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null\dash terminated
-string containing the full or relative path name of the primary
+string 
+\hypertarget{chap:DWATnamepathnameofcompilationsource}
+containing the full or relative path name of the primary
 source file from which the compilation unit was derived.
 
 \item A \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} attribute whose constant value is an
+\hypertarget{chap:DWATlanguageprogramminglanguage}
 integer code indicating the source language of the compilation
 unit. The set of language names and their meanings are given
 in 
@@ -120,6 +124,7 @@ Language name & Meaning\\ \hline
 \end{figure}
 
 \item A \livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list} attribute whose value is a section
+\hypertarget{chap:DWATstmtlistlinenumberinformationforunit}
 offset to the line number information for this compilation
 unit.  This information is placed in a separate object file
 section from the debugging information entries themselves. The
@@ -129,6 +134,7 @@ information for this compilation unit
 (see Section \refersec{chap:linenumberinformation}).
 
 \item A \livelink{chap:DWATmacroinfo}{DW\-\_AT\-\_macro\-\_info} attribute whose value is a section
+\hypertarget{chap:DWATmacroinfomacroinformation}
 offset to the macro information for this compilation unit.
 This information is placed in a separate object file section
 from the debugging information entries themselves. The
@@ -137,13 +143,18 @@ the .debug\_macinfo section of the first byte of the macro
 information for this compilation unit 
 (see Section \refersec{chap:macroinformation}).
 
-\item  A \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir} attribute whose value is a
+\item  A 
+\livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir} 
+attribute 
+\hypertarget{chap:DWATcompdircompilationdirectory}
+whose value is a
 null\dash terminated string containing the current working directory
 of the compilation command that produced this compilation
 unit in whatever form makes sense for the host system.
 
 \item  A \livelink{chap:DWATproducer}{DW\-\_AT\-\_producer} attribute whose value is a null\dash
 terminated string containing information about the compiler
+\hypertarget{chap:DWATproducercompileridentification}
 that produced the compilation unit. The actual contents of
 the string will be specific to each producer, but should
 begin with the name of the compiler vendor or some other
@@ -151,7 +162,9 @@ identifying character sequence that should avoid confusion
 with other producer values.
 
 
-\item  A \livelink{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case} attribute whose integer
+\item  A \livelink{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case} 
+attribute whose integer
+\hypertarget{chap:DWATidentifiercaseidentifiercaserule}
 constant value is a code describing the treatment
 of identifiers within this compilation unit. The
 set of identifier case codes is given in Figure
@@ -218,7 +231,9 @@ using the UTF\dash 8 representation
 
 
 \item A \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram} attribute, which is a \livelink{chap:flag}{flag}
-whose presence indicates that the compilation unit contains a
+whose presence indicates 
+\hypertarget{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}
+that the compilation unit contains a
 subprogram that has been identified as the starting function
 of the program. If more than one compilation unit contains
 this \nolink{flag}, any one of them may contain the starting function.
@@ -241,7 +256,9 @@ of that compilation unit is not valid.
 
 \subsection{Imported Unit Entries}
 \label{chap:importedunitentries}
-The place where a normal or partial unit is imported is
+The 
+\hypertarget{chap:DWATimportimportedunit}
+place where a normal or partial unit is imported is
 represented by a debugging information entry with the 
 tag \livetarg{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}. 
 An imported unit entry contains a
@@ -337,12 +354,15 @@ whose values encode the contiguous or non\dash contiguous address
 ranges, respectively, of the machine instructions generated for
 the module initialization code 
 (see Section \refersec{chap:codeaddressesandranges}). 
+\hypertarget{chap:DWATentrypcentryaddressofmoduleinitialization}
 It may also
 have a \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute whose value is the address of
 the first executable instruction of that initialization code
 (see Section \refersec{chap:entryaddress}).
 
-If the module has been assigned a priority, it may have a
+If 
+\hypertarget{chap:DWATprioritymodulepriority}
+the module has been assigned a priority, it may have a
 \livelink{chap:DWATpriority}{DW\-\_AT\-\_priority} attribute. The value of this attribute is a
 reference to another debugging information entry describing
 a variable with a constant value. The value of this variable
@@ -360,8 +380,11 @@ A namespace is represented by a debugging information entry
 with the 
 tag \livetarg{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}. 
 A namespace extension is
-represented by a \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} entry 
-with a \livelink{chap:DWATextension}{DW\-\_AT\-\_extension}
+\hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}
+represented by a 
+\livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} entry 
+with a 
+\livelink{chap:DWATextension}{DW\-\_AT\-\_extension}
 attribute referring to the previous extension, or if there
 is no previous extension, to the original 
 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
@@ -436,14 +459,18 @@ given another name.
 An imported declaration is represented by one or
 more debugging information entries with the 
 tag \livetarg{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}. 
-When an overloaded entity
+When 
+\hypertarget{chap:DWATimportimporteddeclaration}
+an overloaded entity
 is imported, there is one imported declaration entry for
 each overloading. Each imported declaration entry has a
 \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute, whose value is a reference to the
 debugging information entry representing the declaration that
 is being imported.
 
-An imported declaration may also have a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
+An imported declaration may also have a 
+\livelink{chap:DWATname}{DW\-\_AT\-\_name}
+attribute
 whose value is a null\dash terminated string containing the
 name, as it appears in the source program, by which the
 imported entity is to be known in the context of the imported
@@ -458,6 +485,7 @@ an entity, regardless of the context in which the importing
 declaration or the imported entity occurs.
 
 \textit{A C++ namespace alias may be represented by an imported
+\hypertarget{chap:DWATimportnamespacealias}
 declaration entry with a name attribute whose value is
 a null\dash terminated string containing the alias name as it
 appears in the source program and an import attribute whose
@@ -466,6 +494,7 @@ namespace extension entry.
 }
 
 \textit{A C++ using declaration may be represented by one or more
+\hypertarget{chap:DWATimportnamespaceusingdeclaration}
 imported declaration entries.  When the using declaration
 refers to an overloaded function, there is one imported
 declaration entry corresponding to each overloading. Each
@@ -510,6 +539,7 @@ renamed in this way is known in the context of the imported
 module entry by the same name as it is declared in the module.
 
 \textit{A C++ using directive may be represented by an imported module
+\hypertarget{chap:DWATimportnamespaceusingdirective}
 entry, with an import attribute referring to the namespace
 entry of the appropriate extension of the namespace (which
 might be the original namespace entry) and no owned entries.
@@ -582,8 +612,11 @@ It may also have a \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name}
 described in Section \refersec{chap:linkagenames}.
 
 If the name of the subroutine described by an entry with the
-tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} is visible outside of its containing
-compilation unit, that entry has a \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute,
+tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
+is visible outside of its containing
+\hypertarget{chap:DWATexternalexternalsubroutine}
+compilation unit, that entry has a 
+\livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute,
 which is a \livelink{chap:flag}{flag}.
 
 \textit{Additional attributes for functions that are members of a
@@ -591,7 +624,9 @@ class or structure are described in
 Section \refersec{chap:memberfunctionentries}.
 }
 
-A subroutine entry may contain a \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}
+A 
+\hypertarget{chap:DWATmainsubprogrammainorstartingsubprogram}
+subroutine entry may contain a \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}
 attribute which is 
 a \livelink{chap:flag}{flag} whose presence indicates that the
 subroutine has been identified as the starting function of
@@ -611,7 +646,10 @@ the standard calling conventions for the target architecture
 and will therefore not be safe to call from within a debugger.
 }
 
-A subroutine entry may contain a \livelink{chap:DWATcallingconvention}{DW\-\_AT\-\_calling\-\_convention}
+A subroutine entry may 
+\hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}
+contain a 
+\livelink{chap:DWATcallingconvention}{DW\-\_AT\-\_calling\-\_convention}
 attribute, whose value is an integer constant. The set of
 calling convention codes is given in 
 Figure \refersec{fig:callingconventioncodes}.
@@ -667,18 +705,27 @@ attribute is neither needed nor appropriate in languages such
 as C where functions support recursion by default.
 }
 
-A subprogram entry may have a \livelink{chap:DWATelemental}{DW\-\_AT\-\_elemental} attribute, which
+A subprogram entry 
+\hypertarget{chap:DWATelementalelementalpropertyofasubroutine}
+may have a 
+\livelink{chap:DWATelemental}{DW\-\_AT\-\_elemental} attribute, which
 is a \livelink{chap:flag}{flag}. 
 The attribute indicates whether the subroutine
 or entry point was declared with the ``elemental'' keyword
 or property.
 
-A subprogram entry may have a \livelink{chap:DWATpure}{DW\-\_AT\-\_pure} attribute, which is
+A 
+\hypertarget{chap:DWATpurepurepropertyofasubroutine}
+subprogram entry may have a 
+\livelink{chap:DWATpure}{DW\-\_AT\-\_pure} attribute, which is
 a \livelink{chap:flag}{flag}. 
 The attribute indicates whether the subroutine was
 declared with the ``pure'' keyword or property.
 
-A subprogram entry may have a \livelink{chap:DWATrecursive}{DW\-\_AT\-\_recursive} attribute, which
+A 
+\hypertarget{chap:DWATrecursiverecursivepropertyofasubroutine}
+subprogram entry may have a 
+\livelink{chap:DWATrecursive}{DW\-\_AT\-\_recursive} attribute, which
 is a \livelink{chap:flag}{flag}. 
 The attribute indicates whether the subroutine
 or entry point was declared with the ``recursive'' keyword
@@ -707,7 +754,10 @@ ranges, respectively, of the machine instructions generated
 for the subroutine (see 
 Section \refersec{chap:codeaddressesandranges}).
 
-A subroutine entry may also have a \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute
+A 
+\hypertarget{chap:DWATentrypcentryaddressofsubprogram}
+subroutine entry may also have a 
+\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute
 whose value is the address of the first executable instruction
 of the subroutine (see 
 Section \refersec{chap:entryaddress}).
@@ -763,6 +813,7 @@ Fortran \livelink{chap:fortrancommonblock}{common} \livelink{chap:commonblockent
 has a child entry with the 
 tag \livetarg{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion}. 
 The
+\hypertarget{chap:commonreferencecommonblockusage}
 common inclusion entry has a 
 \livelink{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference} attribute
 whose value is a reference to the debugging information entry
@@ -772,12 +823,17 @@ for the common \nolink{block} being included
 \subsection{Low-Level Information}
 \label{chap:lowlevelinformation}
 
-A subroutine or entry point entry may have a \livelink{chap:DWATreturnaddr}{DW\-\_AT\-\_return\-\_addr}
+A 
+\hypertarget{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}
+subroutine or entry point entry may have a 
+\livelink{chap:DWATreturnaddr}{DW\-\_AT\-\_return\-\_addr}
 attribute, whose value is a location description. The location
 calculated is the place where the return address for the
 subroutine or entry point is stored.
 
-A subroutine or entry point entry may also have a
+A 
+\hypertarget{chap:DWATframebasesubroutineframebaseaddress}
+subroutine or entry point entry may also have a
 \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute, whose value is a location
 description that computes the “frame base” for the
 subroutine or entry point. If the location description is
@@ -819,8 +875,11 @@ outer subroutine from within an inner subroutine. The
 \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link} and \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attributes allow
 debuggers to support this same kind of referencing.}
 
-If a subroutine or entry point is nested, it may have a
-\livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link} attribute, whose value is a location
+If 
+\hypertarget{chap:DWATstaticlinklocationofuplevelframe}
+a subroutine or entry point is nested, it may have a
+\livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}
+attribute, whose value is a location
 description that computes the frame base of the relevant
 instance of the subroutine that immediately encloses the
 subroutine or entry point.
@@ -915,7 +974,10 @@ artificially by the compiler for this instantiation.
 \subsection{Inlinable and Inlined Subroutines}
 A declaration or a definition of an inlinable subroutine
 is represented by a debugging information entry with the
-tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. The entry for a subroutine that is
+tag 
+\livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}.
+The entry for a subroutine that is
+\hypertarget{chap:DWATinlineinlinedsubroutine}
 explicitly declared to be available for inline expansion or
 that was expanded inline implicitly by the compiler has a
 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is an integer constant. The
@@ -948,8 +1010,10 @@ entry with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. Suc
 \paragraph{Abstract Instances}
 \label{chap:abstractinstances}
 Any debugging information entry that is owned (either
+\hypertarget{chap:DWATinlineabstracttinstance}
 directly or indirectly) by a debugging information entry
-that contains the \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute is referred to
+that contains the 
+\livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute is referred to
 as an ``abstract instance entry.'' Any subroutine entry
 that contains a \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is other
 than \livelink{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined} is known as 
@@ -1013,18 +1077,29 @@ Each such entry should be a direct
 child of the entry that represents the scope within which
 the inlining occurs.
 
-Each inlined subroutine entry may have either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}
+Each inlined subroutine entry may have either a 
+\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}
 and \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes or a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges}
 attribute whose values encode the contiguous or non\dash contiguous
 address ranges, respectively, of the machine instructions
 generated for the inlined subroutine (see 
-Section \refersec{chap:codeaddressesandranges}). An
-inlined subroutine entry may also contain a \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}
+Section \refersec{chap:codeaddressesandranges}). 
+An
+\hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}
+inlined subroutine entry may also contain a 
+\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}
 attribute, representing the first executable instruction of
 the inline expansion (see 
 Section \refersec{chap:entryaddress}).
 
-An inlined subroutine entry may also have \livelink{chap:DWATcallfile}{DW\-\_AT\-\_call\-\_file},
+% Positions of the 3 targets here is a bit arbitrary.
+An inlined 
+\hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}
+subroutine 
+\hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}
+entry 
+\hypertarget{chap:DWATcallfilefilecontaininginlinedsubroutinecall}
+may also have \livelink{chap:DWATcallfile}{DW\-\_AT\-\_call\-\_file},
 \livelink{chap:DWATcallline}{DW\-\_AT\-\_call\-\_line} and \livelink{chap:DWATcallcolumn}{DW\-\_AT\-\_call\-\_column} attributes, 
 each of whose
 value is an integer constant. These attributes represent the
@@ -1040,7 +1115,10 @@ The call file, call line and call column coordinates do not
 describe the coordinates of the subroutine declaration that
 was inlined, rather they describe the coordinates of the call.
 
-An inlined subroutine entry may have a \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}
+An inlined subroutine entry 
+\hypertarget{chap:DWATconstexprcompiletimeconstantfunction}
+may have a 
+\livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}
 attribute, which is a \livelink{chap:flag}{flag} 
 whose presence indicates that the
 subroutine has been evaluated as a compile\dash time constant. Such