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