gdb/location.h

   1 /* Data structures and API for event locations in GDB.
   2    Copyright (C) 2013-2016 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 /* Create a new linespec location.  The return result is malloc'd
 118    and should be freed with delete_event_location.  */
 119
 120 extern struct event_location *
 121   new_linespec_location (char **linespec);
 122
 123 /* Return the linespec location (a string) of the given event_location
 124    (which must be of type LINESPEC_LOCATION).  */
 125
 126 extern const char *
 127   get_linespec_location (const struct event_location *location);
 128
 129 /* Create a new address location.
 130    ADDR is the address corresponding to this event_location.
 131    ADDR_STRING, a string of ADDR_STRING_LEN characters, is
 132    the expression that was parsed to determine the address ADDR.  */
 133
 134 extern struct event_location *
 135   new_address_location (CORE_ADDR addr, const char *addr_string,
 136                         int addr_string_len);
 137
 138 /* Return the address location (a CORE_ADDR) of the given event_location
 139    (which must be of type ADDRESS_LOCATION).  */
 140
 141 extern CORE_ADDR
 142   get_address_location (const struct event_location *location);
 143
 144 /* Return the expression (a string) that was used to compute the address
 145    of the given event_location (which must be of type ADDRESS_LOCATION).  */
 146
 147 extern const char *
 148   get_address_string_location (const struct event_location *location);
 149
 150 /* Create a new probe location.  The return result is malloc'd
 151    and should be freed with delete_event_location.  */
 152
 153 extern struct event_location *
 154   new_probe_location (const char *probe);
 155
 156 /* Return the probe location (a string) of the given event_location
 157    (which must be of type PROBE_LOCATION).  */
 158
 159 extern const char *
 160   get_probe_location (const struct event_location *location);
 161
 162 /* Initialize the given explicit location.  */
 163
 164 extern void
 165   initialize_explicit_location (struct explicit_location *explicit_loc);
 166
 167 /* Create a new explicit location.  If not NULL, EXPLICIT is checked for
 168    validity.  If invalid, an exception is thrown.
 169
 170    The return result is malloc'd and should be freed with
 171    delete_event_location.  */
 172
 173 extern struct event_location *
 174   new_explicit_location (const struct explicit_location *explicit_loc);
 175
 176 /* Return the explicit location of the given event_location
 177    (which must be of type EXPLICIT_LOCATION).  */
 178
 179 extern struct explicit_location *
 180   get_explicit_location (struct event_location *location);
 181
 182 /* A const version of the above.  */
 183
 184 extern const struct explicit_location *
 185   get_explicit_location_const (const struct event_location *location);
 186
 187 /* Free an event location and any associated data.  */
 188
 189 extern void delete_event_location (struct event_location *location);
 190
 191 /* Make a cleanup to free LOCATION.  */
 192
 193 extern struct cleanup *
 194   make_cleanup_delete_event_location (struct event_location *location);
 195
 196 /* Return a copy of the given SRC location.  */
 197
 198 extern struct event_location *
 199   copy_event_location (const struct event_location *src);
 200
 201 /* Attempt to convert the input string in *ARGP into an event_location.
 202    ARGP is advanced past any processed input.  Returns an event_location
 203    (malloc'd) if an event location was successfully found in *ARGP,
 204    NULL otherwise.
 205
 206    This function may call error() if *ARGP looks like properly formed,
 207    but invalid, input, e.g., if it is called with missing argument parameters
 208    or invalid options.
 209
 210    The return result must be freed with delete_event_location.
 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 struct event_location *
 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 struct event_location *
 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 struct event_location *
 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 */