A few miscelleaneous corrections including especially fixing the spacing
[dwarf-doc.git] / dwarf5 / latexdoc / dataobject.tex
index 54a0cbc..c496e7c 100644 (file)
@@ -9,49 +9,66 @@ a common \livelink{chap:commonblockentry}{block}.
 
 \section{Data Object Entries}
 \label{chap:dataobjectentries}
+\addtoindexx{data object entries}
 
-
-Program variables, formal parameters and constants are
+Program variables, 
+\addtoindexx{formal parameter entry}
+formal parameters and constants are
 represented by debugging information entries with the tags
-\livetarg{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}, 
-\livetarg{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter} and 
-\livetarg{chap:DWTAGconstant}{DW\-\_TAG\-\_constant},
+\livetarg{chap:DWTAGvariable}{DW\_TAG\_variable}\addtoindexx{variable entry}, 
+\livetarg{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}\addtoindexx{formal parameter entry} and 
+\livetarg{chap:DWTAGconstant}{DW\_TAG\_constant}\addtoindexx{constant (data) entry},
 respectively.
 
-\textit{The tag \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant} is used for languages that
+\textit{The tag \livelink{chap:DWTAGconstant}{DW\_TAG\_constant} is used for languages that
 have true named constants.}
 
 The debugging information entry for a program variable,
 formal parameter or constant may have the following attributes:
-\begin{enumerate}[1.]
-\item A \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is a null-terminated
+\begin{enumerate}[1. ]
+\item A \livelink{chap:DWATname}{DW\_AT\_name} attribute,
+\addtoindexx{name attribute}
+whose value is a null-terminated
 string, containing the data object name as it appears in the
-source program.  If a variable entry describes 
-an 
+source program.
+
+If a variable entry describes an 
 \addtoindex{anonymous union},
 the name attribute is omitted or consists of a single
 zero byte.
 
-\item A \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute, 
+\item A \livelink{chap:DWATexternal}{DW\_AT\_external} attribute, 
 \hypertarget{chap:DWATexternalexternalvariable}
-which is a \livelink{chap:flag}{flag}, if the name
+which 
+\addtoindexx{external attribute}
+is a \livelink{chap:classflag}{flag}, if the name
 of a variable is visible outside of its enclosing compilation
-unit.  The definitions of C++ static data members of structures
+unit.  
+
+\textit{The definitions of C++ static data members of structures
 or classes are represented by variable entries \nolink{flagged} as
 external. Both file static and local variables in C and C++
 are represented by non-external variable entries.
+}
 
-\item A \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute, 
-which is a \livelink{chap:flag}{flag} that
+\item A \livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute, 
+\addtoindexx{declaration attribute}
+which is a \livelink{chap:classflag}{flag} that
 indicates whether this entry represents a non-defining
 declaration of an object.
 
-\item A \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute, whose value describes the
-location of a variable or parameter at run-time.  In a variable
+\item A \livelink{chap:DWATlocation}{DW\_AT\_location} attribute,
+\addtoindexx{location attribute}
+whose value describes the location of a variable or parameter at run-time.
+
+If no location attribute is present in a variable 
 entry representing the definition of a variable (that is,
-with no \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute) if no location attribute
-is present, or if the location attribute is present but has
-an empty location description (as described in Section 2.6),
+\addtoindexx{declaration attribute}
+with no 
+\livelink{chap:DWATdeclaration}{DW\_AT\_declaration} attribute),
+or if the location attribute is present but has
+an empty location description (as described in Section \refersec{chap:locationdescriptions}),
+\addtoindexx{unallocated variable}
 the variable is assumed to exist in the source code but not
 in the executable program (but see number 10, below).
 
@@ -59,26 +76,34 @@ In a variable entry representing a non-defining declaration of a variable, the l
 specified modifies the location specified by the defining declaration and only applies for the
 scope of the variable entry; if no location is specified, then the location specified in the
 defining declaration applies.
-The location of a variable may be further specified with a \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, if
+
+The location of a variable may be further specified with 
+\addtoindexx{segment attribute!and data segment}
+a 
+\livelink{chap:DWATsegment}{DW\_AT\_segment} attribute, if
 appropriate.
 
-\item A \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute describing the type of the variable,
+\item A \livelink{chap:DWATtype}{DW\_AT\_type} attribute describing the type of the variable,
 constant or formal parameter.
 
 \item If the variable entry represents the defining declaration
 for a C++ static data member of a structure, class or union,
