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,
  30 \addtoindexx{name attribute}
  31 whose value is a null-terminated string containing the data object
  32 name as it appears in the source program.
  33
  34 If a variable entry describes an anonymous object (for example
  35 an \addtoindex{anonymous union}),
  36 the name attribute is omitted or its value consists of a single
  37 zero byte.
  38
  39 \item A \DWATexternalDEFN{} attribute,
  40 \hypertarget{chap:DWATexternalexternalvariable}{}
  41 which
  42 \addtoindexx{external attribute}
  43 is a \livelink{chap:classflag}{flag}, if the name
  44 of a variable is visible outside of its enclosing compilation
  45 unit.
  46
  47 \textit{The definitions of \addtoindex{C++} static data members
  48 of structures or classes are represented by variable entries
  49 \nolink{flagged} as external. Both file static and local variables
  50 in \addtoindex{C} and \addtoindex{C++} are represented by
  51 non-external variable entries.}
  52
  53 \item A \DWATdeclaration{} attribute,
  54 \addtoindexx{declaration attribute}
  55 which is a \livelink{chap:classflag}{flag} that
  56 indicates whether this entry represents a non-defining
  57 declaration of an object.
  58
  59 \item A \DWATlocation{} attribute,
  60 \addtoindexx{location attribute}
  61 whose value describes the location of a variable or parameter at run-time.
  62
  63 If no location attribute is present in a variable
  64 entry representing the definition of a variable (that is,
  65 \addtoindexx{declaration attribute}
  66 with no
  67 \DWATdeclaration{} attribute),
  68 or if the location attribute is present but has
  69 an empty location description (as described in Section
  70 \refersec{chap:locationdescriptions}),
  71 \addtoindexx{unallocated variable}
  72 the variable is assumed to exist in the source code but not
  73 in the executable program (but see number 10, below).
  74
  75 In a variable entry representing a non-defining declaration
  76 of a variable, the location specified supersedes the location
  77 specified by the defining declaration but only within the
  78 scope of the variable entry; if no location is specified,
  79 then the location specified in the defining declaration
  80 applies.
  81
  82 \textit{This can occur, for example, for a \addtoindex{C}
  83 or \addtoindex{C++} external variable (one that is defined
  84 and allocated in another compilation unit) and whose location
  85 varies in the current unit due to optimization.}
  86
  87 The location of a variable may be further specified with
  88 \addtoindexx{segment attribute!and data segment}
  89 a \DWATsegment{} attribute, if appropriate.
  90
  91 \item A \DWATtype{} attribute describing the type of the variable,
  92 constant or formal parameter.
  93
  94 \item If the variable entry represents the defining declaration
  95 for a C++ static data member of a structure, class or union,
  96 the entry has a \DWATspecification{} attribute, whose value is a
  97 \livelink{chap:classreference}{reference} to the debugging information entry representing the
  98 declaration of this data member. The referenced entry has the
  99 tag \DWTAGmember{} and will be a child of some class, structure
 100 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
 116 % Getting the link target in a good spot is tricky. So putting
 117 %this one a little early.
 118 \hypertarget{chap:DWATvariableparameternonconstantparameterflag}{}
 119 represent.
 120
 121 \needlines{4}
 122 \item A \DWATvariableparameterDEFN{}
 123 attribute\addtoindexx{variable parameter attribute},
 124 which is a \livelink{chap:classflag}{flag},
 125 if a formal parameter entry represents a parameter whose
 126 value in the calling function may be modified by the callee.
 127 The absence of this attribute implies that the parameter\textquoteright s
 128 value in the calling function cannot be modified by the callee.
 129
 130 \item A \DWATisoptionalDEFN{} attribute,
 131 \hypertarget{chap:DWATisoptionaloptionalparameter}{}
 132 which
 133 \addtoindexx{is optional attribute}
 134 is a \livelink{chap:classflag}{flag}, if a
 135 parameter entry represents an \addtoindex{optional parameter}.
 136
 137 \item A \DWATdefaultvalueDEFN{} attribute
 138 \addtoindexx{default value attribute}
 139 for
 140 \addtoindexx{formal parameter entry!with default value}
 141 a formal parameter
 142 \hypertarget{chap:DWATdefaultvaluedefaultvalueofparameter}{}
 143 entry. The value of this attribute may be a constant, or a reference to the
 144 debugging information entry for a variable, or a reference to a
 145 debugging information entry containing a DWARF procedure.  If the
 146 attribute form is of class constant, that constant is interpreted as
 147 a default value of the type of the formal parameter. If the attribute
 148 form is of class reference, and the referenced entry is for a
 149 variable, the default value of the parameter is the value of the
 150 referenced variable.  If the reference value is 0, no default value
 151 has been specified.  Otherwise, the attribute represents an implicit
 152 \DWOPcallref{} to the referenced debugging information entry, and
 153 the default value of the parameter is the value returned by that
 154 DWARF procedure, interpreted as a value of the type of the formal
 155 parameter.
 156
 157 \textit{For a constant form there is no way to
 158 express the absence of a default value.}
 159
 160 \item A \DWATconstvalueDEFN{} attribute
 161 \addtoindexx{constant value attribute}
 162 \hypertarget{chap:DWATconstvalueconstantobject}{}
 163 for an entry describing a
 164 variable or formal parameter whose value is constant and not
 165 represented by an object in the address space of the program,
 166 or an entry describing a named constant. (Note that such
 167 an entry does not have a location attribute.) The value of
 168 this attribute may be a string or any of the constant data
 169 or data block forms,
 170 as appropriate for the representation
 171 of the variable's value. The value is the actual constant
 172 value of the variable, represented as it would be on the
 173 target architecture.
 174
 175 \textit{One way in which a formal parameter
 176 with a constant value and no location can arise is for a
 177 formal parameter of an inlined subprogram that corresponds
 178 to a constant actual parameter of a call that is inlined.
 179 }
 180
 181 \item A \DWATstartscopeDEFN{}\addtoindexx{start scope attribute}
 182 \hypertarget{chap:DWATstartscopeobjectdeclaration}{}
 183 attribute if the address range for the scope of an
 184 object is a subset of the address range for the
 185 the lexical scope most closely enclosing the object.
 186 There are two cases:
 187 \begin{enumerate}[a) ]
 188 \item If address range for the scope of the object entry
 189 includes all of addresses for the containing scope except
 190 for a contiguous sequence of bytes at the beginning of the
 191 address range for the containing scope, then the address is
 192 specified using a value of class constant. If the address
 193 range for the containing scope is contiguous, the value of
 194 this attribute is the offset in bytes of the beginning of
 195 the address range for the scope of the object from the low
 196 PC value of the debugging information entry that defines
 197 that containing scope. If the address range of the containing
 198 scope is non-contiguous
 199 (see \refersec{chap:noncontiguousaddressranges})
 200 the value of this attribute is the offset in bytes of the
 201 beginning of the address range for the scope of the object
 202 from the beginning of the first \addtoindex{range list} entry
 203 for the containing scope that is not a base selection entry,
 204 a default selection entry or an end-of-list entry.
 205
 206 \needlines{4}
 207 \item Otherwise, the set of addresses for the scope of the
 208 object is specified using a value of class \CLASSrangelistptr{}.
 209 This value indicates the beginning of a \addtoindex{range list}
 210 (see \ref{chap:noncontiguousaddressranges}).
 211 \end{enumerate}
 212
 213
 214 \textit{The scope of a variable may begin somewhere in the middle of
 215 a lexical \livelink{chap:lexicalblock}{block} in a language
 216 that allows executable code in a
 217 \nolink{block} before a variable declaration, or where one declaration
 218 containing initialization code may change the scope of a
 219 subsequent declaration.  For example, in the following \addtoindex{C} code:}
 220
 221 \begin{lstlisting}
 222 float x = 99.99;
 223 int myfunc()
 224 {
 225     float f = x;
 226     float x = 88.99;
 227     return 0;
 228 }
 229 \end{lstlisting}
 230
 231 \textit{\addtoindex{C} scoping rules require that the value of the variable x
 232 assigned to the variable f in the initialization sequence is
 233 the value of the global variable x, rather than the local x,
 234 because the scope of the local variable x only starts after
 235 the full declarator for the local x.}
 236
 237 \textit{Due to optimization, the scope of an object may be
 238 non-contiguous and require use of a \addtoindex{range list} even when
 239 the containing scope is contiguous. Conversely, the scope of
 240 an object may not require its own \addtoindex{range list} even when the
 241 containing scope is non\dash contiguous.}
 242
 243 \item A \DWATendianityDEFN{} attribute,
 244 \addtoindexx{endianity attribute}
 245 \hypertarget{chap:DWATendianityendianityofdata}{}
 246 whose value is a constant that
 247 \addtoindexx{big-endian encoding|see{endianity attribute}}
 248 specifies the endianity of the object. The value of
 249 this attribute specifies an ABI-defined
 250 \byteorder{ing} \addtoindexx{ordering attribute} for
 251 the value of the object. If omitted, the default endianity
 252 of data for the given type is assumed.
 253
 254 The set of values
 255 and their meaning for this attribute is given in
 256 Table \ref{tab:endianityattributevalues}.
 257
 258 \begin{table}[h]
 259 \caption{Endianity attribute values}
 260 \label{tab:endianityattributevalues}
 261 \centering
 262 \begin{tabular}{l|P{9cm}}
 263 \hline
 264 Name&Meaning\\ \hline
 265 \DWENDdefaultTARG{} &  Default endian encoding
 266   (equivalent to the \mbox{absence} of a
 267   \DWATendianity{} attribute) \\
 268 \DWENDbigTARG{} & Big\dash endian encoding \\
 269 \DWENDlittleTARG& Little-endian encoding \\
 270 \hline
 271 \end{tabular}
 272 \end{table}
 273
 274
 275 These represent the default encoding formats as defined by
 276 the target architecture's ABI or processor definition. The
 277 exact definition of these formats may differ in subtle ways
 278 for different architectures.
 279
 280 \needlines{6}
 281 \item A \DWATconstexprDEFN{} attribute,
 282 \addtoindex{constant expression attribute}
 283 \hypertarget{chap:DWATconstexprcompiletimeconstantobject}{}
 284 which is a \CLASSflag, if a
 285 variable entry represents a \addtoindex{C++} object declared with the
 286 \texttt{constexpr} specifier. This attribute indicates that the
 287 variable can be evaluated as a compile\dash time constant.
 288
 289 \textit{In \addtoindex{C++},
 290 a variable declared with \texttt{constexpr} is implicitly
 291 \texttt{const}. Such a variable has a \DWATtype{} attribute
 292 whose value is a \CLASSreference{} to a debugging information
 293 entry describing a \texttt{const} qualified type.}
 294
 295 \item A \DWATlinkagename{} attribute for a
 296 variable or constant entry as described in
 297 Section \refersec{chap:linkagenames}.
 298
 299 \end{enumerate}
 300
 301 \section{Common Block Entries}
 302 \label{chap:commonblockentries}
 303 A Fortran
 304 \livetargi{chap:fortrancommonblock}{common}{Fortran!common block}
 305 \livetargi{chap:commonblockentry}{block}{common block entry}
 306 may
 307 \addtoindexx{Fortran!common block}
 308 be described by a debugging information entry with the
 309 tag \DWTAGcommonblockTARG.
 310
 311 The common \nolink{block}
 312 entry has a \DWATname{} attribute
 313 \addtoindexx{name attribute}
 314 whose value is a null-terminated
 315 string containing the
 316 \livetargi{chap:commonblockreferenceattribute}{common block}{common block reference attribute}
 317 name as it appears in the source program. It may also have a
 318 \DWATlinkagename{} attribute as described in
 319 Section \refersec{chap:linkagenames}.
 320
 321 A common block entry also has a \DWATlocation{} attribute
 322 \addtoindexx{location attribute}
 323 whose value describes the
 324 location of the beginning of the common \nolink{block}.
 325
 326 The common
 327 \nolink{block} entry owns debugging information entries describing
 328 the variables contained within the common \nolink{block}.
 329
 330 \textit{\addtoindex{Fortran} allows each declarer of a common block
 331 to independently define its contents; thus, common blocks are not types.}
 332
 333 \needlines{8}
 334 \section{Namelist Entries}
 335 \label{chap:namelistentries}
 336 \textit{At least one language, Fortran 90, has the concept of a
 337 namelist. A namelist is an ordered list of the names of some
 338 set of declared objects. The namelist object itself may be used
 339 as a replacement for the list of names in various contexts.}
 340
 341 A namelist is represented by a debugging information entry
 342 with the
 343 tag \DWTAGnamelistTARG.
 344 \addtoindexx{namelist entry}
 345 If the namelist itself has a
 346 name, the namelist entry has a \DWATname{} attribute,
 347 \addtoindexx{name attribute}
 348 whose value is a null-terminated
 349 string containing the namelist\textquoteright{}s
 350 name as it appears in the source program.
 351
 352 Each
 353 \hypertarget{chap:DWATnamelistitemnamelistitem}{}
 354 name that is part of the namelist is represented
 355 by a debugging information entry with the tag
 356 \DWTAGnamelistitemTARG.
 357 Each such entry is a child of the
 358 namelist entry, and all of the
 359 namelist item entries for a
 360 \addtoindexx{namelist item entry}
 361 given namelist are ordered as were the list of names they
 362 correspond to in the source program.
 363
 364 Each namelist item entry contains a
 365 \DWATnamelistitemDEFN{} attribute
 366 \addtoindexx{namelist item attribute}
 367 whose
 368 \addtoindexx{namelist item entry}
 369 value is a \livelink{chap:classreference}{reference} to the debugging
 370 information entry representing the declaration of the item
 371 whose name appears in the namelist.
 372
 373