dwarf5/latexdoc/dataobject.tex

   1 \chapter[Data Object and Object List]{Data Object and Object List Entries}
   2 \label{chap:dataobjectandobjectlistentries}
   3
   4 This section presents the debugging information entries that
   5 describe individual data objects: variables, parameters and
   6 constants, and lists of those objects that may be grouped in
   7 a single declaration, such as a
   8 \livelink{chap:commonblockentry}{common block}.
   9
  10 \section{Data Object Entries}
  11 \label{chap:dataobjectentries}
  12 \addtoindexx{data object entries}
  13
  14 Program variables,
  15 \addtoindexx{formal parameter entry}
  16 formal parameters and constants are
  17 represented by debugging information entries with the tags
  18 \DWTAGvariableTARG\addtoindexx{variable entry},
  19 \DWTAGformalparameterTARG\addtoindexx{formal parameter entry} and
  20 \DWTAGconstantTARG\addtoindexx{constant (data) entry},
  21 respectively.
  22
  23 \textit{The tag \DWTAGconstant{} is used for languages that
  24 have true named constants.}
  25
  26 The debugging information entry for a program variable,
  27 formal parameter or constant may have the following attributes:
  28 \begin{enumerate}[1. ]
  29 \item A \DWATname{} attribute,\addtoindexx{name attribute}
  30 whose value is a null-terminated string containing the data object
  31 name.
  32
  33 If a variable entry describes an anonymous object (for example
  34 an \addtoindex{anonymous union}),
  35 the name attribute is omitted or its value consists of a single
  36 zero byte.
  37
  38 \item \hypertarget{chap:DWATexternalexternalvariable}{}
  39 A \DWATexternalDEFN{} attribute,\addtoindexx{external attribute}
  40 which is a \livelink{chap:classflag}{flag}, if the name
  41 of a variable is visible outside of its enclosing compilation
  42 unit.
  43
  44 \textit{The definitions of \addtoindex{C++} static data members
  45 of structures or classes are represented by variable entries
  46 \nolink{flagged} as external. Both file static and local variables
  47 in \addtoindex{C} and \addtoindex{C++} are represented by
  48 non-external variable entries.}
  49
  50 \item A \DWATdeclaration{} attribute,
  51 \addtoindexx{declaration attribute}
  52 which is a \livelink{chap:classflag}{flag} that
  53 indicates whether this entry represents a non-defining
  54 declaration of an object.
  55
  56 \item A \DWATlocation{} attribute,
  57 \addtoindexx{location attribute}
  58 whose value describes the location of a variable or parameter at run-time.
  59
  60 If no location attribute is present in a variable
  61 entry representing the definition of a variable (that is,
  62 \addtoindexx{declaration attribute}
  63 with no
  64 \DWATdeclaration{} attribute),
  65 or if the location attribute is present but has
  66 an empty location description (as described in Section
  67 \refersec{chap:locationdescriptions}),
  68 \addtoindexx{unallocated variable}
  69 the variable is assumed to exist in the source code but not
  70 in the executable program (but see number 10, below).
  71
  72 In a variable entry representing a non-defining declaration
  73 of a variable, the location specified supersedes the location
  74 specified by the defining declaration but only within the
  75 scope of the variable entry; if no location is specified,
  76 then the location specified in the defining declaration
  77 applies.
  78
  79 \textit{This can occur, for example, for a \addtoindex{C}
  80 or \addtoindex{C++} external variable (one that is defined
  81 and allocated in another compilation unit) and whose location
  82 varies in the current unit due to optimization.}
  83
  84 The location of a variable may be further specified with
  85 \addtoindexx{segment attribute!and data segment}
  86 a \DWATsegment{} attribute, if appropriate.
  87
  88 \item A \DWATtype{} attribute describing the type of the variable,
  89 constant or formal parameter.
  90
  91 \item If the variable entry represents the defining declaration
  92 for a C++ static data member of a structure, class or union,
  93 the entry has a \DWATspecification{} attribute, whose value is a
  94 \livelink{chap:classreference}{reference} to the debugging information
  95 entry representing the declaration of this data member. The referenced
  96 entry
  97 \bb
  98 also has the tag \DWTAGvariable{}
  99 \eb
 100 and will be a child of some class, structure or union type entry.
 101
 102 If the variable entry represents a
 103 non-defining declaration, \DWATspecification{} may be used
 104 to reference the defining declaration of the variable. If
 105 no \DWATspecification{} attribute is present, the defining
 106 declaration may be found as a global definition either in the
 107 current compilation unit or in another compilation unit with
 108 the \DWATexternal{} attribute.
 109
 110 Variable entries containing
 111 the \DWATspecification{} attribute do not need to duplicate
 112 information provided by the declaration entry referenced by
 113 the specification attribute. In particular, such variable
 114 entries do not need to contain attributes for the name or
 115 type of the data member whose definition they represent.
 116
 117 \needlines{4}
 118 \item \hypertarget{chap:DWATvariableparameternonconstantparameterflag}{}
 119 A \DWATvariableparameterDEFN{}
 120 attribute\addtoindexx{variable parameter attribute},
 121 which is a \livelink{chap:classflag}{flag},
 122 if a formal parameter entry represents a parameter whose
 123 value in the calling function may be modified by the callee.
 124 The absence of this attribute implies that the parameter\textquoteright s
 125 value in the calling function cannot be modified by the callee.
 126
 127 \item \hypertarget{chap:DWATisoptionaloptionalparameter}{}
 128 A \DWATisoptionalDEFN{} attribute,\addtoindexx{is optional attribute}
 129 which is a \livelink{chap:classflag}{flag}, if a
 130 parameter entry represents an \addtoindex{optional parameter}.
 131
 132 \item \hypertarget{chap:DWATdefaultvaluedefaultvalueofparameter}{}
 133 A \DWATdefaultvalueDEFN{} attribute\addtoindexx{default value attribute}
 134 for \addtoindexx{formal parameter entry!with default value}
 135 a formal parameter entry.
 136 The value of this attribute may be a constant, or a reference to the
 137 debugging information entry for a variable, or a reference to a
 138 debugging information entry containing a DWARF procedure.  If the
 139 attribute form is of class constant, that constant is interpreted as
 140 a value whose type is the same as
 141 the type of the formal parameter. If the attribute
 142 form is of class reference, and the referenced entry is for a
 143 variable, the default value of the parameter is the value of the
 144 referenced variable.  If the reference value is 0, no default value
 145 has been specified.  Otherwise, the attribute represents an implicit
 146 \DWOPcallref{} to the referenced debugging information entry, and
 147 the default value of the parameter is the value returned by that
 148 DWARF procedure, interpreted as a value of the type of the formal
 149 parameter.
 150
 151 \textit{For a constant form there is no way to
 152 express the absence of a default value.}
 153
 154 \item \hypertarget{chap:DWATconstvalueconstantobject}{}
 155 A \DWATconstvalueDEFN{} attribute
 156 \addtoindexx{constant value attribute}
 157 for an entry describing a
 158 variable or formal parameter whose value is constant and not
 159 represented by an object in the address space of the program,
 160 or an entry describing a named constant. (Note that such
 161 an entry does not have a location attribute.) The value of
 162 this attribute may be a string or any of the constant data
 163 or data block forms,
 164 as appropriate for the representation
 165 of the variable's value. The value is the actual constant
 166 value of the variable, represented as it would be on the
 167 target architecture.
 168
 169 \textit{One way in which a formal parameter
 170 with a constant value and no location can arise is for a
 171 formal parameter of an inlined subprogram that corresponds
 172 to a constant actual parameter of a call that is inlined.}
 173
 174 \item \hypertarget{chap:DWATendianityendianityofdata}{}
 175 A \DWATendianityDEFN{} attribute,
 176 \addtoindexx{endianity attribute}
 177 whose value is a constant that
 178 \addtoindexx{big-endian encoding|see{endianity attribute}}
 179 specifies the endianity of the object. The value of
 180 this attribute specifies an ABI-defined
 181 \byteorder{ing} \addtoindexx{ordering attribute} for
 182 the value of the object. If omitted, the default endianity
 183 of data for the given type is assumed.
 184
 185 The set of values
 186 and their meaning for this attribute is given in
 187 Table \ref{tab:endianityattributevalues}.
 188 These represent the default encoding formats as defined by
 189 the target architecture's ABI or processor definition. The
 190 exact definition of these formats may differ in subtle ways
 191 for different architectures.
 192
 193 \begin{table}[ht]
 194 \caption{Endianity attribute values}
 195 \label{tab:endianityattributevalues}
 196 \centering
 197 \begin{tabular}{l|P{9cm}}
 198 \hline
 199 Name&Meaning\\ \hline
 200 \DWENDdefaultTARG{} &  Default endian encoding
 201   (equivalent to the \mbox{absence} of a
 202   \DWATendianity{} attribute) \\
 203 \DWENDbigTARG{} & Big-endian encoding \\
 204 \DWENDlittleTARG& Little-endian encoding \\
 205 \hline
 206 \end{tabular}
 207 \end{table}
 208
 209
 210 \needlines{6}
 211 \item \hypertarget{chap:DWATconstexprcompiletimeconstantobject}{}
 212 A \DWATconstexprDEFN{} attribute,
 213 \addtoindex{constant expression attribute}
 214 which is a \CLASSflag, if a
 215 variable entry represents a \addtoindex{C++} object declared with the
 216 \texttt{constexpr} specifier. This attribute indicates that the
 217 variable can be evaluated as a compile\dash time constant.
 218
 219 \textit{In \addtoindex{C++},
 220 a variable declared with \texttt{constexpr} is implicitly
 221 \texttt{const}. Such a variable has a \DWATtype{} attribute
 222 whose value is a \CLASSreference{} to a debugging information
 223 entry describing a \texttt{const} qualified type.}
 224
 225 \item A \DWATlinkagename{} attribute for a
 226 variable or constant entry as described in
 227 Section \refersec{chap:linkagenames}.
 228
 229 \end{enumerate}
 230
 231 \section{Common Block Entries}
 232 \label{chap:commonblockentries}
 233 A Fortran
 234 \livetargi{chap:fortrancommonblock}{common}{Fortran!common block}
 235 \livetargi{chap:commonblockentry}{block}{common block entry}
 236 may
 237 \addtoindexx{Fortran!common block}
 238 be described by a debugging information entry with the
 239 tag \DWTAGcommonblockTARG.
 240
 241 The common \nolink{block}
 242 entry has a \DWATname{} attribute\addtoindexx{name attribute}
 243 whose value is a null-terminated string containing the
 244 \livetargi{chap:commonblockreferenceattribute}{common block}{common block reference attribute}
 245 name. It may also have a \DWATlinkagename{} attribute as described
 246 in Section \refersec{chap:linkagenames}.
 247
 248 A common block entry also has a \DWATlocation{} attribute
 249 \addtoindexx{location attribute}
 250 whose value describes the
 251 location of the beginning of the common \nolink{block}.
 252
 253 The common
 254 \nolink{block} entry owns debugging information entries describing
 255 the variables contained within the common \nolink{block}.
 256
 257 \textit{\addtoindex{Fortran} allows each declarer of a common block
 258 to independently define its contents; thus, common blocks are not types.}
 259
 260 \needlines{8}
 261 \section{Namelist Entries}
 262 \label{chap:namelistentries}
 263 \textit{At least one language, Fortran 90, has the concept of a
 264 namelist. A namelist is an ordered list of the names of some
 265 set of declared objects. The namelist object itself may be used
 266 as a replacement for the list of names in various contexts.}
 267
 268 A namelist is represented by a debugging information entry
 269 with the tag \DWTAGnamelistTARG.\addtoindexx{namelist entry}
 270 If the namelist itself has a
 271 name, the namelist entry has a \DWATname{} attribute,
 272 \addtoindexx{name attribute}
 273 whose value is a null-terminated
 274 string containing the namelist\textquoteright{}s
 275 name.
 276
 277 Each\hypertarget{chap:DWATnamelistitemnamelistitem}{}
 278 name that is part of the namelist is represented
 279 by a debugging information entry with the tag
 280 \DWTAGnamelistitemTARG.
 281 Each such entry is a child of the
 282 namelist entry, and all of the
 283 namelist item entries for a
 284 \addtoindexx{namelist item entry}
 285 given namelist are ordered as were the list of names they
 286 correspond to in the source program.
 287
 288 Each namelist item entry contains a
 289 \DWATnamelistitemDEFN{} attribute
 290 \addtoindexx{namelist item attribute}
 291 whose
 292 \addtoindexx{namelist item entry}
 293 value is a \livelink{chap:classreference}{reference} to the debugging
 294 information entry representing the declaration of the item
 295 whose name appears in the namelist.
 296
 297