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.  Returns an event_location
 209    (malloc'd) if an event location was successfully found in *ARGP,
 210    NULL otherwise.
 211
 212    This function may call error() if *ARGP looks like properly formed,
 213    but invalid, input, e.g., if it is called with missing argument parameters
 214    or invalid options.
 215
 216    This function is intended to be used by CLI commands and will parse
 217    explicit locations in a CLI-centric way.  Other interfaces should use
 218    string_to_event_location_basic if they want to maintain support for
 219    legacy specifications of probe, address, and linespec locations.
 220
 221    MATCH_TYPE should be either WILD or FULL.  If -q/--qualified is specified
 222    in the input string, it will take precedence over this parameter.  */
 223
 224 extern event_location_up string_to_event_location
 225   (const char **argp, const struct language_defn *language,
 226    symbol_name_match_type match_type = symbol_name_match_type::WILD);
 227
 228 /* Like string_to_event_location, but does not attempt to parse
 229    explicit locations.  MATCH_TYPE indicates how function names should
 230    be matched.  */
 231
 232 extern event_location_up
 233   string_to_event_location_basic (const char **argp,
 234                                   const struct language_defn *language,
 235                                   symbol_name_match_type match_type);
 236
 237 /* Structure filled in by string_to_explicit_location to aid the
 238    completer.  */
 239 struct explicit_completion_info
 240 {
 241   /* Pointer to the last option found.  E.g., in "b -sou src.c -fun
 242      func", LAST_OPTION is left pointing at "-fun func".  */
 243   const char *last_option = NULL;
 244
 245   /* These point to the start and end of a quoted argument, iff the
 246      last argument was quoted.  If parsing finds an incomplete quoted
 247      string (e.g., "break -function 'fun"), then QUOTED_ARG_START is
 248      set to point to the opening \', and QUOTED_ARG_END is left NULL.
 249      If the last option is not quoted, then both are set to NULL. */
 250   const char *quoted_arg_start = NULL;
 251   const char *quoted_arg_end = NULL;
 252
 253   /* True if we saw an explicit location option, as opposed to only
 254      flags that affect both explicit locations and linespecs, like
 255      "-qualified".  */
 256   bool saw_explicit_location_option = false;
 257 };
 258
 259 /* Attempt to convert the input string in *ARGP into an explicit location.
 260    ARGP is advanced past any processed input.  Returns an event_location
 261    (malloc'd) if an explicit location was successfully found in *ARGP,
 262    NULL otherwise.
 263
 264    If COMPLETION_INFO is NULL, this function may call error() if *ARGP
 265    looks like improperly formed input, e.g., if it is called with
 266    missing argument parameters or invalid options.  If COMPLETION_INFO
 267    is not NULL, this function will not throw any exceptions.  */
 268
 269 extern event_location_up
 270   string_to_explicit_location (const char **argp,
 271                                const struct language_defn *language,
 272                                explicit_completion_info *completion_info);
 273
 274 /* A convenience function for testing for unset locations.  */
 275
 276 extern int event_location_empty_p (const struct event_location *location);
 277
 278 /* Set the location's string representation.  */
 279
 280 extern void
 281   set_event_location_string (struct event_location *location,
 282                              std::string &&string);
 283
 284 #endif /* LOCATION_H */