gdb/location.h

   1 /* Data structures and API for event locations in GDB.
   2    Copyright (C) 2013-2020 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 malloc'd explicit string representation of the given
 113    explicit location.  The location must already be canonicalized/valid.  */
 114
 115 extern char *
 116   explicit_location_to_string (const struct explicit_location *explicit_loc);
 117
 118 /* Return a malloc'd linespec string representation of the given
 119    explicit location.  The location must already be canonicalized/valid.  */
 120
 121 extern char *
 122   explicit_location_to_linespec (const struct explicit_location *explicit_loc);
 123
 124 /* Return a string representation of the LOCATION.
 125    This function may return NULL for unspecified linespecs,
 126    e.g, LINESPEC_LOCATION and spec_string is NULL.
 127
 128    The result is cached in LOCATION.  */
 129
 130 extern const char *
 131   event_location_to_string (struct event_location *location);
 132
 133 /* A deleter for a struct event_location.  */
 134
 135 struct event_location_deleter
 136 {
 137   void operator() (event_location *location) const;
 138 };
 139
 140 /* A unique pointer for event_location.  */
 141 typedef std::unique_ptr<event_location, event_location_deleter>
 142      event_location_up;
 143
 144 /* Create a new linespec location.  */
 145
 146 extern event_location_up new_linespec_location
 147   (const char **linespec, symbol_name_match_type match_type);
 148
 149 /* Return the linespec location of the given event_location (which
 150    must be of type LINESPEC_LOCATION).  */
 151
 152 extern const linespec_location *
 153   get_linespec_location (const struct event_location *location);
 154
 155 /* Create a new address location.
 156    ADDR is the address corresponding to this event_location.
 157    ADDR_STRING, a string of ADDR_STRING_LEN characters, is
 158    the expression that was parsed to determine the address ADDR.  */
 159
 160 extern event_location_up new_address_location (CORE_ADDR addr,
 161                                                const char *addr_string,
 162                                                int addr_string_len);
 163
 164 /* Return the address location (a CORE_ADDR) of the given event_location
 165    (which must be of type ADDRESS_LOCATION).  */
 166
 167 extern CORE_ADDR
 168   get_address_location (const struct event_location *location);
 169
 170 /* Return the expression (a string) that was used to compute the address
 171    of the given event_location (which must be of type ADDRESS_LOCATION).  */
 172
 173 extern const char *
 174   get_address_string_location (const struct event_location *location);
 175
 176 /* Create a new probe location.  */
 177
 178 extern event_location_up new_probe_location (const char *probe);
 179
 180 /* Return the probe location (a string) of the given event_location
 181    (which must be of type PROBE_LOCATION).  */
 182
 183 extern const char *
 184   get_probe_location (const struct event_location *location);
 185
 186 /* Initialize the given explicit location.  */
 187
 188 extern void
 189   initialize_explicit_location (struct explicit_location *explicit_loc);
 190
 191 /* Create a new explicit location.  If not NULL, EXPLICIT is checked for
 192    validity.  If invalid, an exception is thrown.  */
 193
 194 extern event_location_up
 195   new_explicit_location (const struct explicit_location *explicit_loc);
 196
 197 /* Return the explicit location of the given event_location
 198    (which must be of type EXPLICIT_LOCATION).  */
 199
 200 extern struct explicit_location *
 201   get_explicit_location (struct event_location *location);
 202
 203 /* A const version of the above.  */
 204
 205 extern const struct explicit_location *
 206   get_explicit_location_const (const struct event_location *location);
 207
 208 /* Return a copy of the given SRC location.  */
 209
 210 extern event_location_up
 211   copy_event_location (const struct event_location *src);
 212
 213 /* Attempt to convert the input string in *ARGP into an event_location.
 214    ARGP is advanced past any processed input.  Returns an event_location
 215    (malloc'd) if an event location was successfully found in *ARGP,
 216    NULL otherwise.
 217
 218    This function may call error() if *ARGP looks like properly formed,
 219    but invalid, input, e.g., if it is called with missing argument parameters
 220    or invalid options.
 221
 222    This function is intended to be used by CLI commands and will parse
 223    explicit locations in a CLI-centric way.  Other interfaces should use
 224    string_to_event_location_basic if they want to maintain support for
 225    legacy specifications of probe, address, and linespec locations.
 226
 227    MATCH_TYPE should be either WILD or FULL.  If -q/--qualified is specified
 228    in the input string, it will take precedence over this parameter.  */
 229
 230 extern event_location_up string_to_event_location
 231   (const char **argp, const struct language_defn *language,
 232    symbol_name_match_type match_type = symbol_name_match_type::WILD);
 233
 234 /* Like string_to_event_location, but does not attempt to parse
 235    explicit locations.  MATCH_TYPE indicates how function names should
 236    be matched.  */
 237
 238 extern event_location_up
 239   string_to_event_location_basic (const char **argp,
 240                                   const struct language_defn *language,
 241                                   symbol_name_match_type match_type);
 242
 243 /* Structure filled in by string_to_explicit_location to aid the
 244    completer.  */
 245 struct explicit_completion_info
 246 {
 247   /* Pointer to the last option found.  E.g., in "b -sou src.c -fun
 248      func", LAST_OPTION is left pointing at "-fun func".  */
 249   const char *last_option = NULL;
 250
 251   /* These point to the start and end of a quoted argument, iff the
 252      last argument was quoted.  If parsing finds an incomplete quoted
 253      string (e.g., "break -function 'fun"), then QUOTED_ARG_START is
 254      set to point to the opening \', and QUOTED_ARG_END is left NULL.
 255      If the last option is not quoted, then both are set to NULL. */
 256   const char *quoted_arg_start = NULL;
 257   const char *quoted_arg_end = NULL;
 258
 259   /* True if we saw an explicit location option, as opposed to only
 260      flags that affect both explicit locations and linespecs, like
 261      "-qualified".  */
 262   bool saw_explicit_location_option = false;
 263 };
 264
 265 /* Attempt to convert the input string in *ARGP into an explicit location.
 266    ARGP is advanced past any processed input.  Returns an event_location
 267    (malloc'd) if an explicit location was successfully found in *ARGP,
 268    NULL otherwise.
 269
 270    If COMPLETION_INFO is NULL, this function may call error() if *ARGP
 271    looks like improperly formed input, e.g., if it is called with
 272    missing argument parameters or invalid options.  If COMPLETION_INFO
 273    is not NULL, this function will not throw any exceptions.  */
 274
 275 extern event_location_up
 276   string_to_explicit_location (const char **argp,
 277                                const struct language_defn *language,
 278                                explicit_completion_info *completion_info);
 279
 280 /* A convenience function for testing for unset locations.  */
 281
 282 extern int event_location_empty_p (const struct event_location *location);
 283
 284 /* Set the location's string representation.  If STRING is NULL, clear
 285    the string representation.  */
 286
 287 extern void
 288   set_event_location_string (struct event_location *location,
 289                              const char *string);
 290
 291 #endif /* LOCATION_H */