[dwarf-doc.git] / dwarf5 / latexdoc / dataobject.tex

\chapter[Data Object and Object List]{Data Object and Object List Entries}
\label{chap:dataobjectandobjectlistentries}

This section presents the debugging information entries that
describe individual data objects: variables, parameters and
constants, and lists of those objects that may be grouped in
a single declaration, such as a 
\livelink{chap:commonblockentry}{common block}.

\section{Data Object Entries}
\label{chap:dataobjectentries}
\addtoindexx{data object entries}

Program variables, 
\addtoindexx{formal parameter entry}
formal parameters and constants are
represented by debugging information entries with the tags
\DWTAGvariableTARG\addtoindexx{variable entry}, 
\DWTAGformalparameterTARG\addtoindexx{formal parameter entry} and 
\DWTAGconstantTARG\addtoindexx{constant (data) entry},
respectively.

\textit{The tag \DWTAGconstant{} 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 \DWATname{} 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 anonymous object (for example
an \addtoindex{anonymous union}),
the name attribute is omitted or its value consists of a single
zero byte.

\item A \DWATexternal{} attribute, 
\hypertarget{chap:DWATexternalexternalvariable}{}
which 
\addtoindexx{external attribute}
is a \livelink{chap:classflag}{flag}, if the name
of a variable is visible outside of its enclosing compilation
unit.  

\textit{The definitions of \addtoindex{C++} static data members 
of structures or classes are represented by variable entries 
\nolink{flagged} as external. Both file static and local variables 
in \addtoindex{C} and \addtoindex{C++} are represented by 
non-external variable entries.}

\item A \DWATdeclaration{} 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 \DWATlocation{} 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,
\addtoindexx{declaration attribute}
with no 
\DWATdeclaration{} 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).

In a variable entry representing a non-defining declaration 
of a variable, the location specified supersedes the location 
specified by the defining declaration but only within the
scope of the variable entry; if no location is specified, 
then the location specified in the defining declaration 
applies.

\textit{This can occur, for example, for a \addtoindex{C} 
or \addtoindex{C++} external variable (one that is defined 
and allocated in another compilation unit) and whose location 
varies in the current unit due to optimization.}

The location of a variable may be further specified with 
\addtoindexx{segment attribute!and data segment}
a \DWATsegment{} attribute, if appropriate.

\item A \DWATtype{} 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 \DWATspecification{} attribute, whose value is a
\livelink{chap:classreference}{reference} to the debugging information entry representing the
declaration of this data member. The referenced entry has the
tag \DWTAGmember{} and will be a child of some class, structure
or union type entry.

If the variable entry represents a
non-defining declaration, \DWATspecification{} may be used
to reference the defining declaration of the variable. If
no \DWATspecification{} 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 \DWATexternal{} attribute.  

Variable entries containing
the \DWATspecification{} 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
type of the data member whose definition they 
% Getting the link target in a good spot is tricky. So putting
%this one a little early.
\hypertarget{chap:DWATvariableparameternonconstantparameterflag}{}
represent.

\needlines{4}
\item A \DWATvariableparameter{}
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 parameter\textquoteright s
value in the calling function cannot be modified by the callee.

\item A \DWATisoptional{} attribute, 
\hypertarget{chap:DWATisoptionaloptionalparameter}{}
which 
\addtoindexx{is optional attribute}
is a \livelink{chap:classflag}{flag}, if a
parameter entry represents an \addtoindex{optional parameter}.

\item A \DWATdefaultvalue{} 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 may be a constant, or a reference to the
debugging information entry for a variable, or a reference to a
debugging information entry containing a DWARF procedure.  If the
attribute form is of class constant, that constant is interpreted as
a default value of the type of the formal parameter. If the attribute
form is of class reference, and the referenced entry is for a
variable, the default value of the parameter is the value of the
referenced variable.  If the reference value is 0, no default value
has been specified.  Otherwise, the attribute represents an implicit
\DWOPcallref{} to the referenced debugging information entry, and
the default value of the parameter is the value returned by that
DWARF procedure, interpreted as a 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 \DWATconstvalue{} attribute 
for 
\hypertarget{chap:DWATconstvalueconstantobject}{}
an entry describing a
variable or formal parameter whose value is constant and not
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 block forms, 
as appropriate for the representation
of the variable's value. The value is the actual constant
value of the variable, represented as it would be on the
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 \DWATstartscope{} 
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) ]
\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
object is specified using a value of class constant. If the
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 \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 \addtoindex{range list} entry
that is not a base selection entry, a default 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:classrangelistptr}{rangelistptr}. 
This value indicates the
beginning of a \addtoindex{range list}
(see \ref{chap:noncontiguousaddressranges}).
\end{enumerate}


