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 /* Free an event location and any associated data.  */
 118
 119 extern void delete_event_location (struct event_location *location);
 120
 121 /* A deleter for a struct event_location.  */
 122
 123 struct event_location_deleter
 124 {
 125   void operator() (event_location *location) const
 126   {
 127     delete_event_location (location);
 128   }
 129 };
 130
 131 /* A unique pointer for event_location.  */
 132 typedef std::unique_ptr<event_location, event_location_deleter>
 133      event_location_up;
 134
 135 /* Create a new linespec location.  */
 136
 137 extern event_location_up new_linespec_location (char **linespec);
 138
 139 /* Return the linespec location (a string) of the given event_location
 140    (which must be of type LINESPEC_LOCATION).  */
 141
 142 extern const char *
 143   get_linespec_location (const struct event_location *location);
 144
 145 /* Create a new address location.
 146    ADDR is the address corresponding to this event_location.
 147    ADDR_STRING, a string of ADDR_STRING_LEN characters, is
 148    the expression that was parsed to determine the address ADDR.  */
 149
 150 extern event_location_up new_address_location (CORE_ADDR addr,
 151                                                const char *addr_string,
 152                                                int addr_string_len);
 153
 154 /* Return the address location (a CORE_ADDR) of the given event_location
 155    (which must be of type ADDRESS_LOCATION).  */
 156
 157 extern CORE_ADDR
 158   get_address_location (const struct event_location *location);
 159
 160 /* Return the expression (a string) that was used to compute the address
 161    of the given event_location (which must be of type ADDRESS_LOCATION).  */
 162
 163 extern const char *
 164   get_address_string_location (const struct event_location *location);
 165
 166 /* Create a new probe location.  */
 167
 168 extern event_location_up new_probe_location (const char *probe);
 169
 170 /* Return the probe location (a string) of the given event_location
 171    (which must be of type PROBE_LOCATION).  */
 172
 173 extern const char *
 174   get_probe_location (const struct event_location *location);
 175
 176 /* Initialize the given explicit location.  */
 177
 178 extern void
 179   initialize_explicit_location (struct explicit_location *explicit_loc);
 180
 181 /* Create a new explicit location.  If not NULL, EXPLICIT is checked for
 182    validity.  If invalid, an exception is thrown.  */
 183
 184 extern event_location_up
 185   new_explicit_location (const struct explicit_location *explicit_loc);
 186
 187 /* Return the explicit location of the given event_location
 188    (which must be of type EXPLICIT_LOCATION).  */
 189
 190 extern struct explicit_location *
 191   get_explicit_location (struct event_location *location);
 192
 193 /* A const version of the above.  */
 194
 195 extern const struct explicit_location *
 196   get_explicit_location_const (const struct event_location *location);
 197
 198 /* Return a copy of the given SRC location.  */
 199
 200 extern event_location_up
 201   copy_event_location (const struct event_location *src);
 202
 203 /* Attempt to convert the input string in *ARGP into an event_location.
 204    ARGP is advanced past any processed input.  Returns an event_location
 205    (malloc'd) if an event location was successfully found in *ARGP,
 206    NULL otherwise.
 207
 208    This function may call error() if *ARGP looks like properly formed,
 209    but invalid, input, e.g., if it is called with missing argument parameters
 210    or invalid options.
 211
 212    This function is intended to be used by CLI commands and will parse
 213    explicit locations in a CLI-centric way.  Other interfaces should use
 214    string_to_event_location_basic if they want to maintain support for
 215    legacy specifications of probe, address, and linespec locations.  */
 216
 217 extern event_location_up
 218   string_to_event_location (char **argp,
 219                             const struct language_defn *langauge);
 220
 221 /* Like string_to_event_location, but does not attempt to parse explicit
 222    locations.  */
 223
 224 extern event_location_up
 225   string_to_event_location_basic (char **argp,
 226                                   const struct language_defn *language);
 227
 228 /* Attempt to convert the input string in *ARGP into an explicit location.
 229    ARGP is advanced past any processed input.  Returns an event_location
 230    (malloc'd) if an explicit location was successfully found in *ARGP,
 231    NULL otherwise.
 232
 233    IF !DONT_THROW, this function may call error() if *ARGP looks like
 234    properly formed input, e.g., if it is called with missing argument
 235    parameters or invalid options.  If DONT_THROW is non-zero, this function
 236    will not throw any exceptions.  */
 237
 238 extern event_location_up
 239   string_to_explicit_location (const char **argp,
 240                                const struct language_defn *langauge,
 241                                int dont_throw);
 242
 243 /* A convenience function for testing for unset locations.  */
 244
 245 extern int event_location_empty_p (const struct event_location *location);
 246
 247 /* Set the location's string representation.  If STRING is NULL, clear
 248    the string representation.  */
 249
 250 extern void
 251   set_event_location_string (struct event_location *location,
 252                              const char *string);
 253 #endif /* LOCATIONS_H */