aboutsummaryrefslogtreecommitdiff
path: root/gdb/location.h
blob: c2083ae7fc7803de514e26337914caba4085227e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
/* Data structures and API for location specs in GDB.
   Copyright (C) 2013-2023 Free Software Foundation, Inc.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

#ifndef LOCATION_H
#define LOCATION_H

#include "symtab.h"

struct language_defn;
struct location_spec;

/* An enumeration of possible signs for a line offset.  */

enum offset_relative_sign
{
  /* No sign  */
  LINE_OFFSET_NONE,

  /* A plus sign ("+")  */
  LINE_OFFSET_PLUS,

  /* A minus sign ("-")  */
  LINE_OFFSET_MINUS,

  /* A special "sign" for unspecified offset.  */
  LINE_OFFSET_UNKNOWN
};

/* A line offset in a location.  */

struct line_offset
{
  /* Line offset and any specified sign.  */
  int offset = 0;
  enum offset_relative_sign sign = LINE_OFFSET_UNKNOWN;
};

/* An enumeration of the various ways to specify a location spec.  */

enum location_spec_type
{
  /* A traditional linespec.  */
  LINESPEC_LOCATION_SPEC,

  /* An address location spec.  */
  ADDRESS_LOCATION_SPEC,

  /* An explicit location spec.  */
  EXPLICIT_LOCATION_SPEC,

  /* A probe location spec.  */
  PROBE_LOCATION_SPEC
};

/* A unique pointer for location_spec.  */
typedef std::unique_ptr<location_spec> location_spec_up;

/* The base class for all location specs used to resolve actual
   locations in the inferior.  */

struct location_spec
{
  virtual ~location_spec () = default;

  /* Clone this object.  */
  virtual location_spec_up clone () const = 0;

  /* Return true if this location spec is empty, false otherwise.  */
  virtual bool empty_p () const = 0;

  /* Return a string representation of this location.

     This function may return NULL for unspecified linespecs, e.g,
     LINESPEC_LOCATION_SPEC and spec_string is NULL.

     The result is cached in the locspec.  */
  const char *to_string () const
  {
    if (m_as_string.empty ())
      m_as_string = compute_string ();
    if (m_as_string.empty ())
      return nullptr;
    return m_as_string.c_str ();
  }

  /* Set this location spec's string representation.  */
  void set_string (std::string &&string)
  {
    m_as_string = std::move (string);
  }

  /* Return this location spec's type.  */
  enum location_spec_type type () const
  {
    return m_type;
  }

protected:

  explicit location_spec (enum location_spec_type t)
    : m_type (t)
  {
  }

  location_spec (enum location_spec_type t, std::string &&str)
    : m_as_string (std::move (str)),
      m_type (t)
  {
  }

  location_spec (const location_spec &other)
    : m_as_string (other.m_as_string),
      m_type (other.m_type)
  {
  }

  /* Compute the string representation of this object.  This is called
     by to_string when needed.  */
  virtual std::string compute_string () const = 0;

  /* Cached string representation of this location spec.  This is
     used, e.g., to save location specs to file.  */
  mutable std::string m_as_string;

private:
  /* The type of this location specification.  */
  enum location_spec_type m_type;
};

/* A "normal" linespec.  */

struct linespec_location_spec : public location_spec
{
  linespec_location_spec (const char **linespec,
			  symbol_name_match_type match_type);

  ~linespec_location_spec ();

  location_spec_up clone () const override;

  bool empty_p () const override;

  /* Whether the function name is fully-qualified or not.  */
  symbol_name_match_type match_type;

  /* The linespec.  */
  char *spec_string = nullptr;

protected:
  linespec_location_spec (const linespec_location_spec &other);

  std::string compute_string () const override;
};

/* An address in the inferior.  */
struct address_location_spec : public location_spec
{
  address_location_spec (CORE_ADDR addr, const char *addr_string,
			 int addr_string_len);

  location_spec_up clone () const override;

  bool empty_p () const override;

  CORE_ADDR address;

protected:
  address_location_spec (const address_location_spec &other);

  std::string compute_string () const override;
};

/* An explicit location spec.  This structure is used to bypass the
   parsing done on linespecs.  It still has the same requirements
   as linespecs, though.  For example, source_filename requires
   at least one other field.  */

struct explicit_location_spec : public location_spec
{
  explicit_location_spec ();

  ~explicit_location_spec ();

  location_spec_up clone () const override;

  bool empty_p () const override;

  /* Return a linespec string representation of this explicit location
     spec.  The explicit location spec must already be
     canonicalized/valid.  */
  std::string to_linespec () const;

  /* The source filename. Malloc'd.  */
  char *source_filename = nullptr;

  /* The function name.  Malloc'd.  */
  char *function_name = nullptr;

  /* Whether the function name is fully-qualified or not.  */
  symbol_name_match_type func_name_match_type
    = symbol_name_match_type::WILD;

  /* The name of a label.  Malloc'd.  */
  char *label_name = nullptr;

