Indexing letter 's'.
[dwarf-doc.git] / dwarf5 / latexdoc / generaldescription.tex
index 1a1f02f..5b66b62 100644 (file)
@@ -360,7 +360,7 @@ actually declared in the source}{objects or types that are not actually declared
 \livetarg{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8}
 &\livelinki{chap:DWATuseUTF8compilationunitusesutf8strings}{Compilation unit uses UTF-8 strings}{compilation unit uses UTF-8 strings} \\
 \livetarg{chap:DWATvariableparameter}{DW\-\_AT\-\_variable\-\_parameter}
-&\livelink{chap:DWATvariableparameternonconstantparameterflag}{Non-constant parameter flag}{non-constant parameter flag}  \\
+&\livelinki{chap:DWATvariableparameternonconstantparameterflag}{Non-constant parameter flag}{non-constant parameter flag}  \\
 \livetarg{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality}
 &\livelinki{chap:DWATvirtualityvirtualityindication}{Virtuality indication}{virtuality indication} \\
 &\livelinki{chap:DWATvirtualityvirtualityofbaseclass}{Virtuality of base class} {virtuality of base class} \\
@@ -494,8 +494,11 @@ In cases where a producer of debugging information feels that
 \hypertarget{chap:DWATsiblingdebugginginformationentryrelationship}
 it will be important for consumers of that information to
 quickly scan chains of sibling entries, while ignoring the
-children of individual siblings, that producer may attach a
-\livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} attribute to any debugging information entry. 
+children of individual siblings, that producer may attach 
+\addtoindexx{sibling attribute}
+a
+\livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} attribute 
+to any debugging information entry. 
 The
 value of this attribute is a reference to the sibling entry
 of the entry to which the attribute is attached.
@@ -521,7 +524,9 @@ the DWARF information.
 For example, if a particular target architecture supports
 both 32\dash bit and 64\dash bit addresses, the compiler will generate
 an object file which specifies that it contains executable
-code generated for one or the other of these address sizes. In
+code generated for one or the other of these 
+\addtoindexx{size of an address}
+address sizes. In
 that case, the DWARF debugging information contained in this
 object file will use the same address size.
 }
@@ -553,7 +558,8 @@ Section \refersec{chap:locationdescriptions}.
 \label{chap:generaloperations}
 Each general operation represents a postfix operation on
 a simple stack machine. Each element of the stack is the
-size of an address on the target machine. The value on the
+\addtoindex{size of an address} on the target machine. 
+The value on the
 top of the stack after ``executing'' the 
 \addtoindex{DWARF expression}
 is 
@@ -581,7 +587,7 @@ from 0 through 31, inclusive.
 
 \item \livetarg{chap:DWOPaddr}{DW\-\_OP\-\_addr} \\
 The \livelink{chap:DWOPaddr}{DW\-\_OP\-\_addr} operation has a single operand that encodes
-a machine address and whose size is the size of an address
+a machine address and whose size is the \addtoindex{size of an address}
 on the target machine.
 
 \item \livetarg{chap:DWOPconst1u}{DW\-\_OP\-\_const1u}, \livetarg{chap:DWOPconst2u}{DW\-\_OP\-\_const2u}, \livetarg{chap:DWOPconst4u}{DW\-\_OP\-\_const4u}, \livetarg{chap:DWOPconst8u}{DW\-\_OP\-\_const8u} \\
@@ -682,7 +688,7 @@ treats it as an address. The value
 retrieved from that address is pushed. 
 The size of the data retrieved from the 
 \addtoindexi{dereferenced}{address!dereference operator}
-address is the size of an address on the target machine.
+address is the \addtoindex{size of an address} on the target machine.
 
 \item \livetarg{chap:DWOPderefsize}{DW\-\_OP\-\_deref\-\_size} \\
 The \livelink{chap:DWOPderefsize}{DW\-\_OP\-\_deref\-\_size} operation behaves like the \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}
@@ -692,7 +698,7 @@ the \livelink{chap:DWOPderefsize}{DW\-\_OP\-\_deref\-\_size} operation, however,
 of the data retrieved from the dereferenced address is
 specified by the single operand. This operand is a 1\dash byte
 unsigned integral constant whose value may not be larger
-than the size of an address on the target machine. The data
+than the \addtoindex{size of an address} on the target machine. The data
 retrieved is zero extended to the size of an address on the
 target machine before being pushed onto the expression stack.
 
@@ -708,7 +714,7 @@ address calculation and pushed as the new stack top. The size
 of the data retrieved from the 
 \addtoindexi{dereferenced}{address!dereference operator}
 address is the
