gdb/location.h

   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
  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   ~linespec_location_spec ();
 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.  */
 159   symbol_name_match_type match_type;
 160
 161   /* The linespec.  */
 162   char *spec_string = nullptr;
 163
 164 protected:
 165   linespec_location_spec (const linespec_location_spec &other);
 166
 167   std::string compute_string () const override;
 168 };
 169
 170 /* An address in the inferior.  */
 171 struct address_location_spec : public location_spec
 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
 182 protected:
 183   address_location_spec (const address_location_spec &other);
 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
 193 struct explicit_location_spec : public location_spec
 194 {
 195   explicit_location_spec ();
 196
 197   ~explicit_location_spec ();
 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.  */
 215   symbol_name_match_type func_name_match_type
 216     = symbol_name_match_type::WILD;
 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.  */
 224   struct line_offset line_offset;
 225
 226 protected:
 227   explicit_location_spec (const explicit_location_spec &other);
 228
 229   std::string compute_string () const override;
 230 };
 231
 232 /* A probe.  */
 233 struct probe_location_spec : public location_spec
 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
 241 protected:
 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
 249 extern location_spec_up new_linespec_location_spec
 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
 255 extern const linespec_location_spec *
 256   as_linespec_location_spec (const location_spec *locspec);
 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
 263 extern 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
 270 const address_location_spec *
 271   as_address_location_spec (const location_spec *locspec);
 272
 273 /* Create a new probe location.  */
 274
 275 extern 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
 280 const probe_location_spec *
 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
 286 static inline location_spec_up
 287 new_explicit_location_spec_function (const char *function_name)
 288 {
 289   explicit_location_spec *spec
 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
 299 const explicit_location_spec *
 300   as_explicit_location_spec (const location_spec *locspec);
 301 explicit_location_spec *
 302   as_explicit_location_spec (location_spec *locspec);
 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
 320 extern location_spec_up string_to_location_spec
 321   (const char **argp, const struct language_defn *language,
 322    symbol_name_match_type match_type = symbol_name_match_type::WILD);
 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
 328 extern 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.  */
 335 struct explicit_completion_info
 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".  */
 352   bool saw_explicit_location_spec_option = false;
 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
 365 extern 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 */