3 @c This file is part of the GDB manual.
5 @c Copyright (C) 2003-2014 Free Software Foundation, Inc.
7 @c See the file gdbint.texinfo for copying conditions.
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
13 @c Foundation; either version 3 of the License, or (at your option)
17 @appendix @value{GDBN} Currently available observers
19 @section Implementation rationale
20 @cindex observers implementation rationale
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.
28 @file{observer.c} implements an internal generic low-level event
29 notification mechanism. This generic event notification mechanism is
30 then re-used to implement the exported high-level notification
31 management routines for all possible notifications.
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
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
44 data, then the generic notification mechanism will need to be
45 enhanced to allow the observer to provide a routine to deallocate the
46 data when attaching the callback.
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.
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}}).
57 @section @code{normal_stop} Notifications
58 @cindex @code{normal_stop} observer
59 @cindex notification about inferior execution stop
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
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
72 The following interfaces are available to manage observers:
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
76 ever @var{event} occurs, return the observer.
79 @deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer});
80 Remove @var{observer} from the list of observers to be notified when
84 @deftypefun extern void observer_notify_@var{event} (void);
85 Send a notification to all @var{event} observers.
88 The following observable events are defined:
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
97 @deftypefun void signal_received (enum gdb_signal @var{siggnal})
98 The inferior was stopped by a signal.
101 @deftypefun void end_stepping_range (void)
102 We are done with a step/next/si/ni command.
105 @deftypefun void signal_exited (enum gdb_signal @var{siggnal})
106 The inferior was terminated by a signal.
109 @deftypefun void exited (int @var{exitstatus})
110 The inferior program is finished.
113 @deftypefun void no_history (void)
114 Reverse execution: target ran out of history info.
117 @deftypefun void target_changed (struct target_ops *@var{target})
118 The target's register contents have changed.
121 @deftypefun void executable_changed (void)
122 The executable being debugged by GDB has changed: The user decided
123 to debug a different program, or the program he was debugging has
124 been modified since being loaded by the debugger (by being recompiled,
128 @deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty})
129 @value{GDBN} has just connected to an inferior. For @samp{run},
130 @value{GDBN} calls this observer while the inferior is still stopped
131 at the entry-point instruction. For @samp{attach} and @samp{core},
132 @value{GDBN} calls this observer immediately after connecting to the
133 inferior, and before any information on the inferior has been printed.
136 @deftypefun void record_changed (struct inferior *@var{inferior}, int @var{started})
137 The status of process record for inferior @var{inferior} in
138 @value{GDBN} has changed. The process record is started if
139 @var{started} is true, and the process record is stopped if
140 @var{started} is false.
143 @deftypefun void solib_loaded (struct so_list *@var{solib})
144 The shared library specified by @var{solib} has been loaded. Note that
145 when @value{GDBN} calls this observer, the library's symbols probably
146 haven't been loaded yet.
149 @deftypefun void solib_unloaded (struct so_list *@var{solib})
150 The shared library specified by @var{solib} has been unloaded.
151 Note that when @value{GDBN} calls this observer, the library's
152 symbols have not been unloaded yet, and thus are still available.
155 @deftypefun void new_objfile (struct objfile *@var{objfile})
156 The symbol file specified by @var{objfile} has been loaded.
157 Called with @var{objfile} equal to @code{NULL} to indicate
158 previously loaded symbol table data has now been invalidated.
161 @deftypefun void free_objfile (struct objfile *@var{objfile})
162 The object file specified by @var{objfile} is about to be freed.
165 @deftypefun void new_thread (struct thread_info *@var{t})
166 The thread specified by @var{t} has been created.
169 @deftypefun void thread_exit (struct thread_info *@var{t}, int @var{silent})
170 The thread specified by @var{t} has exited. The @var{silent} argument
171 indicates that @value{GDBN} is removing the thread from its tables
172 without wanting to notify the user about it.
175 @deftypefun void thread_stop_requested (ptid_t @var{ptid})
176 An explicit stop request was issued to @var{ptid}. If @var{ptid}
177 equals @var{minus_one_ptid}, the request applied to all threads. If
178 @code{ptid_is_pid(ptid)} returns true, the request applied to all
179 threads of the process pointed at by @var{ptid}. Otherwise, the
180 request applied to the single thread pointed at by @var{ptid}.
183 @deftypefun void target_resumed (ptid_t @var{ptid})
184 The target was resumed. The @var{ptid} parameter specifies which
185 thread was resume, and may be RESUME_ALL if all threads are resumed.
188 @deftypefun void about_to_proceed (void)
189 The target is about to be proceeded.
192 @deftypefun void breakpoint_created (struct breakpoint *@var{b})
193 A new breakpoint @var{b} has been created.
196 @deftypefun void breakpoint_deleted (struct breakpoint *@var{b})
197 A breakpoint has been destroyed. The argument @var{b} is the
198 pointer to the destroyed breakpoint.
201 @deftypefun void breakpoint_modified (struct breakpoint *@var{b})
202 A breakpoint has been modified in some way. The argument @var{b}
203 is the modified breakpoint.
206 @deftypefun void traceframe_changed (int @var{tfnum}, int @var{tpnum})
207 The trace frame is changed to @var{tfnum} (e.g., by using the
208 @code{tfind} command). If @var{tfnum} is negative, it means
209 @value{GDBN} resumes live debugging. The number of the tracepoint
210 associated with this traceframe is @var{tpnum}.
213 @deftypefun void architecture_changed (struct gdbarch *@var{newarch})
214 The current architecture has changed. The argument @var{newarch} is
215 a pointer to the new architecture.
218 @deftypefun void thread_ptid_changed (ptid_t @var{old_ptid}, ptid_t @var{new_ptid})
219 The thread's ptid has changed. The @var{old_ptid} parameter specifies
220 the old value, and @var{new_ptid} specifies the new value.
223 @deftypefun void inferior_added (struct inferior *@var{inf})
224 The inferior @var{inf} has been added to the list of inferiors. At
225 this point, it might not be associated with any process.
228 @deftypefun void inferior_appeared (struct inferior *@var{inf})
229 The inferior identified by @var{inf} has been attached to a process.
232 @deftypefun void inferior_exit (struct inferior *@var{inf})
233 Either the inferior associated with @var{inf} has been detached from the
234 process, or the process has exited.
237 @deftypefun void inferior_removed (struct inferior *@var{inf})
238 The inferior @var{inf} has been removed from the list of inferiors.
239 This method is called immediately before freeing @var{inf}.
242 @deftypefun void memory_changed (struct inferior *@var{inferior}, CORE_ADDR @var{addr}, ssize_t @var{len}, const bfd_byte *@var{data})
243 Bytes from @var{data} to @var{data} + @var{len} have been written
244 to the @var{inferior} at @var{addr}.
247 @deftypefun void before_prompt (const char *@var{current_prompt})
248 Called before a top-level prompt is displayed. @var{current_prompt} is
249 the current top-level prompt.
252 @deftypefun void gdb_datadir_changed (void)
253 Variable gdb_datadir has been set. The value may not necessarily change.
256 @deftypefun void command_param_changed (const char *@var{param}, const char *@var{value})
257 The parameter of some @code{set} commands in console are changed. This
258 method is called after a command @code{set @var{param} @var{value}}.
259 @var{param} is the parameter of @code{set} command, and @var{value}
260 is the value of changed parameter.
263 @deftypefun void tsv_created (const struct trace_state_variable *@var{tsv})
264 The new trace state variable @var{tsv} is created.
267 @deftypefun void tsv_deleted (const struct trace_state_variable *@var{tsv})
268 The trace state variable @var{tsv} is deleted. If @var{tsv} is
269 @code{NULL}, all trace state variables are deleted.
272 @deftypefun void tsv_modified (const struct trace_state_variable *@var{tsv})
273 The trace state value @var{tsv} is modified.
276 @deftypefun void test_notification (int @var{somearg})
277 This observer is used for internal testing. Do not use.
278 See testsuite/gdb.gdb/observer.exp.