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