gdb/location.h

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