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