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