gdb/location.h

   1 /* Data structures and API for event locations in GDB.
   2    Copyright (C) 2013-2022 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 event_location;
  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;
  50   enum offset_relative_sign sign;
  51 };
  52
  53 /* An enumeration of the various ways to specify a stop event
  54    location (used with create_breakpoint).  */
  55
  56 enum event_location_type
  57 {
  58   /* A traditional linespec.  */
  59   LINESPEC_LOCATION,
  60
  61   /* An address in the inferior.  */
  62   ADDRESS_LOCATION,
  63
  64   /* An explicit location.  */
  65   EXPLICIT_LOCATION,
  66
  67   /* A probe location.  */
  68   PROBE_LOCATION
  69 };
  70
  71 /* A traditional linespec.  */
  72
  73 struct linespec_location
  74 {
  75   /* Whether the function name is fully-qualified or not.  */
  76   symbol_name_match_type match_type;
  77
  78   /* The linespec.  */
  79   char *spec_string;
  80 };
  81
  82 /* An explicit location.  This structure is used to bypass the
  83    parsing done on linespecs.  It still has the same requirements
  84    as linespecs, though.  For example, source_filename requires
  85    at least one other field.  */
  86
  87 struct explicit_location
  88 {
  89   /* The source filename. Malloc'd.  */
  90   char *source_filename;
  91
  92   /* The function name.  Malloc'd.  */
  93   char *function_name;
  94
  95   /* Whether the function name is fully-qualified or not.  */
  96   symbol_name_match_type func_name_match_type;
  97
  98   /* The name of a label.  Malloc'd.  */
  99   char *label_name;
 100
 101   /* A line offset relative to the start of the symbol
 102      identified by the above fields or the current symtab
 103      if the other fields are NULL.  */
 104   struct line_offset line_offset;
 105 };
 106
 107 /* Return the type of the given event location.  */
 108
 109 extern enum event_location_type
 110   event_location_type (const struct event_location *);
 111
 112 /* Return a linespec string representation of the given explicit
 113    location.  The location must already be canonicalized/valid.  */
 114
 115 extern std::string
 116   explicit_location_to_linespec (const struct explicit_location *explicit_loc);
 117
 118 /* Return a string representation of the LOCATION.
 119    This function may return NULL for unspecified linespecs,
 120    e.g, LINESPEC_LOCATION and spec_string is NULL.
 121
 122    The result is cached in LOCATION.  */
 123
 124 extern const char *
 125   event_location_to_string (struct event_location *location);
 126
 127 /* A deleter for a struct event_location.  */
 128
 129 struct event_location_deleter
 130 {
 131   void operator() (event_location *location) const;
 132 };
 133
 134 /* A unique pointer for event_location.  */
 135 typedef std::unique_ptr<event_location, event_location_deleter>
 136      event_location_up;
 137
 138 /* Create a new linespec location.  */
 139
 140 extern event_location_up new_linespec_location
 141   (const char **linespec, symbol_name_match_type match_type);
 142
 143 /* Return the linespec location of the given event_location (which
 144    must be of type LINESPEC_LOCATION).  */
 145
 146 extern const linespec_location *
 147   get_linespec_location (const struct event_location *location);
 148
 149 /* Create a new address location.
 150    ADDR is the address corresponding to this event_location.
 151    ADDR_STRING, a string of ADDR_STRING_LEN characters, is
 152    the expression that was parsed to determine the address ADDR.  */
 153
 154 extern event_location_up new_address_location (CORE_ADDR addr,
 155                                                const char *addr_string,
 156                                                int addr_string_len);
 157
 158 /* Return the address location (a CORE_ADDR) of the given event_location
 159    (which must be of type ADDRESS_LOCATION).  */
 160
 161 extern CORE_ADDR
 162   get_address_location (const struct event_location *location);
 163
 164 /* Return the expression (a string) that was used to compute the address
 165    of the given event_location (which must be of type ADDRESS_LOCATION).  */
 166
 167 extern const char *
 168   get_address_string_location (const struct event_location *location);
 169
 170 /* Create a new probe location.  */
 171
 172 extern event_location_up new_probe_location (std::string &&probe);
 173
 174 /* Return the probe location (a string) of the given event_location
 175    (which must be of type PROBE_LOCATION).  */
 176
 177 extern const char *
 178   get_probe_location (const struct event_location *location);
 179
 180 /* Initialize the given explicit location.  */
 181
 182 extern void
 183   initialize_explicit_location (struct explicit_location *explicit_loc);
 184
 185 /* Create a new explicit location.  If not NULL, EXPLICIT is checked for
 186    validity.  If invalid, an exception is thrown.  */
 187
 188 extern event_location_up
 189   new_explicit_location (const struct explicit_location *explicit_loc);
 190
 191 /* Return the explicit location of the given event_location
 192    (which must be of type EXPLICIT_LOCATION).  */
 193
 194 extern struct explicit_location *
 195   get_explicit_location (struct event_location *location);
 196
 197 /* A const version of the above.  */
 198
 199 extern const struct explicit_location *
 200   get_explicit_location_const (const struct event_location *location);
 201
 202 /* Return a copy of the given SRC location.  */
 203
 204 extern event_location_up
 205   copy_event_location (const struct event_location *src);
 206
 207 /* Attempt to convert the input string in *ARGP into an event_location.
 208    ARGP is advanced past any processed input.  Always returns a non-nullptr
 209    event_location unique pointer object.
 210
 211    This function may call error() if *ARGP looks like properly formed, but
 212    invalid, input, e.g., if it is called with missing argument parameters
 213    or invalid options.
 214
 215    This function is intended to be used by CLI commands and will parse
 216    explicit locations in a CLI-centric way.  Other interfaces should use
 217    string_to_event_location_basic if they want to maintain support for
 218    legacy specifications of probe, address, and linespec locations.
 219
 220    MATCH_TYPE should be either WILD or FULL.  If -q/--qualified is specified
 221    in the input string, it will take precedence over this parameter.  */
 222
 223 extern event_location_up string_to_event_location
 224   (const char **argp, const struct language_defn *language,
 225    symbol_name_match_type match_type = symbol_name_match_type::WILD);
 226
 227 /* Like string_to_event_location, but does not attempt to parse
 228    explicit locations.  MATCH_TYPE indicates how function names should
 229    be matched.  */
 230
 231 extern event_location_up
 232   string_to_event_location_basic (const char **argp,
 233                                   const struct language_defn *language,
 234                                   symbol_name_match_type match_type);
 235
 236 /* Structure filled in by string_to_explicit_location to aid the
 237    completer.  */
 238 struct explicit_completion_info
 239 {
 240   /* Pointer to the last option found.  E.g., in "b -sou src.c -fun
 241      func", LAST_OPTION is left pointing at "-fun func".  */
 242   const char *last_option = NULL;
 243
 244   /* These point to the start and end of a quoted argument, iff the
 245      last argument was quoted.  If parsing finds an incomplete quoted
 246      string (e.g., "break -function 'fun"), then QUOTED_ARG_START is
 247      set to point to the opening \', and QUOTED_ARG_END is left NULL.
 248      If the last option is not quoted, then both are set to NULL. */
 249   const char *quoted_arg_start = NULL;
 250   const char *quoted_arg_end = NULL;
 251
 252   /* True if we saw an explicit location option, as opposed to only
 253      flags that affect both explicit locations and linespecs, like
 254      "-qualified".  */
 255   bool saw_explicit_location_option = false;
 256 };
 257
 258 /* Attempt to convert the input string in *ARGP into an explicit location.
 259    ARGP is advanced past any processed input.  Returns an event_location
 260    (malloc'd) if an explicit location was successfully found in *ARGP,
 261    NULL otherwise.
 262
 263    If COMPLETION_INFO is NULL, this function may call error() if *ARGP
 264    looks like improperly formed input, e.g., if it is called with
 265    missing argument parameters or invalid options.  If COMPLETION_INFO
 266    is not NULL, this function will not throw any exceptions.  */
 267
 268 extern event_location_up
 269   string_to_explicit_location (const char **argp,
 270                                const struct language_defn *language,
 271                                explicit_completion_info *completion_info);
 272
 273 /* A convenience function for testing for unset locations.  */
 274
 275 extern int event_location_empty_p (const struct event_location *location);
 276
 277 /* Set the location's string representation.  */
 278
 279 extern void
 280   set_event_location_string (struct event_location *location,
 281                              std::string &&string);
 282
 283 #endif /* LOCATION_H */