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