Commit | Line | Data |
---|---|---|
c7c1b3e9 | 1 | /* Data structures and API for event locations in GDB. |
618f726f | 2 | Copyright (C) 2013-2016 Free Software Foundation, Inc. |
c7c1b3e9 KS |
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 | ||
00e52e53 KS |
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 | ||
c7c1b3e9 KS |
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. */ | |
a06efdd6 KS |
57 | LINESPEC_LOCATION, |
58 | ||
59 | /* An address in the inferior. */ | |
5b56227b KS |
60 | ADDRESS_LOCATION, |
61 | ||
00e52e53 KS |
62 | /* An explicit location. */ |
63 | EXPLICIT_LOCATION, | |
64 | ||
5b56227b KS |
65 | /* A probe location. */ |
66 | PROBE_LOCATION | |
c7c1b3e9 KS |
67 | }; |
68 | ||
00e52e53 KS |
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 | ||
c7c1b3e9 KS |
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 | ||
00e52e53 KS |
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 * | |
67994074 | 100 | explicit_location_to_string (const struct explicit_location *explicit_loc); |
00e52e53 KS |
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 * | |
67994074 | 106 | explicit_location_to_linespec (const struct explicit_location *explicit_loc); |
00e52e53 | 107 | |
c7c1b3e9 KS |
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 | ||
305e13e6 JB |
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. */ | |
a06efdd6 KS |
133 | |
134 | extern struct event_location * | |
305e13e6 JB |
135 | new_address_location (CORE_ADDR addr, const char *addr_string, |
136 | int addr_string_len); | |
a06efdd6 KS |
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 | ||
305e13e6 JB |
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 | ||
5b56227b KS |
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 | ||
00e52e53 KS |
162 | /* Initialize the given explicit location. */ |
163 | ||
67994074 KS |
164 | extern void |
165 | initialize_explicit_location (struct explicit_location *explicit_loc); | |
00e52e53 KS |
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 * | |
67994074 | 174 | new_explicit_location (const struct explicit_location *explicit_loc); |
00e52e53 KS |
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 | ||
c7c1b3e9 KS |
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 | ||
eeb1af43 KS |
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. */ | |
c7c1b3e9 KS |
216 | |
217 | extern struct event_location * | |
218 | string_to_event_location (char **argp, | |
219 | const struct language_defn *langauge); | |
220 | ||
eeb1af43 KS |
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 | ||
87f0e720 KS |
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 | ||
c7c1b3e9 KS |
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 */ |