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