-the entry has a \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute, whose value is a
-reference to the debugging information entry representing the
+the entry has a \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute, whose value is a
+\livelink{chap:class:reference}{reference} to the debugging information entry representing the
 declaration of this data member. The referenced entry has the
-tag \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} and will be a child of some class, structure
-or union type entry.  If the variable entry represents a
-non-defining declaration, \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} may be used
+tag \livelink{chap:DWTAGmember}{DW\_TAG\_member} and will be a child of some class, structure
+or union type entry.
+
+If the variable entry represents a
+non-defining declaration, \livelink{chap:DWATspecification}{DW\_AT\_specification} may be used
 to reference the defining declaration of the variable. If
-no \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute is present, the defining
+no \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute is present, the defining
 declaration may be found as a global definition either in the
 current compilation unit or in another compilation unit with
-the \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute.  Variable entries containing
-the \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute do not need to duplicate
+the \livelink{chap:DWATexternal}{DW\_AT\_external} attribute.  
+
+Variable entries containing
+the \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute do not need to duplicate
 information provided by the declaration entry referenced by
 the specification attribute. In particular, such variable
 entries do not need to contain attributes for the name or
@@ -88,19 +113,26 @@ type of the data member whose definition they
 \hypertarget{chap:DWATvariableparameternonconstantparameterflag}
 represent.
 
-\item A \livelink{chap:DWATvariableparameter}{DW\-\_AT\-\_variable\-\_parameter} attribute, 
-which is a \livelink{chap:flag}{flag},
+\item A \livelink{chap:DWATvariableparameter}{DW\_AT\_variable\_parameter}
+attribute\addtoindexx{variable parameter attribute}, 
+which is a \livelink{chap:classflag}{flag},
 if a formal parameter entry represents a parameter whose
-value in the calling function may be modified by the callee..
-The absence of this attribute implies that the parameters
+value in the calling function may be modified by the callee.
+The absence of this attribute implies that the parameter\textquoteright s
 value in the calling function cannot be modified by the callee.
 
-\item A \livelink{chap:DWATisoptional}{DW\-\_AT\-\_is\-\_optional} attribute, 
+\item A \livelink{chap:DWATisoptional}{DW\_AT\_is\_optional} attribute, 
 \hypertarget{chap:DWATisoptionaloptionalparameter}
-which is a \livelink{chap:flag}{flag}, if a
-parameter entry represents an optional parameter.
+which 
+\addtoindexx{is optional attribute}
+is a \livelink{chap:classflag}{flag}, if a
+parameter entry represents an \addtoindex{optional parameter}.
 
-\item A \livelink{chap:DWATdefaultvalue}{DW\-\_AT\-\_default\-\_value} attribute for a formal parameter
+\item A \livelink{chap:DWATdefaultvalue}{DW\_AT\_default\_value} attribute 
+\addtoindexx{default value attribute}
+for 
+\addtoindexx{formal parameter entry!with default value}
+a formal parameter
 \hypertarget{chap:DWATdefaultvaluedefaultvalueofparameter}
 entry. The value of this attribute is a reference to the
 debugging information entry for a variable or subroutine,
@@ -115,7 +147,7 @@ as a default value of the type of the formal parameter.
 \textit{For a constant form there is no way to 
 express the absence of a default value.}
 
-\item A \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute 
+\item A \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value} attribute 
 for 
 \hypertarget{chap:DWATconstvalueconstantobject}
 an entry describing a
@@ -124,21 +156,27 @@ represented by an object in the address space of the program,
 or an entry describing a named constant. (Note that such
 an entry does not have a location attribute.) The value of
 this attribute may be a string or any of the constant data
-or data \livelink{chap:block}{block} forms, 
+or data block forms, 
 as appropriate for the representation
-of the variables value. The value is the actual constant
+of the variable's value. The value is the actual constant
 value of the variable, represented as it would be on the
-target architecture.  One way in which a formal parameter
+target architecture.  
+
+\textit{One way in which a formal parameter
 with a constant value and no location can arise is for a
 formal parameter of an inlined subprogram that corresponds
 to a constant actual parameter of a call that is inlined.
+}
 
-\item A \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute if the scope of an
+\item A \livelink{chap:DWATstartscope}{DW\_AT\_start\_scope} 
+attribute if the scope of 
+\addtoindexx{start scope attribute}
+an
 \hypertarget{chap:DWATstartscopeobjectdeclaration}
 object is smaller than (that is, is a subset of the addresses
 of) the scope most closely enclosing the object. There are
 two cases:
-\begin{enumerate}[a)]
+\begin{enumerate}[a) ]
 \item If the scope of the object entry includes all of the
 containing scope except for a contiguous sequence of bytes at
 the beginning of that containing scope, then the scope of the
@@ -147,14 +185,19 @@ containing scope is contiguous, the value of this attribute
 is the offset in bytes of the beginning of the scope for the
 object from the low pc value of the debugging information
 entry that defines its scope. If the containing scope
-is non-contiguous (see Section 2.17.3), the value of this
+is non-contiguous 
+(see \refersec{chap:noncontiguousaddressranges})
+the value of this
 attribute is the offset in bytes of the beginning of the scope
-for the object from the beginning of the first range list entry
+for the object from the beginning of the first \addtoindex{range list} entry
 that is not a base selection entry or an end of list entry.
 
+\needlines{4}
 \item Otherwise, the scope of the object is specified using
-a value of class \livelink{chap:rangelistptr}{rangelistptr}. This value indicates the
-beginning of a range list (see Section 2.17.3).
+a value of class \livelink{chap:classrangelistptr}{rangelistptr}. 
+This value indicates the
+beginning of a \addtoindex{range list}
+(see \ref{chap:noncontiguousaddressranges}).
 \end{enumerate}
 
 
@@ -182,55 +225,67 @@ because the scope of the local variable x only starts after
 the full declarator for the local x.}
 
 \textit{Due to optimization, the scope of an object may be
-non-contiguous and require use of a range list even when
+non-contiguous and require use of a \addtoindex{range list} even when
 the containing scope is contiguous. Conversely, the scope of
-an object may not require its own range list even when the
+an object may not require its own \addtoindex{range list} even when the
 containing scope is non\dash contiguous.}
 
-\item A \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute, whose value is a constant
+\item A \livelink{chap:DWATendianity}{DW\_AT\_endianity} attribute, 
+whose value 
 \hypertarget{chap:DWATendianityendianityofdata}
-that specifies the endianity of the object. The value of
-this attribute specifies an ABI\dash defined byte ordering for
+is a constant
+\addtoindexx{endianity attribute}
+that 
+\addtoindexx{big-endian encoding|see{endianity attribute}}
+specifies 
+the endianity of the object. The value of
+this attribute specifies an ABI\dash defined 
+byte ordering \addtoindexx{ordering attribute} for
 the value of the object. If omitted, the default endianity
-of data for the given type is assumed.  The set of values
+of data for the given type is assumed.  
+
+The set of values
 and their meaning for this attribute is given in 
-Figure \refersec{fig:endianityattributevalues}.
+Table \ref{tab:endianityattributevalues}.
 
-\begin{figure}[here]
+\begin{table}[here]
+\caption{Endianity attribute values}
+\label{tab:endianityattributevalues}
 \centering
-\begin{tabular}{lp{9cm}}
+\begin{tabular}{l|p{9cm}}
+\hline
 Name&Meaning\\ \hline
-\livetarg{chap:DWENDdefault}{DW\-\_END\-\_default} &  Default endian encoding
-  (equivalent to the absence of a 
-  \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute) \\
-\livetarg{chap:DWENDbig}{DW\-\_END\-\_big} & Big\dash endian encoding \\
-\livetarg{chap:DWENDlittle}{DW\-\_END\-\_little}& Little-endian encoding \\
+\livetarg{chap:DWENDdefault}{DW\_END\_default} &  Default endian encoding
+  (equivalent to the \mbox{absence} of a 
+  \livelink{chap:DWATendianity}{DW\_AT\_endianity} attribute) \\
+\livetarg{chap:DWENDbig}{DW\_END\_big} & Big\dash endian encoding \\
+\livetarg{chap:DWENDlittle}{DW\_END\_little}& Little-endian encoding \\
+\hline
 \end{tabular}
-\caption{Endianity attribute values}
-\label{fig:endianityattributevalues}
-\end{figure}
+\end{table}
 
 
 These represent the default encoding formats as defined by
-the target architectures ABI or processor definition. The
+the target architecture's ABI or processor definition. The
 exact definition of these formats may differ in subtle ways
 for different architectures.
 
 
-\item A \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr} attribute, 
+\item A \livelink{chap:DWATconstexpr}{DW\_AT\_const\_expr} attribute, 
 which 
 \hypertarget{chap:DWATconstexprcompiletimeconstantobject}