-size of an address on the target machine.
+\addtoindex{size of an address} on the target machine.
 
 \item \livetarg{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size}\\
 The \livelink{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size} operation behaves like the
@@ -725,8 +731,8 @@ the size in bytes of the data retrieved from the
 \addtoindexi{dereferenced}{address!dereference operator}
 address is specified by the single operand. This operand is a
 1\dash byte unsigned integral constant whose value may not be larger
-than the size of an address on the target machine. The data
-retrieved is zero extended to the size of an address on the
+than the \addtoindex{size of an address} on the target machine. The data
+retrieved is zero extended to the \addtoindex{size of an address} on the
 target machine before being pushed onto the expression stack.
 
 \item \livetarg{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}\\
@@ -794,8 +800,10 @@ provide arithmetic and logical operations. Except
 as otherwise specified, the arithmetic operations perfom
 addressing arithmetic, that is, unsigned arithmetic that is
 performed modulo one plus the largest representable address
-(for example, 0x100000000 when the size of an address is 32
-bits). Such operations do not cause an exception on overflow.
+(for example, 0x100000000 when the 
+\addtoindex{size of an address} is 32
+bits). 
+Such operations do not cause an exception on overflow.
 
 \begin{enumerate}[1]
 \item \livetarg{chap:DWOPabs}{DW\-\_OP\-\_abs}  \\
@@ -1044,7 +1052,9 @@ of two forms:
 \item \textit{Single location descriptions}, 
 which 
 \addtoindexx{location description!single}
-are a language independent representation of
+are 
+\addtoindexx{single location description}
+a language independent representation of
 addressing rules of arbitrary complexity built from 
 DWARF expressions (See Section \refersec{chap:dwarfexpressions}) 
 and/or other
@@ -1101,7 +1111,9 @@ A single location description is either:
 \begin{enumerate}[1]
 \item A simple location description, representing an object
 \addtoindexx{location description!simple}
-which exists in one contiguous piece at the given location, or 
+which 
+\addtoindexx{simple location description}
+exists in one contiguous piece at the given location, or 
 \item A composite location description consisting of one or more
 \addtoindexx{location description!composite}
 simple location descriptions, each of which is followed by
@@ -1127,7 +1139,9 @@ contiguous piece or all of an object or value.
 
 A 
 \addtoindexx{location description!memory}
-memory location description consists of a non\dash empty DWARF
+memory location description 
+\addtoindexx{memory location description}
+consists of a non\dash empty DWARF
 expression (see 
 Section \refersec{chap:dwarfexpressions}
 ), whose value is the address of
@@ -1238,7 +1252,8 @@ of the resultant value is contained.
 
 \begin{enumerate}[1]
 \item \livetarg{chap:DWOPpiece}{DW\-\_OP\-\_piece} \\
-The \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} operation takes a single operand, which is an
+The \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} operation takes a 
+single operand, which is an
 unsigned LEB128 number.  The number describes the size in bytes
 of the piece of the object referenced by the preceding simple
 location description. If the piece is located in a register,
@@ -1390,7 +1405,7 @@ location list entry consists of:
 
 \begin{enumerate}[1]
 \item A beginning address offset. 
-This address offset has the size of an address and is
+This address offset has the \addtoindex{size of an address} and is
 relative to the applicable base address of the compilation
 unit referencing this location list. It marks the beginning
 of the address 
@@ -1398,7 +1413,7 @@ of the address
 over which the location is valid.
 
 \item An ending address offset.  This address offset again
-has the size of an address and is relative to the applicable
+has the \addtoindex{size of an address} and is relative to the applicable
 base address of the compilation unit referencing this location
 list. It marks the first address past the end of the address
 range over which the location is valid. The ending address
@@ -1410,7 +1425,7 @@ and ending addresses are equal has no effect
 because the size of the range covered by such
 an entry is zero.}
 
-\item A single location description 
+\item A \addtoindex{single location description} 
 describing the location of the object over the range specified by
 the beginning and end addresses.
 \end{enumerate}
@@ -1466,7 +1481,7 @@ entry includes a location description.
 \textit{A base address selection entry and an end of list
 entry for a location list are identical to a base address
 selection entry and end of list entry, respectively, for a
-range list 
+\addtoindex{range list}
 (see Section \refersec{chap:noncontiguousaddressranges}) 
 in interpretation
 and representation.}
@@ -1528,7 +1543,7 @@ value is a constant drawn from the set of codes listed in Figure
 \section{Visibility of Declarations}
 \label{chap:visibilityofdeclarations}
 
