314 lines
12 KiB
Plaintext
314 lines
12 KiB
Plaintext
@c -*-texinfo-*-
|
|
|
|
@c This file is part of the GDB manual.
|
|
@c
|
|
@c Copyright (C) 2003-2018 Free Software Foundation, Inc.
|
|
@c
|
|
@c See the file gdbint.texinfo for copying conditions.
|
|
@c
|
|
@c Also, the @deftypefun lines from this file are processed into a
|
|
@c header file during the GDB build process. Permission is granted
|
|
@c to redistribute and/or modify those lines under the terms of the
|
|
@c GNU General Public License as published by the Free Software
|
|
@c Foundation; either version 3 of the License, or (at your option)
|
|
@c any later version.
|
|
|
|
@node GDB Observers
|
|
@appendix @value{GDBN} Currently available observers
|
|
|
|
@section Implementation rationale
|
|
@cindex observers implementation rationale
|
|
|
|
An @dfn{observer} is an entity which is interested in being notified
|
|
when GDB reaches certain states, or certain events occur in GDB.
|
|
The entity being observed is called the @dfn{subject}. To receive
|
|
notifications, the observer attaches a callback to the subject.
|
|
One subject can have several observers.
|
|
|
|
@file{observer.c} implements an internal generic low-level event
|
|
notification mechanism. This generic event notification mechanism is
|
|
then re-used to implement the exported high-level notification
|
|
management routines for all possible notifications.
|
|
|
|
The current implementation of the generic observer provides support
|
|
for contextual data. This contextual data is given to the subject
|
|
when attaching the callback. In return, the subject will provide
|
|
this contextual data back to the observer as a parameter of the
|
|
callback.
|
|
|
|
Note that the current support for the contextual data is only partial,
|
|
as it lacks a mechanism that would deallocate this data when the
|
|
callback is detached. This is not a problem so far, as this contextual
|
|
data is only used internally to hold a function pointer. Later on, if
|
|
a certain observer needs to provide support for user-level contextual
|
|
data, then the generic notification mechanism will need to be
|
|
enhanced to allow the observer to provide a routine to deallocate the
|
|
data when attaching the callback.
|
|
|
|
The observer implementation is also currently not reentrant.
|
|
In particular, it is therefore not possible to call the attach
|
|
or detach routines during a notification.
|
|
|
|
@section Debugging
|
|
Observer notifications can be traced using the command @samp{set debug
|
|
observer 1} (@pxref{Debugging Output, , Optional messages about
|
|
internal happenings, gdb, Debugging with @var{GDBN}}).
|
|
|
|
@section @code{normal_stop} Notifications
|
|
@cindex @code{normal_stop} observer
|
|
@cindex notification about inferior execution stop
|
|
|
|
@value{GDBN} notifies all @code{normal_stop} observers when the
|
|
inferior execution has just stopped, the associated messages and
|
|
annotations have been printed, and the control is about to be returned
|
|
to the user.
|
|
|
|
Note that the @code{normal_stop} notification is not emitted when
|
|
the execution stops due to a breakpoint, and this breakpoint has
|
|
a condition that is not met. If the breakpoint has any associated
|
|
commands list, the commands are executed after the notification
|
|
is emitted.
|
|
|
|
The following interfaces are available to manage observers:
|
|
|
|
@deftypefun extern struct observer *observer_attach_@var{event} (observer_@var{event}_ftype *@var{f})
|
|
Using the function @var{f}, create an observer that is notified when
|
|
ever @var{event} occurs, return the observer.
|
|
@end deftypefun
|
|
|
|
@deftypefun extern void observer_detach_@var{event} (struct observer *@var{observer});
|
|
Remove @var{observer} from the list of observers to be notified when
|
|
@var{event} occurs.
|
|
@end deftypefun
|
|
|
|
@deftypefun extern void observer_notify_@var{event} (void);
|
|
Send a notification to all @var{event} observers.
|
|
@end deftypefun
|
|
|
|
The following observable events are defined:
|
|
|
|
@deftypefun void normal_stop (struct bpstats *@var{bs}, int @var{print_frame})
|
|
The inferior has stopped for real. The @var{bs} argument describes
|
|
the breakpoints were are stopped at, if any. Second argument
|
|
@var{print_frame} non-zero means display the location where the
|
|
inferior has stopped.
|
|
@end deftypefun
|
|
|
|
@deftypefun void signal_received (enum gdb_signal @var{siggnal})
|
|
The inferior was stopped by a signal.
|
|
@end deftypefun
|
|
|
|
@deftypefun void end_stepping_range (void)
|
|
We are done with a step/next/si/ni command.
|
|
@end deftypefun
|
|
|
|
@deftypefun void signal_exited (enum gdb_signal @var{siggnal})
|
|
The inferior was terminated by a signal.
|
|
@end deftypefun
|
|
|
|
@deftypefun void exited (int @var{exitstatus})
|
|
The inferior program is finished.
|
|
@end deftypefun
|
|
|
|
@deftypefun void no_history (void)
|
|
Reverse execution: target ran out of history info.
|
|
@end deftypefun
|
|
|
|
@deftypefun void sync_execution_done (void)
|
|
A synchronous command finished.
|
|
@end deftypefun
|
|
|
|
@deftypefun void command_error (void)
|
|
An error was caught while executing a command.
|
|
@end deftypefun
|
|
|
|
@deftypefun void target_changed (struct target_ops *@var{target})
|
|
The target's register contents have changed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void executable_changed (void)
|
|
The executable being debugged by GDB has changed: The user decided
|
|
to debug a different program, or the program he was debugging has
|
|
been modified since being loaded by the debugger (by being recompiled,
|
|
for instance).
|
|
@end deftypefun
|
|
|
|
@deftypefun void inferior_created (struct target_ops *@var{objfile}, int @var{from_tty})
|
|
@value{GDBN} has just connected to an inferior. For @samp{run},
|
|
@value{GDBN} calls this observer while the inferior is still stopped
|
|
at the entry-point instruction. For @samp{attach} and @samp{core},
|
|
@value{GDBN} calls this observer immediately after connecting to the
|
|
inferior, and before any information on the inferior has been printed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void record_changed (struct inferior *@var{inferior}, int @var{started}, const char *@var{method}, const char *@var{format})
|
|
The status of process record for inferior @var{inferior} in
|
|
@value{GDBN} has changed. The process record is started if
|
|
@var{started} is true, and the process record is stopped if
|
|
@var{started} is false.
|
|
|
|
When @var{started} is true, @var{method} indicates the short name of the method
|
|
used for recording. If the method supports multiple formats, @var{format}
|
|
indicates which one is being used, otherwise it is NULL. When @var{started} is
|
|
false, they are both NULL.
|
|
@end deftypefun
|
|
|
|
@deftypefun void solib_loaded (struct so_list *@var{solib})
|
|
The shared library specified by @var{solib} has been loaded. Note that
|
|
when @value{GDBN} calls this observer, the library's symbols probably
|
|
haven't been loaded yet.
|
|
@end deftypefun
|
|
|
|
@deftypefun void solib_unloaded (struct so_list *@var{solib})
|
|
The shared library specified by @var{solib} has been unloaded.
|
|
Note that when @value{GDBN} calls this observer, the library's
|
|
symbols have not been unloaded yet, and thus are still available.
|
|
@end deftypefun
|
|
|
|
@deftypefun void new_objfile (struct objfile *@var{objfile})
|
|
The symbol file specified by @var{objfile} has been loaded.
|
|
Called with @var{objfile} equal to @code{NULL} to indicate
|
|
previously loaded symbol table data has now been invalidated.
|
|
@end deftypefun
|
|
|
|
@deftypefun void free_objfile (struct objfile *@var{objfile})
|
|
The object file specified by @var{objfile} is about to be freed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void new_thread (struct thread_info *@var{t})
|
|
The thread specified by @var{t} has been created.
|
|
@end deftypefun
|
|
|
|
@deftypefun void thread_exit (struct thread_info *@var{t}, int @var{silent})
|
|
The thread specified by @var{t} has exited. The @var{silent} argument
|
|
indicates that @value{GDBN} is removing the thread from its tables
|
|
without wanting to notify the user about it.
|
|
@end deftypefun
|
|
|
|
@deftypefun void thread_stop_requested (ptid_t @var{ptid})
|
|
An explicit stop request was issued to @var{ptid}. If @var{ptid}
|
|
equals @var{minus_one_ptid}, the request applied to all threads. If
|
|
@code{ptid_is_pid(ptid)} returns true, the request applied to all
|
|
threads of the process pointed at by @var{ptid}. Otherwise, the
|
|
request applied to the single thread pointed at by @var{ptid}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void target_resumed (ptid_t @var{ptid})
|
|
The target was resumed. The @var{ptid} parameter specifies which
|
|
thread was resume, and may be RESUME_ALL if all threads are resumed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void about_to_proceed (void)
|
|
The target is about to be proceeded.
|
|
@end deftypefun
|
|
|
|
@deftypefun void breakpoint_created (struct breakpoint *@var{b})
|
|
A new breakpoint @var{b} has been created.
|
|
@end deftypefun
|
|
|
|
@deftypefun void breakpoint_deleted (struct breakpoint *@var{b})
|
|
A breakpoint has been destroyed. The argument @var{b} is the
|
|
pointer to the destroyed breakpoint.
|
|
@end deftypefun
|
|
|
|
@deftypefun void breakpoint_modified (struct breakpoint *@var{b})
|
|
A breakpoint has been modified in some way. The argument @var{b}
|
|
is the modified breakpoint.
|
|
@end deftypefun
|
|
|
|
@deftypefun void traceframe_changed (int @var{tfnum}, int @var{tpnum})
|
|
The trace frame is changed to @var{tfnum} (e.g., by using the
|
|
@code{tfind} command). If @var{tfnum} is negative, it means
|
|
@value{GDBN} resumes live debugging. The number of the tracepoint
|
|
associated with this traceframe is @var{tpnum}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void architecture_changed (struct gdbarch *@var{newarch})
|
|
The current architecture has changed. The argument @var{newarch} is
|
|
a pointer to the new architecture.
|
|
@end deftypefun
|
|
|
|
@deftypefun void thread_ptid_changed (ptid_t @var{old_ptid}, ptid_t @var{new_ptid})
|
|
The thread's ptid has changed. The @var{old_ptid} parameter specifies
|
|
the old value, and @var{new_ptid} specifies the new value.
|
|
@end deftypefun
|
|
|
|
@deftypefun void inferior_added (struct inferior *@var{inf})
|
|
The inferior @var{inf} has been added to the list of inferiors. At
|
|
this point, it might not be associated with any process.
|
|
@end deftypefun
|
|
|
|
@deftypefun void inferior_appeared (struct inferior *@var{inf})
|
|
The inferior identified by @var{inf} has been attached to a process.
|
|
@end deftypefun
|
|
|
|
@deftypefun void inferior_exit (struct inferior *@var{inf})
|
|
Either the inferior associated with @var{inf} has been detached from the
|
|
process, or the process has exited.
|
|
@end deftypefun
|
|
|
|
@deftypefun void inferior_removed (struct inferior *@var{inf})
|
|
The inferior @var{inf} has been removed from the list of inferiors.
|
|
This method is called immediately before freeing @var{inf}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void memory_changed (struct inferior *@var{inferior}, CORE_ADDR @var{addr}, ssize_t @var{len}, const bfd_byte *@var{data})
|
|
Bytes from @var{data} to @var{data} + @var{len} have been written
|
|
to the @var{inferior} at @var{addr}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void before_prompt (const char *@var{current_prompt})
|
|
Called before a top-level prompt is displayed. @var{current_prompt} is
|
|
the current top-level prompt.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gdb_datadir_changed (void)
|
|
Variable gdb_datadir has been set. The value may not necessarily change.
|
|
@end deftypefun
|
|
|
|
@deftypefun void command_param_changed (const char *@var{param}, const char *@var{value})
|
|
The parameter of some @code{set} commands in console are changed. This
|
|
method is called after a command @code{set @var{param} @var{value}}.
|
|
@var{param} is the parameter of @code{set} command, and @var{value}
|
|
is the value of changed parameter.
|
|
@end deftypefun
|
|
|
|
@deftypefun void tsv_created (const struct trace_state_variable *@var{tsv})
|
|
The new trace state variable @var{tsv} is created.
|
|
@end deftypefun
|
|
|
|
@deftypefun void tsv_deleted (const struct trace_state_variable *@var{tsv})
|
|
The trace state variable @var{tsv} is deleted. If @var{tsv} is
|
|
@code{NULL}, all trace state variables are deleted.
|
|
@end deftypefun
|
|
|
|
@deftypefun void tsv_modified (const struct trace_state_variable *@var{tsv})
|
|
The trace state value @var{tsv} is modified.
|
|
@end deftypefun
|
|
|
|
@deftypefun void inferior_call_pre (ptid_t @var{thread}, CORE_ADDR @var{address})
|
|
An inferior function at @var{address} is about to be called in thread
|
|
@var{thread}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void inferior_call_post (ptid_t @var{thread}, CORE_ADDR @var{address})
|
|
The inferior function at @var{address} has just been called. This observer
|
|
is called even if the inferior exits during the call. @var{thread} is the
|
|
thread in which the function was called, which may be different from the
|
|
current thread.
|
|
@end deftypefun
|
|
|
|
@deftypefun void register_changed (struct frame_info *@var{frame}, int @var{regnum})
|
|
A register in the inferior has been modified by the @value{GDBN} user.
|
|
@end deftypefun
|
|
|
|
@deftypefun void test_notification (int @var{somearg})
|
|
This observer is used for internal testing. Do not use.
|
|
See testsuite/gdb.gdb/observer.exp.
|
|
@end deftypefun
|
|
|
|
@deftypefun void user_selected_context_changed (user_selected_what @var{selection})
|
|
The user-selected inferior, thread and/or frame has changed. The user_select_what
|
|
flag specifies if the inferior, thread and/or frame has changed.
|
|
@end deftypefun
|