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