1 /* Data structures and API for event locations in GDB. 2 Copyright (C) 2013-2020 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 malloc'd explicit string representation of the given 113 explicit location. The location must already be canonicalized/valid. */ 114 115 extern char * 116 explicit_location_to_string (const struct explicit_location *explicit_loc); 117 118 /* Return a malloc'd linespec string representation of the given 119 explicit location. The location must already be canonicalized/valid. */ 120 121 extern char * 122 explicit_location_to_linespec (const struct explicit_location *explicit_loc); 123 124 /* Return a string representation of the LOCATION. 125 This function may return NULL for unspecified linespecs, 126 e.g, LINESPEC_LOCATION and spec_string is NULL. 127 128 The result is cached in LOCATION. */ 129 130 extern const char * 131 event_location_to_string (struct event_location *location); 132 133 /* A deleter for a struct event_location. */ 134 135 struct event_location_deleter 136 { 137 void operator() (event_location *location) const; 138 }; 139 140 /* A unique pointer for event_location. */ 141 typedef std::unique_ptr<event_location, event_location_deleter> 142 event_location_up; 143 144 /* Create a new linespec location. */ 145 146 extern event_location_up new_linespec_location 147 (const char **linespec, symbol_name_match_type match_type); 148 149 /* Return the linespec location of the given event_location (which 150 must be of type LINESPEC_LOCATION). */ 151 152 extern const linespec_location * 153 get_linespec_location (const struct event_location *location); 154 155 /* Create a new address location. 156 ADDR is the address corresponding to this event_location. 157 ADDR_STRING, a string of ADDR_STRING_LEN characters, is 158 the expression that was parsed to determine the address ADDR. */ 159 160 extern event_location_up new_address_location (CORE_ADDR addr, 161 const char *addr_string, 162 int addr_string_len); 163 164 /* Return the address location (a CORE_ADDR) of the given event_location 165 (which must be of type ADDRESS_LOCATION). */ 166 167 extern CORE_ADDR 168 get_address_location (const struct event_location *location); 169 170 /* Return the expression (a string) that was used to compute the address 171 of the given event_location (which must be of type ADDRESS_LOCATION). */ 172 173 extern const char * 174 get_address_string_location (const struct event_location *location); 175 176 /* Create a new probe location. */ 177 178 extern event_location_up new_probe_location (const char *probe); 179 180 /* Return the probe location (a string) of the given event_location 181 (which must be of type PROBE_LOCATION). */ 182 183 extern const char * 184 get_probe_location (const struct event_location *location); 185 186 /* Initialize the given explicit location. */ 187 188 extern void 189 initialize_explicit_location (struct explicit_location *explicit_loc); 190 191 /* Create a new explicit location. If not NULL, EXPLICIT is checked for 192 validity. If invalid, an exception is thrown. */ 193 194 extern event_location_up 195 new_explicit_location (const struct explicit_location *explicit_loc); 196 197 /* Return the explicit location of the given event_location 198 (which must be of type EXPLICIT_LOCATION). */ 199 200 extern struct explicit_location * 201 get_explicit_location (struct event_location *location); 202 203 /* A const version of the above. */ 204 205 extern const struct explicit_location * 206 get_explicit_location_const (const struct event_location *location); 207 208 /* Return a copy of the given SRC location. */ 209 210 extern event_location_up 211 copy_event_location (const struct event_location *src); 212 213 /* Attempt to convert the input string in *ARGP into an event_location. 214 ARGP is advanced past any processed input. Returns an event_location 215 (malloc'd) if an event location was successfully found in *ARGP, 216 NULL otherwise. 217 218 This function may call error() if *ARGP looks like properly formed, 219 but invalid, input, e.g., if it is called with missing argument parameters 220 or invalid options. 221 222 This function is intended to be used by CLI commands and will parse 223 explicit locations in a CLI-centric way. Other interfaces should use 224 string_to_event_location_basic if they want to maintain support for 225 legacy specifications of probe, address, and linespec locations. 226 227 MATCH_TYPE should be either WILD or FULL. If -q/--qualified is specified 228 in the input string, it will take precedence over this parameter. */ 229 230 extern event_location_up string_to_event_location 231 (const char **argp, const struct language_defn *language, 232 symbol_name_match_type match_type = symbol_name_match_type::WILD); 233 234 /* Like string_to_event_location, but does not attempt to parse 235 explicit locations. MATCH_TYPE indicates how function names should 236 be matched. */ 237 238 extern event_location_up 239 string_to_event_location_basic (const char **argp, 240 const struct language_defn *language, 241 symbol_name_match_type match_type); 242 243 /* Structure filled in by string_to_explicit_location to aid the 244 completer. */ 245 struct explicit_completion_info 246 { 247 /* Pointer to the last option found. E.g., in "b -sou src.c -fun 248 func", LAST_OPTION is left pointing at "-fun func". */ 249 const char *last_option = NULL; 250 251 /* These point to the start and end of a quoted argument, iff the 252 last argument was quoted. If parsing finds an incomplete quoted 253 string (e.g., "break -function 'fun"), then QUOTED_ARG_START is 254 set to point to the opening \', and QUOTED_ARG_END is left NULL. 255 If the last option is not quoted, then both are set to NULL. */ 256 const char *quoted_arg_start = NULL; 257 const char *quoted_arg_end = NULL; 258 259 /* True if we saw an explicit location option, as opposed to only 260 flags that affect both explicit locations and linespecs, like 261 "-qualified". */ 262 bool saw_explicit_location_option = false; 263 }; 264 265 /* Attempt to convert the input string in *ARGP into an explicit location. 266 ARGP is advanced past any processed input. Returns an event_location 267 (malloc'd) if an explicit location was successfully found in *ARGP, 268 NULL otherwise. 269 270 If COMPLETION_INFO is NULL, this function may call error() if *ARGP 271 looks like improperly formed input, e.g., if it is called with 272 missing argument parameters or invalid options. If COMPLETION_INFO 273 is not NULL, this function will not throw any exceptions. */ 274 275 extern event_location_up 276 string_to_explicit_location (const char **argp, 277 const struct language_defn *language, 278 explicit_completion_info *completion_info); 279 280 /* A convenience function for testing for unset locations. */ 281 282 extern int event_location_empty_p (const struct event_location *location); 283 284 /* Set the location's string representation. If STRING is NULL, clear 285 the string representation. */ 286 287 extern void 288 set_event_location_string (struct event_location *location, 289 const char *string); 290 291 #endif /* LOCATION_H */ 292