8f393dd1312825b404f6d86f4216a3db700e38cc
[dwarf-doc.git] / 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 
8 a common \livelink{chap:commonblockentry}{block}.
9
10 \section{Data Object Entries}
11 \label{chap:dataobjectentries}
12 \addtoindexx{data object entries}
13
14 Program variables, formal parameters and constants are
15 represented by debugging information entries with the tags
16 \livetarg{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}\addtoindexx{variable entry}, 
17 \livetarg{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}\addtoindexx{formal parameter entry} and 
18 \livetarg{chap:DWTAGconstant}{DW\-\_TAG\-\_constant}\addtoindexx{constant (data) entry},
19 respectively.
20
21 \textit{The tag \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant} is used for languages that
22 have true named constants.}
23
24 The debugging information entry for a program variable,
25 formal parameter or constant may have the following attributes:
26 \begin{enumerate}[1.]
27 \item A \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is a null-terminated
28 string, containing the data object name as it appears in the
29 source program.  If a variable entry describes 
30 an 
31 \addtoindex{anonymous union},
32 the name attribute is omitted or consists of a single
33 zero byte.
34
35 \item A \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute, 
36 \hypertarget{chap:DWATexternalexternalvariable}
37 which 
38 \addtoindexx{external attribute}
39 is a \livelink{chap:flag}{flag}, if the name
40 of a variable is visible outside of its enclosing compilation
41 unit.  The definitions of C++ static data members of structures
42 or classes are represented by variable entries \nolink{flagged} as
43 external. Both file static and local variables in C and C++
44 are represented by non-external variable entries.
45
46 \item A \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute, 
47 \addtoindexx{declaration attribute}
48 which is a \livelink{chap:flag}{flag} that
49 indicates whether this entry represents a non-defining
50 declaration of an object.
51
52 \item A \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute, whose value describes the
53 location of a variable or parameter at run-time.  In a variable
54 entry representing the definition of a variable (that is,
55 \addtoindexx{declaration attribute}
56 with no 
57 \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute) 
58 if no location attribute
59 is present, or if the location attribute is present but has
60 an empty location description (as described in Section 2.6),
61 the variable is assumed to exist in the source code but not
62 in the executable program (but see number 10, below).
63
64 In a variable entry representing a non-defining declaration of a variable, the location
65 specified modifies the location specified by the defining declaration and only applies for the
66 scope of the variable entry; if no location is specified, then the location specified in the
67 defining declaration applies.
68 The location of a variable may be further specified with a \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, if
69 appropriate.
70
71 \item A \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute describing the type of the variable,
72 constant or formal parameter.
73
74 \item If the variable entry represents the defining declaration
75 for a C++ static data member of a structure, class or union,
76 the entry has a \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute, whose value is a
77 reference to the debugging information entry representing the
78 declaration of this data member. The referenced entry has the
79 tag \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} and will be a child of some class, structure
80 or union type entry.  If the variable entry represents a
81 non-defining declaration, \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} may be used
82 to reference the defining declaration of the variable. If
83 no \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute is present, the defining
84 declaration may be found as a global definition either in the
85 current compilation unit or in another compilation unit with
86 the \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute.  Variable entries containing
87 the \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute do not need to duplicate
88 information provided by the declaration entry referenced by
89 the specification attribute. In particular, such variable
90 entries do not need to contain attributes for the name or
91 type of the data member whose definition they 
92 % Getting the link target in a good spot is tricky. So putting
93 %this one a little early.
94 \hypertarget{chap:DWATvariableparameternonconstantparameterflag}
95 represent.
96
97 \item A \livelink{chap:DWATvariableparameter}{DW\-\_AT\-\_variable\-\_parameter}
98 attribute\addtoindexx{variable parameter attribute}, 
99 which is a \livelink{chap:flag}{flag},
100 if a formal parameter entry represents a parameter whose
101 value in the calling function may be modified by the callee..
102 The absence of this attribute implies that the parameter’s
103 value in the calling function cannot be modified by the callee.
104
105 \item A \livelink{chap:DWATisoptional}{DW\-\_AT\-\_is\-\_optional} attribute, 
106 \hypertarget{chap:DWATisoptionaloptionalparameter}
107 which is a \livelink{chap:flag}{flag}, if a
108 parameter entry represents an optional parameter.
109
110 \item A \livelink{chap:DWATdefaultvalue}{DW\-\_AT\-\_default\-\_value} attribute 
111 \addtoindexx{default value attribute}
112 for a formal parameter
113 \hypertarget{chap:DWATdefaultvaluedefaultvalueofparameter}
114 entry. The value of this attribute is a reference to the
115 debugging information entry for a variable or subroutine,
116 or the value may be a constant. If the attribute form is of
117 class reference, the default value of the parameter is the
118 value of the referenced variable (which may be constant) or
119 the value returned by the referenced subroutine; a reference
120 value of 0 means that no default value has been specified.
121 If the value is of class constant, that constant is interpreted
122 as a default value of the type of the formal parameter.
123
124 \textit{For a constant form there is no way to 
125 express the absence of a default value.}
126
127 \item A \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute 
128 for 
129 \hypertarget{chap:DWATconstvalueconstantobject}
130 an entry describing a
131 variable or formal parameter whose value is constant and not
132 represented by an object in the address space of the program,
133 or an entry describing a named constant. (Note that such
134 an entry does not have a location attribute.) The value of
135 this attribute may be a string or any of the constant data
136 or data \livelink{chap:block}{block} forms, 
137 as appropriate for the representation
138 of the variable’s value. The value is the actual constant
139 value of the variable, represented as it would be on the
140 target architecture.  One way in which a formal parameter
141 with a constant value and no location can arise is for a
142 formal parameter of an inlined subprogram that corresponds
143 to a constant actual parameter of a call that is inlined.
144
145 \item A \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute if the scope of an
146 \hypertarget{chap:DWATstartscopeobjectdeclaration}
147 object is smaller than (that is, is a subset of the addresses
148 of) the scope most closely enclosing the object. There are
149 two cases:
150 \begin{enumerate}[a)]
151 \item If the scope of the object entry includes all of the
152 containing scope except for a contiguous sequence of bytes at
153 the beginning of that containing scope, then the scope of the
154 object is specified using a value of class constant. If the
155 containing scope is contiguous, the value of this attribute
156 is the offset in bytes of the beginning of the scope for the
157 object from the low pc value of the debugging information
158 entry that defines its scope. If the containing scope
159 is non-contiguous 
160 (see \refersec{chap:noncontiguousaddressranges})
161 the value of this
162 attribute is the offset in bytes of the beginning of the scope
163 for the object from the beginning of the first range list entry
164 that is not a base selection entry or an end of list entry.
165
166 \item Otherwise, the scope of the object is specified using
167 a value of class \livelink{chap:rangelistptr}{rangelistptr}. This value indicates the
168 beginning of a range list
169 (see \refersec{chap:noncontiguousaddressranges}).
170 \end{enumerate}
171
172
173 \textit{The scope of a variable may begin somewhere in the middle of
174 a lexical \livelink{chap:lexicalblock}{block} in a language 
175 that allows executable code in a
176 \nolink{block} before a variable declaration, or where one declaration
177 containing initialization code may change the scope of a
178 subsequent declaration.  For example, in the following C code:}
179
180 \begin{lstlisting}
181 float x = 99.99;
182 int myfunc()
183 {
184     float f = x;
185     float x = 88.99;
186     return 0;
187 }
188 \end{lstlisting}
189
190 \textit{C scoping rules require that the value of the variable x
191 assigned to the variable f in the initialization sequence is
192 the value of the global variable x, rather than the local x,
193 because the scope of the local variable x only starts after
194 the full declarator for the local x.}
195
196 \textit{Due to optimization, the scope of an object may be
197 non-contiguous and require use of a range list even when
198 the containing scope is contiguous. Conversely, the scope of
199 an object may not require its own range list even when the
200 containing scope is non\dash contiguous.}
201
202 \item A \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute, 
203 whose value 
204 \hypertarget{chap:DWATendianityendianityofdata}
205 is a constant
206 \addtoindexx{endianity attribute}
207 that 
208 \addtoindexx{big-endian encoding|see{endianity attribute}}
209 specifies 
210 the endianity of the object. The value of
211 this attribute specifies an ABI\dash defined byte ordering for
212 the value of the object. If omitted, the default endianity
213 of data for the given type is assumed.  The set of values
214 and their meaning for this attribute is given in 
215 Figure \refersec{fig:endianityattributevalues}.
216
217 \begin{figure}[here]
218 \centering
219 \begin{tabular}{lp{9cm}}
220 Name&Meaning\\ \hline
221 \livetarg{chap:DWENDdefault}{DW\-\_END\-\_default} &  Default endian encoding
222   (equivalent to the absence of a 
223   \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute) \\
224 \livetarg{chap:DWENDbig}{DW\-\_END\-\_big} & Big\dash endian encoding \\
225 \livetarg{chap:DWENDlittle}{DW\-\_END\-\_little}& Little-endian encoding \\
226 \end{tabular}
227 \caption{Endianity attribute values}
228 \label{fig:endianityattributevalues}
229 \end{figure}
230
231
232 These represent the default encoding formats as defined by
233 the target architecture’s ABI or processor definition. The
234 exact definition of these formats may differ in subtle ways
235 for different architectures.
236
237
238 \item A \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr} attribute, 
239 which 
240 \hypertarget{chap:DWATconstexprcompiletimeconstantobject}
241 is a \livelink{chap:flag}{flag}, if a
242 variable entry represents a C++ object declared with the
243 \textit{constexpr} specifier. This attributes indicates that the
244 variable can be evaluated as a compile\dash time constant.  
245
246 \textit{In C++,
247 a variable declared with constexpr is implicitly const. Such a
248 variable has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute whose value is a reference
249 to a debugging information entry}
250
251 \item A \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute for a 
252 variable or constant entry as described in 
253 Section \refersec{chap:linkagenames}.
254
255 \end{enumerate}
256
257 \section{Common Block Entries}
258 \label{chap:commonblockentries}
259 A Fortran \livetargi{chap:fortrancommonblock}{common}{Fortran!common block} \livetargi{chap:commonblockentry}{block}{common block entry} 
260 may be described by a debugging
261 information entry with the 
262 tag \livetarg{chap:DWTAGcommonblock}{DW\-\_TAG\-\_common\-\_block}. 
263 The
264 common \nolink{block} 
265 entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value
266 is a null-terminated string containing the 
267 \livetargi{chap:commonblockreferenceattribute}{common}{common block reference attribute} \nolink{block}
268 name as it appears in the source program. It may also have a
269 \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute as described in 
270 Section \refersec{chap:linkagenames}. 
271 It
272 also has a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute whose value describes the
273 location of the beginning of the common \nolink{block}. The common
274 \nolink{block} entry owns debugging information entries describing
275 the variables contained within the common \nolink{block}.
276
277 \section{Namelist Entries}
278 \label{chap:namelistentries}
279 \textit{At least one language, Fortran 90, has the concept of a
280 namelist. A namelist is an ordered list of the names of some
281 set of declared objects. The namelist object itself may be used
282 as a replacement for the list of names in various contexts.}
283
284 A namelist is represented by a debugging information entry
285 with the 
286 tag \livetarg{chap:DWTAGnamelist}{DW\-\_TAG\-\_namelist}. 
287 If the namelist itself has a
288 name, the namelist entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose
289 value is a null-terminated string containing the namelist’s
290 name as it appears in the source program.
291
292 Each 
293 \hypertarget{chap:DWATnamelistitemnamelistitem}
294 name that is part of the namelist is represented
295 by a debugging information entry with the tag
296 \livetarg{chap:DWTAGnamelistitem}{DW\-\_TAG\-\_namelist\-\_item}. 
297 Each such entry is a child of the
298 namelist entry, and all of the namelist item entries for a
299 given namelist are ordered as were the list of names they
300 correspond to in the source program.
301
302 Each namelist item entry contains a \livelink{chap:DWATnamelistitem}{DW\-\_AT\-\_namelist\-\_item}
303 attribute whose value is a reference to the debugging
304 information entry representing the declaration of the item
305 whose name appears in the namelist.
306
307