\textit{The scope of a variable may begin somewhere in the middle of
a lexical \livelink{chap:lexicalblock}{block} in a language 
that allows executable code in a
\nolink{block} before a variable declaration, or where one declaration
containing initialization code may change the scope of a
subsequent declaration.  For example, in the following \addtoindex{C} code:}

\begin{lstlisting}
float x = 99.99;
int myfunc()
{
    float f = x;
    float x = 88.99;
    return 0;
}
\end{lstlisting}

\textit{\addtoindex{C} scoping rules require that the value of the variable x
assigned to the variable f in the initialization sequence is
the value of the global variable x, rather than the local x,
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 \addtoindex{range list} even when
the containing scope is contiguous. Conversely, the scope of
an object may not require its own \addtoindex{range list} even when the
containing scope is non\dash contiguous.}

\item A \DWATendianity{} attribute, 
whose value 
\hypertarget{chap:DWATendianityendianityofdata}{}
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
and their meaning for this attribute is given in 
Table \ref{tab:endianityattributevalues}.

\begin{table}[here]
\caption{Endianity attribute values}
\label{tab:endianityattributevalues}
\centering
\begin{tabular}{l|p{9cm}}
\hline
Name&Meaning\\ \hline
\DWENDdefaultTARG{} &  Default endian encoding
  (equivalent to the \mbox{absence} of a 
  \DWATendianity{} attribute) \\
\DWENDbigTARG{} & Big\dash endian encoding \\
\DWENDlittleTARG& Little-endian encoding \\
\hline
\end{tabular}
\end{table}


These represent the default encoding formats as defined by
the target architecture's ABI or processor definition. The
exact definition of these formats may differ in subtle ways
for different architectures.

\needlines{6}
\item A \DWATconstexpr{} attribute, 
which 
\hypertarget{chap:DWATconstexprcompiletimeconstantobject}{}
is a \CLASSflag, if a
variable entry represents a \addtoindex{C++} object declared with the
\texttt{constexpr} specifier. This attribute indicates that the
variable can be evaluated as a compile\dash time constant.  

\textit{In \addtoindex{C++},
a variable declared with \texttt{constexpr} is implicitly 
\texttt{const}. Such a variable has a \DWATtype{} attribute 
whose value is a \CLASSreference{} to a debugging information 
entry describing a \texttt{const} qualified type.}

\item A \DWATlinkagename{} attribute for a 
variable or constant entry as described in 
Section \refersec{chap:linkagenames}.

\end{enumerate}

\section{Common Block Entries}
\label{chap:commonblockentries}
A Fortran 
\livetargi{chap:fortrancommonblock}{common}{Fortran!common block}
\livetargi{chap:commonblockentry}{block}{common block entry} 
may 
\addtoindexx{Fortran!common block}
be described by a debugging information entry with the 
tag \DWTAGcommonblockTARG. 

The common \nolink{block} 
entry has a \DWATname{} attribute 
\addtoindexx{name attribute}
whose value is a null-terminated
string containing the
\livetargi{chap:commonblockreferenceattribute}{common \nolink{block}}{common block reference attribute} 
name as it appears in the source program. It may also have a
\DWATlinkagename{} attribute as described in 
Section \refersec{chap:linkagenames}. 

A common block entry also has a \DWATlocation{} 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}.

\textit{\addtoindex{Fortran} allows each declarer of a common block 
to independently define its contents; thus, common blocks are not types.}

\needlines{8}
\section{Namelist Entries}
\label{chap:namelistentries}
\textit{At least one language, Fortran 90, has the concept of a
namelist. A namelist is an ordered list of the names of some
set of declared objects. The namelist object itself may be used
as a replacement for the list of names in various contexts.}

A namelist is represented by a debugging information entry
with the 
tag \DWTAGnamelistTARG. 
\addtoindexx{namelist entry}
If the namelist itself has a
name, the namelist entry has a \DWATname{} 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
\DWTAGnamelistitemTARG. 
Each such entry is a child of the
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 
\DWATnamelistitem{} 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.