gdb/location.h

   1 /* Data structures and API for location specs in GDB.
   2    Copyright (C) 2013-2024 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
  24 struct language_defn;
  25 struct location_spec;
  26
  27 /* An enumeration of possible signs for a line offset.  */
  28
  29 enum offset_relative_sign
  30 {
  31   /* No sign  */
  32   LINE_OFFSET_NONE,
  33
  34   /* A plus sign ("+")  */
  35   LINE_OFFSET_PLUS,
  36
  37   /* A minus sign ("-")  */
  38   LINE_OFFSET_MINUS,
  39
  40   /* A special "sign" for unspecified offset.  */
  41   LINE_OFFSET_UNKNOWN
  42 };
  43
  44 /* A line offset in a location.  */
  45
  46 struct line_offset
  47 {
  48   /* Line offset and any specified sign.  */
  49   int offset = 0;
  50   enum offset_relative_sign sign = LINE_OFFSET_UNKNOWN;
  51 };
  52
  53 /* An enumeration of the various ways to specify a location spec.  */
  54
  55 enum location_spec_type
  56 {
  57   /* A traditional linespec.  */
  58   LINESPEC_LOCATION_SPEC,
  59
  60   /* An address location spec.  */
  61   ADDRESS_LOCATION_SPEC,
  62
  63   /* An explicit location spec.  */
  64   EXPLICIT_LOCATION_SPEC,
  65
  66   /* A probe location spec.  */
  67   PROBE_LOCATION_SPEC
  68 };
  69
  70 /* A unique pointer for location_spec.  */
  71 typedef 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
  76 struct location_spec
  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 ())
  95       m_as_string = compute_string ();
  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.  */
 108   enum location_spec_type type () const
 109   {
 110     return m_type;
 111   }
 112
 113 protected:
 114
 115   explicit location_spec (enum location_spec_type t)
 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
 126   location_spec (const location_spec &other)
 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
 140 private:
 141   /* The type of this location specification.  */
 142   enum location_spec_type m_type;
 143 };
 144
 145 /* A "normal" linespec.  */
 146
 147 struct linespec_location_spec : public location_spec
 148 {
 149   linespec_location_spec (const char **linespec,
 150                           symbol_name_match_type match_type);
 151
 152   location_spec_up clone () const override;
 153
 154   bool empty_p () const override;
 155
 156   /* Whether the function name is fully-qualified or not.  */
 157   symbol_name_match_type match_type;
 158
 159   /* The linespec.  */
 160   gdb::unique_xmalloc_ptr<char> spec_string;
 161
 162 protected:
 163   linespec_location_spec (const linespec_location_spec &other);
 164
 165   std::string compute_string () const override;
 166 };
 167
 168 /* An address in the inferior.  */
 169 struct address_location_spec : public location_spec
 170 {
 171   address_location_spec (CORE_ADDR addr, const char *addr_string,
 172                          int addr_string_len);
 173
 174   location_spec_up clone () const override;
 175
 176   bool empty_p () const override;
 177
 178   CORE_ADDR address;
 179
 180 protected:
 181   address_location_spec (const address_location_spec &other);
 182
 183   std::string compute_string () const override;
 184 };
 185
 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.  */
 190
 191 struct explicit_location_spec : public location_spec
 192 {
 193   explicit explicit_location_spec (const char *function_name);
 194
 195   explicit_location_spec ()
 196     : explicit_location_spec (nullptr)
 197   {
 198   }
 199
 200   location_spec_up clone () const override;
 201
 202   bool empty_p () const override;
 203
 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;
 208
 209   /* The source filename.  */
 210   gdb::unique_xmalloc_ptr<char> source_filename;
 211
 212   /* The function name.  */
 213   gdb::unique_xmalloc_ptr<char> function_name;
 214
 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;
 218
 219   /* The name of a label.  */
 220   gdb::unique_xmalloc_ptr<char> label_name;
 221
 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;
 226
 227 protected:
 228   explicit_location_spec (const explicit_location_spec &other);
 229
 230   std::string compute_string () const override;
 231 };
 232
 233 /* A probe.  */
 234 struct probe_location_spec : public location_spec
 235 {
 236   explicit probe_location_spec (std::string &&probe);
 237
 238   location_spec_up clone () const override;
 239
 240   bool empty_p () const override;
 241
 242 protected:
 243   probe_location_spec (const probe_location_spec &other) = default;
 244
 245   std::string compute_string () const override;
 246 };
 247
 248 /* Create a new linespec location spec.  */
 249
 250 extern location_spec_up new_linespec_location_spec
 251   (const char **linespec, symbol_name_match_type match_type);
 252
 253 /* Return the given location_spec as a linespec_location_spec.
 254    LOCSPEC must be of type LINESPEC_LOCATION_SPEC.  */
 255
 256 extern const linespec_location_spec *
 257   as_linespec_location_spec (const location_spec *locspec);
 258
 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.  */
 263
 264 extern location_spec_up new_address_location_spec (CORE_ADDR addr,
 265                                                    const char *addr_string,
 266                                                    int addr_string_len);
 267
 268 /* Return the given location_spec as an address_location_spec.
 269    LOCSPEC must be of type ADDRESS_LOCATION_SPEC.  */
 270
 271 const address_location_spec *
 272   as_address_location_spec (const location_spec *locspec);
 273
 274 /* Create a new probe location.  */
 275
 276 extern location_spec_up new_probe_location_spec (std::string &&probe);
 277
 278 /* Assuming LOCSPEC is of type PROBE_LOCATION_SPEC, return LOCSPEC
 279    cast to probe_location_spec.  */
 280
 281 const probe_location_spec *
 282   as_probe_location_spec (const location_spec *locspec);
 283
 284 /* Create a new explicit location with explicit FUNCTION_NAME.  All
 285    other fields are defaulted.  */
 286
 287 static inline location_spec_up
 288 new_explicit_location_spec_function (const char *function_name)
 289 {
 290   explicit_location_spec *spec = new explicit_location_spec (function_name);
 291   return location_spec_up (spec);
 292 }
 293
 294 /* Assuming LOCSPEC is of type EXPLICIT_LOCATION_SPEC, return LOCSPEC
 295    cast to explicit_location_spec.  */
 296
 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);
 301
 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.
 305
 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
 308    or invalid options.
 309
 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.
 314
 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.  */
 317
 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);
 321
 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.  */
 325
 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);
 330
 331 /* Structure filled in by string_to_explicit_location_spec to aid the
 332    completer.  */
 333 struct explicit_completion_info
 334 {
 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;
 338
 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;
 346
 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;
 351 };
 352
 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.
 357
 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.  */
 362
 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);
 367
 368 #endif /* LOCATION_H */