Commit | Line | Data |
---|---|---|
bcd7e15f | 1 | @c -*-texinfo-*- |
16d1a084 DJ |
2 | |
3 | @c This file is part of the GDB manual. | |
4 | @c | |
618f726f | 5 | @c Copyright (C) 2003-2016 Free Software Foundation, Inc. |
16d1a084 DJ |
6 | @c |
7 | @c See the file gdbint.texinfo for copying conditions. | |
8 | @c | |
9 | @c Also, the @deftypefun lines from this file are processed into a | |
10 | @c header file during the GDB build process. Permission is granted | |
11 | @c to redistribute and/or modify those lines under the terms of the | |
12 | @c GNU General Public License as published by the Free Software | |
a1715244 | 13 | @c Foundation; either version 3 of the License, or (at your option) |
16d1a084 DJ |
14 | @c any later version. |
15 | ||
bcd7e15f JB |
16 | @node GDB Observers |
17 | @appendix @value{GDBN} Currently available observers | |
18 | ||
19 | @section Implementation rationale | |
20 | @cindex observers implementation rationale | |
21 | ||
22 | An @dfn{observer} is an entity which is interested in being notified | |
23 | when GDB reaches certain states, or certain events occur in GDB. | |
24 | The entity being observed is called the @dfn{subject}. To receive | |
25 | notifications, the observer attaches a callback to the subject. | |
26 | One subject can have several observers. | |
27 | ||
28 | @file{observer.c} implements an internal generic low-level event | |
6be67e67 | 29 | notification mechanism. This generic event notification mechanism is |
bcd7e15f JB |
30 | then re-used to implement the exported high-level notification |
31 | management routines for all possible notifications. | |
32 | ||
33 | The current implementation of the generic observer provides support | |
34 | for contextual data. This contextual data is given to the subject | |
35 | when attaching the callback. In return, the subject will provide | |
36 | this contextual data back to the observer as a parameter of the | |
37 | callback. | |
38 | ||
39 | Note that the current support for the contextual data is only partial, | |
40 | as it lacks a mechanism that would deallocate this data when the | |
41 | callback is detached. This is not a problem so far, as this contextual | |
42 | data is only used internally to hold a function pointer. Later on, if | |
43 | a certain observer needs to provide support for user-level contextual | |
6be67e67 | 44 | data, then the generic notification mechanism will need to be |
bcd7e15f JB |
45 | enhanced to allow the observer to provide a routine to deallocate the |
46 | data when attaching the callback. | |
47 | ||
48 | The observer implementation is also currently not reentrant. | |
49 | In particular, it is therefore not possible to call the attach | |
50 | or detach routines during a notification. | |
51 | ||
2b4855ab AC |
52 | @section Debugging |
53 | Observer notifications can be traced using the command @samp{set debug | |
54 | observer 1} (@pxref{Debugging Output, , Optional messages about | |
55 | internal happenings, gdb, Debugging with @var{GDBN}}). | |
56 | ||
bcd7e15f JB |
57 | @section @code{normal_stop} Notifications |
58 | @cindex @code{normal_stop} observer | |
59 | @cindex notification about inferior execution stop | |
60 | ||
6be67e67 JB |
61 | @value{GDBN} notifies all @code{normal_stop} observers when the |
62 | inferior execution has just stopped, the associated messages and | |
63 | annotations have been printed, and the control is about to be returned | |
16d1a084 | 64 | to the user. |
6be67e67 JB |
65 | |
66 | Note that the @code{normal_stop} notification is not emitted when | |
67 | the execution stops due to a breakpoint, and this breakpoint has | |
68 | a condition that is not met. If the breakpoint has any associated | |
69 | commands list, the commands are executed after the notification | |
70 | is emitted. | |
bcd7e15f | 71 | |
7a464420 | 72 | The following interfaces are available to manage observers: |
bcd7e15f | 73 | |
7a464420 AC |
74 | @deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f}) |
75 | Using the function @var{f}, create an observer that is notified when | |
d3e8051b | 76 | ever @var{event} occurs, return the observer. |
bcd7e15f JB |
77 | @end deftypefun |
78 | ||
7a464420 | 79 | @deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer}); |
bcd7e15f | 80 | Remove @var{observer} from the list of observers to be notified when |
7a464420 | 81 | @var{event} occurs. |
bcd7e15f JB |
82 | @end deftypefun |
83 | ||
7a464420 AC |
84 | @deftypefun extern void observer_notify_@var{event} (void); |
85 | Send a notification to all @var{event} observers. | |
bcd7e15f JB |
86 | @end deftypefun |
87 | ||
7a464420 | 88 | The following observable events are defined: |
bcd7e15f | 89 | |
1d33d6ba VP |
90 | @deftypefun void normal_stop (struct bpstats *@var{bs}, int @var{print_frame}) |
91 | The inferior has stopped for real. The @var{bs} argument describes | |
92 | the breakpoints were are stopped at, if any. Second argument | |
93 | @var{print_frame} non-zero means display the location where the | |
94 | inferior has stopped. | |
7a464420 | 95 | @end deftypefun |
79346bcb | 96 | |
fd664c91 PA |
97 | @deftypefun void signal_received (enum gdb_signal @var{siggnal}) |
98 | The inferior was stopped by a signal. | |
99 | @end deftypefun | |
100 | ||
101 | @deftypefun void end_stepping_range (void) | |
102 | We are done with a step/next/si/ni command. | |
103 | @end deftypefun | |
104 | ||
105 | @deftypefun void signal_exited (enum gdb_signal @var{siggnal}) | |
106 | The inferior was terminated by a signal. | |
107 | @end deftypefun | |
108 | ||
109 | @deftypefun void exited (int @var{exitstatus}) | |
110 | The inferior program is finished. | |
111 | @end deftypefun | |
112 | ||
113 | @deftypefun void no_history (void) | |
114 | Reverse execution: target ran out of history info. | |
115 | @end deftypefun | |
116 | ||
92bcb5f9 PA |
117 | @deftypefun void sync_execution_done (void) |
118 | A synchronous command finished. | |
119 | @end deftypefun | |
120 | ||
121 | @deftypefun void command_error (void) | |
122 | An error was caught while executing a command. | |
123 | @end deftypefun | |
124 | ||
79346bcb | 125 | @deftypefun void target_changed (struct target_ops *@var{target}) |
67ab9a76 | 126 | The target's register contents have changed. |
79346bcb | 127 | @end deftypefun |
59caf092 | 128 | |
781b42b0 | 129 | @deftypefun void executable_changed (void) |
ea53e89f JB |
130 | The executable being debugged by GDB has changed: The user decided |
131 | to debug a different program, or the program he was debugging has | |
132 | been modified since being loaded by the debugger (by being recompiled, | |
133 | for instance). | |
134 | @end deftypefun | |
135 | ||
59caf092 AC |
136 | @deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty}) |
137 | @value{GDBN} has just connected to an inferior. For @samp{run}, | |
138 | @value{GDBN} calls this observer while the inferior is still stopped | |
139 | at the entry-point instruction. For @samp{attach} and @samp{core}, | |
140 | @value{GDBN} calls this observer immediately after connecting to the | |
141 | inferior, and before any information on the inferior has been printed. | |
142 | @end deftypefun | |
f3bb6704 | 143 | |
38b022b4 | 144 | @deftypefun void record_changed (struct inferior *@var{inferior}, int @var{started}, const char *@var{method}, const char *@var{format}) |
82a90ccf YQ |
145 | The status of process record for inferior @var{inferior} in |
146 | @value{GDBN} has changed. The process record is started if | |
147 | @var{started} is true, and the process record is stopped if | |
148 | @var{started} is false. | |
38b022b4 SM |
149 | |
150 | When @var{started} is true, @var{method} indicates the short name of the method | |
151 | used for recording. If the method supports multiple formats, @var{format} | |
152 | indicates which one is being used, otherwise it is NULL. When @var{started} is | |
153 | false, they are both NULL. | |
82a90ccf YQ |
154 | @end deftypefun |
155 | ||
fbd1b305 MK |
156 | @deftypefun void solib_loaded (struct so_list *@var{solib}) |
157 | The shared library specified by @var{solib} has been loaded. Note that | |
158 | when @value{GDBN} calls this observer, the library's symbols probably | |
159 | haven't been loaded yet. | |
f3bb6704 JJ |
160 | @end deftypefun |
161 | ||
fbd1b305 MK |
162 | @deftypefun void solib_unloaded (struct so_list *@var{solib}) |
163 | The shared library specified by @var{solib} has been unloaded. | |
30a4a70c JB |
164 | Note that when @value{GDBN} calls this observer, the library's |
165 | symbols have not been unloaded yet, and thus are still available. | |
fbd1b305 | 166 | @end deftypefun |
06d3b283 UW |
167 | |
168 | @deftypefun void new_objfile (struct objfile *@var{objfile}) | |
169 | The symbol file specified by @var{objfile} has been loaded. | |
170 | Called with @var{objfile} equal to @code{NULL} to indicate | |
171 | previously loaded symbol table data has now been invalidated. | |
172 | @end deftypefun | |
173 | ||
63644780 NB |
174 | @deftypefun void free_objfile (struct objfile *@var{objfile}) |
175 | The object file specified by @var{objfile} is about to be freed. | |
176 | @end deftypefun | |
177 | ||
683f2885 VP |
178 | @deftypefun void new_thread (struct thread_info *@var{t}) |
179 | The thread specified by @var{t} has been created. | |
180 | @end deftypefun | |
181 | ||
a07daef3 PA |
182 | @deftypefun void thread_exit (struct thread_info *@var{t}, int @var{silent}) |
183 | The thread specified by @var{t} has exited. The @var{silent} argument | |
184 | indicates that @value{GDBN} is removing the thread from its tables | |
185 | without wanting to notify the user about it. | |
063bfe2e VP |
186 | @end deftypefun |
187 | ||
252fbfc8 PA |
188 | @deftypefun void thread_stop_requested (ptid_t @var{ptid}) |
189 | An explicit stop request was issued to @var{ptid}. If @var{ptid} | |
190 | equals @var{minus_one_ptid}, the request applied to all threads. If | |
191 | @code{ptid_is_pid(ptid)} returns true, the request applied to all | |
192 | threads of the process pointed at by @var{ptid}. Otherwise, the | |
193 | request applied to the single thread pointed at by @var{ptid}. | |
194 | @end deftypefun | |
195 | ||
e1ac3328 VP |
196 | @deftypefun void target_resumed (ptid_t @var{ptid}) |
197 | The target was resumed. The @var{ptid} parameter specifies which | |
198 | thread was resume, and may be RESUME_ALL if all threads are resumed. | |
199 | @end deftypefun | |
383f836e | 200 | |
f3b1572e PA |
201 | @deftypefun void about_to_proceed (void) |
202 | The target is about to be proceeded. | |
203 | @end deftypefun | |
204 | ||
8d3788bd VP |
205 | @deftypefun void breakpoint_created (struct breakpoint *@var{b}) |
206 | A new breakpoint @var{b} has been created. | |
383f836e TT |
207 | @end deftypefun |
208 | ||
8d3788bd VP |
209 | @deftypefun void breakpoint_deleted (struct breakpoint *@var{b}) |
210 | A breakpoint has been destroyed. The argument @var{b} is the | |
211 | pointer to the destroyed breakpoint. | |
383f836e TT |
212 | @end deftypefun |
213 | ||
8d3788bd VP |
214 | @deftypefun void breakpoint_modified (struct breakpoint *@var{b}) |
215 | A breakpoint has been modified in some way. The argument @var{b} | |
216 | is the modified breakpoint. | |
383f836e TT |
217 | @end deftypefun |
218 | ||
201b4506 YQ |
219 | @deftypefun void traceframe_changed (int @var{tfnum}, int @var{tpnum}) |
220 | The trace frame is changed to @var{tfnum} (e.g., by using the | |
221 | @code{tfind} command). If @var{tfnum} is negative, it means | |
222 | @value{GDBN} resumes live debugging. The number of the tracepoint | |
223 | associated with this traceframe is @var{tpnum}. | |
224 | @end deftypefun | |
225 | ||
383f836e TT |
226 | @deftypefun void architecture_changed (struct gdbarch *@var{newarch}) |
227 | The current architecture has changed. The argument @var{newarch} is | |
228 | a pointer to the new architecture. | |
229 | @end deftypefun | |
230 | ||
5231c1fd PA |
231 | @deftypefun void thread_ptid_changed (ptid_t @var{old_ptid}, ptid_t @var{new_ptid}) |
232 | The thread's ptid has changed. The @var{old_ptid} parameter specifies | |
233 | the old value, and @var{new_ptid} specifies the new value. | |
234 | @end deftypefun | |
4a92f99b | 235 | |
a79b8f6e VP |
236 | @deftypefun void inferior_added (struct inferior *@var{inf}) |
237 | The inferior @var{inf} has been added to the list of inferiors. At | |
238 | this point, it might not be associated with any process. | |
4a92f99b VP |
239 | @end deftypefun |
240 | ||
a79b8f6e VP |
241 | @deftypefun void inferior_appeared (struct inferior *@var{inf}) |
242 | The inferior identified by @var{inf} has been attached to a process. | |
243 | @end deftypefun | |
244 | ||
245 | @deftypefun void inferior_exit (struct inferior *@var{inf}) | |
246 | Either the inferior associated with @var{inf} has been detached from the | |
247 | process, or the process has exited. | |
248 | @end deftypefun | |
249 | ||
250 | @deftypefun void inferior_removed (struct inferior *@var{inf}) | |
251 | The inferior @var{inf} has been removed from the list of inferiors. | |
252 | This method is called immediately before freeing @var{inf}. | |
8cebebb9 PP |
253 | @end deftypefun |
254 | ||
8de0566d | 255 | @deftypefun void memory_changed (struct inferior *@var{inferior}, CORE_ADDR @var{addr}, ssize_t @var{len}, const bfd_byte *@var{data}) |
8cebebb9 | 256 | Bytes from @var{data} to @var{data} + @var{len} have been written |
8de0566d | 257 | to the @var{inferior} at @var{addr}. |
4a92f99b VP |
258 | @end deftypefun |
259 | ||
d17b6f81 PM |
260 | @deftypefun void before_prompt (const char *@var{current_prompt}) |
261 | Called before a top-level prompt is displayed. @var{current_prompt} is | |
262 | the current top-level prompt. | |
263 | @end deftypefun | |
264 | ||
6dea1fbd JK |
265 | @deftypefun void gdb_datadir_changed (void) |
266 | Variable gdb_datadir has been set. The value may not necessarily change. | |
267 | @end deftypefun | |
268 | ||
5b9afe8a YQ |
269 | @deftypefun void command_param_changed (const char *@var{param}, const char *@var{value}) |
270 | The parameter of some @code{set} commands in console are changed. This | |
271 | method is called after a command @code{set @var{param} @var{value}}. | |
272 | @var{param} is the parameter of @code{set} command, and @var{value} | |
273 | is the value of changed parameter. | |
bb25a15c YQ |
274 | @end deftypefun |
275 | ||
134a2066 YQ |
276 | @deftypefun void tsv_created (const struct trace_state_variable *@var{tsv}) |
277 | The new trace state variable @var{tsv} is created. | |
bb25a15c | 278 | @end deftypefun |
5b9afe8a | 279 | |
134a2066 YQ |
280 | @deftypefun void tsv_deleted (const struct trace_state_variable *@var{tsv}) |
281 | The trace state variable @var{tsv} is deleted. If @var{tsv} is | |
bb25a15c | 282 | @code{NULL}, all trace state variables are deleted. |
5b9afe8a YQ |
283 | @end deftypefun |
284 | ||
134a2066 YQ |
285 | @deftypefun void tsv_modified (const struct trace_state_variable *@var{tsv}) |
286 | The trace state value @var{tsv} is modified. | |
287 | @end deftypefun | |
288 | ||
162078c8 NB |
289 | @deftypefun void inferior_call_pre (ptid_t @var{thread}, CORE_ADDR @var{address}) |
290 | An inferior function at @var{address} is about to be called in thread | |
291 | @var{thread}. | |
292 | @end deftypefun | |
293 | ||
294 | @deftypefun void inferior_call_post (ptid_t @var{thread}, CORE_ADDR @var{address}) | |
295 | The inferior function at @var{address} has just been called. This observer | |
296 | is called even if the inferior exits during the call. @var{thread} is the | |
297 | thread in which the function was called, which may be different from the | |
298 | current thread. | |
299 | @end deftypefun | |
300 | ||
301 | @deftypefun void register_changed (struct frame_info *@var{frame}, int @var{regnum}) | |
302 | A register in the inferior has been modified by the @value{GDBN} user. | |
303 | @end deftypefun | |
304 | ||
a79b8f6e | 305 | @deftypefun void test_notification (int @var{somearg}) |
3ea85240 VP |
306 | This observer is used for internal testing. Do not use. |
307 | See testsuite/gdb.gdb/observer.exp. | |
a79b8f6e | 308 | @end deftypefun |
3ea85240 | 309 | |
4034d0ff AT |
310 | @deftypefun void user_selected_context_changed (user_selected_what @var{selection}) |
311 | The user-selected inferior, thread and/or frame has changed. The user_select_what | |
312 | flag specifies if the inferior, thread and/or frame has changed. | |
313 | @end deftypefun |