GDB (xrefs)
Loading...
Searching...
No Matches
location.h
Go to the documentation of this file.
1/* Data structures and API for location specs in GDB.
2 Copyright (C) 2013-2023 Free Software Foundation, Inc.
3
4 This file is part of GDB.
5
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.
10
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.
15
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/>. */
18
19#ifndef LOCATION_H
20#define LOCATION_H
21
22#include "symtab.h"
23
24struct language_defn;
25struct location_spec;
26
27/* An enumeration of possible signs for a line offset. */
28
30{
31 /* No sign */
33
34 /* A plus sign ("+") */
36
37 /* A minus sign ("-") */
39
40 /* A special "sign" for unspecified offset. */
42};
43
44/* A line offset in a location. */
45
47{
48 /* Line offset and any specified sign. */
49 int offset = 0;
51};
52
53/* An enumeration of the various ways to specify a location spec. */
54
56{
57 /* A traditional linespec. */
59
60 /* An address location spec. */
62
63 /* An explicit location spec. */
65
66 /* A probe location spec. */
68};
69
70/* A unique pointer for location_spec. */
71typedef std::unique_ptr<location_spec> location_spec_up;
72
73/* The base class for all location specs used to resolve actual
74 locations in the inferior. */
75
77{
78 virtual ~location_spec () = default;
79
80 /* Clone this object. */
81 virtual location_spec_up clone () const = 0;
82
83 /* Return true if this location spec is empty, false otherwise. */
84 virtual bool empty_p () const = 0;
85
86 /* Return a string representation of this location.
87
88 This function may return NULL for unspecified linespecs, e.g,
89 LINESPEC_LOCATION_SPEC and spec_string is NULL.
90
91 The result is cached in the locspec. */
92 const char *to_string () const
93 {
94 if (m_as_string.empty ())
96 if (m_as_string.empty ())
97 return nullptr;
98 return m_as_string.c_str ();
99 }
100
101 /* Set this location spec's string representation. */
102 void set_string (std::string &&string)
103 {
104 m_as_string = std::move (string);
105 }
106
107 /* Return this location spec's type. */
109 {
110 return m_type;
111 }
112
113protected:
114
116 : m_type (t)
117 {
118 }
119
120 location_spec (enum location_spec_type t, std::string &&str)
121 : m_as_string (std::move (str)),
122 m_type (t)
123 {
124 }
125
127 : m_as_string (other.m_as_string),
128 m_type (other.m_type)
129 {
130 }
131
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;
135
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;
139
140private:
141 /* The type of this location specification. */
143};
144
145/* A "normal" linespec. */
146
148{
149 linespec_location_spec (const char **linespec,
151
153
154 location_spec_up clone () const override;
155
156 bool empty_p () const override;
157
158 /* Whether the function name is fully-qualified or not. */
160
161 /* The linespec. */
162 char *spec_string = nullptr;
163
164protected:
166
167 std::string compute_string () const override;
168};
169
170/* An address in the inferior. */
172{
173 address_location_spec (CORE_ADDR addr, const char *addr_string,
174 int addr_string_len);
175
176 location_spec_up clone () const override;
177
178 bool empty_p () const override;
179
180 CORE_ADDR address;
181
182protected:
184
185 std::string compute_string () const override;
186};
187
188/* An explicit location spec. This structure is used to bypass the
189 parsing done on linespecs. It still has the same requirements
190 as linespecs, though. For example, source_filename requires
191 at least one other field. */
192
194{
196
198
199 location_spec_up clone () const override;
200
201 bool empty_p () const override;
202
203 /* Return a linespec string representation of this explicit location
204 spec. The explicit location spec must already be
205 canonicalized/valid. */
206 std::string to_linespec () const;
207
208 /* The source filename. Malloc'd. */
209 char *source_filename = nullptr;
210
211 /* The function name. Malloc'd. */
212 char *function_name = nullptr;
213
214 /* Whether the function name is fully-qualified or not. */
217
218 /* The name of a label. Malloc'd. */
219 char *label_name = nullptr;
220
221 /* A line offset relative to the start of the symbol
222 identified by the above fields or the current symtab
223 if the other fields are NULL. */
225
226protected:
228
229 std::string compute_string () const override;
230};
231
232/* A probe. */
234{
235 explicit probe_location_spec (std::string &&probe);
236
237 location_spec_up clone () const override;
238
239 bool empty_p () const override;
240
241protected:
242 probe_location_spec (const probe_location_spec &other) = default;
243
244 std::string compute_string () const override;
245};
246
247/* Create a new linespec location spec. */
248
250 (const char **linespec, symbol_name_match_type match_type);
251
252/* Return the given location_spec as a linespec_location_spec.
253 LOCSPEC must be of type LINESPEC_LOCATION_SPEC. */
254
255extern const linespec_location_spec *
257
258/* Create a new address location spec.
259 ADDR is the address corresponding to this location_spec.
260 ADDR_STRING, a string of ADDR_STRING_LEN characters, is
261 the expression that was parsed to determine the address ADDR. */
262
263extern location_spec_up new_address_location_spec (CORE_ADDR addr,
264 const char *addr_string,
265 int addr_string_len);
266
267/* Return the given location_spec as an address_location_spec.
268 LOCSPEC must be of type ADDRESS_LOCATION_SPEC. */
269
272
273/* Create a new probe location. */
274
275extern location_spec_up new_probe_location_spec (std::string &&probe);
276
277/* Assuming LOCSPEC is of type PROBE_LOCATION_SPEC, return LOCSPEC
278 cast to probe_location_spec. */
279
281 as_probe_location_spec (const location_spec *locspec);
282
283/* Create a new explicit location with explicit FUNCTION_NAME. All
284 other fields are defaulted. */
285
286static inline location_spec_up
287new_explicit_location_spec_function (const char *function_name)
288{
290 = new explicit_location_spec ();
291 spec->function_name
292 = (function_name != nullptr ? xstrdup (function_name) : nullptr);
293 return location_spec_up (spec);
294}
295
296/* Assuming LOCSPEC is of type EXPLICIT_LOCATION_SPEC, return LOCSPEC
297 cast to explicit_location_spec. */
298
303
304/* Attempt to convert the input string in *ARGP into a location_spec.
305 ARGP is advanced past any processed input. Always returns a non-nullptr
306 location_spec unique pointer object.
307
308 This function may call error() if *ARGP looks like properly formed, but
309 invalid, input, e.g., if it is called with missing argument parameters
310 or invalid options.
311
312 This function is intended to be used by CLI commands and will parse
313 explicit location specs in a CLI-centric way. Other interfaces should use
314 string_to_location_spec_basic if they want to maintain support for
315 legacy specifications of probe, address, and linespec location specs.
316
317 MATCH_TYPE should be either WILD or FULL. If -q/--qualified is specified
318 in the input string, it will take precedence over this parameter. */
319
321 (const char **argp, const struct language_defn *language,
323
324/* Like string_to_location_spec, but does not attempt to parse
325 explicit location specs. MATCH_TYPE indicates how function names
326 should be matched. */
327
328extern location_spec_up
329 string_to_location_spec_basic (const char **argp,
330 const struct language_defn *language,
331 symbol_name_match_type match_type);
332
333/* Structure filled in by string_to_explicit_location_spec to aid the
334 completer. */
336{
337 /* Pointer to the last option found. E.g., in "b -sou src.c -fun
338 func", LAST_OPTION is left pointing at "-fun func". */
339 const char *last_option = NULL;
340
341 /* These point to the start and end of a quoted argument, iff the
342 last argument was quoted. If parsing finds an incomplete quoted
343 string (e.g., "break -function 'fun"), then QUOTED_ARG_START is
344 set to point to the opening \', and QUOTED_ARG_END is left NULL.
345 If the last option is not quoted, then both are set to NULL. */
346 const char *quoted_arg_start = NULL;
347 const char *quoted_arg_end = NULL;
348
349 /* True if we saw an explicit location spec option, as opposed to
350 only flags that affect both explicit location specs and
351 linespecs, like "-qualified". */
353};
354
355/* Attempt to convert the input string in *ARGP into an explicit
356 location spec. ARGP is advanced past any processed input. Returns
357 a location_spec (malloc'd) if an explicit location spec was
358 successfully found in *ARGP, NULL otherwise.
359
360 If COMPLETION_INFO is NULL, this function may call error() if *ARGP
361 looks like improperly formed input, e.g., if it is called with
362 missing argument parameters or invalid options. If COMPLETION_INFO
363 is not NULL, this function will not throw any exceptions. */
364
365extern location_spec_up
366 string_to_explicit_location_spec (const char **argp,
367 const struct language_defn *language,
368 explicit_completion_info *completion_info);
369
370#endif /* LOCATION_H */
Definition probe.h:115
language
Definition defs.h:211
std::unique_ptr< location_spec > location_spec_up
Definition location.h:71
const explicit_location_spec * as_explicit_location_spec(const location_spec *locspec)
Definition location.c:266
location_spec_up new_address_location_spec(CORE_ADDR addr, const char *addr_string, int addr_string_len)
Definition location.c:230
offset_relative_sign
Definition location.h:30
@ LINE_OFFSET_MINUS
Definition location.h:38
@ LINE_OFFSET_PLUS
Definition location.h:35
@ LINE_OFFSET_NONE
Definition location.h:32
@ LINE_OFFSET_UNKNOWN
Definition location.h:41
static location_spec_up new_explicit_location_spec_function(const char *function_name)
Definition location.h:287
const address_location_spec * as_address_location_spec(const location_spec *locspec)
Definition location.c:240
location_spec_type
Definition location.h:56
@ LINESPEC_LOCATION_SPEC
Definition location.h:58
@ PROBE_LOCATION_SPEC
Definition location.h:67
@ EXPLICIT_LOCATION_SPEC
Definition location.h:64
@ ADDRESS_LOCATION_SPEC
Definition location.h:61
const linespec_location_spec * as_linespec_location_spec(const location_spec *locspec)
Definition location.c:221
location_spec_up string_to_location_spec_basic(const char **argp, const struct language_defn *language, symbol_name_match_type match_type)
Definition location.c:785
const probe_location_spec * as_probe_location_spec(const location_spec *locspec)
Definition location.c:257
location_spec_up string_to_location_spec(const char **argp, const struct language_defn *language, symbol_name_match_type match_type=symbol_name_match_type::WILD)
Definition location.c:825
location_spec_up new_probe_location_spec(std::string &&probe)
Definition location.c:249
location_spec_up new_linespec_location_spec(const char **linespec, symbol_name_match_type match_type)
Definition location.c:211
location_spec_up string_to_explicit_location_spec(const char **argp, const struct language_defn *language, explicit_completion_info *completion_info)
Definition location.c:629
Definition aarch64.h:67
bool empty_p() const override
Definition location.c:145
std::string compute_string() const override
Definition location.c:158
address_location_spec(CORE_ADDR addr, const char *addr_string, int addr_string_len)
Definition location.c:128
location_spec_up clone() const override
Definition location.c:139
const char * quoted_arg_end
Definition location.h:347
const char * last_option
Definition location.h:339
const char * quoted_arg_start
Definition location.h:346
bool saw_explicit_location_spec_option
Definition location.h:352
bool empty_p() const override
Definition location.c:194
std::string compute_string() const override
Definition location.c:203
symbol_name_match_type func_name_match_type
Definition location.h:216
location_spec_up clone() const override
Definition location.c:188
std::string to_linespec() const
Definition location.c:344
enum offset_relative_sign sign
Definition location.h:50
symbol_name_match_type match_type
Definition location.h:159
location_spec_up clone() const override
Definition location.c:96
std::string compute_string() const override
Definition location.c:116
bool empty_p() const override
Definition location.c:102
linespec_location_spec(const char **linespec, symbol_name_match_type match_type)
Definition location.c:69
std::string m_as_string
Definition location.h:138
virtual location_spec_up clone() const =0
virtual ~location_spec()=default
enum location_spec_type type() const
Definition location.h:108
location_spec(const location_spec &other)
Definition location.h:126
virtual std::string compute_string() const =0
location_spec(enum location_spec_type t)
Definition location.h:115
enum location_spec_type m_type
Definition location.h:142
void set_string(std::string &&string)
Definition location.h:102
location_spec(enum location_spec_type t, std::string &&str)
Definition location.h:120
const char * to_string() const
Definition location.h:92
virtual bool empty_p() const =0
probe_location_spec(const probe_location_spec &other)=default
bool empty_p() const override
Definition location.c:57
std::string compute_string() const override
Definition location.c:62
probe_location_spec(std::string &&probe)
Definition location.c:45
location_spec_up clone() const override
Definition location.c:51
symbol_name_match_type
Definition symtab.h:63