1@c -*-texinfo-*- 2 3@c This file is part of the GDB manual. 4@c 5@c Copyright (C) 2003-2013 Free Software Foundation, Inc. 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 13@c Foundation; either version 3 of the License, or (at your option) 14@c any later version. 15 16@node GDB Observers 17@appendix @value{GDBN} Currently available observers 18 19@section Implementation rationale 20@cindex observers implementation rationale 21 22An @dfn{observer} is an entity which is interested in being notified 23when GDB reaches certain states, or certain events occur in GDB. 24The entity being observed is called the @dfn{subject}. To receive 25notifications, the observer attaches a callback to the subject. 26One subject can have several observers. 27 28@file{observer.c} implements an internal generic low-level event 29notification mechanism. This generic event notification mechanism is 30then re-used to implement the exported high-level notification 31management routines for all possible notifications. 32 33The current implementation of the generic observer provides support 34for contextual data. This contextual data is given to the subject 35when attaching the callback. In return, the subject will provide 36this contextual data back to the observer as a parameter of the 37callback. 38 39Note that the current support for the contextual data is only partial, 40as it lacks a mechanism that would deallocate this data when the 41callback is detached. This is not a problem so far, as this contextual 42data is only used internally to hold a function pointer. Later on, if 43a certain observer needs to provide support for user-level contextual 44data, then the generic notification mechanism will need to be 45enhanced to allow the observer to provide a routine to deallocate the 46data when attaching the callback. 47 48The observer implementation is also currently not reentrant. 49In particular, it is therefore not possible to call the attach 50or detach routines during a notification. 51 52@section Debugging 53Observer notifications can be traced using the command @samp{set debug 54observer 1} (@pxref{Debugging Output, , Optional messages about 55internal happenings, gdb, Debugging with @var{GDBN}}). 56 57@section @code{normal_stop} Notifications 58@cindex @code{normal_stop} observer 59@cindex notification about inferior execution stop 60 61@value{GDBN} notifies all @code{normal_stop} observers when the 62inferior execution has just stopped, the associated messages and 63annotations have been printed, and the control is about to be returned 64to the user. 65 66Note that the @code{normal_stop} notification is not emitted when 67the execution stops due to a breakpoint, and this breakpoint has 68a condition that is not met. If the breakpoint has any associated 69commands list, the commands are executed after the notification 70is emitted. 71 72The following interfaces are available to manage observers: 73 74@deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f}) 75Using the function @var{f}, create an observer that is notified when 76ever @var{event} occurs, return the observer. 77@end deftypefun 78 79@deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer}); 80Remove @var{observer} from the list of observers to be notified when 81@var{event} occurs. 82@end deftypefun 83 84@deftypefun extern void observer_notify_@var{event} (void); 85Send a notification to all @var{event} observers. 86@end deftypefun 87 88The following observable events are defined: 89 90@deftypefun void normal_stop (struct bpstats *@var{bs}, int @var{print_frame}) 91The inferior has stopped for real. The @var{bs} argument describes 92the breakpoints were are stopped at, if any. Second argument 93@var{print_frame} non-zero means display the location where the 94inferior has stopped. 95@end deftypefun 96 97@deftypefun void target_changed (struct target_ops *@var{target}) 98The target's register contents have changed. 99@end deftypefun 100 101@deftypefun void executable_changed (void) 102The executable being debugged by GDB has changed: The user decided 103to debug a different program, or the program he was debugging has 104been modified since being loaded by the debugger (by being recompiled, 105for instance). 106@end deftypefun 107 108@deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty}) 109@value{GDBN} has just connected to an inferior. For @samp{run}, 110@value{GDBN} calls this observer while the inferior is still stopped 111at the entry-point instruction. For @samp{attach} and @samp{core}, 112@value{GDBN} calls this observer immediately after connecting to the 113inferior, and before any information on the inferior has been printed. 114@end deftypefun 115 116@deftypefun void record_changed (struct inferior *@var{inferior}, int @var{started}) 117The status of process record for inferior @var{inferior} in 118@value{GDBN} has changed. The process record is started if 119@var{started} is true, and the process record is stopped if 120@var{started} is false. 121@end deftypefun 122 123@deftypefun void solib_loaded (struct so_list *@var{solib}) 124The shared library specified by @var{solib} has been loaded. Note that 125when @value{GDBN} calls this observer, the library's symbols probably 126haven't been loaded yet. 127@end deftypefun 128 129@deftypefun void solib_unloaded (struct so_list *@var{solib}) 130The shared library specified by @var{solib} has been unloaded. 131Note that when @value{GDBN} calls this observer, the library's 132symbols have not been unloaded yet, and thus are still available. 133@end deftypefun 134 135@deftypefun void new_objfile (struct objfile *@var{objfile}) 136The symbol file specified by @var{objfile} has been loaded. 137Called with @var{objfile} equal to @code{NULL} to indicate 138previously loaded symbol table data has now been invalidated. 139@end deftypefun 140 141@deftypefun void new_thread (struct thread_info *@var{t}) 142The thread specified by @var{t} has been created. 143@end deftypefun 144 145@deftypefun void thread_exit (struct thread_info *@var{t}, int @var{silent}) 146The thread specified by @var{t} has exited. The @var{silent} argument 147indicates that @value{GDBN} is removing the thread from its tables 148without wanting to notify the user about it. 149@end deftypefun 150 151@deftypefun void thread_stop_requested (ptid_t @var{ptid}) 152An explicit stop request was issued to @var{ptid}. If @var{ptid} 153equals @var{minus_one_ptid}, the request applied to all threads. If 154@code{ptid_is_pid(ptid)} returns true, the request applied to all 155threads of the process pointed at by @var{ptid}. Otherwise, the 156request applied to the single thread pointed at by @var{ptid}. 157@end deftypefun 158 159@deftypefun void target_resumed (ptid_t @var{ptid}) 160The target was resumed. The @var{ptid} parameter specifies which 161thread was resume, and may be RESUME_ALL if all threads are resumed. 162@end deftypefun 163 164@deftypefun void about_to_proceed (void) 165The target is about to be proceeded. 166@end deftypefun 167 168@deftypefun void breakpoint_created (struct breakpoint *@var{b}) 169A new breakpoint @var{b} has been created. 170@end deftypefun 171 172@deftypefun void breakpoint_deleted (struct breakpoint *@var{b}) 173A breakpoint has been destroyed. The argument @var{b} is the 174pointer to the destroyed breakpoint. 175@end deftypefun 176 177@deftypefun void breakpoint_modified (struct breakpoint *@var{b}) 178A breakpoint has been modified in some way. The argument @var{b} 179is the modified breakpoint. 180@end deftypefun 181 182@deftypefun void traceframe_changed (int @var{tfnum}, int @var{tpnum}) 183The trace frame is changed to @var{tfnum} (e.g., by using the 184@code{tfind} command). If @var{tfnum} is negative, it means 185@value{GDBN} resumes live debugging. The number of the tracepoint 186associated with this traceframe is @var{tpnum}. 187@end deftypefun 188 189@deftypefun void architecture_changed (struct gdbarch *@var{newarch}) 190The current architecture has changed. The argument @var{newarch} is 191a pointer to the new architecture. 192@end deftypefun 193 194@deftypefun void thread_ptid_changed (ptid_t @var{old_ptid}, ptid_t @var{new_ptid}) 195The thread's ptid has changed. The @var{old_ptid} parameter specifies 196the old value, and @var{new_ptid} specifies the new value. 197@end deftypefun 198 199@deftypefun void inferior_added (struct inferior *@var{inf}) 200The inferior @var{inf} has been added to the list of inferiors. At 201this point, it might not be associated with any process. 202@end deftypefun 203 204@deftypefun void inferior_appeared (struct inferior *@var{inf}) 205The inferior identified by @var{inf} has been attached to a process. 206@end deftypefun 207 208@deftypefun void inferior_exit (struct inferior *@var{inf}) 209Either the inferior associated with @var{inf} has been detached from the 210process, or the process has exited. 211@end deftypefun 212 213@deftypefun void inferior_removed (struct inferior *@var{inf}) 214The inferior @var{inf} has been removed from the list of inferiors. 215This method is called immediately before freeing @var{inf}. 216@end deftypefun 217 218@deftypefun void memory_changed (struct inferior *@var{inferior}, CORE_ADDR @var{addr}, ssize_t @var{len}, const bfd_byte *@var{data}) 219Bytes from @var{data} to @var{data} + @var{len} have been written 220to the @var{inferior} at @var{addr}. 221@end deftypefun 222 223@deftypefun void before_prompt (const char *@var{current_prompt}) 224Called before a top-level prompt is displayed. @var{current_prompt} is 225the current top-level prompt. 226@end deftypefun 227 228@deftypefun void gdb_datadir_changed (void) 229Variable gdb_datadir has been set. The value may not necessarily change. 230@end deftypefun 231 232@deftypefun void command_param_changed (const char *@var{param}, const char *@var{value}) 233The parameter of some @code{set} commands in console are changed. This 234method is called after a command @code{set @var{param} @var{value}}. 235@var{param} is the parameter of @code{set} command, and @var{value} 236is the value of changed parameter. 237@end deftypefun 238 239@deftypefun void tsv_created (const struct trace_state_variable *@var{tsv}) 240The new trace state variable @var{tsv} is created. 241@end deftypefun 242 243@deftypefun void tsv_deleted (const struct trace_state_variable *@var{tsv}) 244The trace state variable @var{tsv} is deleted. If @var{tsv} is 245@code{NULL}, all trace state variables are deleted. 246@end deftypefun 247 248@deftypefun void tsv_modified (const struct trace_state_variable *@var{tsv}) 249The trace state value @var{tsv} is modified. 250@end deftypefun 251 252@deftypefun void test_notification (int @var{somearg}) 253This observer is used for internal testing. Do not use. 254See testsuite/gdb.gdb/observer.exp. 255@end deftypefun 256 257