-is a \livelink{chap:flag}{flag}, if a
+is a \livelink{chap:classflag}{flag}, if a
 variable entry represents a C++ object declared with the
-\textit{constexpr} specifier. This attributes indicates that the
+\texttt{constexpr} specifier. This attribute indicates that the
 variable can be evaluated as a compile\dash time constant.  
 
 \textit{In C++,
-a variable declared with constexpr is implicitly const. Such a
-variable has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute whose value is a reference
-to a debugging information entry}
+a variable declared with \texttt{constexpr} is implicitly \texttt{const}. Such a
+variable has a \livelink{chap:DWATtype}{DW\_AT\_type} attribute whose value is a 
+\livelink{chap:classreference}{reference}
+to a debugging information entry describing a const qualified type.}
 
-\item A \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute for a 
+\item A \livelink{chap:DWATlinkagename}{DW\_AT\_linkage\_name} attribute for a 
 variable or constant entry as described in 
 Section \refersec{chap:linkagenames}.
 
@@ -239,20 +294,28 @@ Section \refersec{chap:linkagenames}.
 \section{Common Block Entries}
 \label{chap:commonblockentries}
 A Fortran \livetargi{chap:fortrancommonblock}{common}{Fortran!common block} \livetargi{chap:commonblockentry}{block}{common block entry} 
-may be described by a debugging
+may 
+\addtoindexx{Fortran!common block}
+be described by a debugging
 information entry with the 
-tag \livetarg{chap:DWTAGcommonblock}{DW\-\_TAG\-\_common\-\_block}. 
-The
-common \nolink{block} 
-entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value
+tag \livetarg{chap:DWTAGcommonblock}{DW\_TAG\_common\_block}. 
+
+The common \nolink{block} 
+entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute 
+\addtoindexx{name attribute}
+whose value
 is a null-terminated string containing the 
 \livetargi{chap:commonblockreferenceattribute}{common}{common block reference attribute} \nolink{block}
 name as it appears in the source program. It may also have a
-\livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute as described in 
+\livelink{chap:DWATlinkagename}{DW\_AT\_linkage\_name} attribute as described in 
 Section \refersec{chap:linkagenames}. 
 It
-also has a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute whose value describes the
-location of the beginning of the common \nolink{block}. The common
+also has a \livelink{chap:DWATlocation}{DW\_AT\_location} attribute
+\addtoindexx{location attribute}
+whose value describes the
+location of the beginning of the common \nolink{block}. 
+
+The common
 \nolink{block} entry owns debugging information entries describing
 the variables contained within the common \nolink{block}.
 
@@ -265,24 +328,33 @@ as a replacement for the list of names in various contexts.}
 
 A namelist is represented by a debugging information entry
 with the 
-tag \livetarg{chap:DWTAGnamelist}{DW\-\_TAG\-\_namelist}. 
+tag \livetarg{chap:DWTAGnamelist}{DW\_TAG\_namelist}. 
+\addtoindexx{namelist entry}
 If the namelist itself has a
-name, the namelist entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose
-value is a null-terminated string containing the namelist’s
+name, the namelist entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
+\addtoindexx{name attribute}
+whose
+value is a null-terminated string containing the namelist\textquoteright s
 name as it appears in the source program.
 
 Each 
 \hypertarget{chap:DWATnamelistitemnamelistitem}
 name that is part of the namelist is represented
 by a debugging information entry with the tag
-\livetarg{chap:DWTAGnamelistitem}{DW\-\_TAG\-\_namelist\-\_item}. 
+\livetarg{chap:DWTAGnamelistitem}{DW\_TAG\_namelist\_item}. 
 Each such entry is a child of the
-namelist entry, and all of the namelist item entries for a
+namelist entry, and all of the 
+namelist item entries for a
+\addtoindexx{namelist item entry}
 given namelist are ordered as were the list of names they
 correspond to in the source program.
 
-Each namelist item entry contains a \livelink{chap:DWATnamelistitem}{DW\-\_AT\-\_namelist\-\_item}
-attribute whose value is a reference to the debugging
+Each namelist item entry contains a 
+\livelink{chap:DWATnamelistitem}{DW\_AT\_namelist\_item} attribute
+\addtoindexx{namelist item attribute}
+whose 
+\addtoindexx{namelist item entry}
+value is a \livelink{chap:classreference}{reference} to the debugging
 information entry representing the declaration of the item
 whose name appears in the namelist.