1 /* Data structures and API for location specs in GDB.
2 Copyright (C) 2013-2024 Free Software Foundation, Inc.
4 This file is part of GDB.
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 3 of the License, or
9 (at your option) any later version.
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with this program. If not, see <http://www.gnu.org/licenses/>. */
27 /* An enumeration of possible signs for a line offset. */
29 enum offset_relative_sign
34 /* A plus sign ("+") */
37 /* A minus sign ("-") */
40 /* A special "sign" for unspecified offset. */
44 /* A line offset in a location. */
48 /* Line offset and any specified sign. */
50 enum offset_relative_sign sign
= LINE_OFFSET_UNKNOWN
;
53 /* An enumeration of the various ways to specify a location spec. */
55 enum location_spec_type
57 /* A traditional linespec. */
58 LINESPEC_LOCATION_SPEC
,
60 /* An address location spec. */
61 ADDRESS_LOCATION_SPEC
,
63 /* An explicit location spec. */
64 EXPLICIT_LOCATION_SPEC
,
66 /* A probe location spec. */
70 /* A unique pointer for location_spec. */
71 typedef std::unique_ptr
<location_spec
> location_spec_up
;
73 /* The base class for all location specs used to resolve actual
74 locations in the inferior. */
78 virtual ~location_spec () = default;
80 /* Clone this object. */
81 virtual location_spec_up
clone () const = 0;
83 /* Return true if this location spec is empty, false otherwise. */
84 virtual bool empty_p () const = 0;
86 /* Return a string representation of this location.
88 This function may return NULL for unspecified linespecs, e.g,
89 LINESPEC_LOCATION_SPEC and spec_string is NULL.
91 The result is cached in the locspec. */
92 const char *to_string () const
94 if (m_as_string
.empty ())
95 m_as_string
= compute_string ();
96 if (m_as_string
.empty ())
98 return m_as_string
.c_str ();
101 /* Set this location spec's string representation. */
102 void set_string (std::string
&&string
)
104 m_as_string
= std::move (string
);
107 /* Return this location spec's type. */
108 enum location_spec_type
type () const
115 explicit location_spec (enum location_spec_type t
)
120 location_spec (enum location_spec_type t
, std::string
&&str
)
121 : m_as_string (std::move (str
)),
126 location_spec (const location_spec
&other
)
127 : m_as_string (other
.m_as_string
),
128 m_type (other
.m_type
)
132 /* Compute the string representation of this object. This is called
133 by to_string when needed. */
134 virtual std::string
compute_string () const = 0;
136 /* Cached string representation of this location spec. This is
137 used, e.g., to save location specs to file. */
138 mutable std::string m_as_string
;
141 /* The type of this location specification. */
142 enum location_spec_type m_type
;
145 /* A "normal" linespec. */
147 struct linespec_location_spec
: public location_spec
149 linespec_location_spec (const char **linespec
,
150 symbol_name_match_type match_type
);
152 location_spec_up
clone () const override
;
154 bool empty_p () const override
;
156 /* Whether the function name is fully-qualified or not. */
157 symbol_name_match_type match_type
;
160 gdb::unique_xmalloc_ptr
<char> spec_string
;
163 linespec_location_spec (const linespec_location_spec
&other
);
165 std::string
compute_string () const override
;
168 /* An address in the inferior. */
169 struct address_location_spec
: public location_spec
171 address_location_spec (CORE_ADDR addr
, const char *addr_string
,
172 int addr_string_len
);
174 location_spec_up
clone () const override
;
176 bool empty_p () const override
;
181 address_location_spec (const address_location_spec
&other
);
183 std::string
compute_string () const override
;
186 /* An explicit location spec. This structure is used to bypass the
187 parsing done on linespecs. It still has the same requirements
188 as linespecs, though. For example, source_filename requires
189 at least one other field. */
191 struct explicit_location_spec
: public location_spec
193 explicit explicit_location_spec (const char *function_name
);
195 explicit_location_spec ()
196 : explicit_location_spec (nullptr)
200 location_spec_up
clone () const override
;
202 bool empty_p () const override
;
204 /* Return a linespec string representation of this explicit location
205 spec. The explicit location spec must already be
206 canonicalized/valid. */
207 std::string
to_linespec () const;
209 /* The source filename. */
210 gdb::unique_xmalloc_ptr
<char> source_filename
;
212 /* The function name. */
213 gdb::unique_xmalloc_ptr
<char> function_name
;
215 /* Whether the function name is fully-qualified or not. */
216 symbol_name_match_type func_name_match_type
217 = symbol_name_match_type::WILD
;
219 /* The name of a label. */
220 gdb::unique_xmalloc_ptr
<char> label_name
;
222 /* A line offset relative to the start of the symbol
223 identified by the above fields or the current symtab
224 if the other fields are NULL. */
225 struct line_offset line_offset
;
228 explicit_location_spec (const explicit_location_spec
&other
);
230 std::string
compute_string () const override
;
234 struct probe_location_spec
: public location_spec
236 explicit probe_location_spec (std::string
&&probe
);
238 location_spec_up
clone () const override
;
240 bool empty_p () const override
;
243 probe_location_spec (const probe_location_spec
&other
) = default;
245 std::string
compute_string () const override
;
248 /* Create a new linespec location spec. */
250 extern location_spec_up new_linespec_location_spec
251 (const char **linespec
, symbol_name_match_type match_type
);
253 /* Return the given location_spec as a linespec_location_spec.
254 LOCSPEC must be of type LINESPEC_LOCATION_SPEC. */
256 extern const linespec_location_spec
*
257 as_linespec_location_spec (const location_spec
*locspec
);
259 /* Create a new address location spec.
260 ADDR is the address corresponding to this location_spec.
261 ADDR_STRING, a string of ADDR_STRING_LEN characters, is
262 the expression that was parsed to determine the address ADDR. */
264 extern location_spec_up
new_address_location_spec (CORE_ADDR addr
,
265 const char *addr_string
,
266 int addr_string_len
);
268 /* Return the given location_spec as an address_location_spec.
269 LOCSPEC must be of type ADDRESS_LOCATION_SPEC. */
271 const address_location_spec
*
272 as_address_location_spec (const location_spec
*locspec
);
274 /* Create a new probe location. */
276 extern location_spec_up
new_probe_location_spec (std::string
&&probe
);
278 /* Assuming LOCSPEC is of type PROBE_LOCATION_SPEC, return LOCSPEC
279 cast to probe_location_spec. */
281 const probe_location_spec
*
282 as_probe_location_spec (const location_spec
*locspec
);
284 /* Create a new explicit location with explicit FUNCTION_NAME. All
285 other fields are defaulted. */
287 static inline location_spec_up
288 new_explicit_location_spec_function (const char *function_name
)
290 explicit_location_spec
*spec
= new explicit_location_spec (function_name
);
291 return location_spec_up (spec
);
294 /* Assuming LOCSPEC is of type EXPLICIT_LOCATION_SPEC, return LOCSPEC
295 cast to explicit_location_spec. */
297 const explicit_location_spec
*
298 as_explicit_location_spec (const location_spec
*locspec
);
299 explicit_location_spec
*
300 as_explicit_location_spec (location_spec
*locspec
);
302 /* Attempt to convert the input string in *ARGP into a location_spec.
303 ARGP is advanced past any processed input. Always returns a non-nullptr
304 location_spec unique pointer object.
306 This function may call error() if *ARGP looks like properly formed, but
307 invalid, input, e.g., if it is called with missing argument parameters
310 This function is intended to be used by CLI commands and will parse
311 explicit location specs in a CLI-centric way. Other interfaces should use
312 string_to_location_spec_basic if they want to maintain support for
313 legacy specifications of probe, address, and linespec location specs.
315 MATCH_TYPE should be either WILD or FULL. If -q/--qualified is specified
316 in the input string, it will take precedence over this parameter. */
318 extern location_spec_up string_to_location_spec
319 (const char **argp
, const struct language_defn
*language
,
320 symbol_name_match_type match_type
= symbol_name_match_type::WILD
);
322 /* Like string_to_location_spec, but does not attempt to parse
323 explicit location specs. MATCH_TYPE indicates how function names
324 should be matched. */
326 extern location_spec_up
327 string_to_location_spec_basic (const char **argp
,
328 const struct language_defn
*language
,
329 symbol_name_match_type match_type
);
331 /* Structure filled in by string_to_explicit_location_spec to aid the
333 struct explicit_completion_info
335 /* Pointer to the last option found. E.g., in "b -sou src.c -fun
336 func", LAST_OPTION is left pointing at "-fun func". */
337 const char *last_option
= NULL
;
339 /* These point to the start and end of a quoted argument, iff the
340 last argument was quoted. If parsing finds an incomplete quoted
341 string (e.g., "break -function 'fun"), then QUOTED_ARG_START is
342 set to point to the opening \', and QUOTED_ARG_END is left NULL.
343 If the last option is not quoted, then both are set to NULL. */
344 const char *quoted_arg_start
= NULL
;
345 const char *quoted_arg_end
= NULL
;
347 /* True if we saw an explicit location spec option, as opposed to
348 only flags that affect both explicit location specs and
349 linespecs, like "-qualified". */
350 bool saw_explicit_location_spec_option
= false;
353 /* Attempt to convert the input string in *ARGP into an explicit
354 location spec. ARGP is advanced past any processed input. Returns
355 a location_spec (malloc'd) if an explicit location spec was
356 successfully found in *ARGP, NULL otherwise.
358 If COMPLETION_INFO is NULL, this function may call error() if *ARGP
359 looks like improperly formed input, e.g., if it is called with
360 missing argument parameters or invalid options. If COMPLETION_INFO
361 is not NULL, this function will not throw any exceptions. */
363 extern location_spec_up
364 string_to_explicit_location_spec (const char **argp
,
365 const struct language_defn
*language
,
366 explicit_completion_info
*completion_info
);
368 #endif /* LOCATION_H */