-\textit{Several languages (such as Modula-2
+\textit{Several languages (such as \addtoindex{Modula-2}
 have the concept of the visibility of a declaration. The
 visibility specifies which declarations are to be 
 visible outside of the entity in which they are
@@ -1600,7 +1615,9 @@ which is a \livelink{chap:flag}{flag}.
 \textit{In some systems, addresses are specified as offsets within a
 given 
 \addtoindexx{address space!segmented}
-segment rather than as locations within a single flat
+segment 
+\addtoindexx{segmented adddressing|see{address space}}
+rather than as locations within a single flat
 \addtoindexx{address space!flat}.
 address space.}
 
@@ -1608,8 +1625,9 @@ Any debugging information entry that contains a description
 \hypertarget{chap:DWATsegmentaddressinginformation}
 of the location of an object or subroutine may have
 a 
-\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
-attribute, whose value is a location
+\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, 
+\addtoindexx{segment attribute}
+whose value is a location
 description. The description evaluates to the segment selector
 of the item being described. If the entry containing the
 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute has a 
@@ -1622,15 +1640,23 @@ or
 a location
 description that evaluates to an address, then those address
 values represent the offset portion of the address within
-the segment specified by \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}.
+the segment specified 
+\addtoindexx{segment attribute}
+by \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}.
 
-If an entry has no \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, it inherits
+If an entry has no 
+\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, it inherits
+\addtoindexx{segment attribute}
 the segment value from its parent entry.  If none of the
 entries in the chain of parents for this entry back to
-its containing compilation unit entry have \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
-attributes, then the entry is assumed to exist within a flat
-address space. Similarly, if the entry has a \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
-attribute containing an empty location description, that
+its containing compilation unit entry have 
+\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attributes, 
+then the entry is assumed to exist within a flat
+address space. 
+Similarly, if the entry has a 
+\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute 
+\addtoindexx{segment attribute}
+containing an empty location description, that
 entry is assumed to exist within a 
 \addtoindexi{flat}{address space!flat}.
 address space.
@@ -1737,7 +1763,10 @@ example,
 \livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} and 
 \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} 
 \addtoindexx{declaration attribute}
-clearly cannot apply to a referring
+clearly cannot apply to a 
+\addtoindexx{declaration attribute}
+referring
+\addtoindexx{sibling attribute}
 entry.}
 
 
@@ -1804,10 +1833,14 @@ Any
 \hypertarget{chap:DWATnamenameofdeclaration}
 debugging information entry 
 \addtoindexx{identifier names}
-representing a program entity
+representing 
+\addtoindexx{names!identifier}
+a program entity
 that has been given a name may have a 
 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
-whose value is a string representing the name as it appears in
+whose 
+\addtoindexx{name attribute}
+value is a string representing the name as it appears in
 the source program. A debugging information entry containing
 no name attribute, or containing a name attribute whose value
 consists of a name containing a single null byte, represents
@@ -1816,12 +1849,18 @@ a program entity for which no name was given in the source.
 \textit{Because the names of program objects described by DWARF are the
 names as they appear in the source program, implementations
 of language translators that use some form of mangled name
+\addtoindex{mangled names}
 (as do many implementations of C++) should use the unmangled
-form of the name in the DWARF \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
+form of the name in the 
+DWARF \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
+\addtoindexx{name attribute}
 including the keyword operator (in names such as “operator
 +”), if present. See also 
 Section \refersec{chap:linkagenames} regarding the use
-of \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} for mangled names. Sequences of
+of \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} for 
+\addtoindex{mangled names}
+mangled names. 
+Sequences of
 multiple whitespace characters may be compressed.}
 
 \section{Data Locations and DWARF Procedures}
@@ -1894,6 +1933,7 @@ for a non-contiguous range of addresses.
 In addition, a non-contiguous range of 
 addresses may also be specified for the
 \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute.
+\addtoindexx{start scope attribute}
 If an entity has no associated machine code, 
 none of these attributes are specified.
 
@@ -1939,50 +1979,63 @@ attributes should be produced.
 \subsection{Non\dash Contiguous Address Ranges}
 \label{chap:noncontiguousaddressranges}
 When the set of addresses of a debugging information entry
+\addtoindexx{non-contiguous address ranges}
 cannot be described as a single contiguous range, the entry has
 a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute 
 \addtoindexx{ranges attribute}
 whose value is of class \livelink{chap:rangelistptr}{rangelistptr}
