More changes from Committee review. This checkin corresponds to
[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 as it appears in the source program.
33
34 If a variable entry describes an 
35 \addtoindex{anonymous union},
36 the name attribute is omitted or its value describes a single
37 zero byte.
38
39 \item A \DWATexternal{} attribute, 
40 \hypertarget{chap:DWATexternalexternalvariable}{}
41 which 
42 \addtoindexx{external attribute}
43 is a \livelink{chap:classflag}{flag}, if the name
44 of a variable is visible outside of its enclosing compilation
45 unit.  
46
47 \textit{The definitions of \addtoindex{C++} static data members of structures
48 or classes are represented by variable entries \nolink{flagged} as
49 external. Both file static and local variables in \addtoindex{C} and \addtoindex{C++}
50 are represented by non-external variable entries.
51 }
52
53 \item A \DWATdeclaration{} attribute, 
54 \addtoindexx{declaration attribute}
55 which is a \livelink{chap:classflag}{flag} that
56 indicates whether this entry represents a non-defining
57 declaration of an object.
58
59 \item A \DWATlocation{} attribute,
60 \addtoindexx{location attribute}
61 whose value describes the location of a variable or parameter at run-time.
62
63 If no location attribute is present in a variable 
64 entry representing the definition of a variable (that is,
65 \addtoindexx{declaration attribute}
66 with no 
67 \DWATdeclaration{} attribute),
68 or if the location attribute is present but has
69 an empty location description (as described in Section \refersec{chap:locationdescriptions}),
70 \addtoindexx{unallocated variable}
71 the variable is assumed to exist in the source code but not
72 in the executable program (but see number 10, below).
73
74 In a variable entry representing a non-defining declaration of a variable, the location
75 specified modifies the location specified by the defining declaration and only applies for the
76 scope of the variable entry; if no location is specified, then the location specified in the
77 defining declaration applies.
78
79 \textit{This can occur, for example, for a \addtoindex{C} or \addtoindex{C++}
80 external variable (one that is defined and allocated in another compilation unit) 
81 and whose location varies in the current unit due to optimization.}
82
83 The location of a variable may be further specified with 
84 \addtoindexx{segment attribute!and data segment}
85
86 \DWATsegment{} attribute, if
87 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 
114 % Getting the link target in a good spot is tricky. So putting
115 %this one a little early.
116 \hypertarget{chap:DWATvariableparameternonconstantparameterflag}{}
117 represent.
118
119 \needlines{4}
120 \item A \DWATvariableparameter{}
121 attribute\addtoindexx{variable parameter attribute}, 
122 which is a \livelink{chap:classflag}{flag},
123 if a formal parameter entry represents a parameter whose
124 value in the calling function may be modified by the callee.
125 The absence of this attribute implies that the parameter\textquoteright s
126 value in the calling function cannot be modified by the callee.
127
128 \item A \DWATisoptional{} attribute, 
129 \hypertarget{chap:DWATisoptionaloptionalparameter}{}
130 which 
131 \addtoindexx{is optional attribute}
132 is a \livelink{chap:classflag}{flag}, if a
133 parameter entry represents an \addtoindex{optional parameter}.
134
135 \item A \DWATdefaultvalue{} attribute 
136 \addtoindexx{default value attribute}
137 for 
138 \addtoindexx{formal parameter entry!with default value}
139 a formal parameter
140 \hypertarget{chap:DWATdefaultvaluedefaultvalueofparameter}{}
141 entry. The value of this attribute may be a constant, or a reference to the
142 debugging information entry for a variable, or a reference to a
143 debugging information entry containing a DWARF procedure.  If the
144 attribute form is of class constant, that constant is interpreted as
145 a default value of the type of the formal parameter. If the attribute
146 form is of class reference, and the referenced entry is for a
147 variable, the default value of the parameter is the value of the
148 referenced variable.  If the reference value is 0, no default value
149 has been specified.  Otherwise, the attribute represents an implicit
150 \DWOPcallref{} to the referenced debugging information entry, and
151 the default value of the parameter is the value returned by that
152 DWARF procedure, interpreted as a value of the type of the formal
153 parameter.
154
155 \textit{For a constant form there is no way to 
156 express the absence of a default value.}
157
158 \item A \DWATconstvalue{} attribute 
159 for 
160 \hypertarget{chap:DWATconstvalueconstantobject}{}
161 an entry describing a
162 variable or formal parameter whose value is constant and not
163 represented by an object in the address space of the program,
164 or an entry describing a named constant. (Note that such
165 an entry does not have a location attribute.) The value of
166 this attribute may be a string or any of the constant data
167 or data block forms, 
168 as appropriate for the representation
169 of the variable's value. The value is the actual constant
170 value of the variable, represented as it would be on the
171 target architecture.  
172
173 \textit{One way in which a formal parameter
174 with a constant value and no location can arise is for a
175 formal parameter of an inlined subprogram that corresponds
176 to a constant actual parameter of a call that is inlined.
177 }
178
179 \item A \DWATstartscope{} 
180 attribute if the scope of 
181 \addtoindexx{start scope attribute}
182 an
183 \hypertarget{chap:DWATstartscopeobjectdeclaration}{}
184 object is smaller than (that is, is a subset of the addresses
185 of) the scope most closely enclosing the object. There are
186 two cases:
187 \begin{enumerate}[a) ]
188 \item If the scope of the object entry includes all of the
189 containing scope except for a contiguous sequence of bytes at
190 the beginning of that containing scope, then the scope of the
191 object is specified using a value of class constant. If the
192 containing scope is contiguous, the value of this attribute
193 is the offset in bytes of the beginning of the scope for the
194 object from the low pc value of the debugging information
195 entry that defines its scope. If the containing scope
196 is non-contiguous 
197 (see \refersec{chap:noncontiguousaddressranges})
198 the value of this
199 attribute is the offset in bytes of the beginning of the scope
200 for the object from the beginning of the first \addtoindex{range list} entry
201 that is not a base selection entry, a default selection entry or an end-of-list entry.
202
203 \needlines{4}
204 \item Otherwise, the scope of the object is specified using
205 a value of class \livelink{chap:classrangelistptr}{rangelistptr}. 
206 This value indicates the
207 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\dash contiguous.}
240
241 \item A \DWATendianity{} attribute, 
242 whose value 
243 \hypertarget{chap:DWATendianityendianityofdata}{}
244 is a constant
245 \addtoindexx{endianity attribute}
246 that 
247 \addtoindexx{big-endian encoding|see{endianity attribute}}
248 specifies 
249 the endianity of the object. The value of
250 this attribute specifies an ABI\dash defined 
251 byte ordering \addtoindexx{ordering attribute} for
252 the value of the object. If omitted, the default endianity
253 of data for the given type is assumed.  
254
255 The set of values
256 and their meaning for this attribute is given in 
257 Table \ref{tab:endianityattributevalues}.
258
259 \begin{table}[here]
260 \caption{Endianity attribute values}
261 \label{tab:endianityattributevalues}
262 \centering
263 \begin{tabular}{l|p{9cm}}
264 \hline
265 Name&Meaning\\ \hline
266 \DWENDdefaultTARG{} &  Default endian encoding
267   (equivalent to the \mbox{absence} of a 
268   \DWATendianity{} attribute) \\
269 \DWENDbigTARG{} & Big\dash endian encoding \\
270 \DWENDlittleTARG& Little-endian encoding \\
271 \hline
272 \end{tabular}
273 \end{table}
274
275
276 These represent the default encoding formats as defined by
277 the target architecture's ABI or processor definition. The
278 exact definition of these formats may differ in subtle ways
279 for different architectures.
280
281 \needlines{6}
282 \item A \DWATconstexpr{} attribute, 
283 which 
284 \hypertarget{chap:DWATconstexprcompiletimeconstantobject}{}
285 is a \livelink{chap:classflag}{flag}, if a
286 variable entry represents a \addtoindex{C++} object declared with the
287 \texttt{constexpr} specifier. This attribute indicates that the
288 variable can be evaluated as a compile\dash time constant.  
289
290 \textit{In \addtoindex{C++},
291 a variable declared with \texttt{constexpr} is implicitly \texttt{const}. Such a
292 variable has a \DWATtype{} attribute whose value is a 
293 \livelink{chap:classreference}{reference}
294 to a debugging information entry describing a const qualified type.}
295
296 \item A \DWATlinkagename{} attribute for a 
297 variable or constant entry as described in 
298 Section \refersec{chap:linkagenames}.
299
300 \end{enumerate}
301
302 \section{Common Block Entries}
303 \label{chap:commonblockentries}
304 A Fortran \livetargi{chap:fortrancommonblock}{common}{Fortran!common block} \livetargi{chap:commonblockentry}{block}{common block entry} 
305 may 
306 \addtoindexx{Fortran!common block}
307 be described by a debugging
308 information entry with the 
309 tag \DWTAGcommonblockTARG. 
310
311 The common \nolink{block} 
312 entry has a \DWATname{} attribute 
313 \addtoindexx{name attribute}
314 whose value is a null-terminated
315 string containing the
316 \livetargi{chap:commonblockreferenceattribute}{common \nolink{block}}{common block reference attribute} 
317 name as it appears in the source program. It may also have a
318 \DWATlinkagename{} attribute as described in 
319 Section \refersec{chap:linkagenames}. 
320
321 A common block entry also has a \DWATlocation{} attribute
322 \addtoindexx{location attribute}
323 whose value describes the
324 location of the beginning of the common \nolink{block}. 
325
326 The common
327 \nolink{block} entry owns debugging information entries describing
328 the variables contained within the common \nolink{block}.
329
330 \textit{\addtoindex{Fortran} allows each declarer of a common block 
331 to independently define its contents; thus, common blocks are not types.}
332
333 \needlines{8}
334 \section{Namelist Entries}
335 \label{chap:namelistentries}
336 \textit{At least one language, Fortran 90, has the concept of a
337 namelist. A namelist is an ordered list of the names of some
338 set of declared objects. The namelist object itself may be used
339 as a replacement for the list of names in various contexts.}
340
341 A namelist is represented by a debugging information entry
342 with the 
343 tag \DWTAGnamelistTARG. 
344 \addtoindexx{namelist entry}
345 If the namelist itself has a
346 name, the namelist entry has a \DWATname{} attribute,
347 \addtoindexx{name attribute}
348 whose value is a null-terminated
349 string containing the namelist\textquoteright{}s
350 name as it appears in the source program.
351
352 Each 
353 \hypertarget{chap:DWATnamelistitemnamelistitem}{}
354 name that is part of the namelist is represented
355 by a debugging information entry with the tag
356 \DWTAGnamelistitemTARG. 
357 Each such entry is a child of the
358 namelist entry, and all of the 
359 namelist item entries for a
360 \addtoindexx{namelist item entry}
361 given namelist are ordered as were the list of names they
362 correspond to in the source program.
363
364 Each namelist item entry contains a 
365 \DWATnamelistitem{} attribute
366 \addtoindexx{namelist item attribute}
367 whose 
368 \addtoindexx{namelist item entry}
369 value is a \livelink{chap:classreference}{reference} to the debugging
370 information entry representing the declaration of the item
371 whose name appears in the namelist.
372
373