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.  The return result is malloc'd
 130    and should be freed with delete_event_location.  */
 131
 132 extern struct event_location *
 133   new_address_location (CORE_ADDR addr);
 134
 135 /* Return the address location (a CORE_ADDR) of the given event_location
 136    (which must be of type ADDRESS_LOCATION).  */
 137
 138 extern CORE_ADDR
 139   get_address_location (const struct event_location *location);
 140
 141 /* Create a new probe location.  The return result is malloc'd
 142    and should be freed with delete_event_location.  */
 143
 144 extern struct event_location *
 145   new_probe_location (const char *probe);
 146
 147 /* Return the probe location (a string) of the given event_location
 148    (which must be of type PROBE_LOCATION).  */
 149
 150 extern const char *
 151   get_probe_location (const struct event_location *location);
 152
 153 /* Initialize the given explicit location.  */
 154
 155 extern void
 156   initialize_explicit_location (struct explicit_location *explicit_loc);
 157
 158 /* Create a new explicit location.  If not NULL, EXPLICIT is checked for
 159    validity.  If invalid, an exception is thrown.
 160
 161    The return result is malloc'd and should be freed with
 162    delete_event_location.  */
 163
 164 extern struct event_location *
 165   new_explicit_location (const struct explicit_location *explicit_loc);
 166
 167 /* Return the explicit location of the given event_location
 168    (which must be of type EXPLICIT_LOCATION).  */
 169
 170 extern struct explicit_location *
 171   get_explicit_location (struct event_location *location);
 172
 173 /* A const version of the above.  */
 174
 175 extern const struct explicit_location *
 176   get_explicit_location_const (const struct event_location *location);
 177
 178 /* Free an event location and any associated data.  */
 179
 180 extern void delete_event_location (struct event_location *location);
 181
 182 /* Make a cleanup to free LOCATION.  */
 183
 184 extern struct cleanup *
 185   make_cleanup_delete_event_location (struct event_location *location);
 186
 187 /* Return a copy of the given SRC location.  */
 188
 189 extern struct event_location *
 190   copy_event_location (const struct event_location *src);
 191
 192 /* Attempt to convert the input string in *ARGP into an event_location.
 193    ARGP is advanced past any processed input.  Returns an event_location
 194    (malloc'd) if an event location was successfully found in *ARGP,
 195    NULL otherwise.
 196
 197    This function may call error() if *ARGP looks like properly formed,
 198    but invalid, input, e.g., if it is called with missing argument parameters
 199    or invalid options.
 200
 201    The return result must be freed with delete_event_location.  */
 202
 203 extern struct event_location *
 204   string_to_event_location (char **argp,
 205                             const struct language_defn *langauge);
 206
 207 /* Attempt to convert the input string in *ARGP into an explicit location.
 208    ARGP is advanced past any processed input.  Returns an event_location
 209    (malloc'd) if an explicit location was successfully found in *ARGP,
 210    NULL otherwise.
 211
 212    IF !DONT_THROW, this function may call error() if *ARGP looks like
 213    properly formed input, e.g., if it is called with missing argument
 214    parameters or invalid options.  If DONT_THROW is non-zero, this function
 215    will not throw any exceptions.  */
 216
 217 extern struct event_location *
 218   string_to_explicit_location (const char **argp,
 219                                const struct language_defn *langauge,
 220                                int dont_throw);
 221
 222 /* A convenience function for testing for unset locations.  */
 223
 224 extern int event_location_empty_p (const struct event_location *location);
 225
 226 /* Set the location's string representation.  If STRING is NULL, clear
 227    the string representation.  */
 228
 229 extern void
 230   set_event_location_string (struct event_location *location,
 231                              const char *string);
 232 #endif /* LOCATIONS_H */