  /* A line offset relative to the start of the symbol
     identified by the above fields or the current symtab
     if the other fields are NULL.  */
  struct line_offset line_offset;

protected:
  explicit_location_spec (const explicit_location_spec &other);

  std::string compute_string () const override;
};

/* A probe.  */
struct probe_location_spec : public location_spec
{
  explicit probe_location_spec (std::string &&probe);

  location_spec_up clone () const override;

  bool empty_p () const override;

protected:
  probe_location_spec (const probe_location_spec &other) = default;

  std::string compute_string () const override;
};

/* Create a new linespec location spec.  */

extern location_spec_up new_linespec_location_spec
  (const char **linespec, symbol_name_match_type match_type);

/* Return the given location_spec as a linespec_location_spec.
   LOCSPEC must be of type LINESPEC_LOCATION_SPEC.  */

extern const linespec_location_spec *
  as_linespec_location_spec (const location_spec *locspec);

/* Create a new address location spec.
   ADDR is the address corresponding to this location_spec.
   ADDR_STRING, a string of ADDR_STRING_LEN characters, is
   the expression that was parsed to determine the address ADDR.  */

extern location_spec_up new_address_location_spec (CORE_ADDR addr,
						   const char *addr_string,
						   int addr_string_len);

/* Return the given location_spec as an address_location_spec.
   LOCSPEC must be of type ADDRESS_LOCATION_SPEC.  */

const address_location_spec *
  as_address_location_spec (const location_spec *locspec);

/* Create a new probe location.  */

extern location_spec_up new_probe_location_spec (std::string &&probe);

/* Assuming LOCSPEC is of type PROBE_LOCATION_SPEC, return LOCSPEC
   cast to probe_location_spec.  */

const probe_location_spec *
  as_probe_location_spec (const location_spec *locspec);

/* Create a new explicit location with explicit FUNCTION_NAME.  All
   other fields are defaulted.  */

static inline location_spec_up
new_explicit_location_spec_function (const char *function_name)
{
  explicit_location_spec *spec
    = new explicit_location_spec ();
  spec->function_name
    = (function_name != nullptr ? xstrdup (function_name) : nullptr);
  return location_spec_up (spec);
}

/* Assuming LOCSPEC is of type EXPLICIT_LOCATION_SPEC, return LOCSPEC
   cast to explicit_location_spec.  */

const explicit_location_spec *
  as_explicit_location_spec (const location_spec *locspec);
explicit_location_spec *
  as_explicit_location_spec (location_spec *locspec);

/* Attempt to convert the input string in *ARGP into a location_spec.
   ARGP is advanced past any processed input.  Always returns a non-nullptr
   location_spec unique pointer object.

   This function may call error() if *ARGP looks like properly formed, but
   invalid, input, e.g., if it is called with missing argument parameters
   or invalid options.

   This function is intended to be used by CLI commands and will parse
   explicit location specs in a CLI-centric way.  Other interfaces should use
   string_to_location_spec_basic if they want to maintain support for
   legacy specifications of probe, address, and linespec location specs.

   MATCH_TYPE should be either WILD or FULL.  If -q/--qualified is specified
   in the input string, it will take precedence over this parameter.  */

extern 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);

/* Like string_to_location_spec, but does not attempt to parse
   explicit location specs.  MATCH_TYPE indicates how function names
   should be matched.  */

extern location_spec_up
  string_to_location_spec_basic (const char **argp,
				 const struct language_defn *language,
				 symbol_name_match_type match_type);

/* Structure filled in by string_to_explicit_location_spec to aid the
   completer.  */
struct explicit_completion_info
{
  /* Pointer to the last option found.  E.g., in "b -sou src.c -fun
     func", LAST_OPTION is left pointing at "-fun func".  */
  const char *last_option = NULL;

  /* These point to the start and end of a quoted argument, iff the
     last argument was quoted.  If parsing finds an incomplete quoted
     string (e.g., "break -function 'fun"), then QUOTED_ARG_START is
     set to point to the opening \', and QUOTED_ARG_END is left NULL.
     If the last option is not quoted, then both are set to NULL. */
  const char *quoted_arg_start = NULL;
  const char *quoted_arg_end = NULL;

  /* True if we saw an explicit location spec option, as opposed to
     only flags that affect both explicit location specs and
     linespecs, like "-qualified".  */
  bool saw_explicit_location_spec_option = false;
};

/* Attempt to convert the input string in *ARGP into an explicit
   location spec.  ARGP is advanced past any processed input.  Returns
   a location_spec (malloc'd) if an explicit location spec was
   successfully found in *ARGP, NULL otherwise.

   If COMPLETION_INFO is NULL, this function may call error() if *ARGP
   looks like improperly formed input, e.g., if it is called with
   missing argument parameters or invalid options.  If COMPLETION_INFO
   is not NULL, this function will not throw any exceptions.  */

extern location_spec_up
  string_to_explicit_location_spec (const char **argp,
				    const struct language_defn *language,
				    explicit_completion_info *completion_info);

#endif /* LOCATION_H */