-and indicates the beginning of a range list. Similarly,
-a \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute may have a value of class
+and indicates the beginning of a \addtoindex{range list}.
+Similarly,
+a \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute 
+\addtoindexx{start scope attribute}
+may have a value of class
 \livelink{chap:rangelistptr}{rangelistptr} for the same reason.  
 
 Range lists are contained
 in a separate object file section called 
 \addtoindex{.debug\_ranges}. A
-range list is indicated by a 
+\addtoindex{range list} is indicated by a 
 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute whose
 \addtoindexx{ranges attribute}
 value is represented as an offset from the beginning of the
-\addtoindex{.debug\_ranges} section to the beginning of the range list.
+\addtoindex{.debug\_ranges} section to the beginning of the 
+\addtoindex{range list}.
 
-Each entry in a range list is either a range list entry,
+Each entry in a \addtoindex{range list} is either a 
+\addtoindex{range list} entry,
 \addtoindexx{base address selection entry!in range list}
 a base address selection entry, or an 
 \addtoindexx{end of list entry!in range list}
 end of list entry.
 
-A range list entry consists of:
+A \addtoindex{range list} entry consists of:
 
 \begin{enumerate}[1]
-\item A beginning address offset. This address offset has the size of an address and is relative to
-the applicable base address of the compilation unit referencing this range list. It marks the
+\item A beginning address offset. This address offset has the 
+\addtoindex{size of an address} and is relative to
+the applicable base address of the compilation unit referencing this 
+\addtoindex{range list}. 
+It marks the
 beginning of an 
 \addtoindexi{address}{address range!in range list} 
 range.
 
-\item An ending address offset. This address offset again has the size of an address and is relative
-to the applicable base address of the compilation unit referencing this range list. It marks the
+\item An ending address offset. This address offset again has the 
+\addtoindex{size of an address} and is relative
+to the applicable base address of the compilation unit referencing 
+this \addtoindex{range list}.
+It marks the
 first address past the end of the address range.
 The ending address must be greater than or
 equal to the beginning address.
 
-\textit{A range list entry (but not a base address selection or end of list entry) whose beginning and
+\textit{A \addtoindex{range list} entry (but not a base address selection or end of list entry) whose beginning and
 ending addresses are equal has no effect because the size of the range covered by such an
 entry is zero.}
 \end{enumerate}
 
-The applicable base address of a range list entry is determined
+The applicable base address of a \addtoindex{range list} entry
+is determined
 by the closest preceding base address selection entry (see
 below) in the same range list. If there is no such selection
 entry, then the applicable base address defaults to the base
@@ -1994,7 +2047,8 @@ code is contained in a single contiguous section, no base
 address selection entry is needed.}
 
 Address range entries in
-a range list may not overlap. There is no requirement that
+a \addtoindex{range list} may not overlap.
+There is no requirement that
 the entries be ordered in any particular way.
 
 A base address selection entry consists of:
@@ -2010,18 +2064,20 @@ and ending address offsets of subsequent entries of the location list.
 affects only the list in which it is contained.}
 
 
-The end of any given range list is marked by an 
+The end of any given \addtoindex{range list} is marked by an 
 \addtoindexx{end of list entry!in range list}
 end of list entry, 
 which consists of a 0 for the beginning address
-offset and a 0 for the ending address offset. A range list
+offset and a 0 for the ending address offset. 
+A \addtoindex{range list}
 containing only an end of list entry describes an empty scope
 (which contains no instructions).
 
 \textit{A base address selection entry and an 
 \addtoindexx{end of list entry!in range list}
 end of list entry for
-a range list are identical to a base address selection entry
+a \addtoindex{range list} 
+are identical to a base address selection entry
 and end of list entry, respectively, for a location list
 (see Section \refersec{chap:locationlists}) 
 in interpretation and representation.}
@@ -2105,7 +2161,9 @@ type descriptions of the form typename’Class, and
 Generally, any debugging information
 entry that 
 \hypertarget{chap:DWATdescriptionartificialnameordescription}
-has, or may have, a 
+has, or may have, 
+\addtoindexx{name attribute}
+a 
 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, may
 also have 
 \addtoindexx{description attribute}
@@ -2144,7 +2202,11 @@ languages,
 make use of implementation defined names within
 object files that are different from the identifier names
 (see Section \refersec{chap:identifiernames}) of entities as they appear in the
-source. Such names, sometimes known as mangled names,
+source. Such names, sometimes known 
+\addtoindex{names!mangled}
+as 
+\addtoindexx{mangled names}
+mangled names,
 are used in various ways, such as: to encode additional
 information about an entity, to distinguish multiple entities
 that have the same name, and so on. When an entity has an