1 /* Data structures and API for location specs in GDB. 2 Copyright (C) 2013-2023 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 location_spec; 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 = 0; 50 enum offset_relative_sign sign = LINE_OFFSET_UNKNOWN; 51 }; 52 53 /* An enumeration of the various ways to specify a location spec. */ 54 55 enum location_spec_type 56 { 57 /* A traditional linespec. */ 58 LINESPEC_LOCATION_SPEC, 59 60 /* An address location spec. */ 61 ADDRESS_LOCATION_SPEC, 62 63 /* An explicit location spec. */ 64 EXPLICIT_LOCATION_SPEC, 65 66 /* A probe location spec. */ 67 PROBE_LOCATION_SPEC 68 }; 69 70 /* A unique pointer for location_spec. */ 71 typedef std::unique_ptr<location_spec> location_spec_up; 72 73 /* The base class for all location specs used to resolve actual 74 locations in the inferior. */ 75 76 struct location_spec 77 { 78 virtual ~location_spec () = default; 79 80 /* Clone this object. */ 81 virtual location_spec_up clone () const = 0; 82 83 /* Return true if this location spec is empty, false otherwise. */ 84 virtual bool empty_p () const = 0; 85 86 /* Return a string representation of this location. 87 88 This function may return NULL for unspecified linespecs, e.g, 89 LINESPEC_LOCATION_SPEC and spec_string is NULL. 90 91 The result is cached in the locspec. */ 92 const char *to_string () const 93 { 94 if (m_as_string.empty ()) 95 m_as_string = compute_string (); 96 if (m_as_string.empty ()) 97 return nullptr; 98 return m_as_string.c_str (); 99 } 100 101 /* Set this location spec's string representation. */ 102 void set_string (std::string &&string) 103 { 104 m_as_string = std::move (string); 105 } 106 107 /* Return this location spec's type. */ 108 enum location_spec_type type () const 109 { 110 return m_type; 111 } 112 113 protected: 114 115 explicit location_spec (enum location_spec_type t) 116 : m_type (t) 117 { 118 } 119 120 location_spec (enum location_spec_type t, std::string &&str) 121 : m_as_string (std::move (str)), 122 m_type (t) 123 { 124 } 125 126 location_spec (const location_spec &other) 127 : m_as_string (other.m_as_string), 128 m_type (other.m_type) 129 { 130 } 131 132 /* Compute the string representation of this object. This is called 133 by to_string when needed. */ 134 virtual std::string compute_string () const = 0; 135 136 /* Cached string representation of this location spec. This is 137 used, e.g., to save location specs to file. */ 138 mutable std::string m_as_string; 139 140 private: 141 /* The type of this location specification. */ 142 enum location_spec_type m_type; 143 }; 144 145 /* A "normal" linespec. */ 146 147 struct linespec_location_spec : public location_spec 148 { 149 linespec_location_spec (const char **linespec, 150 symbol_name_match_type match_type); 151 152 ~linespec_location_spec (); 153 154 location_spec_up clone () const override; 155 156 bool empty_p () const override; 157 158 /* Whether the function name is fully-qualified or not. */ 159 symbol_name_match_type match_type; 160 161 /* The linespec. */ 162 char *spec_string = nullptr; 163 164 protected: 165 linespec_location_spec (const linespec_location_spec &other); 166 167 std::string compute_string () const override; 168 }; 169 170 /* An address in the inferior. */ 171 struct address_location_spec : public location_spec 172 { 173 address_location_spec (CORE_ADDR addr, const char *addr_string, 174 int addr_string_len); 175 176 location_spec_up clone () const override; 177 178 bool empty_p () const override; 179 180 CORE_ADDR address; 181 182 protected: 183 address_location_spec (const address_location_spec &other); 184 185 std::string compute_string () const override; 186 }; 187 188 /* An explicit location spec. This structure is used to bypass the 189 parsing done on linespecs. It still has the same requirements 190 as linespecs, though. For example, source_filename requires 191 at least one other field. */ 192 193 struct explicit_location_spec : public location_spec 194 { 195 explicit_location_spec (); 196 197 ~explicit_location_spec (); 198 199 location_spec_up clone () const override; 200 201 bool empty_p () const override; 202 203 /* Return a linespec string representation of this explicit location 204 spec. The explicit location spec must already be 205 canonicalized/valid. */ 206 std::string to_linespec () const; 207 208 /* The source filename. Malloc'd. */ 209 char *source_filename = nullptr; 210 211 /* The function name. Malloc'd. */ 212 char *function_name = nullptr; 213 214 /* Whether the function name is fully-qualified or not. */ 215 symbol_name_match_type func_name_match_type 216 = symbol_name_match_type::WILD; 217 218 /* The name of a label. Malloc'd. */ 219 char *label_name = nullptr; 220 221 /* A line offset relative to the start of the symbol 222 identified by the above fields or the current symtab 223 if the other fields are NULL. */ 224 struct line_offset line_offset; 225 226 protected: 227 explicit_location_spec (const explicit_location_spec &other); 228 229 std::string compute_string () const override; 230 }; 231 232 /* A probe. */ 233 struct probe_location_spec : public location_spec 234 { 235 explicit probe_location_spec (std::string &&probe); 236 237 location_spec_up clone () const override; 238 239 bool empty_p () const override; 240 241 protected: 242 probe_location_spec (const probe_location_spec &other) = default; 243 244 std::string compute_string () const override; 245 }; 246 247 /* Create a new linespec location spec. */ 248 249 extern location_spec_up new_linespec_location_spec 250 (const char **linespec, symbol_name_match_type match_type); 251 252 /* Return the given location_spec as a linespec_location_spec. 253 LOCSPEC must be of type LINESPEC_LOCATION_SPEC. */ 254 255 extern const linespec_location_spec * 256 as_linespec_location_spec (const location_spec *locspec); 257 258 /* Create a new address location spec. 259 ADDR is the address corresponding to this location_spec. 260 ADDR_STRING, a string of ADDR_STRING_LEN characters, is 261 the expression that was parsed to determine the address ADDR. */ 262 263 extern location_spec_up new_address_location_spec (CORE_ADDR addr, 264 const char *addr_string, 265 int addr_string_len); 266 267 /* Return the given location_spec as an address_location_spec. 268 LOCSPEC must be of type ADDRESS_LOCATION_SPEC. */ 269 270 const address_location_spec * 271 as_address_location_spec (const location_spec *locspec); 272 273 /* Create a new probe location. */ 274 275 extern location_spec_up new_probe_location_spec (std::string &&probe); 276 277 /* Assuming LOCSPEC is of type PROBE_LOCATION_SPEC, return LOCSPEC 278 cast to probe_location_spec. */ 279 280 const probe_location_spec * 281 as_probe_location_spec (const location_spec *locspec); 282 283 /* Create a new explicit location with explicit FUNCTION_NAME. All 284 other fields are defaulted. */ 285 286 static inline location_spec_up 287 new_explicit_location_spec_function (const char *function_name) 288 { 289 explicit_location_spec *spec 290 = new explicit_location_spec (); 291 spec->function_name 292 = (function_name != nullptr ? xstrdup (function_name) : nullptr); 293 return location_spec_up (spec); 294 } 295 296 /* Assuming LOCSPEC is of type EXPLICIT_LOCATION_SPEC, return LOCSPEC 297 cast to explicit_location_spec. */ 298 299 const explicit_location_spec * 300 as_explicit_location_spec (const location_spec *locspec); 301 explicit_location_spec * 302 as_explicit_location_spec (location_spec *locspec); 303 304 /* Attempt to convert the input string in *ARGP into a location_spec. 305 ARGP is advanced past any processed input. Always returns a non-nullptr 306 location_spec unique pointer object. 307 308 This function may call error() if *ARGP looks like properly formed, but 309 invalid, input, e.g., if it is called with missing argument parameters 310 or invalid options. 311 312 This function is intended to be used by CLI commands and will parse 313 explicit location specs in a CLI-centric way. Other interfaces should use 314 string_to_location_spec_basic if they want to maintain support for 315 legacy specifications of probe, address, and linespec location specs. 316 317 MATCH_TYPE should be either WILD or FULL. If -q/--qualified is specified 318 in the input string, it will take precedence over this parameter. */ 319 320 extern location_spec_up string_to_location_spec 321 (const char **argp, const struct language_defn *language, 322 symbol_name_match_type match_type = symbol_name_match_type::WILD); 323 324 /* Like string_to_location_spec, but does not attempt to parse 325 explicit location specs. MATCH_TYPE indicates how function names 326 should be matched. */ 327 328 extern location_spec_up 329 string_to_location_spec_basic (const char **argp, 330 const struct language_defn *language, 331 symbol_name_match_type match_type); 332 333 /* Structure filled in by string_to_explicit_location_spec to aid the 334 completer. */ 335 struct explicit_completion_info 336 { 337 /* Pointer to the last option found. E.g., in "b -sou src.c -fun 338 func", LAST_OPTION is left pointing at "-fun func". */ 339 const char *last_option = NULL; 340 341 /* These point to the start and end of a quoted argument, iff the 342 last argument was quoted. If parsing finds an incomplete quoted 343 string (e.g., "break -function 'fun"), then QUOTED_ARG_START is 344 set to point to the opening \', and QUOTED_ARG_END is left NULL. 345 If the last option is not quoted, then both are set to NULL. */ 346 const char *quoted_arg_start = NULL; 347 const char *quoted_arg_end = NULL; 348 349 /* True if we saw an explicit location spec option, as opposed to 350 only flags that affect both explicit location specs and 351 linespecs, like "-qualified". */ 352 bool saw_explicit_location_spec_option = false; 353 }; 354 355 /* Attempt to convert the input string in *ARGP into an explicit 356 location spec. ARGP is advanced past any processed input. Returns 357 a location_spec (malloc'd) if an explicit location spec was 358 successfully found in *ARGP, NULL otherwise. 359 360 If COMPLETION_INFO is NULL, this function may call error() if *ARGP 361 looks like improperly formed input, e.g., if it is called with 362 missing argument parameters or invalid options. If COMPLETION_INFO 363 is not NULL, this function will not throw any exceptions. */ 364 365 extern location_spec_up 366 string_to_explicit_location_spec (const char **argp, 367 const struct language_defn *language, 368 explicit_completion_info *completion_info); 369 370 #endif /* LOCATION_H */ 371