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