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