1 /* Data structures and API for event locations in GDB.
2 Copyright (C) 2013-2022 Free Software Foundation, Inc.
4 This file is part of GDB.
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.
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.
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/>. */
25 struct event_location
;
27 /* An enumeration of possible signs for a line offset. */
29 enum offset_relative_sign
34 /* A plus sign ("+") */
37 /* A minus sign ("-") */
40 /* A special "sign" for unspecified offset. */
44 /* A line offset in a location. */
48 /* Line offset and any specified sign. */
50 enum offset_relative_sign sign
;
53 /* An enumeration of the various ways to specify a stop event
54 location (used with create_breakpoint). */
56 enum event_location_type
58 /* A traditional linespec. */
61 /* An address in the inferior. */
64 /* An explicit location. */
67 /* A probe location. */
71 /* A traditional linespec. */
73 struct linespec_location
75 /* Whether the function name is fully-qualified or not. */
76 symbol_name_match_type match_type
;
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. */
87 struct explicit_location
89 /* The source filename. Malloc'd. */
90 char *source_filename
;
92 /* The function name. Malloc'd. */
95 /* Whether the function name is fully-qualified or not. */
96 symbol_name_match_type func_name_match_type
;
98 /* The name of a label. Malloc'd. */
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
;
107 /* Return the type of the given event location. */
109 extern enum event_location_type
110 event_location_type (const struct event_location
*);
112 /* Return a linespec string representation of the given explicit
113 location. The location must already be canonicalized/valid. */
116 explicit_location_to_linespec (const struct explicit_location
*explicit_loc
);
118 /* Return a string representation of the LOCATION.
119 This function may return NULL for unspecified linespecs,
120 e.g, LINESPEC_LOCATION and spec_string is NULL.
122 The result is cached in LOCATION. */
125 event_location_to_string (struct event_location
*location
);
127 /* A deleter for a struct event_location. */
129 struct event_location_deleter
131 void operator() (event_location
*location
) const;
134 /* A unique pointer for event_location. */
135 typedef std::unique_ptr
<event_location
, event_location_deleter
>
138 /* Create a new linespec location. */
140 extern event_location_up new_linespec_location
141 (const char **linespec
, symbol_name_match_type match_type
);
143 /* Return the linespec location of the given event_location (which
144 must be of type LINESPEC_LOCATION). */
146 extern const linespec_location
*
147 get_linespec_location (const struct event_location
*location
);
149 /* Create a new address location.
150 ADDR is the address corresponding to this event_location.
151 ADDR_STRING, a string of ADDR_STRING_LEN characters, is
152 the expression that was parsed to determine the address ADDR. */
154 extern event_location_up
new_address_location (CORE_ADDR addr
,
155 const char *addr_string
,
156 int addr_string_len
);
158 /* Return the address location (a CORE_ADDR) of the given event_location
159 (which must be of type ADDRESS_LOCATION). */
162 get_address_location (const struct event_location
*location
);
164 /* Return the expression (a string) that was used to compute the address
165 of the given event_location (which must be of type ADDRESS_LOCATION). */
168 get_address_string_location (const struct event_location
*location
);
170 /* Create a new probe location. */
172 extern event_location_up
new_probe_location (std::string
&&probe
);
174 /* Return the probe location (a string) of the given event_location
175 (which must be of type PROBE_LOCATION). */
178 get_probe_location (const struct event_location
*location
);
180 /* Initialize the given explicit location. */
183 initialize_explicit_location (struct explicit_location
*explicit_loc
);
185 /* Create a new explicit location. If not NULL, EXPLICIT is checked for
186 validity. If invalid, an exception is thrown. */
188 extern event_location_up
189 new_explicit_location (const struct explicit_location
*explicit_loc
);
191 /* Return the explicit location of the given event_location
192 (which must be of type EXPLICIT_LOCATION). */
194 extern struct explicit_location
*
195 get_explicit_location (struct event_location
*location
);
197 /* A const version of the above. */
199 extern const struct explicit_location
*
200 get_explicit_location_const (const struct event_location
*location
);
202 /* Return a copy of the given SRC location. */
204 extern event_location_up
205 copy_event_location (const struct event_location
*src
);
207 /* Attempt to convert the input string in *ARGP into an event_location.
208 ARGP is advanced past any processed input. Returns an event_location
209 (malloc'd) if an event location was successfully found in *ARGP,
212 This function may call error() if *ARGP looks like properly formed,
213 but invalid, input, e.g., if it is called with missing argument parameters
216 This function is intended to be used by CLI commands and will parse
217 explicit locations in a CLI-centric way. Other interfaces should use
218 string_to_event_location_basic if they want to maintain support for
219 legacy specifications of probe, address, and linespec locations.
221 MATCH_TYPE should be either WILD or FULL. If -q/--qualified is specified
222 in the input string, it will take precedence over this parameter. */
224 extern event_location_up string_to_event_location
225 (const char **argp
, const struct language_defn
*language
,
226 symbol_name_match_type match_type
= symbol_name_match_type::WILD
);
228 /* Like string_to_event_location, but does not attempt to parse
229 explicit locations. MATCH_TYPE indicates how function names should
232 extern event_location_up
233 string_to_event_location_basic (const char **argp
,
234 const struct language_defn
*language
,
235 symbol_name_match_type match_type
);
237 /* Structure filled in by string_to_explicit_location to aid the
239 struct explicit_completion_info
241 /* Pointer to the last option found. E.g., in "b -sou src.c -fun
242 func", LAST_OPTION is left pointing at "-fun func". */
243 const char *last_option
= NULL
;
245 /* These point to the start and end of a quoted argument, iff the
246 last argument was quoted. If parsing finds an incomplete quoted
247 string (e.g., "break -function 'fun"), then QUOTED_ARG_START is
248 set to point to the opening \', and QUOTED_ARG_END is left NULL.
249 If the last option is not quoted, then both are set to NULL. */
250 const char *quoted_arg_start
= NULL
;
251 const char *quoted_arg_end
= NULL
;
253 /* True if we saw an explicit location option, as opposed to only
254 flags that affect both explicit locations and linespecs, like
256 bool saw_explicit_location_option
= false;
259 /* Attempt to convert the input string in *ARGP into an explicit location.
260 ARGP is advanced past any processed input. Returns an event_location
261 (malloc'd) if an explicit location was successfully found in *ARGP,
264 If COMPLETION_INFO is NULL, this function may call error() if *ARGP
265 looks like improperly formed input, e.g., if it is called with
266 missing argument parameters or invalid options. If COMPLETION_INFO
267 is not NULL, this function will not throw any exceptions. */
269 extern event_location_up
270 string_to_explicit_location (const char **argp
,
271 const struct language_defn
*language
,
272 explicit_completion_info
*completion_info
);
274 /* A convenience function for testing for unset locations. */
276 extern int event_location_empty_p (const struct event_location
*location
);
278 /* Set the location's string representation. */
281 set_event_location_string (struct event_location
*location
,
282 std::string
&&string
);
284 #endif /* LOCATION_H */