gdb/doc/observer.texi

   1 @c -*-texinfo-*-
   2
   3 @c This file is part of the GDB manual.
   4 @c
   5 @c Copyright (C) 2003-2016 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
  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
  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.
  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
  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.
  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
  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
  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
  62 inferior execution has just stopped, the associated messages and
  63 annotations have been printed, and the control is about to be returned
  64 to the user.
  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.
  71
  72 The following interfaces are available to manage observers:
  73
  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.
  77 @end deftypefun
  78
  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
  81 @var{event} occurs.
  82 @end deftypefun
  83
  84 @deftypefun extern void observer_notify_@var{event} (void);
  85 Send a notification to all @var{event} observers.
  86 @end deftypefun
  87
  88 The following observable events are defined:
  89
  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.
  95 @end deftypefun
  96
  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
 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
 125 @deftypefun void target_changed (struct target_ops *@var{target})
 126 The target's register contents have changed.
 127 @end deftypefun
 128
 129 @deftypefun void executable_changed (void)
 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
 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
 143
 144 @deftypefun void record_changed (struct inferior *@var{inferior}, int @var{started}, const char *@var{method}, const char *@var{format})
 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.
 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.
 154 @end deftypefun
 155
 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.
 160 @end deftypefun
 161
 162 @deftypefun void solib_unloaded (struct so_list *@var{solib})
 163 The shared library specified by @var{solib} has been unloaded.
 164 Note that when @value{GDBN} calls this observer, the library's
 165 symbols have not been unloaded yet, and thus are still available.
 166 @end deftypefun
 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
 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
 178 @deftypefun void new_thread (struct thread_info *@var{t})
 179 The thread specified by @var{t} has been created.
 180 @end deftypefun
 181
 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.
 186 @end deftypefun
 187
 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
 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
 200
 201 @deftypefun void about_to_proceed (void)
 202 The target is about to be proceeded.
 203 @end deftypefun
 204
 205 @deftypefun void breakpoint_created (struct breakpoint *@var{b})
 206 A new breakpoint @var{b} has been created.
 207 @end deftypefun
 208
 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.
 212 @end deftypefun
 213
 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.
 217 @end deftypefun
 218
 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
 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
 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
 235
 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.
 239 @end deftypefun
 240
 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}.
 253 @end deftypefun
 254
 255 @deftypefun void memory_changed (struct inferior *@var{inferior}, CORE_ADDR @var{addr}, ssize_t @var{len}, const bfd_byte *@var{data})
 256 Bytes from @var{data} to @var{data} + @var{len} have been written
 257 to the @var{inferior} at @var{addr}.
 258 @end deftypefun
 259
 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
 265 @deftypefun void gdb_datadir_changed (void)
 266 Variable gdb_datadir has been set.  The value may not necessarily change.
 267 @end deftypefun
 268
 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.
 274 @end deftypefun
 275
 276 @deftypefun void tsv_created (const struct trace_state_variable *@var{tsv})
 277 The new trace state variable @var{tsv} is created.
 278 @end deftypefun
 279
 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
 282 @code{NULL}, all trace state variables are deleted.
 283 @end deftypefun
 284
 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
 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
 305 @deftypefun void test_notification (int @var{somearg})
 306 This observer is used for internal testing.  Do not use.
 307 See testsuite/gdb.gdb/observer.exp.
 308 @end deftypefun
 309