\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2016 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2016 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2013 Free Software Foundation, Inc.
+Copyright (C) 1988-2016 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
You can run @code{@value{GDBP}} without printing the front material, which describes
-@value{GDBN}'s non-warranty, by specifying @code{-silent}:
+@value{GDBN}'s non-warranty, by specifying @code{--silent}
+(or @code{-q}/@code{--quiet}):
@smallexample
-@value{GDBP} -silent
+@value{GDBP} --silent
@end smallexample
@noindent
instead of the current directory.
@item -data-directory @var{directory}
+@itemx -D @var{directory}
@cindex @code{--data-directory}
+@cindex @code{-D}
Run @value{GDBN} using @var{directory} as its data directory.
The data directory is where @value{GDBN} searches for its
auxiliary files. @xref{Data Files}.
option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
Using @value{GDBN} under @sc{gnu} Emacs}).
-@c @item -xdb
-@c @cindex @code{--xdb}
-@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
-@c For information, see the file @file{xdb_trans.html}, which is usually
-@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
-@c systems.
-
@item -interpreter @var{interp}
@cindex @code{--interpreter}
Use the interpreter @var{interp} for interface with the controlling
key designated as the @key{META} shift on your keyboard (if there is
one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
+If the number of possible completions is large, @value{GDBN} will
+print as much of the list as it has collected, as well as a message
+indicating that the list may be truncated.
+
+@smallexample
+(@value{GDBP}) b m@key{TAB}@key{TAB}
+main
+<... the rest of the possible completions ...>
+*** List may be truncated, max-completions reached. ***
+(@value{GDBP}) b m
+@end smallexample
+
+@noindent
+This behavior can be controlled with the following commands:
+
+@table @code
+@kindex set max-completions
+@item set max-completions @var{limit}
+@itemx set max-completions unlimited
+Set the maximum number of completion candidates. @value{GDBN} will
+stop looking for more completions once it collects this many candidates.
+This is useful when completing on things like function names as collecting
+all the possible candidates can be time consuming.
+The default value is 200. A value of zero disables tab-completion.
+Note that setting either no limit or a very large limit can make
+completion slow.
+@kindex show max-completions
+@item show max-completions
+Show the maximum number of candidates that @value{GDBN} will collect and show
+during completion.
+@end table
+
@cindex quotes in commands
@cindex completion of quoted strings
Sometimes the string you need, while logically a ``word'', may contain
@item run
@itemx r
Use the @code{run} command to start your program under @value{GDBN}.
-You must first specify the program name (except on VxWorks) with an
-argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
-@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
-(@pxref{Files, ,Commands to Specify Files}).
+You must first specify the program name with an argument to
+@value{GDBN} (@pxref{Invocation, ,Getting In and Out of
+@value{GDBN}}), or by using the @code{file} or @code{exec-file}
+command (@pxref{Files, ,Commands to Specify Files}).
@end table
elaboration phase. Under these circumstances, insert breakpoints in your
elaboration code before running your program.
+@anchor{set exec-wrapper}
@kindex set exec-wrapper
@item set exec-wrapper @var{wrapper}
@itemx show exec-wrapper
$@file{.zshenv} for the Z shell, or the file specified in the
@samp{BASH_ENV} environment variable for BASH.
+@anchor{set auto-connect-native-target}
+@kindex set auto-connect-native-target
+@item set auto-connect-native-target
+@itemx set auto-connect-native-target on
+@itemx set auto-connect-native-target off
+@itemx show auto-connect-native-target
+
+By default, if not connected to any target yet (e.g., with
+@code{target remote}), the @code{run} command starts your program as a
+native process under @value{GDBN}, on your local machine. If you're
+sure you don't want to debug programs on your local machine, you can
+tell @value{GDBN} to not connect to the native target automatically
+with the @code{set auto-connect-native-target off} command.
+
+If @code{on}, which is the default, and if @value{GDBN} is not
+connected to a target already, the @code{run} command automaticaly
+connects to the native target, if one is available.
+
+If @code{off}, and if @value{GDBN} is not connected to a target
+already, the @code{run} command fails with an error:
+
+@smallexample
+(@value{GDBP}) run
+Don't know how to run. Try "help target".
+@end smallexample
+
+If @value{GDBN} is already connected to a target, @value{GDBN} always
+uses it with the @code{run} command.
+
+In any case, you can explicitly connect to the native target with the
+@code{target native} command. For example,
+
+@smallexample
+(@value{GDBP}) set auto-connect-native-target off
+(@value{GDBP}) run
+Don't know how to run. Try "help target".
+(@value{GDBP}) target native
+(@value{GDBP}) run
+Starting program: ./a.out
+[Inferior 1 (process 10421) exited normally]
+@end smallexample
+
+In case you connected explicitly to the @code{native} target,
+@value{GDBN} remains connected even if all inferiors exit, ready for
+the next @code{run} command. Use the @code{disconnect} command to
+disconnect.
+
+Examples of other commands that likewise respect the
+@code{auto-connect-native-target} setting: @code{attach}, @code{info
+proc}, @code{info os}.
+
@kindex set disable-randomization
@item set disable-randomization
@itemx set disable-randomization on
@kindex set environment
@item set environment @var{varname} @r{[}=@var{value}@r{]}
Set environment variable @var{varname} to @var{value}. The value
-changes for your program only, not for @value{GDBN} itself. @var{value} may
-be any string; the values of environment variables are just strings, and
-any interpretation is supplied by your program itself. The @var{value}
+changes for your program (and the shell @value{GDBN} uses to launch
+it), not for @value{GDBN} itself. The @var{value} may be any string; the
+values of environment variables are just strings, and any
+interpretation is supplied by your program itself. The @var{value}
parameter is optional; if it is eliminated, the variable is set to a
null value.
@c "any string" here does not include leading, trailing
@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
are not actually required.)
+Note that on Unix systems, @value{GDBN} runs your program via a shell,
+which also inherits the environment set with @code{set environment}.
+If necessary, you can avoid that by using the @samp{env} program as a
+wrapper instead of using @code{set environment}. @xref{set
+exec-wrapper}, for an example doing just that.
+
@kindex unset environment
@item unset environment @var{varname}
Remove variable @var{varname} from the environment to be passed to your
in the first field of the @samp{info inferiors} display.
@end table
+@vindex $_inferior@r{, convenience variable}
+The debugger convenience variable @samp{$_inferior} contains the
+number of the current inferior. You may find this useful in writing
+breakpoint conditional expressions, command scripts, and so forth.
+@xref{Convenience Vars,, Convenience Variables}, for general
+information on convenience variables.
You can get multiple executables into a debugging session via the
@code{add-inferior} and @w{@code{clone-inferior}} commands. On some
@kindex add-inferior
@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
Adds @var{n} inferiors to be run using @var{executable} as the
-executable. @var{n} defaults to 1. If no executable is specified,
+executable; @var{n} defaults to 1. If no executable is specified,
the inferiors begins empty, with no program. You can still assign or
change the program assigned to the inferior at any time by using the
@code{file} command with the executable name as its argument.
@kindex clone-inferior
@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
Adds @var{n} inferiors ready to execute the same program as inferior
-@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the
+@var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the
number of the current inferior. This is a convenient command when you
want to run another instance of the inferior you are debugging.
@smallexample
(@value{GDBP}) maint info program-spaces
Id Executable
+* 1 hello
2 goodbye
Bound inferiors: ID 1 (process 21561)
-* 1 hello
@end smallexample
Here we can see that no inferior is running the program @code{hello},
@cindex threads of execution
@cindex multiple threads
@cindex switching threads
-In some operating systems, such as HP-UX and Solaris, a single program
+In some operating systems, such as GNU/Linux and Solaris, a single program
may have more than one @dfn{thread} of execution. The precise semantics
of threads differ from one operating system to another, but in general
the threads of a single program are akin to multiple processes---except
@itemize @bullet
@item automatic notification of new threads
-@item @samp{thread @var{threadno}}, a command to switch among threads
+@item @samp{thread @var{thread-id}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{thread-id-list}] [@var{all}] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@item @samp{set print thread-events}, which controls printing of
isn't compatible with the program.
@end itemize
-@quotation
-@emph{Warning:} These facilities are not yet available on every
-@value{GDBN} configuration where the operating system supports threads.
-If your @value{GDBN} does not support threads, these commands have no
-effect. For example, a system without thread support shows no output
-from @samp{info threads}, and always rejects the @code{thread} command,
-like this:
-
-@smallexample
-(@value{GDBP}) info threads
-(@value{GDBP}) thread 1
-Thread ID 1 not known. Use the "info threads" command to
-see the IDs of currently known threads.
-@end smallexample
-@c FIXME to implementors: how hard would it be to say "sorry, this GDB
-@c doesn't support threads"?
-@end quotation
-
@cindex focus of debugging
@cindex current thread
The @value{GDBN} thread debugging facility allows you to observe all
@c thread without first checking `info threads'.
Whenever @value{GDBN} detects a new thread in your program, it displays
the target system's identification for the thread with a message in the
-form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
+form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier
whose form varies depending on the particular system. For example, on
@sc{gnu}/Linux, you might see
@end smallexample
@noindent
-when @value{GDBN} notices a new thread. In contrast, on an SGI system,
+when @value{GDBN} notices a new thread. In contrast, on other systems,
the @var{systag} is simply something like @samp{process 368}, with no
further qualifier.
@c multithread systems permit starting a program with multiple
@c threads ab initio?
-@cindex thread number
+@anchor{thread numbers}
+@cindex thread number, per inferior
@cindex thread identifier (GDB)
-For debugging purposes, @value{GDBN} associates its own thread
-number---always a single integer---with each thread in your program.
+For debugging purposes, @value{GDBN} associates its own thread number
+---always a single integer---with each thread of an inferior. This
+number is unique between all threads of an inferior, but not unique
+between threads of different inferiors.
+
+@cindex qualified thread ID
+You can refer to a given thread in an inferior using the qualified
+@var{inferior-num}.@var{thread-num} syntax, also known as
+@dfn{qualified thread ID}, with @var{inferior-num} being the inferior
+number and @var{thread-num} being the thread number of the given
+inferior. For example, thread @code{2.3} refers to thread number 3 of
+inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}),
+then @value{GDBN} infers you're referring to a thread of the current
+inferior.
+
+Until you create a second inferior, @value{GDBN} does not show the
+@var{inferior-num} part of thread IDs, even though you can always use
+the full @var{inferior-num}.@var{thread-num} form to refer to threads
+of inferior 1, the initial inferior.
+
+@anchor{thread ID lists}
+@cindex thread ID lists
+Some commands accept a space-separated @dfn{thread ID list} as
+argument. A list element can be:
+
+@enumerate
+@item
+A thread ID as shown in the first field of the @samp{info threads}
+display, with or without an inferior qualifier. E.g., @samp{2.1} or
+@samp{1}.
+
+@item
+A range of thread numbers, again with or without an inferior
+qualifier, as in @var{inf}.@var{thr1}-@var{thr2} or
+@var{thr1}-@var{thr2}. E.g., @samp{1.2-4} or @samp{2-4}.
+
+@item
+All threads of an inferior, specified with a star wildcard, with or
+without an inferior qualifier, as in @var{inf}.@code{*} (e.g.,
+@samp{1.*}) or @code{*}. The former refers to all threads of the
+given inferior, and the latter form without an inferior qualifier
+refers to all threads of the current inferior.
+
+@end enumerate
+
+For example, if the current inferior is 1, and inferior 7 has one
+thread with ID 7.1, the thread list @samp{1 2-3 4.5 6.7-9 7.*}
+includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads
+7 to 9 of inferior 6 and all threads of inferior 7. That is, in
+expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5 6.7 6.8 6.9
+7.1}.
+
+
+@anchor{global thread numbers}
+@cindex global thread number
+@cindex global thread identifier (GDB)
+In addition to a @emph{per-inferior} number, each thread is also
+assigned a unique @emph{global} number, also known as @dfn{global
+thread ID}, a single integer. Unlike the thread number component of
+the thread ID, no two threads have the same global ID, even when
+you're debugging multiple inferiors.
+
+From @value{GDBN}'s perspective, a process always has at least one
+thread. In other words, @value{GDBN} assigns a thread number to the
+program's ``main thread'' even if the program is not multi-threaded.
+
+@vindex $_thread@r{, convenience variable}
+@vindex $_gthread@r{, convenience variable}
+The debugger convenience variables @samp{$_thread} and
+@samp{$_gthread} contain, respectively, the per-inferior thread number
+and the global thread number of the current thread. You may find this
+useful in writing breakpoint conditional expressions, command scripts,
+and so forth. @xref{Convenience Vars,, Convenience Variables}, for
+general information on convenience variables.
+
+If @value{GDBN} detects the program is multi-threaded, it augments the
+usual message about stopping at a breakpoint with the ID and name of
+the thread that hit the breakpoint.
+
+@smallexample
+Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68
+@end smallexample
+
+Likewise when the program receives a signal:
+
+@smallexample
+Thread 1 "main" received signal SIGINT, Interrupt.
+@end smallexample
@table @code
@kindex info threads
-@item info threads @r{[}@var{id}@dots{}@r{]}
-Display a summary of all threads currently in your program. Optional
-argument @var{id}@dots{} is one or more thread ids separated by spaces, and
-means to print information only about the specified thread or threads.
+@item info threads @r{[}@var{thread-id-list}@r{]}
+
+Display information about one or more threads. With no arguments
+displays information about all threads. You can specify the list of
+threads that you want to display using the thread ID list syntax
+(@pxref{thread ID lists}).
+
@value{GDBN} displays for each thread (in this order):
@enumerate
@item
-the thread number assigned by @value{GDBN}
+the per-inferior thread number assigned by @value{GDBN}
+
+@item
+the global thread number assigned by @value{GDBN}, if the @samp{-gid}
+option was specified
@item
the target system's thread identifier (@var{systag})
@smallexample
(@value{GDBP}) info threads
Id Target Id Frame
- 3 process 35 thread 27 0x34e5 in sigpause ()
- 2 process 35 thread 23 0x34e5 in sigpause ()
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ 2 process 35 thread 23 0x34e5 in sigpause ()
+ 3 process 35 thread 27 0x34e5 in sigpause ()
at threadtest.c:68
@end smallexample
+If you're debugging multiple inferiors, @value{GDBN} displays thread
+IDs using the qualified @var{inferior-num}.@var{thread-num} format.
+Otherwise, only @var{thread-num} is shown.
+
+If you specify the @samp{-gid} option, @value{GDBN} displays a column
+indicating each thread's global thread ID:
+
+@smallexample
+(@value{GDBP}) info threads
+ Id GId Target Id Frame
+ 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ 1.2 3 process 35 thread 23 0x34e5 in sigpause ()
+ 1.3 4 process 35 thread 27 0x34e5 in sigpause ()
+* 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8)
+@end smallexample
+
On Solaris, you can display more information about user threads with a
Solaris-specific command:
@end table
@table @code
-@kindex thread @var{threadno}
-@item thread @var{threadno}
-Make thread number @var{threadno} the current thread. The command
-argument @var{threadno} is the internal @value{GDBN} thread number, as
-shown in the first field of the @samp{info threads} display.
-@value{GDBN} responds by displaying the system identifier of the thread
-you selected, and its current stack frame summary:
+@kindex thread @var{thread-id}
+@item thread @var{thread-id}
+Make thread ID @var{thread-id} the current thread. The command
+argument @var{thread-id} is the @value{GDBN} thread ID, as shown in
+the first field of the @samp{info threads} display, with or without an
+inferior qualifier (e.g., @samp{2.1} or @samp{1}).
+
+@value{GDBN} responds by displaying the system identifier of the
+thread you selected, and its current stack frame summary:
@smallexample
(@value{GDBP}) thread 2
@samp{Switching to} depends on your system's conventions for identifying
threads.
-@vindex $_thread@r{, convenience variable}
-The debugger convenience variable @samp{$_thread} contains the number
-of the current thread. You may find this useful in writing breakpoint
-conditional expressions, command scripts, and so forth. See
-@xref{Convenience Vars,, Convenience Variables}, for general
-information on convenience variables.
-
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{threadno} | all] @var{command}
+@item thread apply [@var{thread-id-list} | all [-ascending]] @var{command}
The @code{thread apply} command allows you to apply the named
-@var{command} to one or more threads. Specify the numbers of the
-threads that you want affected with the command argument
-@var{threadno}. It can be a single thread number, one of the numbers
-shown in the first field of the @samp{info threads} display; or it
-could be a range of thread numbers, as in @code{2-4}. To apply a
-command to all threads, type @kbd{thread apply all @var{command}}.
+@var{command} to one or more threads. Specify the threads that you
+want affected using the thread ID list syntax (@pxref{thread ID
+lists}), or specify @code{all} to apply to all threads. To apply a
+command to all threads in descending order, type @kbd{thread apply all
+@var{command}}. To apply a command to all threads in ascending order,
+type @kbd{thread apply all -ascending @var{command}}.
+
@kindex thread name
@cindex name a thread
the child process (@pxref{Attach}). From that point on you can debug
the child process just like any other process which you attached to.
-On some systems, @value{GDBN} provides support for debugging programs that
-create additional processes using the @code{fork} or @code{vfork} functions.
-Currently, the only platforms with this feature are HP-UX (11.x and later
-only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
+On some systems, @value{GDBN} provides support for debugging programs
+that create additional processes using the @code{fork} or @code{vfork}
+functions. On @sc{gnu}/Linux platforms, this feature is supported
+with kernel version 2.5.46 and later.
+
+The fork debugging commands are supported in native mode and when
+connected to @code{gdbserver} in either @code{target remote} mode or
+@code{target extended-remote} mode.
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
Program exited normally.
(@value{GDBP}) info inferiors
Id Description Executable
-* 2 <null> prog2
1 <null> prog1
+* 2 <null> prog2
@end smallexample
@item same
@end table
@end table
+@code{follow-exec-mode} is supported in native mode and
+@code{target extended-remote} mode.
+
You can use the @code{catch} command to make @value{GDBN} stop whenever
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
Catchpoints, ,Setting Catchpoints}.
program.
On some systems, you can set breakpoints in shared libraries before
-the executable is run. There is a minor limitation on HP-UX systems:
-you must wait until the executable is run in order to set breakpoints
-in shared library routines that are not called directly by the program
-(for example, routines that are arguments in a @code{pthread_create}
-call).
+the executable is run.
@cindex watchpoints
@cindex data breakpoints
@kindex tbreak
@item tbreak @var{args}
-Set a breakpoint enabled only for one stop. @var{args} are the
+Set a breakpoint enabled only for one stop. The @var{args} are the
same as for the @code{break} command, and the breakpoint is set in the same
way, but the breakpoint is automatically deleted after the first time your
program stops there. @xref{Disabling, ,Disabling Breakpoints}.
@kindex hbreak
@cindex hardware breakpoints
@item hbreak @var{args}
-Set a hardware-assisted breakpoint. @var{args} are the same as for the
+Set a hardware-assisted breakpoint. The @var{args} are the same as for the
@code{break} command and the breakpoint is set in the same way, but the
breakpoint requires hardware support and some target hardware may not
have this support. The main purpose of this is EPROM/ROM code
@kindex thbreak
@item thbreak @var{args}
-Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
+Set a hardware-assisted breakpoint enabled only for one stop. The @var{args}
are the same as for the @code{hbreak} command and the breakpoint is set in
the same way. However, like the @code{tbreak} command,
the breakpoint is automatically deleted after the
@item set breakpoint always-inserted off
All breakpoints, including newly added by the user, are inserted in
the target only when the target is resumed. All breakpoints are
-removed from the target when it stops.
+removed from the target when it stops. This is the default mode.
@item set breakpoint always-inserted on
Causes all breakpoints to be inserted in the target at all times. If
the user adds a new breakpoint, or changes an existing breakpoint, the
breakpoints in the target are updated immediately. A breakpoint is
-removed from the target only when breakpoint itself is removed.
-
-@cindex non-stop mode, and @code{breakpoint always-inserted}
-@item set breakpoint always-inserted auto
-This is the default mode. If @value{GDBN} is controlling the inferior
-in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
-@code{breakpoint always-inserted} mode is on. If @value{GDBN} is
-controlling the inferior in all-stop mode, @value{GDBN} behaves as if
-@code{breakpoint always-inserted} mode is off.
+removed from the target only when breakpoint itself is deleted.
@end table
@value{GDBN} handles conditional breakpoints by evaluating these conditions
catch errors where you have no clue what part of your program is the
culprit.)
-On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
-x86-based targets, @value{GDBN} includes support for hardware
-watchpoints, which do not slow down the running of your program.
+On some systems, such as most PowerPC or x86-based targets,
+@value{GDBN} includes support for hardware watchpoints, which do not
+slow down the running of your program.
@table @code
@kindex watch
-@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint for an expression. @value{GDBN} will break when the
expression @var{expr} is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
(@value{GDBP}) watch foo
@end smallexample
-If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
+If the command includes a @code{@r{[}thread @var{thread-id}@r{]}}
argument, @value{GDBN} breaks only when the thread identified by
-@var{threadnum} changes the value of @var{expr}. If any other threads
+@var{thread-id} changes the value of @var{expr}. If any other threads
change the value of @var{expr}, @value{GDBN} will not break. Note
that watchpoints restricted to a single thread in this way only work
with Hardware Watchpoints.
@end smallexample
@kindex rwatch
-@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint that will break when the value of @var{expr} is read
by the program.
@kindex awatch
-@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
@table @code
@kindex catch
@item catch @var{event}
-Stop when @var{event} occurs. @var{event} can be any of the following:
+Stop when @var{event} occurs. The @var{event} can be any of the following:
@table @code
@item throw @r{[}@var{regexp}@r{]}
@item exec
@kindex catch exec
@cindex break on fork/exec
-A call to @code{exec}. This is currently only available for HP-UX
-and @sc{gnu}/Linux.
+A call to @code{exec}.
@item syscall
@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
@item fork
@kindex catch fork
-A call to @code{fork}. This is currently only available for HP-UX
-and @sc{gnu}/Linux.
+A call to @code{fork}.
@item vfork
@kindex catch vfork
-A call to @code{vfork}. This is currently only available for HP-UX
-and @sc{gnu}/Linux.
+A call to @code{vfork}.
@item load @r{[}regexp@r{]}
@itemx unload @r{[}regexp@r{]}
@subsection Static Probe Points
@cindex static probe point, SystemTap
+@cindex static probe point, DTrace
@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands
for Statically Defined Tracing, and the probes are designed to have a tiny
-runtime code and data footprint, and no dynamic relocations. They are
-usable from assembly, C and C@t{++} languages. See
-@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
-for a good reference on how the @acronym{SDT} probes are implemented.
+runtime code and data footprint, and no dynamic relocations.
+
+Currently, the following types of probes are supported on
+ELF-compatible systems:
-Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
-@acronym{SDT} probes are supported on ELF-compatible systems. See
+@itemize @bullet
+
+@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
+@acronym{SDT} probes@footnote{See
@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
-for more information on how to add @code{SystemTap} @acronym{SDT} probes
-in your applications.
+for more information on how to add @code{SystemTap} @acronym{SDT}
+probes in your applications.}. @code{SystemTap} probes are usable
+from assembly, C and C@t{++} languages@footnote{See
+@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
+for a good reference on how the @acronym{SDT} probes are implemented.}.
+
+@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace})
+@acronym{USDT} probes. @code{DTrace} probes are usable from C and
+C@t{++} languages.
+@end itemize
@cindex semaphores on static probe points
-Some probes have an associated semaphore variable; for instance, this
-happens automatically if you defined your probe using a DTrace-style
-@file{.d} file. If your probe has a semaphore, @value{GDBN} will
-automatically enable it when you specify a breakpoint using the
-@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's
-location by some other method (e.g., @code{break file:line}), then
-@value{GDBN} will not automatically set the semaphore.
+Some @code{SystemTap} probes have an associated semaphore variable;
+for instance, this happens automatically if you defined your probe
+using a DTrace-style @file{.d} file. If your probe has a semaphore,
+@value{GDBN} will automatically enable it when you specify a
+breakpoint using the @samp{-probe-stap} notation. But, if you put a
+breakpoint at a probe's location by some other method (e.g.,
+@code{break file:line}), then @value{GDBN} will not automatically set
+the semaphore. @code{DTrace} probes do not support semaphores.
You can examine the available static static probes using @code{info
probes}, with optional arguments:
@table @code
@kindex info probes
-@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+@item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{type} is either @code{stap} for listing
+@code{SystemTap} probes or @code{dtrace} for listing @code{DTrace}
+probes. If omitted all probes are listed regardless of their types.
+
If given, @var{provider} is a regular expression used to match against provider
names when selecting which probes to list. If omitted, probes by all
probes from all providers are listed.
List the available static probes, from all types.
@end table
+@cindex enabling and disabling probes
+Some probe points can be enabled and/or disabled. The effect of
+enabling or disabling a probe depends on the type of probe being
+handled. Some @code{DTrace} probes can be enabled or
+disabled, but @code{SystemTap} probes cannot be disabled.
+
+You can enable (or disable) one or more probes using the following
+commands, with optional arguments:
+
+@table @code
+@kindex enable probes
+@item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{provider} is a regular expression used to match against
+provider names when selecting which probes to enable. If omitted,
+all probes from all providers are enabled.
+
+If given, @var{name} is a regular expression to match against probe
+names when selecting which probes to enable. If omitted, probe names
+are not considered when deciding whether to enable them.
+
+If given, @var{objfile} is a regular expression used to select which
+object files (executable or shared libraries) to examine. If not
+given, all object files are considered.
+
+@kindex disable probes
+@item disable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+See the @code{enable probes} command above for a description of the
+optional arguments accepted by this command.
+@end table
+
@vindex $_probe_arg@r{, convenience variable}
A probe may specify up to twelve arguments. These are available at the
point at which the probe is defined---that is, when the current PC is
at the probe's location. The arguments are available using the
convenience variables (@pxref{Convenience Vars})
-@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is
-an integer of the appropriate size; types are not preserved. The
+@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap}
+probes each probe argument is an integer of the appropriate size;
+types are not preserved. In @code{DTrace} probes types are preserved
+provided that they are recognized as such by @value{GDBN}; otherwise
+the value of the probe argument will be a long integer. The
convenience variable @code{$_probe_argc} holds the number of arguments
at the current probe point.
particular command you use). Either when continuing or when stepping,
your program may stop even sooner, due to a breakpoint or a signal. (If
it stops due to a signal, you may want to use @code{handle}, or use
-@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
+@samp{signal 0} to resume execution (@pxref{Signals, ,Signals}),
+or you may step into the signal's handler (@pxref{stepping and signal
+handlers}).)
@table @code
@kindex continue
@item until @var{location}
@itemx u @var{location}
-Continue running your program until either the specified location is
-reached, or the current stack frame returns. @var{location} is any of
+Continue running your program until either the specified @var{location} is
+reached, or the current stack frame returns. The location is any of
the forms described in @ref{Specify Location}.
This form of the command uses temporary breakpoints, and
hence is quicker than @code{until} without an argument. The specified
@cindex skipping over functions and files
The program you are debugging may contain some functions which are
-uninteresting to debug. The @code{skip} comand lets you tell @value{GDBN} to
-skip a function or all functions in a file when stepping.
+uninteresting to debug. The @code{skip} command lets you tell @value{GDBN} to
+skip a function, all functions in a file or a particular function in
+a particular file when stepping.
For example, consider the following C function:
@code{step} at line 103, you'll step over @code{boring} and directly into
@code{foo}.
-You can also instruct @value{GDBN} to skip all functions in a file, with, for
-example, @code{skip file boring.c}.
+Functions may be skipped by providing either a function name, linespec
+(@pxref{Specify Location}), regular expression that matches the function's
+name, file name or a @code{glob}-style pattern that matches the file name.
+
+On Posix systems the form of the regular expression is
+``Extended Regular Expressions''. See for example @samp{man 7 regex}
+on @sc{gnu}/Linux systems. On non-Posix systems the form of the regular
+expression is whatever is provided by the @code{regcomp} function of
+the underlying system.
+See for example @samp{man 7 glob} on @sc{gnu}/Linux systems for a
+description of @code{glob}-style patterns.
@table @code
+@kindex skip
+@item skip @r{[}@var{options}@r{]}
+The basic form of the @code{skip} command takes zero or more options
+that specify what to skip.
+The @var{options} argument is any useful combination of the following:
+
+@table @code
+@item -file @var{file}
+@itemx -fi @var{file}
+Functions in @var{file} will be skipped over when stepping.
+
+@item -gfile @var{file-glob-pattern}
+@itemx -gfi @var{file-glob-pattern}
+@cindex skipping over files via glob-style patterns
+Functions in files matching @var{file-glob-pattern} will be skipped
+over when stepping.
+
+@smallexample
+(gdb) skip -gfi utils/*.c
+@end smallexample
+
+@item -function @var{linespec}
+@itemx -fu @var{linespec}
+Functions named by @var{linespec} or the function containing the line
+named by @var{linespec} will be skipped over when stepping.
+@xref{Specify Location}.
+
+@item -rfunction @var{regexp}
+@itemx -rfu @var{regexp}
+@cindex skipping over functions via regular expressions
+Functions whose name matches @var{regexp} will be skipped over when stepping.
+
+This form is useful for complex function names.
+For example, there is generally no need to step into C@t{++} @code{std::string}
+constructors or destructors. Plus with C@t{++} templates it can be hard to
+write out the full name of the function, and often it doesn't matter what
+the template arguments are. Specifying the function to be skipped as a
+regular expression makes this easier.
+
+@smallexample
+(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(
+@end smallexample
+
+If you want to skip every templated C@t{++} constructor and destructor
+in the @code{std} namespace you can do:
+
+@smallexample
+(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(
+@end smallexample
+@end table
+
+If no options are specified, the function you're currently debugging
+will be skipped.
+
@kindex skip function
-@item skip @r{[}@var{linespec}@r{]}
-@itemx skip function @r{[}@var{linespec}@r{]}
+@item skip function @r{[}@var{linespec}@r{]}
After running this command, the function named by @var{linespec} or the
function containing the line named by @var{linespec} will be skipped over when
stepping. @xref{Specify Location}.
After running this command, any function whose source lives in @var{filename}
will be skipped over when stepping.
+@smallexample
+(gdb) skip file boring.c
+File boring.c will be skipped when stepping.
+@end smallexample
+
If you do not specify @var{filename}, functions whose source lives in the file
you're currently debugging will be skipped.
@end table
@table @emph
@item Identifier
A number identifying this skip.
-@item Type
-The type of this skip, either @samp{function} or @samp{file}.
@item Enabled or Disabled
-Enabled skips are marked with @samp{y}. Disabled skips are marked with @samp{n}.
-@item Address
-For function skips, this column indicates the address in memory of the function
-being skipped. If you've set a function skip on a function which has not yet
-been loaded, this field will contain @samp{<PENDING>}. Once a shared library
-which has the function is loaded, @code{info skip} will show the function's
-address here.
-@item What
-For file skips, this field contains the filename being skipped. For functions
-skips, this field contains the function name and its line number in the file
-where it is defined.
+Enabled skips are marked with @samp{y}.
+Disabled skips are marked with @samp{n}.
+@item Glob
+If the file name is a @samp{glob} pattern this is @samp{y}.
+Otherwise it is @samp{n}.
+@item File
+The name or @samp{glob} pattern of the file to be skipped.
+If no file is specified this is @samp{<none>}.
+@item RE
+If the function name is a @samp{regular expression} this is @samp{y}.
+Otherwise it is @samp{n}.
+@item Function
+The name or regular expression of the function to skip.
+If no function is specified this is @samp{<none>}.
@end table
@kindex skip delete
@kindex handle
@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
-Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
+Change the way @value{GDBN} handles signal @var{signal}. The @var{signal}
can be the number of a signal or its name (with or without the
@samp{SIG} at the beginning); a list of signal numbers of the form
@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
Program a Signal}.
+@cindex stepping and signal handlers
+@anchor{stepping and signal handlers}
+
+@value{GDBN} optimizes for stepping the mainline code. If a signal
+that has @code{handle nostop} and @code{handle pass} set arrives while
+a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is
+in progress, @value{GDBN} lets the signal handler run and then resumes
+stepping the mainline code once the signal handler returns. In other
+words, @value{GDBN} steps over the signal handler. This prevents
+signals that you've specified as not interesting (with @code{handle
+nostop}) from changing the focus of debugging unexpectedly. Note that
+the signal handler itself may still hit a breakpoint, stop for another
+signal that has @code{handle stop} in effect, or for any other event
+that normally results in stopping the stepping command sooner. Also
+note that @value{GDBN} still informs you that the program received a
+signal if @code{handle print} is set.
+
+@anchor{stepping into signal handlers}
+
+If you set @code{handle pass} for a signal, and your program sets up a
+handler for it, then issuing a stepping command, such as @code{step}
+or @code{stepi}, when your program is stopped due to the signal will
+step @emph{into} the signal handler (if the target supports that).
+
+Likewise, if you use the @code{queue-signal} command to queue a signal
+to be delivered to the current thread when execution of the thread
+resumes (@pxref{Signaling, ,Giving your Program a Signal}), then a
+stepping command will step into the signal handler.
+
+Here's an example, using @code{stepi} to step to the first instruction
+of @code{SIGUSR1}'s handler:
+
+@smallexample
+(@value{GDBP}) handle SIGUSR1
+Signal Stop Print Pass to program Description
+SIGUSR1 Yes Yes Yes User defined signal 1
+(@value{GDBP}) c
+Continuing.
+
+Program received signal SIGUSR1, User defined signal 1.
+main () sigusr1.c:28
+28 p = 0;
+(@value{GDBP}) si
+sigusr1_handler () at sigusr1.c:9
+9 @{
+@end smallexample
+
+The same, but using @code{queue-signal} instead of waiting for the
+program to receive the signal first:
+
+@smallexample
+(@value{GDBP}) n
+28 p = 0;
+(@value{GDBP}) queue-signal SIGUSR1
+(@value{GDBP}) si
+sigusr1_handler () at sigusr1.c:9
+9 @{
+(@value{GDBP})
+@end smallexample
+
@cindex extra signal information
@anchor{extra signal information}
Depending on target support, @code{$_siginfo} may also be writable.
+@cindex Intel MPX boundary violations
+@cindex boundary violations, Intel MPX
+On some targets, a @code{SIGSEGV} can be caused by a boundary
+violation, i.e., accessing an address outside of the allowed range.
+In those cases @value{GDBN} may displays additional information,
+depending on how @value{GDBN} has been told to handle the signal.
+With @code{handle stop SIGSEGV}, @value{GDBN} displays the violation
+kind: "Upper" or "Lower", the memory address accessed and the
+bounds, while with @code{handle nostop SIGSEGV} no additional
+information is displayed.
+
+The usual output of a segfault is:
+@smallexample
+Program received signal SIGSEGV, Segmentation fault
+0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
+68 value = *(p + len);
+@end smallexample
+
+While a bound violation is presented as:
+@smallexample
+Program received signal SIGSEGV, Segmentation fault
+Upper bound violation while accessing address 0x7fffffffc3b3
+Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]
+0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
+68 value = *(p + len);
+@end smallexample
+
@node Thread Stops
@section Stopping and Starting Multi-thread Programs
@item set scheduler-locking @var{mode}
@cindex scheduler locking mode
@cindex lock scheduler
-Set the scheduler locking mode. If it is @code{off}, then there is no
-locking and any thread may run at any time. If @code{on}, then only the
-current thread may run when the inferior is resumed. The @code{step}
-mode optimizes for single-stepping; it prevents other threads
-from preempting the current thread while you are stepping, so that
-the focus of debugging does not change unexpectedly.
-Other threads only rarely (or never) get a chance to run
-when you step. They are more likely to run when you @samp{next} over a
-function call, and they are completely free to run when you use commands
-like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
-thread hits a breakpoint during its timeslice, @value{GDBN} does not change
-the current thread away from the thread that you are debugging.
+Set the scheduler locking mode. It applies to normal execution,
+record mode, and replay mode. If it is @code{off}, then there is no
+locking and any thread may run at any time. If @code{on}, then only
+the current thread may run when the inferior is resumed. The
+@code{step} mode optimizes for single-stepping; it prevents other
+threads from preempting the current thread while you are stepping, so
+that the focus of debugging does not change unexpectedly. Other
+threads never get a chance to run when you step, and they are
+completely free to run when you use commands like @samp{continue},
+@samp{until}, or @samp{finish}. However, unless another thread hits a
+breakpoint during its timeslice, @value{GDBN} does not change the
+current thread away from the thread that you are debugging. The
+@code{replay} mode behaves like @code{off} in record mode and like
+@code{on} in replay mode.
@item show scheduler-locking
Display the current scheduler locking mode.
@cindex non-stop mode
@c This section is really only a place-holder, and needs to be expanded
-@c with more details.
+@c with more details.
For some multi-threaded targets, @value{GDBN} supports an optional
mode of operation in which you can examine stopped program threads in
the debugger while other threads continue to execute freely. This
-minimizes intrusion when debugging live systems, such as programs
-where some threads have real-time constraints or must continue to
+minimizes intrusion when debugging live systems, such as programs
+where some threads have real-time constraints or must continue to
respond to external events. This is referred to as @dfn{non-stop} mode.
In non-stop mode, when a thread stops to report a debugging event,
execution commands such as @code{continue} and @code{step} apply by default
only to the current thread in non-stop mode, rather than all threads as
in all-stop mode. This allows you to control threads explicitly in
-ways that are not possible in all-stop mode --- for example, stepping
+ways that are not possible in all-stop mode --- for example, stepping
one thread while allowing others to run freely, stepping
-one thread while holding all others stopped, or stepping several threads
+one thread while holding all others stopped, or stepping several threads
independently and simultaneously.
To enter non-stop mode, use this sequence of commands before you run
or attach to your program:
@smallexample
-# Enable the async interface.
-set target-async 1
-
# If using the CLI, pagination breaks non-stop.
set pagination off
@end table
Note these commands only reflect whether non-stop mode is enabled,
-not whether the currently-executing program is being run in non-stop mode.
+not whether the currently-executing program is being run in non-stop mode.
In particular, the @code{set non-stop} preference is only consulted when
-@value{GDBN} starts or connects to the target program, and it is generally
+@value{GDBN} starts or connects to the target program, and it is generally
not possible to switch modes once debugging has started. Furthermore,
since not all targets support non-stop mode, even when you have enabled
non-stop mode, @value{GDBN} may still fall back to all-stop operation by
default.
In non-stop mode, all execution commands apply only to the current thread
-by default. That is, @code{continue} only continues one thread.
+by default. That is, @code{continue} only continues one thread.
To continue all threads, issue @code{continue -a} or @code{c -a}.
-You can use @value{GDBN}'s background execution commands
+You can use @value{GDBN}'s background execution commands
(@pxref{Background Execution}) to run some threads in the background
-while you continue to examine or step others from @value{GDBN}.
+while you continue to examine or step others from @value{GDBN}.
The MI execution commands (@pxref{GDB/MI Program Execution}) are
always executed asynchronously in non-stop mode.
Suspending execution is done with the @code{interrupt} command when
-running in the background, or @kbd{Ctrl-c} during foreground execution.
-In all-stop mode, this stops the whole process;
-but in non-stop mode the interrupt applies only to the current thread.
+running in the background, or @kbd{Ctrl-c} during foreground execution.
+In all-stop mode, this stops the whole process;
+but in non-stop mode the interrupt applies only to the current thread.
To stop the whole program, use @code{interrupt -a}.
Other execution commands do not currently support the @code{-a} option.
In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
that thread current, as it does in all-stop mode. This is because the
-thread stop notifications are asynchronous with respect to @value{GDBN}'s
+thread stop notifications are asynchronous with respect to @value{GDBN}'s
command interpreter, and it would be confusing if @value{GDBN} unexpectedly
changed to a different thread just as you entered a command to operate on the
previously current thread.
@value{GDBN}'s execution commands have two variants: the normal
foreground (synchronous) behavior, and a background
-(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
+(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
the program to report that some thread has stopped before prompting for
another command. In background execution, @value{GDBN} immediately gives
a command prompt so that you can issue other commands while your program runs.
-You need to explicitly enable asynchronous mode before you can use
-background execution commands. You can use these commands to
-manipulate the asynchronous mode setting:
-
-@table @code
-@kindex set target-async
-@item set target-async on
-Enable asynchronous mode.
-@item set target-async off
-Disable asynchronous mode.
-@kindex show target-async
-@item show target-async
-Show the current target-async setting.
-@end table
-
If the target doesn't support async mode, @value{GDBN} issues an error
message if you attempt to use the background execution commands.
@item interrupt
@itemx interrupt -a
-Suspend execution of the running program. In all-stop mode,
+Suspend execution of the running program. In all-stop mode,
@code{interrupt} stops the whole process, but in non-stop mode, it stops
-only the current thread. To stop the whole program in non-stop mode,
+only the current thread. To stop the whole program in non-stop mode,
use @code{interrupt -a}.
@end table
@table @code
@cindex breakpoints and threads
@cindex thread breakpoints
-@kindex break @dots{} thread @var{threadno}
-@item break @var{linespec} thread @var{threadno}
-@itemx break @var{linespec} thread @var{threadno} if @dots{}
-@var{linespec} specifies source lines; there are several ways of
+@kindex break @dots{} thread @var{thread-id}
+@item break @var{location} thread @var{thread-id}
+@itemx break @var{location} thread @var{thread-id} if @dots{}
+@var{location} specifies source lines; there are several ways of
writing them (@pxref{Specify Location}), but the effect is always to
specify some source line.
-Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
+Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular thread reaches this breakpoint. @var{threadno} is one of the
-numeric thread identifiers assigned by @value{GDBN}, shown in the first
-column of the @samp{info threads} display.
+particular thread reaches this breakpoint. The @var{thread-id} specifier
+is one of the thread identifiers assigned by @value{GDBN}, shown
+in the first column of the @samp{info threads} display.
-If you do not specify @samp{thread @var{threadno}} when you set a
+If you do not specify @samp{thread @var{thread-id}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your
program.
You can use the @code{thread} qualifier on conditional breakpoints as
-well; in this case, place @samp{thread @var{threadno}} before or
+well; in this case, place @samp{thread @var{thread-id}} before or
after the breakpoint condition, like this:
@smallexample
@kindex record
@kindex record full
@kindex record btrace
+@kindex record btrace bts
+@kindex record btrace pt
+@kindex record bts
+@kindex record pt
@kindex rec
@kindex rec full
@kindex rec btrace
+@kindex rec btrace bts
+@kindex rec btrace pt
+@kindex rec bts
+@kindex rec pt
@item record @var{method}
This command starts the process record and replay target. The
recording method can be specified as parameter. Without a parameter
replay implementation. This method allows replaying and reverse
execution.
-@item btrace
-Hardware-supported instruction recording. This method does not allow
-replaying and reverse execution.
+@item btrace @var{format}
+Hardware-supported instruction recording. This method does not record
+data. Further, the data is collected in a ring buffer so old data will
+be overwritten when the buffer is full. It allows limited reverse
+execution. Variables and registers are not available during reverse
+execution.
+
+The recording format can be specified as parameter. Without a parameter
+the command chooses the recording format. The following recording
+formats are available:
+
+@table @code
+@item bts
+@cindex branch trace store
+Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In
+this format, the processor stores a from/to record for each executed
+branch in the btrace ring buffer.
+
+@item pt
+@cindex Intel Processor Trace
+Use the @dfn{Intel Processor Trace} recording format. In this
+format, the processor stores the execution trace in a compressed form
+that is afterwards decoded by @value{GDBN}.
-This recording method may not be available on all processors.
+The trace can be recorded with very low overhead. The compressed
+trace format also allows small trace buffers to already contain a big
+number of instructions compared to @acronym{BTS}.
+
+Decoding the recorded execution trace, on the other hand, is more
+expensive than decoding @acronym{BTS} trace. This is mostly due to the
+increased number of instructions to process. You should increase the
+buffer-size with care.
+@end table
+
+Not all recording formats may be available on all processors.
@end table
The process record and replay target can only debug a process that is
the @kbd{run} or @kbd{start} commands, and then start the recording
with the @kbd{record @var{method}} command.
-Both @code{record @var{method}} and @code{rec @var{method}} are
-aliases of @code{target record-@var{method}}.
-
@cindex displaced stepping, and process record and replay
Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
will be automatically disabled when process record and replay target
@item show record full memory-query
Show the current setting of @code{memory-query}.
+@kindex set record btrace
+The @code{btrace} record target does not trace data. As a
+convenience, when replaying, @value{GDBN} reads read-only memory off
+the live program directly, assuming that the addresses of the
+read-only areas don't change. This for example makes it possible to
+disassemble code while replaying, but not to print variables.
+In some cases, being able to inspect variables might be useful.
+You can use the following command for that:
+
+@item set record btrace replay-memory-access
+Control the behavior of the @code{btrace} recording method when
+accessing memory during replay. If @code{read-only} (the default),
+@value{GDBN} will only allow accesses to read-only memory.
+If @code{read-write}, @value{GDBN} will allow accesses to read-only
+and to read-write memory. Beware that the accessed memory corresponds
+to the live target and not necessarily to the current replay
+position.
+
+@kindex show record btrace
+@item show record btrace replay-memory-access
+Show the current setting of @code{replay-memory-access}.
+
+@kindex set record btrace bts
+@item set record btrace bts buffer-size @var{size}
+@itemx set record btrace bts buffer-size unlimited
+Set the requested ring buffer size for branch tracing in @acronym{BTS}
+format. Default is 64KB.
+
+If @var{size} is a positive number, then @value{GDBN} will try to
+allocate a buffer of at least @var{size} bytes for each new thread
+that uses the btrace recording method and the @acronym{BTS} format.
+The actually obtained buffer size may differ from the requested
+@var{size}. Use the @code{info record} command to see the actual
+buffer size for each thread that uses the btrace recording method and
+the @acronym{BTS} format.
+
+If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to
+allocate a buffer of 4MB.
+
+Bigger buffers mean longer traces. On the other hand, @value{GDBN} will
+also need longer to process the branch trace data before it can be used.
+
+@item show record btrace bts buffer-size @var{size}
+Show the current setting of the requested ring buffer size for branch
+tracing in @acronym{BTS} format.
+
+@kindex set record btrace pt
+@item set record btrace pt buffer-size @var{size}
+@itemx set record btrace pt buffer-size unlimited
+Set the requested ring buffer size for branch tracing in Intel
+Processor Trace format. Default is 16KB.
+
+If @var{size} is a positive number, then @value{GDBN} will try to
+allocate a buffer of at least @var{size} bytes for each new thread
+that uses the btrace recording method and the Intel Processor Trace
+format. The actually obtained buffer size may differ from the
+requested @var{size}. Use the @code{info record} command to see the
+actual buffer size for each thread.
+
+If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to
+allocate a buffer of 4MB.
+
+Bigger buffers mean longer traces. On the other hand, @value{GDBN} will
+also need longer to process the branch trace data before it can be used.
+
+@item show record btrace pt buffer-size @var{size}
+Show the current setting of the requested ring buffer size for branch
+tracing in Intel Processor Trace format.
+
@kindex info record
@item info record
Show various statistics about the recording depending on the recording
@end itemize
@item btrace
-For the @code{btrace} recording method, it shows the number of
-instructions that have been recorded and the number of blocks of
-sequential control-flow that is formed by the recorded instructions.
+For the @code{btrace} recording method, it shows:
+
+@itemize @bullet
+@item
+Recording format.
+@item
+Number of instructions that have been recorded.
+@item
+Number of blocks of sequential control-flow formed by the recorded
+instructions.
+@item
+Whether in record mode or replay mode.
+@end itemize
+
+For the @code{bts} recording format, it also shows:
+@itemize @bullet
+@item
+Size of the perf ring buffer.
+@end itemize
+
+For the @code{pt} recording format, it also shows:
+@itemize @bullet
+@item
+Size of the perf ring buffer.
+@end itemize
@end table
@kindex record delete
Disassembles instructions from the recorded execution log. By
default, ten instructions are disassembled. This can be changed using
the @code{set record instruction-history-size} command. Instructions
-are printed in execution order. There are several ways to specify
-what part of the execution log to disassemble:
+are printed in execution order.
+
+It can also print mixed source+disassembly if you specify the the
+@code{/m} or @code{/s} modifier, and print the raw instructions in hex
+as well as in symbolic form by specifying the @code{/r} modifier.
+
+The current position marker is printed for the instruction at the
+current program counter value. This instruction can appear multiple
+times in the trace and the current position marker will be printed
+every time. To omit the current position marker, specify the
+@code{/p} modifier.
+
+To better align the printed instructions when the trace contains
+instructions from more than one function, the function name may be
+omitted by specifying the @code{/f} modifier.
+
+Speculatively executed instructions are prefixed with @samp{?}. This
+feature is not available for all recording formats.
+
+There are several ways to specify what part of the execution log to
+disassemble:
@table @code
@item record instruction-history @var{insn}
@item record instruction-history -
Disassembles ten more instructions before the last disassembly.
-@item record instruction-history @var{begin} @var{end}
+@item record instruction-history @var{begin}, @var{end}
Disassembles instructions beginning with instruction number
@var{begin} until instruction number @var{end}. The instruction
-number @var{end} is not included.
+number @var{end} is included.
@end table
This command may not be available for all recording methods.
function giving the name of that function, the source lines
for this instruction sequence (if the @code{/l} modifier is
specified), and the instructions numbers that form the sequence (if
-the @code{/i} modifier is specified).
+the @code{/i} modifier is specified). The function names are indented
+to reflect the call stack depth if the @code{/c} modifier is
+specified. The @code{/l}, @code{/i}, and @code{/c} modifiers can be
+given together.
@smallexample
(@value{GDBP}) @b{list 1, 10}
8 foo ();
9 ...
10 @}
-(@value{GDBP}) @b{record function-call-history /l}
-1 foo.c:6-8 bar
-2 foo.c:2-3 foo
-3 foo.c:9-10 bar
+(@value{GDBP}) @b{record function-call-history /ilc}
+1 bar inst 1,4 at foo.c:6,8
+2 foo inst 5,10 at foo.c:2,3
+3 bar inst 11,13 at foo.c:9,10
@end smallexample
By default, ten lines are printed. This can be changed using the
@item record function-call-history -
Prints ten more functions before the last ten-line print.
-@item record function-call-history @var{begin} @var{end}
+@item record function-call-history @var{begin}, @var{end}
Prints functions beginning with function number @var{begin} until
-function number @var{end}. The function number @var{end} is not
-included.
+function number @var{end}. The function number @var{end} is included.
@end table
This command may not be available for all recording methods.
@menu
* Frames:: Stack frames
* Backtrace:: Backtraces
-* Frame Filter Management:: Managing frame filters
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
+* Frame Filter Management:: Managing frame filters
@end menu
correct tracing of the function call chain. However, @value{GDBN} has
no provision for frameless functions elsewhere in the stack.
-@table @code
-@kindex frame@r{, command}
-@cindex current stack frame
-@item frame @var{args}
-The @code{frame} command allows you to move from one stack frame to another,
-and to print the stack frame you select. @var{args} may be either the
-address of the frame or the stack frame number. Without an argument,
-@code{frame} prints the current stack frame.
-
-@kindex select-frame
-@cindex selecting frame silently
-@item select-frame
-The @code{select-frame} command allows you to move from one stack frame
-to another without printing the frame. This is the silent version of
-@code{frame}.
-@end table
-
@node Backtrace
@section Backtraces
@itemx bt full
@itemx bt full @var{n}
@itemx bt full -@var{n}
-Print the values of the local variables also. @var{n} specifies the
-number of frames to print, as described above.
+Print the values of the local variables also. As described above,
+@var{n} specifies the number of frames to print.
@item backtrace no-filters
@itemx bt no-filters
Show the current way to display filenames.
@end table
+@node Selection
+@section Selecting a Frame
+
+Most commands for examining the stack and other data in your program work on
+whichever stack frame is selected at the moment. Here are the commands for
+selecting a stack frame; all of them finish by printing a brief description
+of the stack frame just selected.
+
+@table @code
+@kindex frame@r{, selecting}
+@kindex f @r{(@code{frame})}
+@item frame @var{n}
+@itemx f @var{n}
+Select frame number @var{n}. Recall that frame zero is the innermost
+(currently executing) frame, frame one is the frame that called the
+innermost one, and so on. The highest-numbered frame is the one for
+@code{main}.
+
+@item frame @var{stack-addr} [ @var{pc-addr} ]
+@itemx f @var{stack-addr} [ @var{pc-addr} ]
+Select the frame at address @var{stack-addr}. This is useful mainly if the
+chaining of stack frames has been damaged by a bug, making it
+impossible for @value{GDBN} to assign numbers properly to all frames. In
+addition, this can be useful when your program has multiple stacks and
+switches between them. The optional @var{pc-addr} can also be given to
+specify the value of PC for the stack frame.
+
+@kindex up
+@item up @var{n}
+Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
+numbers @var{n}, this advances toward the outermost frame, to higher
+frame numbers, to frames that have existed longer.
+
+@kindex down
+@kindex do @r{(@code{down})}
+@item down @var{n}
+Move @var{n} frames down the stack; @var{n} defaults to 1. For
+positive numbers @var{n}, this advances toward the innermost frame, to
+lower frame numbers, to frames that were created more recently.
+You may abbreviate @code{down} as @code{do}.
+@end table
+
+All of these commands end by printing two lines of output describing the
+frame. The first line shows the frame number, the function name, the
+arguments, and the source file and line number of execution in that
+frame. The second line shows the text of that source line.
+
+@need 1000
+For example:
+
+@smallexample
+@group
+(@value{GDBP}) up
+#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
+ at env.c:10
+10 read_input_file (argv[i]);
+@end group
+@end smallexample
+
+After such a printout, the @code{list} command with no arguments
+prints ten lines centered on the point of execution in the frame.
+You can also edit the program at the point of execution with your favorite
+editing program by typing @code{edit}.
+@xref{List, ,Printing Source Lines},
+for details.
+
+@table @code
+@kindex select-frame
+@item select-frame
+The @code{select-frame} command is a variant of @code{frame} that does
+not display the new frame after selecting it. This command is
+intended primarily for use in @value{GDBN} command scripts, where the
+output might be unnecessary and distracting.
+
+@kindex down-silently
+@kindex up-silently
+@item up-silently @var{n}
+@itemx down-silently @var{n}
+These two commands are variants of @code{up} and @code{down},
+respectively; they differ in that they do their work silently, without
+causing display of the new frame. They are intended primarily for use
+in @value{GDBN} command scripts, where the output might be unnecessary and
+distracting.
+@end table
+
+@node Frame Info
+@section Information About a Frame
+
+There are several other commands to print information about the selected
+stack frame.
+
+@table @code
+@item frame
+@itemx f
+When used without any argument, this command does not change which
+frame is selected, but prints a brief description of the currently
+selected stack frame. It can be abbreviated @code{f}. With an
+argument, this command is used to select a stack frame.
+@xref{Selection, ,Selecting a Frame}.
+
+@kindex info frame
+@kindex info f @r{(@code{info frame})}
+@item info frame
+@itemx info f
+This command prints a verbose description of the selected stack frame,
+including:
+
+@itemize @bullet
+@item
+the address of the frame
+@item
+the address of the next frame down (called by this frame)
+@item
+the address of the next frame up (caller of this frame)
+@item
+the language in which the source code corresponding to this frame is written
+@item
+the address of the frame's arguments
+@item
+the address of the frame's local variables
+@item
+the program counter saved in it (the address of execution in the caller frame)
+@item
+which registers were saved in the frame
+@end itemize
+
+@noindent The verbose description is useful when
+something has gone wrong that has made the stack format fail to fit
+the usual conventions.
+
+@item info frame @var{addr}
+@itemx info f @var{addr}
+Print a verbose description of the frame at address @var{addr}, without
+selecting that frame. The selected frame remains unchanged by this
+command. This requires the same kind of address (more than one for some
+architectures) that you specify in the @code{frame} command.
+@xref{Selection, ,Selecting a Frame}.
+
+@kindex info args
+@item info args
+Print the arguments of the selected frame, each on a separate line.
+
+@item info locals
+@kindex info locals
+Print the local variables of the selected frame, each on a separate
+line. These are all variables (declared either static or automatic)
+accessible at the point of execution of the selected frame.
+
+@end table
+
@node Frame Filter Management
@section Management of Frame Filters.
@cindex managing frame filters
@anchor{disable frame-filter all}
@item disable frame-filter @var{filter-dictionary} @var{filter-name}
Disable a frame filter in the dictionary matching
-@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
+@var{filter-dictionary} and @var{filter-name}. The
@var{filter-dictionary} may be @code{all}, @code{global},
-@code{progspace} or the name of the object file where the frame filter
+@code{progspace}, or the name of the object file where the frame filter
dictionary resides. When @code{all} is specified, all frame filters
-across all dictionaries are disabled. @var{filter-name} is the name
+across all dictionaries are disabled. The @var{filter-name} is the name
of the frame filter and is used when @code{all} is not the option for
@var{filter-dictionary}. A disabled frame-filter is not deleted, it
may be enabled again later.
@kindex enable frame-filter
@item enable frame-filter @var{filter-dictionary} @var{filter-name}
Enable a frame filter in the dictionary matching
-@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
+@var{filter-dictionary} and @var{filter-name}. The
@var{filter-dictionary} may be @code{all}, @code{global},
@code{progspace} or the name of the object file where the frame filter
dictionary resides. When @code{all} is specified, all frame filters across
-all dictionaries are enabled. @var{filter-name} is the name of the frame
+all dictionaries are enabled. The @var{filter-name} is the name of the frame
filter and is used when @code{all} is not the option for
@var{filter-dictionary}.
@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority}
Set the @var{priority} of a frame filter in the dictionary matching
@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}. @var{filter-dictionary} may be @code{global},
+@var{filter-name}. The @var{filter-dictionary} may be @code{global},
@code{progspace} or the name of the object file where the frame filter
-dictionary resides. @var{priority} is an integer.
+dictionary resides. The @var{priority} is an integer.
@kindex show frame-filter priority
@item show frame-filter priority @var{filter-dictionary} @var{filter-name}
Show the @var{priority} of a frame filter in the dictionary matching
@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}. @var{filter-dictionary} may be @code{global},
+@var{filter-name}. The @var{filter-dictionary} may be @code{global},
@code{progspace} or the name of the object file where the frame filter
dictionary resides.
@end smallexample
@end table
-@node Selection
-@section Selecting a Frame
-
-Most commands for examining the stack and other data in your program work on
-whichever stack frame is selected at the moment. Here are the commands for
-selecting a stack frame; all of them finish by printing a brief description
-of the stack frame just selected.
-
-@table @code
-@kindex frame@r{, selecting}
-@kindex f @r{(@code{frame})}
-@item frame @var{n}
-@itemx f @var{n}
-Select frame number @var{n}. Recall that frame zero is the innermost
-(currently executing) frame, frame one is the frame that called the
-innermost one, and so on. The highest-numbered frame is the one for
-@code{main}.
-
-@item frame @var{addr}
-@itemx f @var{addr}
-Select the frame at address @var{addr}. This is useful mainly if the
-chaining of stack frames has been damaged by a bug, making it
-impossible for @value{GDBN} to assign numbers properly to all frames. In
-addition, this can be useful when your program has multiple stacks and
-switches between them.
-
-On the SPARC architecture, @code{frame} needs two addresses to
-select an arbitrary frame: a frame pointer and a stack pointer.
-
-On the @acronym{MIPS} and Alpha architecture, it needs two addresses: a stack
-pointer and a program counter.
-
-On the 29k architecture, it needs three addresses: a register stack
-pointer, a program counter, and a memory stack pointer.
-
-@kindex up
-@item up @var{n}
-Move @var{n} frames up the stack. For positive numbers @var{n}, this
-advances toward the outermost frame, to higher frame numbers, to frames
-that have existed longer. @var{n} defaults to one.
-
-@kindex down
-@kindex do @r{(@code{down})}
-@item down @var{n}
-Move @var{n} frames down the stack. For positive numbers @var{n}, this
-advances toward the innermost frame, to lower frame numbers, to frames
-that were created more recently. @var{n} defaults to one. You may
-abbreviate @code{down} as @code{do}.
-@end table
-
-All of these commands end by printing two lines of output describing the
-frame. The first line shows the frame number, the function name, the
-arguments, and the source file and line number of execution in that
-frame. The second line shows the text of that source line.
-
-@need 1000
-For example:
-
-@smallexample
-@group
-(@value{GDBP}) up
-#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
- at env.c:10
-10 read_input_file (argv[i]);
-@end group
-@end smallexample
-
-After such a printout, the @code{list} command with no arguments
-prints ten lines centered on the point of execution in the frame.
-You can also edit the program at the point of execution with your favorite
-editing program by typing @code{edit}.
-@xref{List, ,Printing Source Lines},
-for details.
-
-@table @code
-@kindex down-silently
-@kindex up-silently
-@item up-silently @var{n}
-@itemx down-silently @var{n}
-These two commands are variants of @code{up} and @code{down},
-respectively; they differ in that they do their work silently, without
-causing display of the new frame. They are intended primarily for use
-in @value{GDBN} command scripts, where the output might be unnecessary and
-distracting.
-@end table
-
-@node Frame Info
-@section Information About a Frame
-
-There are several other commands to print information about the selected
-stack frame.
-
-@table @code
-@item frame
-@itemx f
-When used without any argument, this command does not change which
-frame is selected, but prints a brief description of the currently
-selected stack frame. It can be abbreviated @code{f}. With an
-argument, this command is used to select a stack frame.
-@xref{Selection, ,Selecting a Frame}.
-
-@kindex info frame
-@kindex info f @r{(@code{info frame})}
-@item info frame
-@itemx info f
-This command prints a verbose description of the selected stack frame,
-including:
-
-@itemize @bullet
-@item
-the address of the frame
-@item
-the address of the next frame down (called by this frame)
-@item
-the address of the next frame up (caller of this frame)
-@item
-the language in which the source code corresponding to this frame is written
-@item
-the address of the frame's arguments
-@item
-the address of the frame's local variables
-@item
-the program counter saved in it (the address of execution in the caller frame)
-@item
-which registers were saved in the frame
-@end itemize
-
-@noindent The verbose description is useful when
-something has gone wrong that has made the stack format fail to fit
-the usual conventions.
-
-@item info frame @var{addr}
-@itemx info f @var{addr}
-Print a verbose description of the frame at address @var{addr}, without
-selecting that frame. The selected frame remains unchanged by this
-command. This requires the same kind of address (more than one for some
-architectures) that you specify in the @code{frame} command.
-@xref{Selection, ,Selecting a Frame}.
-
-@kindex info args
-@item info args
-Print the arguments of the selected frame, each on a separate line.
-
-@item info locals
-@kindex info locals
-Print the local variables of the selected frame, each on a separate
-line. These are all variables (declared either static or automatic)
-accessible at the point of execution of the selected frame.
-
-@end table
-
-
@node Source
@chapter Examining Source Files
each repetition moves up in the source file.
In general, the @code{list} command expects you to supply zero, one or two
-@dfn{linespecs}. Linespecs specify source lines; there are several ways
+@dfn{locations}. Locations specify source lines; there are several ways
of writing them (@pxref{Specify Location}), but the effect is always
to specify some source line.
Here is a complete description of the possible arguments for @code{list}:
@table @code
-@item list @var{linespec}
-Print lines centered around the line specified by @var{linespec}.
+@item list @var{location}
+Print lines centered around the line specified by @var{location}.
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-linespecs. When a @code{list} command has two linespecs, and the
-source file of the second linespec is omitted, this refers to
-the same source file as the first linespec.
+locations. When a @code{list} command has two locations, and the
+source file of the second location is omitted, this refers to
+the same source file as the first location.
@item list ,@var{last}
Print lines ending with @var{last}.
@node Specify Location
@section Specifying a Location
@cindex specifying location
-@cindex linespec
+@cindex location
+@cindex source location
+
+@menu
+* Linespec Locations:: Linespec locations
+* Explicit Locations:: Explicit locations
+* Address Locations:: Address locations
+@end menu
Several @value{GDBN} commands accept arguments that specify a location
of your program's code. Since @value{GDBN} is a source-level
-debugger, a location usually specifies some line in the source code;
-for that reason, locations are also known as @dfn{linespecs}.
+debugger, a location usually specifies some line in the source code.
+Locations may be specified using three different formats:
+linespec locations, explicit locations, or address locations.
+
+@node Linespec Locations
+@subsection Linespec Locations
+@cindex linespec locations
-Here are all the different ways of specifying a code location that
-@value{GDBN} understands:
+A @dfn{linespec} is a colon-separated list of source location parameters such
+as file name, function name, etc. Here are all the different ways of
+specifying a linespec:
@table @code
@item @var{linenum}
functions in different source files.
@item @var{label}
-Specifies the line at which the label named @var{label} appears.
-@value{GDBN} searches for the label in the function corresponding to
-the currently selected stack frame. If there is no current selected
-stack frame (for instance, if the inferior is not running), then
-@value{GDBN} will not search for a label.
-
-@item *@var{address}
-Specifies the program address @var{address}. For line-oriented
-commands, such as @code{list} and @code{edit}, this specifies a source
-line that contains @var{address}. For @code{break} and other
-breakpoint oriented commands, this can be used to set breakpoints in
+Specifies the line at which the label named @var{label} appears
+in the function corresponding to the currently selected stack frame.
+If there is no current selected stack frame (for instance, if the inferior
+is not running), then @value{GDBN} will not search for a label.
+
+@cindex breakpoint at static probe point
+@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static probes. @xref{Static Probe Points}, for more
+information on finding and using static probes. This form of linespec
+specifies the location of such a static probe.
+
+If @var{objfile} is given, only probes coming from that shared library
+or executable matching @var{objfile} as a regular expression are considered.
+If @var{provider} is given, then only probes from that provider are considered.
+If several probes match the spec, @value{GDBN} will insert a breakpoint at
+each one of those probes.
+@end table
+
+@node Explicit Locations
+@subsection Explicit Locations
+@cindex explicit locations
+
+@dfn{Explicit locations} allow the user to directly specify the source
+location's parameters using option-value pairs.
+
+Explicit locations are useful when several functions, labels, or
+file names have the same name (base name for files) in the program's
+sources. In these cases, explicit locations point to the source
+line you meant more accurately and unambiguously. Also, using
+explicit locations might be faster in large programs.
+
+For example, the linespec @samp{foo:bar} may refer to a function @code{bar}
+defined in the file named @file{foo} or the label @code{bar} in a function
+named @code{foo}. @value{GDBN} must search either the file system or
+the symbol table to know.
+
+The list of valid explicit location options is summarized in the
+following table:
+
+@table @code
+@item -source @var{filename}
+The value specifies the source file name. To differentiate between
+files with the same base name, prepend as many directories as is necessary
+to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise
+@value{GDBN} will use the first file it finds with the given base
+name. This option requires the use of either @code{-function} or @code{-line}.
+
+@item -function @var{function}
+The value specifies the name of a function. Operations
+on function locations unmodified by other options (such as @code{-label}
+or @code{-line}) refer to the line that begins the body of the function.
+In C, for example, this is the line with the open brace.
+
+@item -label @var{label}
+The value specifies the name of a label. When the function
+name is not specified, the label is searched in the function of the currently
+selected stack frame.
+
+@item -line @var{number}
+The value specifies a line offset for the location. The offset may either
+be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on
+the command. When specified without any other options, the line offset is
+relative to the current line.
+@end table
+
+Explicit location options may be abbreviated by omitting any non-unique
+trailing characters from the option name, e.g., @code{break -s main.c -li 3}.
+
+@node Address Locations
+@subsection Address Locations
+@cindex address locations
+
+@dfn{Address locations} indicate a specific program address. They have
+the generalized form *@var{address}.
+
+For line-oriented commands, such as @code{list} and @code{edit}, this
+specifies a source line that contains @var{address}. For @code{break} and
+other breakpoint-oriented commands, this can be used to set breakpoints in
parts of your program which do not have debugging information or
source files.
Here @var{address} may be any expression valid in the current working
language (@pxref{Languages, working language}) that specifies a code
address. In addition, as a convenience, @value{GDBN} extends the
-semantics of expressions used in locations to cover the situations
-that frequently happen during debugging. Here are the various forms
+semantics of expressions used in locations to cover several situations
+that frequently occur during debugging. Here are the various forms
of @var{address}:
@table @code
This form specifies the address of the function's first instruction,
before the stack frame and arguments have been set up.
-@item '@var{filename}'::@var{funcaddr}
+@item '@var{filename}':@var{funcaddr}
Like @var{funcaddr} above, but also specifies the name of the source
file explicitly. This is useful if the name of the function does not
specify the function unambiguously, e.g., if there are several
functions with identical names in different source files.
@end table
-@cindex breakpoint at static probe point
-@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
-The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
-applications to embed static probes. @xref{Static Probe Points}, for more
-information on finding and using static probes. This form of linespec
-specifies the location of such a static probe.
-
-If @var{objfile} is given, only probes coming from that shared library
-or executable matching @var{objfile} as a regular expression are considered.
-If @var{provider} is given, then only probes from that provider are considered.
-If several probes match the spec, @value{GDBN} will insert a breakpoint at
-each one of those probes.
-
-@end table
-
-
@node Edit
@section Editing Source Files
@cindex editing source files
@file{/mnt/cross/baz.c}, then the command
@smallexample
-(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+(@value{GDBP}) set substitute-path /foo/bar /mnt/cross
@end smallexample
@noindent
-will tell @value{GDBN} to replace @samp{/usr/src} with
+will tell @value{GDBN} to replace @samp{/foo/bar} with
@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
@file{baz.c} even though it was moved.
@table @code
@kindex info line
-@item info line @var{linespec}
+@item info line @var{location}
Print the starting and ending addresses of the compiled code for
-source line @var{linespec}. You can specify source lines in any of
+source line @var{location}. You can specify source lines in any of
the ways documented in @ref{Specify Location}.
@end table
@noindent
@cindex code address and its source line
We can also inquire (using @code{*@var{addr}} as the form for
-@var{linespec}) what source line covers a particular address:
+@var{location}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
@cindex listing machine instructions
@item disassemble
@itemx disassemble /m
+@itemx disassemble /s
@itemx disassemble /r
This specialized command dumps a range of memory as machine
instructions. It can also print mixed source+disassembly by specifying
-the @code{/m} modifier and print the raw instructions in hex as well as
-in symbolic form by specifying the @code{/r}.
+the @code{/m} or @code{/s} modifier and print the raw instructions in hex
+as well as in symbolic form by specifying the @code{/r} modifier.
The default memory range is the function surrounding the
program counter of the selected frame. A single argument to this
command is a program counter value; @value{GDBN} dumps the function
End of assembler dump.
@end smallexample
-Here is an example showing mixed source+assembly for Intel x86, when the
-program is stopped just after function prologue:
+Here is an example showing mixed source+assembly for Intel x86
+with @code{/m} or @code{/s}, when the program is stopped just after
+function prologue in a non-optimized function with no inline code.
@smallexample
(@value{GDBP}) disas /m main
End of assembler dump.
@end smallexample
+The @code{/m} option is deprecated as its output is not useful when
+there is either inlined code or re-ordered code.
+The @code{/s} option is the preferred choice.
+Here is an example for AMD x86-64 showing the difference between
+@code{/m} output and @code{/s} output.
+This example has one inline function defined in a header file,
+and the code is compiled with @samp{-O2} optimization.
+Note how the @code{/m} output is missing the disassembly of
+several instructions that are present in the @code{/s} output.
+
+@file{foo.h}:
+
+@smallexample
+int
+foo (int a)
+@{
+ if (a < 0)
+ return a * 2;
+ if (a == 0)
+ return 1;
+ return a + 10;
+@}
+@end smallexample
+
+@file{foo.c}:
+
+@smallexample
+#include "foo.h"
+volatile int x, y;
+int
+main ()
+@{
+ x = foo (y);
+ return 0;
+@}
+@end smallexample
+
+@smallexample
+(@value{GDBP}) disas /m main
+Dump of assembler code for function main:
+5 @{
+
+6 x = foo (y);
+ 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y>
+ 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x>
+
+7 return 0;
+8 @}
+ 0x000000000040041d <+29>: xor %eax,%eax
+ 0x000000000040041f <+31>: retq
+ 0x0000000000400420 <+32>: add %eax,%eax
+ 0x0000000000400422 <+34>: jmp 0x400417 <main+23>
+
+End of assembler dump.
+(@value{GDBP}) disas /s main
+Dump of assembler code for function main:
+foo.c:
+5 @{
+6 x = foo (y);
+ 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y>
+
+foo.h:
+4 if (a < 0)
+ 0x0000000000400406 <+6>: test %eax,%eax
+ 0x0000000000400408 <+8>: js 0x400420 <main+32>
+
+6 if (a == 0)
+7 return 1;
+8 return a + 10;
+ 0x000000000040040a <+10>: lea 0xa(%rax),%edx
+ 0x000000000040040d <+13>: test %eax,%eax
+ 0x000000000040040f <+15>: mov $0x1,%eax
+ 0x0000000000400414 <+20>: cmovne %edx,%eax
+
+foo.c:
+6 x = foo (y);
+ 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x>
+
+7 return 0;
+8 @}
+ 0x000000000040041d <+29>: xor %eax,%eax
+ 0x000000000040041f <+31>: retq
+
+foo.h:
+5 return a * 2;
+ 0x0000000000400420 <+32>: add %eax,%eax
+ 0x0000000000400422 <+34>: jmp 0x400417 <main+23>
+End of assembler dump.
+@end smallexample
+
Here is another example showing raw instructions in hex for AMD x86-64,
@smallexample
End of assembler dump.
@end smallexample
-Addresses cannot be specified as a linespec (@pxref{Specify Location}).
+Addresses cannot be specified as a location (@pxref{Specify Location}).
So, for example, if you want to disassemble function @code{bar}
in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
and not @samp{disassemble foo.c:bar}.
character set than GDB does
* Caching Target Data:: Data caching for targets
* Searching Memory:: Searching memory for a sequence of bytes
+* Value Sizes:: Managing memory allocated for values
@end menu
@node Expressions
@cindex casts, to view memory
@item @{@var{type}@} @var{addr}
Refers to an object of type @var{type} stored at address @var{addr} in
-memory. @var{addr} may be any expression whose value is an integer or
-pointer (but parentheses are required around binary operators, just as in
-a cast). This construct is allowed regardless of what kind of data is
-normally supposed to reside at @var{addr}.
+memory. The address @var{addr} may be any expression whose value is
+an integer or pointer (but parentheses are required around binary
+operators, just as in a cast). This construct is allowed regardless
+of what kind of data is normally supposed to reside at @var{addr}.
@end table
@node Ambiguous Expressions
@table @r
@item @var{n}, the repeat count
The repeat count is a decimal integer; the default is 1. It specifies
-how much memory (counting by units @var{u}) to display.
+how much memory (counting by units @var{u}) to display. If a negative
+number is specified, memory is examined backward from @var{addr}.
@c This really is **decimal**; unaffected by 'set radix' as of GDB
@c 4.1.2.
words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
+You can also specify a negative repeat count to examine memory backward
+from the given address. For example, @samp{x/-3uh 0x54320} prints three
+halfwords (@code{h}) at @code{0x54314}, @code{0x54328}, and @code{0x5431c}.
+
Since the letters indicating unit sizes are all distinct from the
letters specifying output formats, you do not have to remember whether
unit size or format comes first; either order works. The output
@code{disassemble} gives an alternative way of inspecting machine
instructions; see @ref{Machine Code,,Source and Machine Code}.
+If a negative repeat count is specified for the formats @samp{s} or @samp{i},
+the command displays null-terminated strings or instructions before the given
+address as many as the absolute value of the given number. For the @samp{i}
+format, we use line number information in the debug info to accurately locate
+instruction boundaries while disassembling backward. If line info is not
+available, the command stops examining memory with an error message.
+
All the defaults for the arguments to @code{x} are designed to make it
easy to continue scanning memory with minimal specifications each time
you use @code{x}. For example, after you have inspected three machine
are from the last memory unit printed; this is not the same as the last
address printed if several units were printed on the last line of output.
+@anchor{addressable memory unit}
+@cindex addressable memory unit
+Most targets have an addressable memory unit size of 8 bits. This means
+that to each memory address are associated 8 bits of data. Some
+targets, however, have other addressable memory unit sizes.
+Within @value{GDBN} and this document, the term
+@dfn{addressable memory unit} (or @dfn{memory unit} for short) is used
+when explicitly referring to a chunk of data of that size. The word
+@dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of
+the addressable memory unit size of the target. For most systems,
+addressable memory unit is a synonym of byte.
+
@cindex remote memory comparison
+@cindex target memory comparison
@cindex verify remote memory image
+@cindex verify target memory image
When you are debugging a program running on a remote target machine
-(@pxref{Remote Debugging}), you may wish to verify the program's image in the
-remote machine's memory against the executable file you downloaded to
-the target. The @code{compare-sections} command is provided for such
-situations.
+(@pxref{Remote Debugging}), you may wish to verify the program's image
+in the remote machine's memory against the executable file you
+downloaded to the target. Or, on any target, you may want to check
+whether the program has corrupted its own read-only sections. The
+@code{compare-sections} command is provided for such situations.
@table @code
@kindex compare-sections
-@item compare-sections @r{[}@var{section-name}@r{]}
+@item compare-sections @r{[}@var{section-name}@r{|}@code{-r}@r{]}
Compare the data of a loadable section @var{section-name} in the
executable file of the program being debugged with the same section in
-the remote machine's memory, and report any mismatches. With no
-arguments, compares all loadable sections. This command's
-availability depends on the target's support for the @code{"qCRC"}
-remote request.
+the target machine's memory, and report any mismatches. With no
+arguments, compares all loadable sections. With an argument of
+@code{-r}, compares all loadable read-only sections.
+
+Note: for remote targets, this command can be accelerated if the
+target supports computing the CRC checksum of a block of memory
+(@pxref{qCRC packet}).
@end table
@node Auto Display
@xref{General Query Packets}.
This variable contains the address of the thread information block.
-@end table
+@item $_inferior
+The number of the current inferior. @xref{Inferiors and
+Programs, ,Debugging Multiple Inferiors and Programs}.
+
+@item $_thread
+The thread number of the current thread. @xref{thread numbers}.
-On HP-UX systems, if you refer to a function or variable name that
-begins with a dollar sign, @value{GDBN} searches for a user or system
-name first, before it searches for a convenience variable.
+@item $_gthread
+The global number of the current thread. @xref{global thread numbers}.
+
+@end table
@node Convenience Funs
@section Convenience Functions
@findex $_strlen@r{, convenience function}
Returns the length of string @var{str}.
+@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
+@findex $_caller_is@r{, convenience function}
+Returns one if the calling function's name is equal to @var{name}.
+Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+Example:
+
+@smallexample
+(gdb) backtrace
+#0 bottom_func ()
+ at testsuite/gdb.python/py-caller-is.c:21
+#1 0x00000000004005a0 in middle_func ()
+ at testsuite/gdb.python/py-caller-is.c:27
+#2 0x00000000004005ab in top_func ()
+ at testsuite/gdb.python/py-caller-is.c:33
+#3 0x00000000004005b6 in main ()
+ at testsuite/gdb.python/py-caller-is.c:39
+(gdb) print $_caller_is ("middle_func")
+$1 = 1
+(gdb) print $_caller_is ("top_func", 2)
+$1 = 1
+@end smallexample
+
+@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
+@findex $_caller_matches@r{, convenience function}
+Returns one if the calling function's name matches the regular expression
+@var{regexp}. Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
+@findex $_any_caller_is@r{, convenience function}
+Returns one if any calling function's name is equal to @var{name}.
+Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+This function differs from @code{$_caller_is} in that this function
+checks all stack frames from the immediate caller to the frame specified
+by @var{number_of_frames}, whereas @code{$_caller_is} only checks the
+frame specified by @var{number_of_frames}.
+
+@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
+@findex $_any_caller_matches@r{, convenience function}
+Returns one if any calling function's name matches the regular expression
+@var{regexp}. Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+This function differs from @code{$_caller_matches} in that this function
+checks all stack frames from the immediate caller to the frame specified
+by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the
+frame specified by @var{number_of_frames}.
+
+@item $_as_string(@var{value})
+@findex $_as_string@r{, convenience function}
+Return the string representation of @var{value}.
+
+This function is useful to obtain the textual label (enumerator) of an
+enumeration value. For example, assuming the variable @var{node} is of
+an enumerated type:
+
+@smallexample
+(gdb) printf "Visiting node of type %s\n", $_as_string(node)
+Visiting node of type NODE_INTEGER
+@end smallexample
+
@end table
@value{GDBN} provides the ability to list and get help on
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
As discussed in detail below, register values are normally relative to
-the selected stack frame. @var{regname} may be any register name valid on
+the selected stack frame. The @var{regname} may be any register name valid on
the machine you are using, with or without the initial @samp{$}.
@end table
+@anchor{standard registers}
@cindex stack pointer register
@cindex program counter register
@cindex process status register
@anchor{linux info os infotypes}
@table @code
+@kindex info os cpus
+@item cpus
+Display the list of all CPUs/cores. For each CPU/core, @value{GDBN} prints
+the available fields from /proc/cpuinfo. For each supported architecture
+different fields are available. Two common entries are processor which gives
+CPU number and bogomips; a system constant that is calculated during
+kernel initialization.
+
+@kindex info os files
+@item files
+Display the list of open file descriptors on the target. For each
+file descriptor, @value{GDBN} prints the identifier of the process
+owning the descriptor, the command of the owning process, the value
+of the descriptor, and the target of the descriptor.
+
+@kindex info os modules
+@item modules
+Display the list of all loaded kernel modules on the target. For each
+module, @value{GDBN} prints the module name, the size of the module in
+bytes, the number of times the module is used, the dependencies of the
+module, the status of the module, and the address of the loaded module
+in memory.
+
+@kindex info os msg
+@item msg
+Display the list of all System V message queues on the target. For each
+message queue, @value{GDBN} prints the message queue key, the message
+queue identifier, the access permissions, the current number of bytes
+on the queue, the current number of messages on the queue, the processes
+that last sent and received a message on the queue, the user and group
+of the owner and creator of the message queue, the times at which a
+message was last sent and received on the queue, and the time at which
+the message queue was last changed.
+
@kindex info os processes
@item processes
Display the list of processes on the target. For each process,
so that processes belonging to the same process group are grouped together
and the process group leader is listed first.
-@kindex info os threads
-@item threads
-Display the list of threads running on the target. For each thread,
-@value{GDBN} prints the identifier of the process that the thread
-belongs to, the command of the process, the thread identifier, and the
-processor core that it is currently running on. The main thread of a
-process is not listed.
-
-@kindex info os files
-@item files
-Display the list of open file descriptors on the target. For each
-file descriptor, @value{GDBN} prints the identifier of the process
-owning the descriptor, the command of the owning process, the value
-of the descriptor, and the target of the descriptor.
-
-@kindex info os sockets
-@item sockets
-Display the list of Internet-domain sockets on the target. For each
-socket, @value{GDBN} prints the address and port of the local and
-remote endpoints, the current state of the connection, the creator of
-the socket, the IP address family of the socket, and the type of the
-connection.
+@kindex info os semaphores
+@item semaphores
+Display the list of all System V semaphore sets on the target. For each
+semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
+set identifier, the access permissions, the number of semaphores in the
+set, the user and group of the owner and creator of the semaphore set,
+and the times at which the semaphore set was operated upon and changed.
@kindex info os shm
@item shm
attaches to the region, and the times at which the region was last
attached to, detach from, and changed.
-@kindex info os semaphores
-@item semaphores
-Display the list of all System V semaphore sets on the target. For each
-semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
-set identifier, the access permissions, the number of semaphores in the
-set, the user and group of the owner and creator of the semaphore set,
-and the times at which the semaphore set was operated upon and changed.
-
-@kindex info os msg
-@item msg
-Display the list of all System V message queues on the target. For each
-message queue, @value{GDBN} prints the message queue key, the message
-queue identifier, the access permissions, the current number of bytes
-on the queue, the current number of messages on the queue, the processes
-that last sent and received a message on the queue, the user and group
-of the owner and creator of the message queue, the times at which a
-message was last sent and received on the queue, and the time at which
-the message queue was last changed.
+@kindex info os sockets
+@item sockets
+Display the list of Internet-domain sockets on the target. For each
+socket, @value{GDBN} prints the address and port of the local and
+remote endpoints, the current state of the connection, the creator of
+the socket, the IP address family of the socket, and the type of the
+connection.
-@kindex info os modules
-@item modules
-Display the list of all loaded kernel modules on the target. For each
-module, @value{GDBN} prints the module name, the size of the module in
-bytes, the number of times the module is used, the dependencies of the
-module, the status of the module, and the address of the loaded module
-in memory.
+@kindex info os threads
+@item threads
+Display the list of threads running on the target. For each thread,
+@value{GDBN} prints the identifier of the process that the thread
+belongs to, the command of the process, the thread identifier, and the
+processor core that it is currently running on. The main thread of a
+process is not listed.
@end table
@item info os
@code{restore} to copy data between target memory and a file. The
@code{dump} and @code{append} commands write data to a file, and the
@code{restore} command reads data from a file back into the inferior's
-memory. Files may be in binary, Motorola S-record, Intel hex, or
-Tektronix Hex format; however, @value{GDBN} can only append to binary
-files.
+memory. Files may be in binary, Motorola S-record, Intel hex,
+Tektronix Hex, or Verilog Hex format; however, @value{GDBN} can only
+append to binary files, and cannot read from Verilog Hex files.
@table @code
Motorola S-record format.
@item tekhex
Tektronix Hex format.
+@item verilog
+Verilog Hex format.
@end table
@value{GDBN} uses the same definitions of these formats as the
Note that this command is implemented only for some systems (as of
this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390).
+
+On @sc{gnu}/Linux, this command can take into account the value of the
+file @file{/proc/@var{pid}/coredump_filter} when generating the core
+dump (@pxref{set use-coredump-filter}).
+
+@kindex set use-coredump-filter
+@anchor{set use-coredump-filter}
+@item set use-coredump-filter on
+@itemx set use-coredump-filter off
+Enable or disable the use of the file
+@file{/proc/@var{pid}/coredump_filter} when generating core dump
+files. This file is used by the Linux kernel to decide what types of
+memory mappings will be dumped or ignored when generating a core dump
+file. @var{pid} is the process ID of a currently running process.
+
+To make use of this feature, you have to write in the
+@file{/proc/@var{pid}/coredump_filter} file a value, in hexadecimal,
+which is a bit mask representing the memory mapping types. If a bit
+is set in the bit mask, then the memory mappings of the corresponding
+types will be dumped; otherwise, they will be ignored. This
+configuration is inherited by child processes. For more information
+about the bits that can be set in the
+@file{/proc/@var{pid}/coredump_filter} file, please refer to the
+manpage of @code{core(5)}.
+
+By default, this option is @code{on}. If this option is turned
+@code{off}, @value{GDBN} does not read the @file{coredump_filter} file
+and instead uses the same default value as the Linux kernel in order
+to decide which pages will be dumped in the core dump file. This
+value is currently @code{0x33}, which means that bits @code{0}
+(anonymous private mappings), @code{1} (anonymous shared mappings),
+@code{4} (ELF headers) and @code{5} (private huge pages) are active.
+This will cause these memory mappings to be dumped automatically.
@end table
@node Character Sets
$2 = (void *) 0x8049560
@end smallexample
+@node Value Sizes
+@section Value Sizes
+
+Whenever @value{GDBN} prints a value memory will be allocated within
+@value{GDBN} to hold the contents of the value. It is possible in
+some languages with dynamic typing systems, that an invalid program
+may indicate a value that is incorrectly large, this in turn may cause
+@value{GDBN} to try and allocate an overly large ammount of memory.
+
+@table @code
+@kindex set max-value-size
+@item set max-value-size @var{bytes}
+@itemx set max-value-size unlimited
+Set the maximum size of memory that @value{GDBN} will allocate for the
+contents of a value to @var{bytes}, trying to display a value that
+requires more memory than that will result in an error.
+
+Setting this variable does not effect values that have already been
+allocated within @value{GDBN}, only future allocations.
+
+There's a minimum size that @code{max-value-size} can be set to in
+order that @value{GDBN} can still operate correctly, this minimum is
+currently 16 bytes.
+
+The limit applies to the results of some subexpressions as well as to
+complete expressions. For example, an expression denoting a simple
+integer component, such as @code{x.y.z}, may fail if the size of
+@var{x.y} is dynamic and exceeds @var{bytes}. On the other hand,
+@value{GDBN} is sometimes clever; the expression @code{A[i]}, where
+@var{A} is an array variable with non-constant size, will generally
+succeed regardless of the bounds on @var{A}, as long as the component
+size is less than @var{bytes}.
+
+The default value of @code{max-value-size} is currently 64k.
+
+@kindex show max-value-size
+@item show max-value-size
+Show the maximum size of memory, in bytes, that @value{GDBN} will
+allocate for the contents of a value.
+@end table
+
@node Optimized Code
@chapter Debugging Optimized Code
@cindex optimized code, debugging
the macro may begin with a hyphen.
@kindex info macros
-@item info macros @var{linespec}
+@item info macros @var{location}
Show all macro definitions that are in effect at the location specified
-by @var{linespec}, and describe the source location or compiler
+by @var{location}, and describe the source location or compiler
command-line where those definitions were established.
@kindex macro define
@kindex trace
@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be a source line, a function name, or
-an address in the target program. @xref{Specify Location}. The
-@code{trace} command defines a tracepoint, which is a point in the
-target program where the debugger will briefly stop, collect some
-data, and then allow the program to continue. Setting a tracepoint or
-changing its actions takes effect immediately if the remote stub
+Its argument @var{location} can be any valid location.
+@xref{Specify Location}. The @code{trace} command defines a tracepoint,
+which is a point in the target program where the debugger will briefly stop,
+collect some data, and then allow the program to continue. Setting a tracepoint
+or changing its actions takes effect immediately if the remote stub
supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
in tracing}).
If remote stub doesn't support the @samp{InstallInTrace} feature, all
@kindex tvariable
The @code{tvariable} command creates a new trace state variable named
@code{$@var{name}}, and optionally gives it an initial value of
-@var{expression}. @var{expression} is evaluated when this command is
+@var{expression}. The @var{expression} is evaluated when this command is
entered; the result will be converted to an integer if possible,
otherwise @value{GDBN} will report an error. A subsequent
@code{tvariable} command specifying the same name does not create a
Collect the return address. This is helpful if you want to see more
of a backtrace.
+@emph{Note:} The return address location can not always be reliably
+determined up front, and the wrong address / registers may end up
+collected instead. On some architectures the reliability is higher
+for tracepoints at function entry, while on others it's the opposite.
+When this happens, backtracing will stop because the return address is
+found unavailable (unless another collect rule happened to match it).
+
@item $_probe_argc
Collects the number of arguments from the static probe at which the
tracepoint is located.
Same as @samp{tfind none}.
@item tfind
-No argument means find the next trace snapshot.
+No argument means find the next trace snapshot or find the first
+one if no trace snapshot is selected.
@item tfind -
Find the previous trace snapshot before the current one. This permits
a live target, but it is not possible to run any new trace experiments.
@code{tstatus} will report the state of the trace run at the moment
the data was saved, as well as the current trace frame you are examining.
-@var{filename} or @var{dirname} must be on a filesystem accessible to
+Both @var{filename} and @var{dirname} must be on a filesystem accessible to
the host.
@smallexample
@section Supported Languages
@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java,
-OpenCL C, Pascal, assembly, Modula-2, and Ada.
+OpenCL C, Pascal, Rust, assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
language you use: the @value{GDBN} @code{@@} and @code{::} operators,
* OpenCL C:: OpenCL C
* Fortran:: Fortran
* Pascal:: Pascal
+* Rust:: Rust
* Modula-2:: Modula-2
* Ada:: Ada
@end menu
@item @var{op}=
Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
and translated to @w{@code{@var{a} = @var{a op b}}}.
-@w{@code{@var{op}=}} and @code{=} have the same precedence.
+@w{@code{@var{op}=}} and @code{=} have the same precedence. The operator
@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
@item ?:
The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
-of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
-integral type.
+of as: if @var{a} then @var{b} else @var{c}. The argument @var{a}
+should be of an integral type.
@item ||
Logical @sc{or}. Defined on integral types.
one entry per virtual table; there may be multiple virtual tables when
multiple inheritance is in use.
+@cindex C@t{++} demangling
+@item demangle @var{name}
+Demangle @var{name}.
+@xref{Symbols}, for a more complete description of the @code{demangle} command.
+
@cindex C@t{++} symbol display
@item set print demangle
@itemx show print demangle
controls whether static members of Pascal objects are displayed.
@xref{Print Settings, pascal_static-members}.
+@node Rust
+@subsection Rust
+
+@value{GDBN} supports the @url{https://www.rust-lang.org/, Rust
+Programming Language}. Type- and value-printing, and expression
+parsing, are reasonably complete. However, there are a few
+peculiarities and holes to be aware of.
+
+@itemize @bullet
+@item
+Linespecs (@pxref{Specify Location}) are never relative to the current
+crate. Instead, they act as if there were a global namespace of
+crates, somewhat similar to the way @code{extern crate} behaves.
+
+That is, if @value{GDBN} is stopped at a breakpoint in a function in
+crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt
+to set a breakpoint in a function named @samp{f} in a crate named
+@samp{B}.
+
+As a consequence of this approach, linespecs also cannot refer to
+items using @samp{self::} or @samp{super::}.
+
+@item
+Because @value{GDBN} implements Rust name-lookup semantics in
+expressions, it will sometimes prepend the current crate to a name.
+For example, if @value{GDBN} is stopped at a breakpoint in the crate
+@samp{K}, then @code{print ::x::y} will try to find the symbol
+@samp{K::x::y}.
+
+However, since it is useful to be able to refer to other crates when
+debugging, @value{GDBN} provides the @code{extern} extension to
+circumvent this. To use the extension, just put @code{extern} before
+a path expression to refer to the otherwise unavailable ``global''
+scope.
+
+In the above example, if you wanted to refer to the symbol @samp{y} in
+the crate @samp{x}, you would use @code{print extern x::y}.
+
+@item
+The Rust expression evaluator does not support ``statement-like''
+expressions such as @code{if} or @code{match}, or lambda expressions.
+
+@item
+Tuple expressions are not implemented.
+
+@item
+The Rust expression evaluator does not currently implement the
+@code{Drop} trait. Objects that may be created by the evaluator will
+never be destroyed.
+
+@item
+@value{GDBN} does not implement type inference for generics. In order
+to call generic functions or otherwise refer to generic items, you
+will have to specify the type parameters manually.
+
+@item
+@value{GDBN} currently uses the C@t{++} demangler for Rust. In most
+cases this does not cause any problems. However, in an expression
+context, completing a generic function name will give syntactically
+invalid results. This happens because Rust requires the @samp{::}
+operator between the function name and its generic arguments. For
+example, @value{GDBN} might provide a completion like
+@code{crate::f<u32>}, where the parser would require
+@code{crate::f::<u32>}.
+
+@item
+As of this writing, the Rust compiler (version 1.8) has a few holes in
+the debugging information it generates. These holes prevent certain
+features from being implemented by @value{GDBN}:
+@itemize @bullet
+
+@item
+Method calls cannot be made via traits.
+
+@item
+Trait objects cannot be created or inspected.
+
+@item
+Operator overloading is not implemented.
+
+@item
+When debugging in a monomorphized function, you cannot use the generic
+type names.
+
+@item
+The type @code{Self} is not available.
+
+@item
+@code{use} statements are not available, so some names may not be
+available in the crate.
+@end itemize
+@end itemize
+
@node Modula-2
@subsection Modula-2
@item ORD(@var{x})
Returns the ordinal value of its argument. For example, the ordinal
-value of a character is its @sc{ascii} value (on machines supporting the
-@sc{ascii} character set). @var{x} must be of an ordered type, which include
-integral, character and enumerated types.
+value of a character is its @sc{ascii} value (on machines supporting
+the @sc{ascii} character set). The argument @var{x} must be of an
+ordered type, which include integral, character and enumerated types.
@item SIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+Returns the size of its argument. The argument @var{x} can be a
+variable or a type.
@item TRUNC(@var{r})
Returns the integral part of @var{r}.
@item TSIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+Returns the size of its argument. The argument @var{x} can be a
+variable or a type.
@item VAL(@var{t},@var{i})
Returns the member of the type @var{t} whose ordinal value is @var{i}.
in @value{GDBN}.
* Omissions from Ada:: Restrictions on the Ada expression syntax.
* Additions to Ada:: Extensions of the Ada expression syntax.
+* Overloading support for Ada:: Support for expressions involving overloaded
+ subprograms.
* Stopping Before Main Program:: Debugging the program during elaboration.
* Ada Exceptions:: Ada Exceptions
* Ada Tasks:: Listing and setting breakpoints in tasks.
(@samp{#}) still works at the beginning of a line in Ada mode, but not in the
middle (to allow based literals).
-The debugger supports limited overloading. Given a subprogram call in which
-the function symbol has multiple definitions, it will use the number of
-actual parameters and some information about their types to attempt to narrow
-the set of definitions. It also makes very limited use of context, preferring
-procedures to functions in the context of the @code{call} command, and
-functions to procedures elsewhere.
-
@node Omissions from Ada
@subsubsection Omissions from Ada
@cindex Ada, omissions from
@end itemize
+@node Overloading support for Ada
+@subsubsection Overloading support for Ada
+@cindex overloading, Ada
+
+The debugger supports limited overloading. Given a subprogram call in which
+the function symbol has multiple definitions, it will use the number of
+actual parameters and some information about their types to attempt to narrow
+the set of definitions. It also makes very limited use of context, preferring
+procedures to functions in the context of the @code{call} command, and
+functions to procedures elsewhere.
+
+If, after narrowing, the set of matching definitions still contains more than
+one definition, @value{GDBN} will display a menu to query which one it should
+use, for instance:
+
+@smallexample
+(@value{GDBP}) print f(1)
+Multiple matches for f
+[0] cancel
+[1] foo.f (integer) return boolean at foo.adb:23
+[2] foo.f (foo.new_integer) return boolean at foo.adb:28
+>
+@end smallexample
+
+In this case, just select one menu entry either to cancel expression evaluation
+(type @kbd{0} and press @key{RET}) or to continue evaluation with a specific
+instance (type the corresponding number and press @key{RET}).
+
+Here are a couple of commands to customize @value{GDBN}'s behavior in this
+case:
+
+@table @code
+
+@kindex set ada print-signatures
+@item set ada print-signatures
+Control whether parameter types and return types are displayed in overloads
+selection menus. It is @code{on} by default.
+@xref{Overloading support for Ada}.
+
+@kindex show ada print-signatures
+@item show ada print-signatures
+Show the current setting for displaying parameter types and return types in
+overloads selection menu.
+@xref{Overloading support for Ada}.
+
+@end table
+
@node Stopping Before Main Program
@subsubsection Stopping at the Very Beginning
@item task @var{taskno}
@cindex Ada task switching
-This command is like the @code{thread @var{threadno}}
+This command is like the @code{thread @var{thread-id}}
command (@pxref{Threads}). It switches the context of debugging
from the current task to the given task.
#4 0x804aacc in un () at un.adb:5
@end smallexample
-@item break @var{linespec} task @var{taskno}
-@itemx break @var{linespec} task @var{taskno} if @dots{}
+@item break @var{location} task @var{taskno}
+@itemx break @var{location} task @var{taskno} if @dots{}
@cindex breakpoints and tasks, in Ada
@cindex task breakpoints, in Ada
@kindex break @dots{} task @var{taskno}@r{ (Ada)}
These commands are like the @code{break @dots{} thread @dots{}}
-command (@pxref{Thread Stops}).
-@var{linespec} specifies source lines, as described
+command (@pxref{Thread Stops}). The
+@var{location} argument specifies source lines, as described
in @ref{Specify Location}.
Use the qualifier @samp{task @var{taskno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular Ada task reaches this breakpoint. @var{taskno} is one of the
+particular Ada task reaches this breakpoint. The @var{taskno} is one of the
numeric task identifiers assigned by @value{GDBN}, shown in the first
column of the @samp{info tasks} display.
tasking support may be limited or even unavailable, depending on
the platform being used.
For instance, on x86-linux, the list of tasks is available, but task
-switching is not supported. On Tru64, however, task switching will work
-as usual.
+switching is not supported.
-On certain platforms, including Tru64, the debugger needs to perform some
+On certain platforms, the debugger needs to perform some
memory writes in order to provide Ada tasking support. When inspecting
a core file, this means that the core file must be opened with read-write
privileges, using the command @samp{"set write on"} (@pxref{Patching}).
@end table
+@cindex GNAT descriptive types
+@cindex GNAT encoding
+Internally, the debugger also relies on the compiler following a number
+of conventions known as the @samp{GNAT Encoding}, all documented in
+@file{gcc/ada/exp_dbug.ads} in the GCC sources. This encoding describes
+how the debugging information should be generated for certain types.
+In particular, this convention makes use of @dfn{descriptive types},
+which are artificial types generated purely to help the debugger.
+
+These encodings were defined at a time when the debugging information
+format used was not powerful enough to describe some of the more complex
+types available in Ada. Since DWARF allows us to express nearly all
+Ada features, the long-term goal is to slowly replace these descriptive
+types by their pure DWARF equivalent. To facilitate that transition,
+a new maintenance option is available to force the debugger to ignore
+those descriptive types. It allows the user to quickly evaluate how
+well @value{GDBN} works without them.
+
+@table @code
+
+@kindex maint ada set ignore-descriptive-types
+@item maintenance ada set ignore-descriptive-types [on|off]
+Control whether the debugger should ignore descriptive types.
+The default is not to ignore descriptives types (@code{off}).
+
+@kindex maint ada show ignore-descriptive-types
+@item maintenance ada show ignore-descriptive-types
+Show if descriptive types are ignored by @value{GDBN}.
+
+@end table
+
@node Unsupported Languages
@section Unsupported Languages
__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
@end smallexample
+@kindex demangle
+@cindex demangle
+@item demangle @r{[}-l @var{language}@r{]} @r{[}@var{--}@r{]} @var{name}
+Demangle @var{name}.
+If @var{language} is provided it is the name of the language to demangle
+@var{name} in. Otherwise @var{name} is demangled in the current language.
+
+The @samp{--} option specifies the end of options,
+and is useful when @var{name} begins with a dash.
+
+The parameter @code{demangle-style} specifies how to interpret the kind
+of mangling used. @xref{Print Settings}.
+
@kindex whatis
@item whatis[/@var{flags}] [@var{arg}]
Print the data type of @var{arg}, which can be either an expression
@item
which programming language it is written in,
@item
+if the debug information provides it, the program that compiled the file
+(which may include, e.g., the compiler version and command line arguments),
+@item
whether the executable includes debugging information for that file, and
if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
@item
@item show opaque-type-resolution
Show whether opaque types are resolved or not.
+@kindex set print symbol-loading
+@cindex print messages when symbols are loaded
+@item set print symbol-loading
+@itemx set print symbol-loading full
+@itemx set print symbol-loading brief
+@itemx set print symbol-loading off
+The @code{set print symbol-loading} command allows you to control the
+printing of messages when @value{GDBN} loads symbol information.
+By default a message is printed for the executable and one for each
+shared library, and normally this is what you want. However, when
+debugging apps with large numbers of shared libraries these messages
+can be annoying.
+When set to @code{brief} a message is printed for each executable,
+and when @value{GDBN} loads a collection of shared libraries at once
+it will only print one message regardless of the number of shared
+libraries. When set to @code{off} no messages are printed.
+
+@kindex show print symbol-loading
+@item show print symbol-loading
+Show whether messages will be printed when a @value{GDBN} command
+entered from the keyboard causes symbol information to be loaded.
+
@kindex maint print symbols
@cindex symbol dump
@kindex maint print psymbols
@}
(@value{GDBP})
@end smallexample
-@end table
+@kindex maint info line-table
+@cindex listing @value{GDBN}'s internal line tables
+@cindex line tables, listing @value{GDBN}'s internal
+@item maint info line-table @r{[} @var{regexp} @r{]}
+
+List the @code{struct linetable} from all @code{struct symtab}
+instances whose name matches @var{regexp}. If @var{regexp} is not
+given, list the @code{struct linetable} from all @code{struct symtab}.
+
+@kindex maint set symbol-cache-size
+@cindex symbol cache size
+@item maint set symbol-cache-size @var{size}
+Set the size of the symbol cache to @var{size}.
+The default size is intended to be good enough for debugging
+most applications. This option exists to allow for experimenting
+with different sizes.
+
+@kindex maint show symbol-cache-size
+@item maint show symbol-cache-size
+Show the size of the symbol cache.
+
+@kindex maint print symbol-cache
+@cindex symbol cache, printing its contents
+@item maint print symbol-cache
+Print the contents of the symbol cache.
+This is useful when debugging symbol cache issues.
+
+@kindex maint print symbol-cache-statistics
+@cindex symbol cache, printing usage statistics
+@item maint print symbol-cache-statistics
+Print symbol cache usage statistics.
+This helps determine how well the cache is being utilized.
+
+@kindex maint flush-symbol-cache
+@cindex symbol cache, flushing
+@item maint flush-symbol-cache
+Flush the contents of the symbol cache, all entries are removed.
+This command is useful when debugging the symbol cache.
+It is also useful when collecting performance data.
+
+@end table
@node Altering
@chapter Altering Execution
* Returning:: Returning from a function
* Calling:: Calling your program's functions
* Patching:: Patching your program
+* Compiling and Injecting Code:: Compiling and injecting code in @value{GDBN}
@end menu
@node Assignment
@table @code
@kindex jump
@kindex j @r{(@code{jump})}
-@item jump @var{linespec}
-@itemx j @var{linespec}
-@itemx jump @var{location}
+@item jump @var{location}
@itemx j @var{location}
-Resume execution at line @var{linespec} or at address given by
-@var{location}. Execution stops again immediately if there is a
-breakpoint there. @xref{Specify Location}, for a description of the
-different forms of @var{linespec} and @var{location}. It is common
+Resume execution at @var{location}. Execution stops again immediately
+if there is a breakpoint there. @xref{Specify Location}, for a description
+of the different forms of @var{location}. It is common
practice to use the @code{tbreak} command in conjunction with
@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
The @code{jump} command does not change the current stack frame, or
the stack pointer, or the contents of any memory location or any
-register other than the program counter. If line @var{linespec} is in
+register other than the program counter. If @var{location} is in
a different function from the one currently executing, the results may
be bizarre if the two functions expect different patterns of arguments or
of local variables. For this reason, the @code{jump} command requests
well acquainted with the machine-language code of your program.
@end table
-@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
On many systems, you can get much the same effect as the @code{jump}
command by storing a new value into the register @code{$pc}. The
difference is that this does not start your program running; it only
@table @code
@kindex signal
@item signal @var{signal}
-Resume execution where your program stopped, but immediately give it the
-signal @var{signal}. @var{signal} can be the name or the number of a
+Resume execution where your program is stopped, but immediately give it the
+signal @var{signal}. The @var{signal} can be the name or the number of a
signal. For example, on many systems @code{signal 2} and @code{signal
SIGINT} are both ways of sending an interrupt signal.
@code{continue} command; @samp{signal 0} causes it to resume without a
signal.
-@code{signal} does not repeat when you press @key{RET} a second time
-after executing the command.
-@end table
-@c @end group
+@emph{Note:} When resuming a multi-threaded program, @var{signal} is
+delivered to the currently selected thread, not the thread that last
+reported a stop. This includes the situation where a thread was
+stopped due to a signal. So if you want to continue execution
+suppressing the signal that stopped a thread, you should select that
+same thread before issuing the @samp{signal 0} command. If you issue
+the @samp{signal 0} command with another thread as the selected one,
+@value{GDBN} detects that and asks for confirmation.
Invoking the @code{signal} command is not the same as invoking the
@code{kill} utility from the shell. Sending a signal with @code{kill}
the signal handling tables (@pxref{Signals}). The @code{signal} command
passes the signal directly to your program.
+@code{signal} does not repeat when you press @key{RET} a second time
+after executing the command.
+
+@kindex queue-signal
+@item queue-signal @var{signal}
+Queue @var{signal} to be delivered immediately to the current thread
+when execution of the thread resumes. The @var{signal} can be the name or
+the number of a signal. For example, on many systems @code{signal 2} and
+@code{signal SIGINT} are both ways of sending an interrupt signal.
+The handling of the signal must be set to pass the signal to the program,
+otherwise @value{GDBN} will report an error.
+You can control the handling of signals from @value{GDBN} with the
+@code{handle} command (@pxref{Signals}).
+
+Alternatively, if @var{signal} is zero, any currently queued signal
+for the current thread is discarded and when execution resumes no signal
+will be delivered. This is useful when your program stopped on account
+of a signal and would ordinarily see the signal when resumed with the
+@code{continue} command.
+
+This command differs from the @code{signal} command in that the signal
+is just queued, execution is not resumed. And @code{queue-signal} cannot
+be used to pass a signal whose handling state has been set to @code{nopass}
+(@pxref{Signals}).
+@end table
+@c @end group
+
+@xref{stepping into signal handlers}, for information on how stepping
+commands behave when the thread has a signal queued.
@node Returning
@section Returning from a Function
@cindex inferior functions, calling
@item print @var{expr}
Evaluate the expression @var{expr} and display the resulting value.
-@var{expr} may include calls to functions in the program being
+The expression may include calls to functions in the program being
debugged.
@kindex call
as well as reading.
@end table
+@node Compiling and Injecting Code
+@section Compiling and injecting code in @value{GDBN}
+@cindex injecting code
+@cindex writing into executables
+@cindex compiling code
+
+@value{GDBN} supports on-demand compilation and code injection into
+programs running under @value{GDBN}. GCC 5.0 or higher built with
+@file{libcc1.so} must be installed for this functionality to be enabled.
+This functionality is implemented with the following commands.
+
+@table @code
+@kindex compile code
+@item compile code @var{source-code}
+@itemx compile code -raw @var{--} @var{source-code}
+Compile @var{source-code} with the compiler language found as the current
+language in @value{GDBN} (@pxref{Languages}). If compilation and
+injection is not supported with the current language specified in
+@value{GDBN}, or the compiler does not support this feature, an error
+message will be printed. If @var{source-code} compiles and links
+successfully, @value{GDBN} will load the object-code emitted,
+and execute it within the context of the currently selected inferior.
+It is important to note that the compiled code is executed immediately.
+After execution, the compiled code is removed from @value{GDBN} and any
+new types or variables you have defined will be deleted.
+
+The command allows you to specify @var{source-code} in two ways.
+The simplest method is to provide a single line of code to the command.
+E.g.:
+
+@smallexample
+compile code printf ("hello world\n");
+@end smallexample
+
+If you specify options on the command line as well as source code, they
+may conflict. The @samp{--} delimiter can be used to separate options
+from actual source code. E.g.:
+
+@smallexample
+compile code -r -- printf ("hello world\n");
+@end smallexample
+
+Alternatively you can enter source code as multiple lines of text. To
+enter this mode, invoke the @samp{compile code} command without any text
+following the command. This will start the multiple-line editor and
+allow you to type as many lines of source code as required. When you
+have completed typing, enter @samp{end} on its own line to exit the
+editor.
+
+@smallexample
+compile code
+>printf ("hello\n");
+>printf ("world\n");
+>end
+@end smallexample
+
+Specifying @samp{-raw}, prohibits @value{GDBN} from wrapping the
+provided @var{source-code} in a callable scope. In this case, you must
+specify the entry point of the code by defining a function named
+@code{_gdb_expr_}. The @samp{-raw} code cannot access variables of the
+inferior. Using @samp{-raw} option may be needed for example when
+@var{source-code} requires @samp{#include} lines which may conflict with
+inferior symbols otherwise.
+
+@kindex compile file
+@item compile file @var{filename}
+@itemx compile file -raw @var{filename}
+Like @code{compile code}, but take the source code from @var{filename}.
+
+@smallexample
+compile file /home/user/example.c
+@end smallexample
+@end table
+
+@table @code
+@item compile print @var{expr}
+@itemx compile print /@var{f} @var{expr}
+Compile and execute @var{expr} with the compiler language found as the
+current language in @value{GDBN} (@pxref{Languages}). By default the
+value of @var{expr} is printed in a format appropriate to its data type;
+you can choose a different format by specifying @samp{/@var{f}}, where
+@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
+Formats}.
+
+@item compile print
+@itemx compile print /@var{f}
+@cindex reprint the last value
+Alternatively you can enter the expression (source code producing it) as
+multiple lines of text. To enter this mode, invoke the @samp{compile print}
+command without any text following the command. This will start the
+multiple-line editor.
+@end table
+
+@noindent
+The process of compiling and injecting the code can be inspected using:
+
+@table @code
+@anchor{set debug compile}
+@item set debug compile
+@cindex compile command debugging info
+Turns on or off display of @value{GDBN} process of compiling and
+injecting the code. The default is off.
+
+@item show debug compile
+Displays the current state of displaying @value{GDBN} process of
+compiling and injecting the code.
+@end table
+
+@subsection Compilation options for the @code{compile} command
+
+@value{GDBN} needs to specify the right compilation options for the code
+to be injected, in part to make its ABI compatible with the inferior
+and in part to make the injected code compatible with @value{GDBN}'s
+injecting process.
+
+@noindent
+The options used, in increasing precedence:
+
+@table @asis
+@item target architecture and OS options (@code{gdbarch})
+These options depend on target processor type and target operating
+system, usually they specify at least 32-bit (@code{-m32}) or 64-bit
+(@code{-m64}) compilation option.
+
+@item compilation options recorded in the target
+@value{NGCC} (since version 4.7) stores the options used for compilation
+into @code{DW_AT_producer} part of DWARF debugging information according
+to the @value{NGCC} option @code{-grecord-gcc-switches}. One has to
+explicitly specify @code{-g} during inferior compilation otherwise
+@value{NGCC} produces no DWARF. This feature is only relevant for
+platforms where @code{-g} produces DWARF by default, otherwise one may
+try to enforce DWARF by using @code{-gdwarf-4}.
+
+@item compilation options set by @code{set compile-args}
+@end table
+
+@noindent
+You can override compilation options using the following command:
+
+@table @code
+@item set compile-args
+@cindex compile command options override
+Set compilation options used for compiling and injecting code with the
+@code{compile} commands. These options override any conflicting ones
+from the target architecture and/or options stored during inferior
+compilation.
+
+@item show compile-args
+Displays the current state of compilation options override.
+This does not show all the options actually used during compilation,
+use @ref{set debug compile} for that.
+@end table
+
+@subsection Caveats when using the @code{compile} command
+
+There are a few caveats to keep in mind when using the @code{compile}
+command. As the caveats are different per language, the table below
+highlights specific issues on a per language basis.
+
+@table @asis
+@item C code examples and caveats
+When the language in @value{GDBN} is set to @samp{C}, the compiler will
+attempt to compile the source code with a @samp{C} compiler. The source
+code provided to the @code{compile} command will have much the same
+access to variables and types as it normally would if it were part of
+the program currently being debugged in @value{GDBN}.
+
+Below is a sample program that forms the basis of the examples that
+follow. This program has been compiled and loaded into @value{GDBN},
+much like any other normal debugging session.
+
+@smallexample
+void function1 (void)
+@{
+ int i = 42;
+ printf ("function 1\n");
+@}
+
+void function2 (void)
+@{
+ int j = 12;
+ function1 ();
+@}
+
+int main(void)
+@{
+ int k = 6;
+ int *p;
+ function2 ();
+ return 0;
+@}
+@end smallexample
+
+For the purposes of the examples in this section, the program above has
+been compiled, loaded into @value{GDBN}, stopped at the function
+@code{main}, and @value{GDBN} is awaiting input from the user.
+
+To access variables and types for any program in @value{GDBN}, the
+program must be compiled and packaged with debug information. The
+@code{compile} command is not an exception to this rule. Without debug
+information, you can still use the @code{compile} command, but you will
+be very limited in what variables and types you can access.
+
+So with that in mind, the example above has been compiled with debug
+information enabled. The @code{compile} command will have access to
+all variables and types (except those that may have been optimized
+out). Currently, as @value{GDBN} has stopped the program in the
+@code{main} function, the @code{compile} command would have access to
+the variable @code{k}. You could invoke the @code{compile} command
+and type some source code to set the value of @code{k}. You can also
+read it, or do anything with that variable you would normally do in
+@code{C}. Be aware that changes to inferior variables in the
+@code{compile} command are persistent. In the following example:
+
+@smallexample
+compile code k = 3;
+@end smallexample
+
+@noindent
+the variable @code{k} is now 3. It will retain that value until
+something else in the example program changes it, or another
+@code{compile} command changes it.
+
+Normal scope and access rules apply to source code compiled and
+injected by the @code{compile} command. In the example, the variables
+@code{j} and @code{k} are not accessible yet, because the program is
+currently stopped in the @code{main} function, where these variables
+are not in scope. Therefore, the following command
+
+@smallexample
+compile code j = 3;
+@end smallexample
+
+@noindent
+will result in a compilation error message.
+
+Once the program is continued, execution will bring these variables in
+scope, and they will become accessible; then the code you specify via
+the @code{compile} command will be able to access them.
+
+You can create variables and types with the @code{compile} command as
+part of your source code. Variables and types that are created as part
+of the @code{compile} command are not visible to the rest of the program for
+the duration of its run. This example is valid:
+
+@smallexample
+compile code int ff = 5; printf ("ff is %d\n", ff);
+@end smallexample
+
+However, if you were to type the following into @value{GDBN} after that
+command has completed:
+
+@smallexample
+compile code printf ("ff is %d\n'', ff);
+@end smallexample
+
+@noindent
+a compiler error would be raised as the variable @code{ff} no longer
+exists. Object code generated and injected by the @code{compile}
+command is removed when its execution ends. Caution is advised
+when assigning to program variables values of variables created by the
+code submitted to the @code{compile} command. This example is valid:
+
+@smallexample
+compile code int ff = 5; k = ff;
+@end smallexample
+
+The value of the variable @code{ff} is assigned to @code{k}. The variable
+@code{k} does not require the existence of @code{ff} to maintain the value
+it has been assigned. However, pointers require particular care in
+assignment. If the source code compiled with the @code{compile} command
+changed the address of a pointer in the example program, perhaps to a
+variable created in the @code{compile} command, that pointer would point
+to an invalid location when the command exits. The following example
+would likely cause issues with your debugged program:
+
+@smallexample
+compile code int ff = 5; p = &ff;
+@end smallexample
+
+In this example, @code{p} would point to @code{ff} when the
+@code{compile} command is executing the source code provided to it.
+However, as variables in the (example) program persist with their
+assigned values, the variable @code{p} would point to an invalid
+location when the command exists. A general rule should be followed
+in that you should either assign @code{NULL} to any assigned pointers,
+or restore a valid location to the pointer before the command exits.
+
+Similar caution must be exercised with any structs, unions, and typedefs
+defined in @code{compile} command. Types defined in the @code{compile}
+command will no longer be available in the next @code{compile} command.
+Therefore, if you cast a variable to a type defined in the
+@code{compile} command, care must be taken to ensure that any future
+need to resolve the type can be achieved.
+
+@smallexample
+(gdb) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v;
+(gdb) compile code printf ("%d\n", ((struct a *) argv)->a);
+gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’
+Compilation failed.
+(gdb) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a);
+42
+@end smallexample
+
+Variables that have been optimized away by the compiler are not
+accessible to the code submitted to the @code{compile} command.
+Access to those variables will generate a compiler error which @value{GDBN}
+will print to the console.
+@end table
+
+@subsection Compiler search for the @code{compile} command
+
+@value{GDBN} needs to find @value{NGCC} for the inferior being debugged which
+may not be obvious for remote targets of different architecture than where
+@value{GDBN} is running. Environment variable @code{PATH} (@code{PATH} from
+shell that executed @value{GDBN}, not the one set by @value{GDBN}
+command @code{set environment}). @xref{Environment}. @code{PATH} on
+@value{GDBN} host is searched for @value{NGCC} binary matching the
+target architecture and operating system.
+
+Specifically @code{PATH} is searched for binaries matching regular expression
+@code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being
+debugged. @var{arch} is processor name --- multiarch is supported, so for
+example both @code{i386} and @code{x86_64} targets look for pattern
+@code{(x86_64|i.86)} and both @code{s390} and @code{s390x} targets look
+for pattern @code{s390x?}. @var{os} is currently supported only for
+pattern @code{linux(-gnu)?}.
+
@node GDB Files
@chapter @value{GDBN} Files
@menu
* Files:: Commands to specify files
+* File Caching:: Information about @value{GDBN}'s file caching
* Separate Debug Files:: Debugging information in separate files
* MiniDebugInfo:: Debugging information in a special section
* Index Files:: Index files speed up GDB
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
-into the program that is running. @var{address} should be the memory
+into the program that is running. The @var{address} should give the memory
address at which the file has been loaded; @value{GDBN} cannot figure
this out for itself. You can additionally specify an arbitrary number
of @samp{-s @var{section} @var{address}} pairs, to give an explicit
For this command to work, you must have used @code{symbol-file} or
@code{exec-file} commands in advance.
-@kindex add-shared-symbol-files
-@kindex assf
-@item add-shared-symbol-files @var{library-file}
-@itemx assf @var{library-file}
-The @code{add-shared-symbol-files} command can currently be used only
-in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
-alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
-@value{GDBN} automatically looks for shared libraries, however if
-@value{GDBN} does not find yours, you can invoke
-@code{add-shared-symbol-files}. It takes one argument: the shared
-library's file name. @code{assf} is a shorthand alias for
-@code{add-shared-symbol-files}.
-
@kindex section
@item section @var{section} @var{addr}
The @code{section} command changes the base address of the named
@cindex shared libraries
@anchor{Shared Libraries}
-@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
-and IBM RS/6000 AIX shared libraries.
+@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, SunOS,
+Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and
+DSBT (TIC6X) shared libraries.
On MS-Windows @value{GDBN} must be linked with the Expat library to support
shared libraries. @xref{Expat}.
references to a function in a shared library, however---unless you are
debugging a core file).
-On HP-UX, if the program loads a library explicitly, @value{GDBN}
-automatically loads the symbols at the time of the @code{shl_load} call.
-
@c FIXME: some @value{GDBN} release may permit some refs to undef
@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
@c FIXME...lib; check this from time to time when updating manual
that match @var{regex}. If @var{regex} is omitted then print
all shared libraries that are loaded.
+@kindex info dll
+@item info dll @var{regex}
+This is an alias of @code{info sharedlibrary}.
+
@kindex sharedlibrary
@kindex share
@item sharedlibrary @var{regex}
to specify the search directories for target libraries.
@table @code
-@cindex prefix for shared library file names
+@cindex prefix for executable and shared library file names
@cindex system root, alternate
@kindex set solib-absolute-prefix
@kindex set sysroot
Use @var{path} as the system root for the program being debugged. Any
absolute shared library paths will be prefixed with @var{path}; many
runtime loaders store the absolute paths to the shared library in the
-target program's memory. If you use @code{set sysroot} to find shared
-libraries, they need to be laid out in the same way that they are on
-the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy
-under @var{path}.
-
-If @var{path} starts with the sequence @file{remote:}, @value{GDBN} will
-retrieve the target libraries from the remote system. This is only
-supported when using a remote target that supports the @code{remote get}
-command (@pxref{File Transfer,,Sending files to a remote system}).
-The part of @var{path} following the initial @file{remote:}
-(if present) is used as system root prefix on the remote file system.
-@footnote{If you want to specify a local system root using a directory
-that happens to be named @file{remote:}, you need to use some equivalent
-variant of the name like @file{./remote:}.}
+target program's memory. When starting processes remotely, and when
+attaching to already-running processes (local or remote), their
+executable filenames will be prefixed with @var{path} if reported to
+@value{GDBN} as absolute by the operating system. If you use
+@code{set sysroot} to find executables and shared libraries, they need
+to be laid out in the same way that they are on the target, with
+e.g.@: a @file{/bin}, @file{/lib} and @file{/usr/lib} hierarchy under
+@var{path}.
+
+If @var{path} starts with the sequence @file{target:} and the target
+system is remote then @value{GDBN} will retrieve the target binaries
+from the remote system. This is only supported when using a remote
+target that supports the @code{remote get} command (@pxref{File
+Transfer,,Sending files to a remote system}). The part of @var{path}
+following the initial @file{target:} (if present) is used as system
+root prefix on the remote file system. If @var{path} starts with the
+sequence @file{remote:} this is converted to the sequence
+@file{target:} by @code{set sysroot}@footnote{Historically the
+functionality to retrieve binaries from the remote system was
+provided by prefixing @var{path} with @file{remote:}}. If you want
+to specify a local system root using a directory that happens to be
+named @file{target:} or @file{remote:}, you need to use some
+equivalent variant of the name like @file{./target:}.
For targets with an MS-DOS based filesystem, such as MS-Windows and
SymbianOS, @value{GDBN} tries prefixing a few variants of the target
c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll
@end smallexample
-If that does not find the shared library, @value{GDBN} tries removing
+If that does not find the binary, @value{GDBN} tries removing
the @samp{:} character from the drive spec, both for convenience, and,
for the case of the host file system not supporting file names with
colons:
@value{GDBN} can find the correct copies of both
@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}.
-If that still does not find the shared library, @value{GDBN} tries
+If that still does not find the binary, @value{GDBN} tries
removing the whole drive spec from the target file name:
@smallexample
@kindex show sysroot
@item show sysroot
-Display the current shared library prefix.
+Display the current executable and shared library prefix.
@kindex set solib-search-path
@item set solib-search-path @var{path}
Show whether a source file may have multiple base names.
@end table
+@node File Caching
+@section File Caching
+@cindex caching of opened files
+@cindex caching of bfd objects
+
+To speed up file loading, and reduce memory usage, @value{GDBN} will
+reuse the @code{bfd} objects used to track open files. @xref{Top, ,
+BFD, bfd, The Binary File Descriptor Library}. The following commands
+allow visibility and control of the caching behavior.
+
+@table @code
+@kindex maint info bfds
+@item maint info bfds
+This prints information about each @code{bfd} object that is known to
+@value{GDBN}.
+
+@kindex maint set bfd-sharing
+@kindex maint show bfd-sharing
+@kindex bfd caching
+@item maint set bfd-sharing
+@item maint show bfd-sharing
+Control whether @code{bfd} objects can be shared. When sharing is
+enabled @value{GDBN} reuses already open @code{bfd} objects rather
+than reopening the same file. Turning sharing off does not cause
+already shared @code{bfd} objects to be unshared, but all future files
+that are opened will create a new @code{bfd} object. Similarly,
+re-enabling sharing does not cause multiple existing @code{bfd}
+objects to be collapsed into a single shared @code{bfd} object.
+
+@kindex set debug bfd-cache @var{level}
+@kindex bfd caching
+@item set debug bfd-cache @var{level}
+Turns on debugging of the bfd cache, setting the level to @var{level}.
+
+@kindex show debug bfd-cache
+@kindex bfd caching
+@item show debug bfd-cache
+Show the current debugging level of the bfd cache.
+@end table
+
@node Separate Debug Files
@section Debugging Information in Separate Files
@cindex separate debugging information files
@item
The executable contains a @dfn{build ID}, a unique bit string that is
also present in the corresponding debug info file. (This is supported
-only on some operating systems, notably those which use the ELF format
+only on some operating systems, when using the ELF or PE file formats
for binary files and the @sc{gnu} Binutils.) For more details about
this feature, see the description of the @option{--build-id}
command-line option in @ref{Options, , Command Line Options, ld.info,
CRC.
@emph{Note:} This is the same CRC polynomial as used in handling the
-@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{Remote Protocol,
-, @value{GDBN} Remote Serial Protocol}). However in the
-case of the Remote Serial Protocol, the CRC is computed @emph{most}
-significant bit first, and the result is not inverted, so trailing
-zeros have no effect on the CRC value.
+@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{qCRC packet}).
+However in the case of the Remote Serial Protocol, the CRC is computed
+@emph{most} significant bit first, and the result is not inverted, so
+trailing zeros have no effect on the CRC value.
To complete the description, we show below the code of the function
which produces the CRC used in @code{.gnu_debuglink}. Inverting the
see the appropriate section in @ref{Embedded Processors, ,Embedded
Processors}.
+@item target native
+@cindex native target
+Setup for local/native process debugging. Useful to make the
+@code{run} command spawn native processes (likewise @code{attach},
+etc.@:) even when @code{set auto-connect-native-target} is @code{off}
+(@pxref{set auto-connect-native-target}).
+
@end table
Different targets are available on different configurations of @value{GDBN};
@node Connecting
@section Connecting to a Remote Target
+@cindex remote debugging, connecting
+@cindex @code{gdbserver}, connecting
+@cindex remote debugging, types of connections
+@cindex @code{gdbserver}, types of connections
+@cindex @code{gdbserver}, @code{target remote} mode
+@cindex @code{gdbserver}, @code{target extended-remote} mode
+
+This section describes how to connect to a remote target, including the
+types of connections and their differences, how to set up executable and
+symbol files on the host and target, and the commands used for
+connecting to and disconnecting from the remote target.
+
+@subsection Types of Remote Connections
+
+@value{GDBN} supports two types of remote connections, @code{target remote}
+mode and @code{target extended-remote} mode. Note that many remote targets
+support only @code{target remote} mode. There are several major
+differences between the two types of connections, enumerated here:
+
+@table @asis
-On the @value{GDBN} host machine, you will need an unstripped copy of
-your program, since @value{GDBN} needs symbol and debugging information.
-Start up @value{GDBN} as usual, using the name of the local copy of your
-program as the first argument.
+@cindex remote debugging, detach and program exit
+@item Result of detach or program exit
+@strong{With target remote mode:} When the debugged program exits or you
+detach from it, @value{GDBN} disconnects from the target. When using
+@code{gdbserver}, @code{gdbserver} will exit.
+
+@strong{With target extended-remote mode:} When the debugged program exits or
+you detach from it, @value{GDBN} remains connected to the target, even
+though no program is running. You can rerun the program, attach to a
+running program, or use @code{monitor} commands specific to the target.
+
+When using @code{gdbserver} in this case, it does not exit unless it was
+invoked using the @option{--once} option. If the @option{--once} option
+was not used, you can ask @code{gdbserver} to exit using the
+@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}).
+
+@item Specifying the program to debug
+For both connection types you use the @code{file} command to specify the
+program on the host system. If you are using @code{gdbserver} there are
+some differences in how to specify the location of the program on the
+target.
+
+@strong{With target remote mode:} You must either specify the program to debug
+on the @code{gdbserver} command line or use the @option{--attach} option
+(@pxref{Attaching to a program,,Attaching to a Running Program}).
+
+@cindex @option{--multi}, @code{gdbserver} option
+@strong{With target extended-remote mode:} You may specify the program to debug
+on the @code{gdbserver} command line, or you can load the program or attach
+to it using @value{GDBN} commands after connecting to @code{gdbserver}.
+
+@anchor{--multi Option in Types of Remote Connnections}
+You can start @code{gdbserver} without supplying an initial command to run
+or process ID to attach. To do this, use the @option{--multi} command line
+option. Then you can connect using @code{target extended-remote} and start
+the program you want to debug (see below for details on using the
+@code{run} command in this scenario). Note that the conditions under which
+@code{gdbserver} terminates depend on how @value{GDBN} connects to it
+(@code{target remote} or @code{target extended-remote}). The
+@option{--multi} option to @code{gdbserver} has no influence on that.
+
+@item The @code{run} command
+@strong{With target remote mode:} The @code{run} command is not
+supported. Once a connection has been established, you can use all
+the usual @value{GDBN} commands to examine and change data. The
+remote program is already running, so you can use commands like
+@kbd{step} and @kbd{continue}.
+
+@strong{With target extended-remote mode:} The @code{run} command is
+supported. The @code{run} command uses the value set by
+@code{set remote exec-file} (@pxref{set remote exec-file}) to select
+the program to run. Command line arguments are supported, except for
+wildcard expansion and I/O redirection (@pxref{Arguments}).
+
+If you specify the program to debug on the command line, then the
+@code{run} command is not required to start execution, and you can
+resume using commands like @kbd{step} and @kbd{continue} as with
+@code{target remote} mode.
+
+@anchor{Attaching in Types of Remote Connections}
+@item Attaching
+@strong{With target remote mode:} The @value{GDBN} command @code{attach} is
+not supported. To attach to a running program using @code{gdbserver}, you
+must use the @option{--attach} option (@pxref{Running gdbserver}).
+
+@strong{With target extended-remote mode:} To attach to a running program,
+you may use the @code{attach} command after the connection has been
+established. If you are using @code{gdbserver}, you may also invoke
+@code{gdbserver} using the @option{--attach} option
+(@pxref{Running gdbserver}).
+
+@end table
+
+@anchor{Host and target files}
+@subsection Host and Target Files
+@cindex remote debugging, symbol files
+@cindex symbol files, remote debugging
+
+@value{GDBN}, running on the host, needs access to symbol and debugging
+information for your program running on the target. This requires
+access to an unstripped copy of your program, and possibly any associated
+symbol files. Note that this section applies equally to both @code{target
+remote} mode and @code{target extended-remote} mode.
+
+Some remote targets (@pxref{qXfer executable filename read}, and
+@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over
+the same connection used to communicate with @value{GDBN}. With such a
+target, if the remote program is unstripped, the only command you need is
+@code{target remote} (or @code{target extended-remote}).
+
+If the remote program is stripped, or the target does not support remote
+program file access, start up @value{GDBN} using the name of the local
+unstripped copy of your program as the first argument, or use the
+@code{file} command. Use @code{set sysroot} to specify the location (on
+the host) of target libraries (unless your @value{GDBN} was compiled with
+the correct sysroot using @code{--with-sysroot}). Alternatively, you
+may use @code{set solib-search-path} to specify how @value{GDBN} locates
+target libraries.
+
+The symbol file and target libraries must exactly match the executable
+and libraries on the target, with one exception: the files on the host
+system should not be stripped, even if the files on the target system
+are. Mismatched or missing files will lead to confusing results
+during debugging. On @sc{gnu}/Linux targets, mismatched or missing
+files may also prevent @code{gdbserver} from debugging multi-threaded
+programs.
-@cindex @code{target remote}
+@subsection Remote Connection Commands
+@cindex remote connection commands
@value{GDBN} can communicate with the target over a serial line, or
over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
each case, @value{GDBN} uses the same protocol for debugging your
program; only the medium carrying the debugging packets varies. The
-@code{target remote} command establishes a connection to the target.
-Its arguments indicate which medium to use:
+@code{target remote} and @code{target extended-remote} commands
+establish a connection to the target. Both commands accept the same
+arguments, which indicate the medium to use:
@table @code
@item target remote @var{serial-device}
+@itemx target extended-remote @var{serial-device}
@cindex serial line, @code{target remote}
Use @var{serial-device} to communicate with the target. For example,
to use a serial line connected to the device named @file{/dev/ttyb}:
@item target remote @code{@var{host}:@var{port}}
@itemx target remote @code{tcp:@var{host}:@var{port}}
+@itemx target extended-remote @code{@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
@cindex @acronym{TCP} port, @code{target remote}
Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
The @var{host} may be either a host name or a numeric @acronym{IP}
Note that the colon is still required here.
@item target remote @code{udp:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp:@var{host}:@var{port}}
@cindex @acronym{UDP} port, @code{target remote}
Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
cause havoc with your debugging session.
@item target remote | @var{command}
+@itemx target extended-remote | @var{command}
@cindex pipe, @code{target remote} to
Run @var{command} in the background and communicate with it using a
pipe. The @var{command} is a shell command, to be parsed and expanded
@end table
-Once the connection has been established, you can use all the usual
-commands to examine and change data. The remote program is already
-running; you can use @kbd{step} and @kbd{continue}, and you do not
-need to use @kbd{run}.
-
@cindex interrupting remote programs
@cindex remote programs, interrupting
Whenever @value{GDBN} is waiting for the remote program, if you type the
Give up (and stop debugging it)? (y or n)
@end smallexample
-If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
-(If you decide you want to try again later, you can use @samp{target
-remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
-goes back to waiting.
+In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons
+the remote debugging session. (If you decide you want to try again later,
+you can use @kbd{target remote} again to connect once more.) If you type
+@kbd{n}, @value{GDBN} goes back to waiting.
+
+In @code{target extended-remote} mode, typing @kbd{n} will leave
+@value{GDBN} connected to the target.
@table @code
@kindex detach (remote)
@code{detach} command to release it from @value{GDBN} control.
Detaching from the target normally resumes its execution, but the results
will depend on your particular remote stub. After the @code{detach}
-command, @value{GDBN} is free to connect to another target.
+command in @code{target remote} mode, @value{GDBN} is free to connect to
+another target. In @code{target extended-remote} mode, @value{GDBN} is
+still connected to the target.
@kindex disconnect
@item disconnect
-The @code{disconnect} command behaves like @code{detach}, except that
+The @code{disconnect} command closes the connection to the target, and
the target is generally not resumed. It will wait for @value{GDBN}
(this instance or another one) to connect and continue debugging. After
the @code{disconnect} command, @value{GDBN} is again free to connect to
@cindex remote connection without stubs
@code{gdbserver} is a control program for Unix-like systems, which
allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}---but without linking in the usual debugging stub.
+@code{target remote} or @code{target extended-remote}---but without
+linking in the usual debugging stub.
@code{gdbserver} is not a complete replacement for the debugging stubs,
because it requires essentially the same operating-system facilities
@code{gdbserver}.
@end quotation
+@anchor{Running gdbserver}
@subsection Running @code{gdbserver}
@cindex arguments, to @code{gdbserver}
@cindex @code{gdbserver}, command-line arguments
display through a pipe connected to gdbserver.
Both @code{stdout} and @code{stderr} use the same pipe.
+@anchor{Attaching to a program}
@subsubsection Attaching to a Running Program
@cindex attach to a program, @code{gdbserver}
@cindex @option{--attach}, @code{gdbserver} option
target> gdbserver --attach @var{comm} @var{pid}
@end smallexample
-@var{pid} is the process ID of a currently running process. It isn't necessary
-to point @code{gdbserver} at a binary for the running process.
+@var{pid} is the process ID of a currently running process. It isn't
+necessary to point @code{gdbserver} at a binary for the running process.
+
+In @code{target extended-remote} mode, you can also attach using the
+@value{GDBN} attach command
+(@pxref{Attaching in Types of Remote Connections}).
@pindex pidof
You can debug processes by name instead of process ID if your target has the
has multiple threads, most versions of @code{pidof} support the
@code{-s} option to only return the first process ID.
-@subsubsection Multi-Process Mode for @code{gdbserver}
-@cindex @code{gdbserver}, multiple processes
-@cindex multiple processes with @code{gdbserver}
-
-When you connect to @code{gdbserver} using @code{target remote},
-@code{gdbserver} debugs the specified program only once. When the
-program exits, or you detach from it, @value{GDBN} closes the connection
-and @code{gdbserver} exits.
-
-If you connect using @kbd{target extended-remote}, @code{gdbserver}
-enters multi-process mode. When the debugged program exits, or you
-detach from it, @value{GDBN} stays connected to @code{gdbserver} even
-though no program is running. The @code{run} and @code{attach}
-commands instruct @code{gdbserver} to run or attach to a new program.
-The @code{run} command uses @code{set remote exec-file} (@pxref{set
-remote exec-file}) to select the program to run. Command line
-arguments are supported, except for wildcard expansion and I/O
-redirection (@pxref{Arguments}).
-
-@cindex @option{--multi}, @code{gdbserver} option
-To start @code{gdbserver} without supplying an initial command to run
-or process ID to attach, use the @option{--multi} command line option.
-Then you can connect using @kbd{target extended-remote} and start
-the program you want to debug.
-
-In multi-process mode @code{gdbserver} does not automatically exit unless you
-use the option @option{--once}. You can terminate it by using
-@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the
-conditions under which @code{gdbserver} terminates depend on how @value{GDBN}
-connects to it (@kbd{target remote} or @kbd{target extended-remote}). The
-@option{--multi} option to @code{gdbserver} has no influence on that.
-
@subsubsection TCP port allocation lifecycle of @code{gdbserver}
-This section applies only when @code{gdbserver} is run to listen on a TCP port.
+This section applies only when @code{gdbserver} is run to listen on a TCP
+port.
@code{gdbserver} normally terminates after all of its debugged processes have
terminated in @kbd{target remote} mode. On the other hand, for @kbd{target
multiple instances of @code{gdbserver} running on the same host, since each
instance closes its port after the first connection.
+@anchor{Other Command-Line Arguments for gdbserver}
@subsubsection Other Command-Line Arguments for @code{gdbserver}
+You can use the @option{--multi} option to start @code{gdbserver} without
+specifying a program to debug or a process to attach to. Then you can
+attach in @code{target extended-remote} mode and run or attach to a
+program. For more information,
+@pxref{--multi Option in Types of Remote Connnections}.
+
@cindex @option{--debug}, @code{gdbserver} option
The @option{--debug} option tells @code{gdbserver} to display extra
status information about the debugging process.
remote protocol debug output. These options are intended for
@code{gdbserver} development and for bug reports to the developers.
+@cindex @option{--debug-format}, @code{gdbserver} option
+The @option{--debug-format=option1[,option2,...]} option tells
+@code{gdbserver} to include additional information in each output.
+Possible options are:
+
+@table @code
+@item none
+Turn off all extra information in debugging output.
+@item all
+Turn on all extra information in debugging output.
+@item timestamps
+Include a timestamp in each line of debugging output.
+@end table
+
+Options are processed in order. Thus, for example, if @option{none}
+appears last then no additional information is added to debugging output.
+
@cindex @option{--wrapper}, @code{gdbserver} option
The @option{--wrapper} option specifies a wrapper to launch programs
for debugging. The option should be followed by the name of the
@subsection Connecting to @code{gdbserver}
-Run @value{GDBN} on the host system.
+The basic procedure for connecting to the remote target is:
+@itemize
-First make sure you have the necessary symbol files. Load symbols for
-your application using the @code{file} command before you connect. Use
-@code{set sysroot} to locate target libraries (unless your @value{GDBN}
-was compiled with the correct sysroot using @code{--with-sysroot}).
+@item
+Run @value{GDBN} on the host system.
-The symbol file and target libraries must exactly match the executable
-and libraries on the target, with one exception: the files on the host
-system should not be stripped, even if the files on the target system
-are. Mismatched or missing files will lead to confusing results
-during debugging. On @sc{gnu}/Linux targets, mismatched or missing
-files may also prevent @code{gdbserver} from debugging multi-threaded
-programs.
+@item
+Make sure you have the necessary symbol files
+(@pxref{Host and target files}).
+Load symbols for your application using the @code{file} command before you
+connect. Use @code{set sysroot} to locate target libraries (unless your
+@value{GDBN} was compiled with the correct sysroot using
+@code{--with-sysroot}).
+@item
Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}).
For TCP connections, you must start up @code{gdbserver} prior to using
-the @code{target remote} command. Otherwise you may get an error whose
+the @code{target} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
@samp{Connection refused}. Don't use the @code{load}
-command in @value{GDBN} when using @code{gdbserver}, since the program is
-already on the target.
+command in @value{GDBN} when using @code{target remote} mode, since the
+program is already on the target.
+@end itemize
+
+@anchor{Monitor Commands for gdbserver}
@subsection Monitor Commands for @code{gdbserver}
@cindex monitor commands, for @code{gdbserver}
-@anchor{Monitor Commands for gdbserver}
During a @value{GDBN} session using @code{gdbserver}, you can use the
@code{monitor} command to send special requests to @code{gdbserver}.
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor set debug-format option1@r{[},option2,...@r{]}
+Specify additional text to add to debugging messages.
+Possible options are:
+
+@table @code
+@item none
+Turn off all extra information in debugging output.
+@item all
+Turn on all extra information in debugging output.
+@item timestamps
+Include a timestamp in each line of debugging output.
+@end table
+
+Options are processed in order. Thus, for example, if @option{none}
+appears last then no additional information is added to debugging output.
+
@item monitor set libthread-db-search-path [PATH]
@cindex gdbserver, search path for @code{libthread_db}
When this command is issued, @var{path} is a colon-separated list of
@item show serial baud
Show the current speed of the remote connection.
+@item set serial parity @var{parity}
+Set the parity for the remote serial I/O. Supported values of @var{parity} are:
+@code{even}, @code{none}, and @code{odd}. The default is @code{none}.
+
+@item show serial parity
+Show the current parity of the serial port.
+
@item set remotebreak
@cindex interrupt remote programs
@cindex BREAK signal instead of Ctrl-C
@tab @code{Z4}
@tab @code{awatch}
+@item @code{pid-to-exec-file}
+@tab @code{qXfer:exec-file:read}
+@tab @code{attach}, @code{run}
+
@item @code{target-features}
@tab @code{qXfer:features:read}
@tab @code{set architecture}
@tab @code{qSupported}
@tab Remote communications parameters
+@item @code{catch-syscalls}
+@tab @code{QCatchSyscalls}
+@tab @code{catch syscall}
+
@item @code{pass-signals}
@tab @code{QPassSignals}
@tab @code{handle @var{signal}}
@tab @code{vFile:readlink}
@tab Host I/O
+@item @code{hostio-fstat-packet}
+@tab @code{vFile:fstat}
+@tab Host I/O
+
+@item @code{hostio-setfs-packet}
+@tab @code{vFile:setfs}
+@tab Host I/O
+
@item @code{noack-packet}
@tab @code{QStartNoAckMode}
@tab Packet acknowledgment
@item @code{conditional-breakpoints-packet}
@tab @code{Z0 and Z1}
@tab @code{Support for target-side breakpoint condition evaluation}
+
+@item @code{multiprocess-extensions}
+@tab @code{multiprocess extensions}
+@tab Debug multiple processes and remote process PID awareness
+
+@item @code{swbreak-feature}
+@tab @code{swbreak stop reason}
+@tab @code{break}
+
+@item @code{hwbreak-feature}
+@tab @code{hwbreak stop reason}
+@tab @code{hbreak}
+
+@item @code{fork-event-feature}
+@tab @code{fork stop reason}
+@tab @code{fork}
+
+@item @code{vfork-event-feature}
+@tab @code{vfork stop reason}
+@tab @code{vfork}
+
+@item @code{exec-event-feature}
+@tab @code{exec stop reason}
+@tab @code{exec}
+
+@item @code{thread-events}
+@tab @code{QThreadEvents}
+@tab Tracking thread lifetime.
+
+@item @code{no-resumed-stop-reply}
+@tab @code{no resumed thread left stop reply}
+@tab Tracking thread lifetime.
+
@end multitable
@node Remote Stub
way of knowing what the exception handling tables on your target system
are like (for example, the processor's table might be in @sc{rom},
containing entries which point to a table in @sc{ram}).
-@var{exception_number} is the exception number which should be changed;
+The @var{exception_number} specifies the exception which should be changed;
its meaning is architecture-dependent (for example, different numbers
might represent divide by zero, misaligned access, etc). When this
exception occurs, control should be transferred directly to
configurations.
@menu
-* HP-UX:: HP-UX
* BSD libkvm Interface:: Debugging BSD kernel memory images
* SVR4 Process Information:: SVR4 process information
* DJGPP Native:: Features specific to the DJGPP port
* Darwin:: Features specific to Darwin
@end menu
-@node HP-UX
-@subsection HP-UX
-
-On HP-UX systems, if you refer to a function or variable name that
-begins with a dollar sign, @value{GDBN} searches for a user or system
-name first, before it searches for a convenience variable.
-
-
@node BSD libkvm Interface
@subsection BSD libkvm Interface
facility, the command @code{info proc} is available to report
information about the process running your program, or about any
process running on your system. This includes, as of this writing,
-@sc{gnu}/Linux, OSF/1 (Digital Unix), Solaris, and Irix, but
-not HP-UX, for example.
+@sc{gnu}/Linux and Solaris, for example.
This command may also work on core files that were created on a system
that has the @samp{/proc} facility.
Thread Information Block (readable on the X86 CPU family using @code{$fs}
selector for 32-bit programs and @code{$gs} for 64-bit programs).
-@kindex info dll
-@item info dll
-This is a Cygwin-specific alias of @code{info shared}.
-
-@kindex dll-symbols
-@item dll-symbols
-This command loads symbols from a dll similarly to
-add-sym command but without the need to specify a base address.
-
@kindex set cygwin-exceptions
@cindex debugging the Cygwin DLL
@cindex Cygwin DLL, debugging
Note that before the debugged program has started execution, no DLLs
will have been loaded. The easiest way around this problem is simply to
start the program --- either by setting a breakpoint or letting the
-program run once to completion. It is also possible to force
-@value{GDBN} to load a particular DLL before starting the executable ---
-see the shared library information in @ref{Files}, or the
-@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
-explicitly loading symbols from a DLL with no debugging information will
-cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
-which may adversely affect symbol lookup performance.
+program run once to completion.
@subsubsection DLL Name Prefixes
embedded operating systems that are available for several different
architectures.
-@menu
-* VxWorks:: Using @value{GDBN} with VxWorks
-@end menu
-
@value{GDBN} includes the ability to debug programs running on
various real-time operating systems.
-@node VxWorks
-@subsection Using @value{GDBN} with VxWorks
-
-@cindex VxWorks
-
-@table @code
-
-@kindex target vxworks
-@item target vxworks @var{machinename}
-A VxWorks system, attached via TCP/IP. The argument @var{machinename}
-is the target system's machine name or IP address.
-
-@end table
-
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
-
-@value{GDBN} enables developers to spawn and debug tasks running on networked
-VxWorks targets from a Unix host. Already-running tasks spawned from
-the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
-both the Unix host and on the VxWorks target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
-installed with the name @code{vxgdb}, to distinguish it from a
-@value{GDBN} for debugging programs on the host itself.)
-
-@table @code
-@item VxWorks-timeout @var{args}
-@kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses to rpc's. You might use this if
-your VxWorks target is a slow software simulator or is on the far side
-of a thin network line.
-@end table
-
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
-
-@findex INCLUDE_RDB
-To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
-to include the remote debugging interface routines in the VxWorks
-library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
-VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
-kernel. The resulting kernel contains @file{rdb.a}, and spawns the
-source debugging task @code{tRdbTask} when VxWorks is booted. For more
-information on configuring and remaking VxWorks, see the manufacturer's
-manual.
-@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
-
-Once you have included @file{rdb.a} in your VxWorks system image and set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
-@code{vxgdb}, depending on your installation).
-
-@value{GDBN} comes up showing the prompt:
-
-@smallexample
-(vxgdb)
-@end smallexample
-
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
-
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
-
-The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
-network. To connect to a target whose host name is ``@code{tt}'', type:
-
-@smallexample
-(vxgdb) target vxworks tt
-@end smallexample
-
-@need 750
-@value{GDBN} displays messages like these:
-
-@smallexample
-Attaching remote machine across net...
-Connected to tt.
-@end smallexample
-
-@need 1000
-@value{GDBN} then attempts to read the symbol tables of any object modules
-loaded into the VxWorks target since it was last booted. @value{GDBN} locates
-these files by searching the directories listed in the command search
-path (@pxref{Environment, ,Your Program's Environment}); if it fails
-to find an object file, it displays a message such as:
-
-@smallexample
-prog.o: No such file or directory.
-@end smallexample
-
-When this happens, add the appropriate directory to the search path with
-the @value{GDBN} command @code{path}, and execute the @code{target}
-command again.
-
-@node VxWorks Download
-@subsubsection VxWorks Download
-
-@cindex download to VxWorks
-If you have connected to the VxWorks target and you want to debug an
-object that has not yet been loaded, you can use the @value{GDBN}
-@code{load} command to download a file from Unix to VxWorks
-incrementally. The object file given as an argument to the @code{load}
-command is actually opened twice: first by the VxWorks target in order
-to download the code, then by @value{GDBN} in order to read the symbol
-table. This can lead to problems if the current working directories on
-the two systems differ. If both systems have NFS mounted the same
-filesystems, you can avoid these problems by using absolute paths.
-Otherwise, it is simplest to set the working directory on both systems
-to the directory in which the object file resides, and then to reference
-the file by its name, without any path. For instance, a program
-@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
-and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
-program, type this on VxWorks:
-
-@smallexample
--> cd "@var{vxpath}/vw/demo/rdb"
-@end smallexample
-
-@noindent
-Then, in @value{GDBN}, type:
-
-@smallexample
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
-@end smallexample
-
-@value{GDBN} displays a response similar to this:
-
-@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
-@end smallexample
-
-You can also use the @code{load} command to reload an object module
-after editing and recompiling the corresponding source file. Note that
-this makes @value{GDBN} delete all currently-defined breakpoints,
-auto-displays, and convenience variables, and to clear the value
-history. (This is necessary in order to preserve the integrity of
-debugger's data structures that reference the target system's symbol
-table.)
-
-@node VxWorks Attach
-@subsubsection Running Tasks
-
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
-
-@smallexample
-(vxgdb) attach @var{task}
-@end smallexample
-
-@noindent
-where @var{task} is the VxWorks hexadecimal task ID. The task can be running
-or suspended when you attach to it. Running tasks are suspended at
-the time of attachment.
-
@node Embedded Processors
@section Embedded Processors
@menu
-* ARM:: ARM RDI
-* M32R/D:: Renesas M32R/D
+* ARM:: ARM
* M68K:: Motorola M68K
* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
* PowerPC Embedded:: PowerPC Embedded
-* PA:: HP PA Embedded
-* Sparclet:: Tsqware Sparclet
-* Sparclite:: Fujitsu Sparclite
-* Z8000:: Zilog Z8000
* AVR:: Atmel AVR
* CRIS:: CRIS
* Super-H:: Renesas Super-H
@node ARM
@subsection ARM
-@cindex ARM RDI
-
-@table @code
-@kindex target rdi
-@item target rdi @var{dev}
-ARM Angel monitor, via RDI library interface to ADP protocol. You may
-use this target to communicate with both boards running the Angel
-monitor, or with the EmbeddedICE JTAG debug device.
-
-@kindex target rdp
-@item target rdp @var{dev}
-ARM Demon monitor.
-
-@end table
@value{GDBN} provides the following ARM-specific commands:
Show whether ARM-specific debugging messages are enabled.
@end table
-The following commands are available when an ARM target is debugged
-using the RDI interface:
-
-@table @code
-@item rdilogfile @r{[}@var{file}@r{]}
-@kindex rdilogfile
-@cindex ADP (Angel Debugger Protocol) logging
-Set the filename for the ADP (Angel Debugger Protocol) packet log.
-With an argument, sets the log file to the specified @var{file}. With
-no argument, show the current log file name. The default log file is
-@file{rdi.log}.
-
-@item rdilogenable @r{[}@var{arg}@r{]}
-@kindex rdilogenable
-Control logging of ADP packets. With an argument of 1 or @code{"yes"}
-enables logging, with an argument 0 or @code{"no"} disables it. With
-no arguments displays the current setting. When logging is enabled,
-ADP packets exchanged between @value{GDBN} and the RDI target device
-are logged to a file.
-
-@item set rdiromatzero
-@kindex set rdiromatzero
-@cindex ROM at zero address, RDI
-Tell @value{GDBN} whether the target has ROM at address 0. If on,
-vector catching is disabled, so that zero address can be used. If off
-(the default), vector catching is enabled. For this command to take
-effect, it needs to be invoked prior to the @code{target rdi} command.
-
-@item show rdiromatzero
-@kindex show rdiromatzero
-Show the current setting of ROM at zero address.
-
-@item set rdiheartbeat
-@kindex set rdiheartbeat
-@cindex RDI heartbeat
-Enable or disable RDI heartbeat packets. It is not recommended to
-turn on this option, since it confuses ARM and EPI JTAG interface, as
-well as the Angel monitor.
-
-@item show rdiheartbeat
-@kindex show rdiheartbeat
-Show the setting of RDI heartbeat packets.
-@end table
-
@table @code
@item target sim @r{[}@var{simargs}@r{]} @dots{}
The @value{GDBN} ARM simulator accepts the following optional arguments.
@table @code
@item --swi-support=@var{type}
-Tell the simulator which SWI interfaces to support.
+Tell the simulator which SWI interfaces to support. The argument
@var{type} may be a comma separated list of the following values.
The default value is @code{all}.
@end table
@end table
-@node M32R/D
-@subsection Renesas M32R/D and M32R/SDI
-
-@table @code
-@kindex target m32r
-@item target m32r @var{dev}
-Renesas M32R/D ROM monitor.
-
-@kindex target m32rsdi
-@item target m32rsdi @var{dev}
-Renesas M32R SDI server, connected via parallel port to the board.
-@end table
-
-The following @value{GDBN} commands are specific to the M32R monitor:
-
-@table @code
-@item set download-path @var{path}
-@kindex set download-path
-@cindex find downloadable @sc{srec} files (M32R)
-Set the default path for finding downloadable @sc{srec} files.
-
-@item show download-path
-@kindex show download-path
-Show the default path for downloadable @sc{srec} files.
-
-@item set board-address @var{addr}
-@kindex set board-address
-@cindex M32-EVA target board address
-Set the IP address for the M32R-EVA target board.
-
-@item show board-address
-@kindex show board-address
-Show the current IP address of the target board.
-
-@item set server-address @var{addr}
-@kindex set server-address
-@cindex download server address (M32R)
-Set the IP address for the download server, which is the @value{GDBN}'s
-host machine.
-
-@item show server-address
-@kindex show server-address
-Display the IP address of the download server.
-
-@item upload @r{[}@var{file}@r{]}
-@kindex upload@r{, M32R}
-Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
-upload capability. If no @var{file} argument is given, the current
-executable file is uploaded.
-
-@item tload @r{[}@var{file}@r{]}
-@kindex tload@r{, M32R}
-Test the @code{upload} command.
-@end table
-
-The following commands are available for M32R/SDI:
-
-@table @code
-@item sdireset
-@kindex sdireset
-@cindex reset SDI connection, M32R
-This command resets the SDI connection.
-
-@item sdistatus
-@kindex sdistatus
-This command shows the SDI connection status.
-
-@item debug_chaos
-@kindex debug_chaos
-@cindex M32R/Chaos debugging
-Instructs the remote that M32R/Chaos debugging is to be used.
-
-@item use_debug_dma
-@kindex use_debug_dma
-Instructs the remote to use the DEBUG_DMA method of accessing memory.
-
-@item use_mon_code
-@kindex use_mon_code
-Instructs the remote to use the MON_CODE method of accessing memory.
-
-@item use_ib_break
-@kindex use_ib_break
-Instructs the remote to set breakpoints by IB break.
-
-@item use_dbt_break
-@kindex use_dbt_break
-Instructs the remote to set breakpoints by DBT.
-@end table
-
@node M68K
@subsection M68k
-The Motorola m68k configuration includes ColdFire support, and a
-target command for the following ROM monitor.
-
-@table @code
-
-@kindex target dbug
-@item target dbug @var{dev}
-dBUG ROM monitor for Motorola ColdFire.
-
-@end table
+The Motorola m68k configuration includes ColdFire support.
@node MicroBlaze
@subsection MicroBlaze
@node MIPS Embedded
@subsection @acronym{MIPS} Embedded
-@cindex @acronym{MIPS} boards
-@value{GDBN} can use the @acronym{MIPS} remote debugging protocol to talk to a
-@acronym{MIPS} board attached to a serial line. This is available when
-you configure @value{GDBN} with @samp{--target=mips-elf}.
-
-@need 1000
-Use these @value{GDBN} commands to specify the connection to your target board:
-
-@table @code
-@item target mips @var{port}
-@kindex target mips @var{port}
-To run a program on the board, start up @code{@value{GDBP}} with the
-name of your program as the argument. To connect to the board, use the
-command @samp{target mips @var{port}}, where @var{port} is the name of
-the serial port connected to the board. If the program has not already
-been downloaded to the board, you may use the @code{load} command to
-download it. You can then use all the usual @value{GDBN} commands.
-
-For example, this sequence connects to the target board through a serial
-port, and loads and runs a program called @var{prog} through the
-debugger:
-
-@smallexample
-host$ @value{GDBP} @var{prog}
-@value{GDBN} is free software and @dots{}
-(@value{GDBP}) target mips /dev/ttyb
-(@value{GDBP}) load @var{prog}
-(@value{GDBP}) run
-@end smallexample
-
-@item target mips @var{hostname}:@var{portnumber}
-On some @value{GDBN} host configurations, you can specify a TCP
-connection (for instance, to a serial line managed by a terminal
-concentrator) instead of a serial port, using the syntax
-@samp{@var{hostname}:@var{portnumber}}.
-
-@item target pmon @var{port}
-@kindex target pmon @var{port}
-PMON ROM monitor.
-
-@item target ddb @var{port}
-@kindex target ddb @var{port}
-NEC's DDB variant of PMON for Vr4300.
-
-@item target lsi @var{port}
-@kindex target lsi @var{port}
-LSI variant of PMON.
-
-@kindex target r3900
-@item target r3900 @var{dev}
-Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-
-@kindex target array
-@item target array @var{dev}
-Array Tech LSI33K RAID controller board.
-
-@end table
-
-
@noindent
-@value{GDBN} also supports these special commands for @acronym{MIPS} targets:
+@value{GDBN} supports these special commands for @acronym{MIPS} targets:
@table @code
@item set mipsfpu double
As usual, you can inquire about the @code{mipsfpu} variable with
@samp{show mipsfpu}.
-
-@item set timeout @var{seconds}
-@itemx set retransmit-timeout @var{seconds}
-@itemx show timeout
-@itemx show retransmit-timeout
-@cindex @code{timeout}, @acronym{MIPS} protocol
-@cindex @code{retransmit-timeout}, @acronym{MIPS} protocol
-@kindex set timeout
-@kindex show timeout
-@kindex set retransmit-timeout
-@kindex show retransmit-timeout
-You can control the timeout used while waiting for a packet, in the @acronym{MIPS}
-remote protocol, with the @code{set timeout @var{seconds}} command. The
-default is 5 seconds. Similarly, you can control the timeout used while
-waiting for an acknowledgment of a packet with the @code{set
-retransmit-timeout @var{seconds}} command. The default is 3 seconds.
-You can inspect both values with @code{show timeout} and @code{show
-retransmit-timeout}. (These commands are @emph{only} available when
-@value{GDBN} is configured for @samp{--target=mips-elf}.)
-
-The timeout set by @code{set timeout} does not apply when @value{GDBN}
-is waiting for your program to stop. In that case, @value{GDBN} waits
-forever because it has no way of knowing how long the program is going
-to run before stopping.
-
-@item set syn-garbage-limit @var{num}
-@kindex set syn-garbage-limit@r{, @acronym{MIPS} remote}
-@cindex synchronize with remote @acronym{MIPS} target
-Limit the maximum number of characters @value{GDBN} should ignore when
-it tries to synchronize with the remote target. The default is 10
-characters. Setting the limit to -1 means there's no limit.
-
-@item show syn-garbage-limit
-@kindex show syn-garbage-limit@r{, @acronym{MIPS} remote}
-Show the current limit on the number of characters to ignore when
-trying to synchronize with the remote system.
-
-@item set monitor-prompt @var{prompt}
-@kindex set monitor-prompt@r{, @acronym{MIPS} remote}
-@cindex remote monitor prompt
-Tell @value{GDBN} to expect the specified @var{prompt} string from the
-remote monitor. The default depends on the target:
-@table @asis
-@item pmon target
-@samp{PMON}
-@item ddb target
-@samp{NEC010}
-@item lsi target
-@samp{PMON>}
-@end table
-
-@item show monitor-prompt
-@kindex show monitor-prompt@r{, @acronym{MIPS} remote}
-Show the current strings @value{GDBN} expects as the prompt from the
-remote monitor.
-
-@item set monitor-warnings
-@kindex set monitor-warnings@r{, @acronym{MIPS} remote}
-Enable or disable monitor warnings about hardware breakpoints. This
-has effect only for the @code{lsi} target. When on, @value{GDBN} will
-display warning messages whose codes are returned by the @code{lsi}
-PMON monitor for breakpoint commands.
-
-@item show monitor-warnings
-@kindex show monitor-warnings@r{, @acronym{MIPS} remote}
-Show the current setting of printing monitor warnings.
-
-@item pmon @var{command}
-@kindex pmon@r{, @acronym{MIPS} remote}
-@cindex send PMON command
-This command allows sending an arbitrary @var{command} string to the
-monitor. The monitor must be in debug mode for this to work.
@end table
@node PowerPC Embedded
@table @code
@kindex break-range
@item break-range @var{start-location}, @var{end-location}
-Set a breakpoint for an address range.
-@var{start-location} and @var{end-location} can specify a function name,
+Set a breakpoint for an address range given by
+@var{start-location} and @var{end-location}, which can specify a function name,
a line number, an offset of lines from the current line or from the start
location, or an address of an instruction (see @ref{Specify Location},
for a list of all the possible ways to specify a @var{location}.)
of scalar type, thus assuming that the variable is accessed through the
address of its first byte.
-@kindex target dink32
-@item target dink32 @var{dev}
-DINK32 ROM monitor.
-
-@kindex target ppcbug
-@item target ppcbug @var{dev}
-@kindex target ppcbug1
-@item target ppcbug1 @var{dev}
-PPCBUG ROM monitor for PowerPC.
-
-@kindex target sds
-@item target sds @var{dev}
-SDS monitor, running on a PowerPC board (such as Motorola's ADS).
@end table
-@cindex SDS protocol
-The following commands specific to the SDS protocol are supported
-by @value{GDBN}:
-
-@table @code
-@item set sdstimeout @var{nsec}
-@kindex set sdstimeout
-Set the timeout for SDS protocol reads to be @var{nsec} seconds. The
-default is 2 seconds.
-
-@item show sdstimeout
-@kindex show sdstimeout
-Show the current value of the SDS timeout.
-
-@item sds @var{command}
-@kindex sds@r{, a command}
-Send the specified @var{command} string to the SDS monitor.
-@end table
-
-
-@node PA
-@subsection HP PA Embedded
-
-@table @code
-
-@kindex target op50n
-@item target op50n @var{dev}
-OP50N monitor, running on an OKI HPPA board.
-
-@kindex target w89k
-@item target w89k @var{dev}
-W89K monitor, running on a Winbond HPPA board.
-
-@end table
-
-@node Sparclet
-@subsection Tsqware Sparclet
-
-@cindex Sparclet
-
-@value{GDBN} enables developers to debug tasks running on
-Sparclet targets from a Unix host.
-@value{GDBN} uses code that runs on
-both the Unix host and on the Sparclet target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host.
-
-@table @code
-@item remotetimeout @var{args}
-@kindex remotetimeout
-@value{GDBN} supports the option @code{remotetimeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses.
-@end table
-
-@cindex compiling, on Sparclet
-When compiling for debugging, include the options @samp{-g} to get debug
-information and @samp{-Ttext} to relocate the program to where you wish to
-load it on the target. You may also want to add the options @samp{-n} or
-@samp{-N} in order to reduce the size of the sections. Example:
-
-@smallexample
-sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
-@end smallexample
-
-You can use @code{objdump} to verify that the addresses are what you intended:
-
-@smallexample
-sparclet-aout-objdump --headers --syms prog
-@end smallexample
-
-@cindex running, on Sparclet
-Once you have set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
-(or @code{sparclet-aout-gdb}, depending on your installation).
-
-@value{GDBN} comes up showing the prompt:
-
-@smallexample
-(gdbslet)
-@end smallexample
-
-@menu
-* Sparclet File:: Setting the file to debug
-* Sparclet Connection:: Connecting to Sparclet
-* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
-@end menu
-
-@node Sparclet File
-@subsubsection Setting File to Debug
-
-The @value{GDBN} command @code{file} lets you choose with program to debug.
-
-@smallexample
-(gdbslet) file prog
-@end smallexample
-
-@need 1000
-@value{GDBN} then attempts to read the symbol table of @file{prog}.
-@value{GDBN} locates
-the file by searching the directories listed in the command search
-path.
-If the file was compiled with debug information (option @samp{-g}), source
-files will be searched as well.
-@value{GDBN} locates
-the source files by searching the directories listed in the directory search
-path (@pxref{Environment, ,Your Program's Environment}).
-If it fails
-to find a file, it displays a message such as:
-
-@smallexample
-prog: No such file or directory.
-@end smallexample
-
-When this happens, add the appropriate directories to the search paths with
-the @value{GDBN} commands @code{path} and @code{dir}, and execute the
-@code{target} command again.
-
-@node Sparclet Connection
-@subsubsection Connecting to Sparclet
-
-The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
-To connect to a target on serial port ``@code{ttya}'', type:
-
-@smallexample
-(gdbslet) target sparclet /dev/ttya
-Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
-@end smallexample
-
-@need 750
-@value{GDBN} displays messages like these:
-
-@smallexample
-Connected to ttya.
-@end smallexample
-
-@node Sparclet Download
-@subsubsection Sparclet Download
-
-@cindex download to Sparclet
-Once connected to the Sparclet target,
-you can use the @value{GDBN}
-@code{load} command to download the file from the host to the target.
-The file name and load offset should be given as arguments to the @code{load}
-command.
-Since the file format is aout, the program must be loaded to the starting
-address. You can use @code{objdump} to find out what this value is. The load
-offset is an offset which is added to the VMA (virtual memory address)
-of each of the file's sections.
-For instance, if the program
-@file{prog} was linked to text address 0x1201000, with data at 0x12010160
-and bss at 0x12010170, in @value{GDBN}, type:
-
-@smallexample
-(gdbslet) load prog 0x12010000
-Loading section .text, size 0xdb0 vma 0x12010000
-@end smallexample
-
-If the code is loaded at a different address then what the program was linked
-to, you may need to use the @code{section} and @code{add-symbol-file} commands
-to tell @value{GDBN} where to map the symbol table.
-
-@node Sparclet Execution
-@subsubsection Running and Debugging
-
-@cindex running and debugging Sparclet programs
-You can now begin debugging the task using @value{GDBN}'s execution control
-commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
-manual for the list of commands.
-
-@smallexample
-(gdbslet) b main
-Breakpoint 1 at 0x12010000: file prog.c, line 3.
-(gdbslet) run
-Starting program: prog
-Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
-3 char *symarg = 0;
-(gdbslet) step
-4 char *execarg = "hello!";
-(gdbslet)
-@end smallexample
-
-@node Sparclite
-@subsection Fujitsu Sparclite
-
-@table @code
-
-@kindex target sparclite
-@item target sparclite @var{dev}
-Fujitsu sparclite boards, used only for the purpose of loading.
-You must use an additional command to debug the program.
-For example: target remote @var{dev} using @value{GDBN} standard
-remote protocol.
-
-@end table
-
-@node Z8000
-@subsection Zilog Z8000
-
-@cindex Z8000
-@cindex simulator, Z8000
-@cindex Zilog Z8000 simulator
-
-When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
-a Z8000 simulator.
-
-For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
-unsegmented variant of the Z8000 architecture) or the Z8001 (the
-segmented variant). The simulator recognizes which architecture is
-appropriate by inspecting the object code.
-
-@table @code
-@item target sim @var{args}
-@kindex sim
-@kindex target sim@r{, with Z8000}
-Debug programs on a simulated CPU. If the simulator supports setup
-options, specify them via @var{args}.
-@end table
-
-@noindent
-After specifying this target, you can debug programs for the simulated
-CPU in the same style as programs for your host computer; use the
-@code{file} command to load a new program image, the @code{run} command
-to run your program, and so on.
-
-As well as making available all the usual machine registers
-(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
-additional items of information as specially named registers:
-
-@table @code
-
-@item cycles
-Counts clock-ticks in the simulator.
-
-@item insts
-Counts instructions run in the simulator.
-
-@item time
-Execution time in 60ths of a second.
-
-@end table
-
-You can refer to these values in @value{GDBN} expressions with the usual
-conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
-conditional breakpoint that suspends only after at least 5000
-simulated clock ticks.
-
@node AVR
@subsection Atmel AVR
@cindex AVR
from functions.
@end table
-@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).
-@cindex Intel(R) Memory Protection Extensions (MPX).
+
+@subsubsection Intel @dfn{Memory Protection Extensions} (MPX).
+@cindex Intel Memory Protection Extensions (MPX).
Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
@footnote{The register named with capital letters represent the architecture
Python, the display includes the memory size, in bits, accessible to
the pointer.
+Bounds can also be stored in bounds tables, which are stored in
+application memory. These tables store bounds for pointers by specifying
+the bounds pointer's value along with its bounds. Evaluating and changing
+bounds located in bound tables is therefore interesting while investigating
+bugs on MPX context. @value{GDBN} provides commands for this purpose:
+
+@table @code
+@item show mpx bound @var{pointer}
+@kindex show mpx bound
+Display bounds of the given @var{pointer}.
+
+@item set mpx bound @var{pointer}, @var{lbound}, @var{ubound}
+@kindex set mpx bound
+Set the bounds of a pointer in the bound table.
+This command takes three parameters: @var{pointer} is the pointers
+whose bounds are to be changed, @var{lbound} and @var{ubound} are new values
+for lower and upper bounds respectively.
+@end table
+
@node Alpha
@subsection Alpha
@cindex history size
@kindex set history size
-@cindex @env{HISTSIZE}, environment variable
+@cindex @env{GDBHISTSIZE}, environment variable
@item set history size @var{size}
@itemx set history size unlimited
Set the number of commands which @value{GDBN} keeps in its history list.
-This defaults to the value of the environment variable
-@code{HISTSIZE}, or to 256 if this variable is not set. If @var{size}
-is @code{unlimited}, the number of commands @value{GDBN} keeps in the
-history list is unlimited.
+This defaults to the value of the environment variable @env{GDBHISTSIZE}, or
+to 256 if this variable is not set. Non-numeric values of @env{GDBHISTSIZE}
+are ignored. If @var{size} is @code{unlimited} or if @env{GDBHISTSIZE} is
+either a negative number or the empty string, then the number of commands
+@value{GDBN} keeps in the history list is unlimited.
+
+@cindex remove duplicate history
+@kindex set history remove-duplicates
+@item set history remove-duplicates @var{count}
+@itemx set history remove-duplicates unlimited
+Control the removal of duplicate history entries in the command history list.
+If @var{count} is non-zero, @value{GDBN} will look back at the last @var{count}
+history entries and remove the first entry that is a duplicate of the current
+entry being added to the command history list. If @var{count} is
+@code{unlimited} then this lookbehind is unbounded. If @var{count} is 0, then
+removal of duplicate history entries is disabled.
+
+Only history entries added during the current session are considered for
+removal. This option is set to 0 by default.
+
@end table
History expansion assigns special meaning to the character @kbd{!}.
@node Screen Size
@section Screen Size
@cindex size of screen
+@cindex screen size
+@cindex pagination
+@cindex page size
@cindex pauses in output
Certain commands to @value{GDBN} may produce large amounts of
@kindex set input-radix
@item set input-radix @var{base}
Set the default base for numeric input. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+for @var{base} are decimal 8, 10, or 16. The base must itself be
specified either unambiguously or using the current input radix; for
example, any of
@kindex set output-radix
@item set output-radix @var{base}
Set the default base for numeric display. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+for @var{base} are decimal 8, 10, or 16. The base must itself be
specified either unambiguously or using the current input radix.
@kindex show input-radix
results or introduce security risks (e.g., if the file comes from untrusted
sources).
+@menu
+* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
+* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
+
+* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
+* Auto-loading verbose mode:: @samp{set/show debug auto-load}
+@end menu
+
+There are various kinds of files @value{GDBN} can automatically load.
+In addition to these files, @value{GDBN} supports auto-loading code written
+in various extension languages. @xref{Auto-loading extensions}.
+
Note that loading of these associated files (including the local @file{.gdbinit}
file) requires accordingly configured @code{auto-load safe-path}
(@pxref{Auto-loading safe path}).
@end smallexample
@end table
-These are various kinds of files @value{GDBN} can automatically load:
-
-@itemize @bullet
-@item
-@xref{objfile-gdb.py file}, controlled by @ref{set auto-load python-scripts}.
-@item
-@xref{objfile-gdb.gdb file}, controlled by @ref{set auto-load gdb-scripts}.
-@item
-@xref{dotdebug_gdb_scripts section},
-controlled by @ref{set auto-load python-scripts}.
-@item
-@xref{Init File in the Current Directory},
-controlled by @ref{set auto-load local-gdbinit}.
-@item
-@xref{libthread_db.so.1 file}, controlled by @ref{set auto-load libthread-db}.
-@end itemize
-
These are @value{GDBN} control commands for the auto-loading:
@multitable @columnfractions .5 .5
@tab Show setting of @value{GDBN} Python scripts.
@item @xref{info auto-load python-scripts}.
@tab Show state of @value{GDBN} Python scripts.
+@item @xref{set auto-load guile-scripts}.
+@tab Control for @value{GDBN} Guile scripts.
+@item @xref{show auto-load guile-scripts}.
+@tab Show setting of @value{GDBN} Guile scripts.
+@item @xref{info auto-load guile-scripts}.
+@tab Show state of @value{GDBN} Guile scripts.
@item @xref{set auto-load scripts-directory}.
@tab Control for @value{GDBN} auto-loaded scripts location.
@item @xref{show auto-load scripts-directory}.
@tab Show @value{GDBN} auto-loaded scripts location.
+@item @xref{add-auto-load-scripts-directory}.
+@tab Add directory for auto-loaded scripts location list.
@item @xref{set auto-load local-gdbinit}.
@tab Control for init file in the current directory.
@item @xref{show auto-load local-gdbinit}.
@tab Add directory trusted for automatic loading.
@end multitable
-@menu
-* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
-* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
-* objfile-gdb.gdb file:: @samp{set/show/info auto-load gdb-script}
-* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
-* Auto-loading verbose mode:: @samp{set/show debug auto-load}
-@xref{Python Auto-loading}.
-@end menu
-
@node Init File in the Current Directory
@subsection Automatically loading init file in the current directory
@cindex auto-loading init file in the current directory
for each such library print list of inferior @var{pid}s using it.
@end table
-@node objfile-gdb.gdb file
-@subsection The @file{@var{objfile}-gdb.gdb} file
-@cindex auto-loading @file{@var{objfile}-gdb.gdb}
-
-@value{GDBN} tries to load an @file{@var{objfile}-gdb.gdb} file containing
-canned sequences of commands (@pxref{Sequences}), as long as @samp{set
-auto-load gdb-scripts} is set to @samp{on}.
-
-Note that loading of this script file also requires accordingly configured
-@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-
-For more background refer to the similar Python scripts auto-loading
-description (@pxref{objfile-gdb.py file}).
-
-@table @code
-@anchor{set auto-load gdb-scripts}
-@kindex set auto-load gdb-scripts
-@item set auto-load gdb-scripts [on|off]
-Enable or disable the auto-loading of canned sequences of commands scripts.
-
-@anchor{show auto-load gdb-scripts}
-@kindex show auto-load gdb-scripts
-@item show auto-load gdb-scripts
-Show whether auto-loading of canned sequences of commands scripts is enabled or
-disabled.
-
-@anchor{info auto-load gdb-scripts}
-@kindex info auto-load gdb-scripts
-@cindex print list of auto-loaded canned sequences of commands scripts
-@item info auto-load gdb-scripts [@var{regexp}]
-Print the list of all canned sequences of commands scripts that @value{GDBN}
-auto-loaded.
-@end table
-
-If @var{regexp} is supplied only canned sequences of commands scripts with
-matching names are printed.
-
@node Auto-loading safe path
@subsection Security restriction for auto-loading
@cindex auto-loading safe-path
@anchor{add-auto-load-safe-path}
@kindex add-auto-load-safe-path
@item add-auto-load-safe-path
-Add an entry (or list of entries) the list of directories trusted for automatic
-loading and execution of scripts. Multiple entries may be delimited by the
-host platform path separator in use.
+Add an entry (or list of entries) to the list of directories trusted for
+automatic loading and execution of scripts. Multiple entries may be delimited
+by the host platform path separator in use.
@end table
This variable defaults to what @code{--with-auto-load-dir} has been configured
@item show debug coff-pe-read
Displays the current state of displaying debugging messages related to
reading of COFF/PE exported symbols.
-@item set debug dwarf2-die
-@cindex DWARF2 DIEs
-Dump DWARF2 DIEs after they are read in.
+@item set debug dwarf-die
+@cindex DWARF DIEs
+Dump DWARF DIEs after they are read in.
The value is the number of nesting levels to print.
A value of zero turns off the display.
-@item show debug dwarf2-die
-Show the current state of DWARF2 DIE debugging.
-@item set debug dwarf2-read
-@cindex DWARF2 Reading
+@item show debug dwarf-die
+Show the current state of DWARF DIE debugging.
+@item set debug dwarf-line
+@cindex DWARF Line Tables
+Turns on or off display of debugging messages related to reading
+DWARF line tables. The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
+@item show debug dwarf-line
+Show the current state of DWARF line table debugging.
+@item set debug dwarf-read
+@cindex DWARF Reading
Turns on or off display of debugging messages related to reading
DWARF debug info. The default is 0 (off).
A value of 1 provides basic information.
A value greater than 1 provides more verbose information.
-@item show debug dwarf2-read
-Show the current state of DWARF2 reader debugging.
+@item show debug dwarf-read
+Show the current state of DWARF reader debugging.
@item set debug displaced
@cindex displaced stepping debugging info
Turns on or off display of @value{GDBN} debugging info for the
@item show debug expression
Displays the current state of displaying debugging info about
@value{GDBN} expression parsing.
+@item set debug fbsd-lwp
+@cindex FreeBSD LWP debug messages
+Turns on or off debugging messages from the FreeBSD LWP debug support.
+@item show debug fbsd-lwp
+Show the current state of FreeBSD LWP debugging messages.
@item set debug frame
@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
info.
@item set debug gnu-nat
@cindex @sc{gnu}/Hurd debug messages
-Turns on or off debugging messages from the @sc{gnu}/Hurd debug support.
+Turn on or off debugging messages from the @sc{gnu}/Hurd debug support.
@item show debug gnu-nat
Show the current state of @sc{gnu}/Hurd debugging messages.
@item set debug infrun
Displays the current state of @value{GDBN} inferior debugging.
@item set debug jit
@cindex just-in-time compilation, debugging messages
-Turns on or off debugging messages from JIT debug support.
+Turn on or off debugging messages from JIT debug support.
@item show debug jit
Displays the current state of @value{GDBN} JIT debugging.
@item set debug lin-lwp
@cindex @sc{gnu}/Linux LWP debug messages
@cindex Linux lightweight processes
-Turns on or off debugging messages from the Linux LWP debug support.
+Turn on or off debugging messages from the Linux LWP debug support.
@item show debug lin-lwp
Show the current state of Linux LWP debugging messages.
+@item set debug linux-namespaces
+@cindex @sc{gnu}/Linux namespaces debug messages
+Turn on or off debugging messages from the Linux namespaces debug support.
+@item show debug linux-namespaces
+Show the current state of Linux namespaces debugging messages.
@item set debug mach-o
@cindex Mach-O symbols processing
Control display of debugging messages related to Mach-O symbols
reading of COFF/PE exported symbols.
@item set debug notification
@cindex remote async notification debugging info
-Turns on or off debugging messages about remote async notification.
+Turn on or off debugging messages about remote async notification.
The default is off.
@item show debug notification
Displays the current state of remote async notification debugging messages.
info.
@item set debug solib-frv
@cindex FR-V shared-library debugging
-Turns on or off debugging messages for FR-V shared-library code.
+Turn on or off debugging messages for FR-V shared-library code.
@item show debug solib-frv
Display the current state of FR-V shared-library code debugging
messages.
+@item set debug symbol-lookup
+@cindex symbol lookup
+Turns on or off display of debugging messages related to symbol lookup.
+The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
+@item show debug symbol-lookup
+Show the current state of symbol lookup debugging messages.
@item set debug symfile
@cindex symbol file functions
Turns on or off display of debugging messages related to symbol file functions.
Turns on or off display of @value{GDBN} target debugging info. This info
includes what is going on at the target level of GDB, as it happens. The
default is 0. Set it to 1 to track events, and to 2 to also track the
-value of large memory transfers. Changes to this flag do not take effect
-until the next time you connect to a target or use the @code{run} command.
+value of large memory transfers.
@item show debug target
Displays the current state of displaying @value{GDBN} target debugging
info.
@item show debug timestamp
Displays the current state of displaying timestamps with @value{GDBN}
debugging info.
-@item set debugvarobj
+@item set debug varobj
@cindex variable object debugging info
Turns on or off display of @value{GDBN} variable object debugging
info. The default is off.
-@item show debugvarobj
+@item show debug varobj
Displays the current state of displaying @value{GDBN} variable object
debugging info.
@item set debug xml
@cindex XML parser debugging
-Turns on or off debugging messages for built-in XML parsers.
+Turn on or off debugging messages for built-in XML parsers.
@item show debug xml
Displays the current state of XML debugging messages.
@end table
@chapter Extending @value{GDBN}
@cindex extending GDB
-@value{GDBN} provides three mechanisms for extension. The first is based
-on composition of @value{GDBN} commands, the second is based on the
-Python scripting language, and the third is for defining new aliases of
-existing commands.
+@value{GDBN} provides several mechanisms for extension.
+@value{GDBN} also provides the ability to automatically load
+extensions when it reads a file for debugging. This allows the
+user to automatically customize @value{GDBN} for the program
+being debugged.
-To facilitate the use of the first two extensions, @value{GDBN} is capable
+@menu
+* Sequences:: Canned Sequences of @value{GDBN} Commands
+* Python:: Extending @value{GDBN} using Python
+* Guile:: Extending @value{GDBN} using Guile
+* Auto-loading extensions:: Automatically loading extensions
+* Multiple Extension Languages:: Working with multiple extension languages
+* Aliases:: Creating new spellings of existing commands
+@end menu
+
+To facilitate the use of extension languages, @value{GDBN} is capable
of evaluating the contents of a file. When doing so, @value{GDBN}
-can recognize which scripting language is being used by looking at
+can recognize which extension language is being used by looking at
the filename extension. Files with an unrecognized filename extension
are always treated as a @value{GDBN} Command Files.
@xref{Command Files,, Command files}.
@end table
-@menu
-* Sequences:: Canned Sequences of Commands
-* Python:: Scripting @value{GDBN} using Python
-* Aliases:: Creating new spellings of existing commands
-@end menu
-
@node Sequences
@section Canned Sequences of Commands
* Hooks:: Hooks for user-defined commands
* Command Files:: How to write scripts of commands to be stored in a file
* Output:: Commands for controlled output
+* Auto-loading sequences:: Controlling auto-loaded command files
@end menu
@node Define
@item define @var{commandname}
Define a command named @var{commandname}. If there is already a command
by that name, you are asked to confirm that you want to redefine it.
-@var{commandname} may be a bare command name consisting of letters,
+The argument @var{commandname} may be a bare command name consisting of letters,
numbers, dashes, and underscores. It may also start with any predefined
prefix command. For example, @samp{define target my-target} creates
a user-defined @samp{target my-target} command.
@end table
-@node Python
-@section Scripting @value{GDBN} using Python
-@cindex python scripting
-@cindex scripting with python
-
-You can script @value{GDBN} using the @uref{http://www.python.org/,
-Python programming language}. This feature is available only if
-@value{GDBN} was configured using @option{--with-python}.
-
-@cindex python directory
-Python scripts used by @value{GDBN} should be installed in
-@file{@var{data-directory}/python}, where @var{data-directory} is
-the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
-This directory, known as the @dfn{python directory},
-is automatically added to the Python Search Path in order to allow
-the Python interpreter to locate all scripts installed at this location.
-
-Additionally, @value{GDBN} commands and convenience functions which
-are written in Python and are located in the
-@file{@var{data-directory}/python/gdb/command} or
-@file{@var{data-directory}/python/gdb/function} directories are
-automatically imported when @value{GDBN} starts.
-
-@menu
-* Python Commands:: Accessing Python from @value{GDBN}.
-* Python API:: Accessing @value{GDBN} from Python.
-* Python Auto-loading:: Automatically loading Python code.
-* Python modules:: Python modules provided by @value{GDBN}.
-@end menu
+@node Auto-loading sequences
+@subsection Controlling auto-loading native @value{GDBN} scripts
+@cindex native script auto-loading
-@node Python Commands
-@subsection Python Commands
-@cindex python commands
-@cindex commands to access python
+When a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library),
+@value{GDBN} will look for the command file @file{@var{objfile}-gdb.gdb}.
+@xref{Auto-loading extensions}.
-@value{GDBN} provides two commands for accessing the Python interpreter,
-and one related setting:
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
@table @code
-@kindex python-interactive
-@kindex pi
-@item python-interactive @r{[}@var{command}@r{]}
-@itemx pi @r{[}@var{command}@r{]}
-Without an argument, the @code{python-interactive} command can be used
-to start an interactive Python prompt. To return to @value{GDBN},
-type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
-
-Alternatively, a single-line Python command can be given as an
-argument and evaluated. If the command is an expression, the result
-will be printed; otherwise, nothing will be printed. For example:
-
-@smallexample
-(@value{GDBP}) python-interactive 2 + 3
-5
-@end smallexample
-
-@kindex python
-@kindex py
-@item python @r{[}@var{command}@r{]}
-@itemx py @r{[}@var{command}@r{]}
-The @code{python} command can be used to evaluate Python code.
-
-If given an argument, the @code{python} command will evaluate the
-argument as a Python command. For example:
-
-@smallexample
-(@value{GDBP}) python print 23
-23
-@end smallexample
-
-If you do not provide an argument to @code{python}, it will act as a
-multi-line command, like @code{define}. In this case, the Python
-script is made up of subsequent command lines, given after the
-@code{python} command. This command list is terminated using a line
-containing @code{end}. For example:
+@anchor{set auto-load gdb-scripts}
+@kindex set auto-load gdb-scripts
+@item set auto-load gdb-scripts [on|off]
+Enable or disable the auto-loading of canned sequences of commands scripts.
-@smallexample
-(@value{GDBP}) python
-Type python script
-End with a line saying just "end".
->print 23
->end
-23
-@end smallexample
+@anchor{show auto-load gdb-scripts}
+@kindex show auto-load gdb-scripts
+@item show auto-load gdb-scripts
+Show whether auto-loading of canned sequences of commands scripts is enabled or
+disabled.
-@kindex set python print-stack
-@item set python print-stack
-By default, @value{GDBN} will print only the message component of a
-Python exception when an error occurs in a Python script. This can be
-controlled using @code{set python print-stack}: if @code{full}, then
-full Python stack printing is enabled; if @code{none}, then Python stack
-and message printing is disabled; if @code{message}, the default, only
-the message component of the error is printed.
+@anchor{info auto-load gdb-scripts}
+@kindex info auto-load gdb-scripts
+@cindex print list of auto-loaded canned sequences of commands scripts
+@item info auto-load gdb-scripts [@var{regexp}]
+Print the list of all canned sequences of commands scripts that @value{GDBN}
+auto-loaded.
@end table
-It is also possible to execute a Python script from the @value{GDBN}
-interpreter:
-
-@table @code
-@item source @file{script-name}
-The script name must end with @samp{.py} and @value{GDBN} must be configured
-to recognize the script language based on filename extension using
-the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
+If @var{regexp} is supplied only canned sequences of commands scripts with
+matching names are printed.
-@item python execfile ("script-name")
-This method is based on the @code{execfile} Python built-in function,
-and thus is always available.
-@end table
+@c Python docs live in a separate file.
+@include python.texi
-@node Python API
-@subsection Python API
-@cindex python api
-@cindex programming in python
+@c Guile docs live in a separate file.
+@include guile.texi
-You can get quick online help for @value{GDBN}'s Python API by issuing
-the command @w{@kbd{python help (gdb)}}.
+@node Auto-loading extensions
+@section Auto-loading extensions
+@cindex auto-loading extensions
-Functions and methods which have two or more optional arguments allow
-them to be specified using keyword syntax. This allows passing some
-optional arguments while skipping others. Example:
-@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
+@value{GDBN} provides two mechanisms for automatically loading extensions
+when a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library):
+@file{@var{objfile}-gdb.@var{ext}} and the @code{.debug_gdb_scripts}
+section of modern file formats like ELF.
@menu
-* Basic Python:: Basic Python Functions.
-* Exception Handling:: How Python exceptions are translated.
-* Values From Inferior:: Python representation of values.
-* Types In Python:: Python representation of types.
-* Pretty Printing API:: Pretty-printing values.
-* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
-* Writing a Pretty-Printer:: Writing a Pretty-Printer.
-* Type Printing API:: Pretty-printing types.
-* Frame Filter API:: Filtering Frames.
-* Frame Decorator API:: Decorating Frames.
-* Writing a Frame Filter:: Writing a Frame Filter.
-* Inferiors In Python:: Python representation of inferiors (processes)
-* Events In Python:: Listening for events from @value{GDBN}.
-* Threads In Python:: Accessing inferior threads from Python.
-* Commands In Python:: Implementing new commands in Python.
-* Parameters In Python:: Adding new @value{GDBN} parameters.
-* Functions In Python:: Writing new convenience functions.
-* Progspaces In Python:: Program spaces.
-* Objfiles In Python:: Object files.
-* Frames In Python:: Accessing inferior stack frames from Python.
-* Blocks In Python:: Accessing blocks from Python.
-* Symbols In Python:: Python representation of symbols.
-* Symbol Tables In Python:: Python representation of symbol tables.
-* Line Tables In Python:: Python representation of line tables.
-* Breakpoints In Python:: Manipulating breakpoints using Python.
-* Finish Breakpoints in Python:: Setting Breakpoints on function return
- using Python.
-* Lazy Strings In Python:: Python representation of lazy strings.
-* Architectures In Python:: Python representation of architectures.
+* objfile-gdb.ext file: objfile-gdbdotext file. The @file{@var{objfile}-gdb.@var{ext}} file
+* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The @code{.debug_gdb_scripts} section
+* Which flavor to choose?::
@end menu
-@node Basic Python
-@subsubsection Basic Python
-
-@cindex python stdout
-@cindex python pagination
-At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
-@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
-A Python program which outputs to one of these streams may have its
-output interrupted by the user (@pxref{Screen Size}). In this
-situation, a Python @code{KeyboardInterrupt} exception is thrown.
-
-Some care must be taken when writing Python code to run in
-@value{GDBN}. Two things worth noting in particular:
-
-@itemize @bullet
-@item
-@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
-Python code must not override these, or even change the options using
-@code{sigaction}. If your program changes the handling of these
-signals, @value{GDBN} will most likely stop working correctly. Note
-that it is unfortunately common for GUI toolkits to install a
-@code{SIGCHLD} handler.
-
-@item
-@value{GDBN} takes care to mark its internal file descriptors as
-close-on-exec. However, this cannot be done in a thread-safe way on
-all platforms. Your Python programs should be aware of this and
-should both create new file descriptors with the close-on-exec flag
-set and arrange to close unneeded file descriptors before starting a
-child process.
-@end itemize
-
-@cindex python functions
-@cindex python module
-@cindex gdb module
-@value{GDBN} introduces a new Python module, named @code{gdb}. All
-methods and classes added by @value{GDBN} are placed in this module.
-@value{GDBN} automatically @code{import}s the @code{gdb} module for
-use in all scripts evaluated by the @code{python} command.
-
-@findex gdb.PYTHONDIR
-@defvar gdb.PYTHONDIR
-A string containing the python directory (@pxref{Python}).
-@end defvar
-
-@findex gdb.execute
-@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
-Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
-If a GDB exception happens while @var{command} runs, it is
-translated as described in @ref{Exception Handling,,Exception Handling}.
-
-@var{from_tty} specifies whether @value{GDBN} ought to consider this
-command as having originated from the user invoking it interactively.
-It must be a boolean value. If omitted, it defaults to @code{False}.
-
-By default, any output produced by @var{command} is sent to
-@value{GDBN}'s standard output. If the @var{to_string} parameter is
-@code{True}, then output will be collected by @code{gdb.execute} and
-returned as a string. The default is @code{False}, in which case the
-return value is @code{None}. If @var{to_string} is @code{True}, the
-@value{GDBN} virtual terminal will be temporarily set to unlimited width
-and height, and its pagination will be disabled; @pxref{Screen Size}.
-@end defun
-
-@findex gdb.breakpoints
-@defun gdb.breakpoints ()
-Return a sequence holding all of @value{GDBN}'s breakpoints.
-@xref{Breakpoints In Python}, for more information.
-@end defun
-
-@findex gdb.parameter
-@defun gdb.parameter (parameter)
-Return the value of a @value{GDBN} parameter. @var{parameter} is a
-string naming the parameter to look up; @var{parameter} may contain
-spaces if the parameter has a multi-part name. For example,
-@samp{print object} is a valid parameter name.
-
-If the named parameter does not exist, this function throws a
-@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
-parameter's value is converted to a Python value of the appropriate
-type, and returned.
-@end defun
-
-@findex gdb.history
-@defun gdb.history (number)
-Return a value from @value{GDBN}'s value history (@pxref{Value
-History}). @var{number} indicates which history element to return.
-If @var{number} is negative, then @value{GDBN} will take its absolute value
-and count backward from the last element (i.e., the most recent element) to
-find the value to return. If @var{number} is zero, then @value{GDBN} will
-return the most recent element. If the element specified by @var{number}
-doesn't exist in the value history, a @code{gdb.error} exception will be
-raised.
-
-If no exception is raised, the return value is always an instance of
-@code{gdb.Value} (@pxref{Values From Inferior}).
-@end defun
-
-@findex gdb.parse_and_eval
-@defun gdb.parse_and_eval (expression)
-Parse @var{expression} as an expression in the current language,
-evaluate it, and return the result as a @code{gdb.Value}.
-@var{expression} must be a string.
-
-This function can be useful when implementing a new command
-(@pxref{Commands In Python}), as it provides a way to parse the
-command's argument as an expression. It is also useful simply to
-compute values, for example, it is the only way to get the value of a
-convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
-@end defun
-
-@findex gdb.find_pc_line
-@defun gdb.find_pc_line (pc)
-Return the @code{gdb.Symtab_and_line} object corresponding to the
-@var{pc} value. @xref{Symbol Tables In Python}. If an invalid
-value of @var{pc} is passed as an argument, then the @code{symtab} and
-@code{line} attributes of the returned @code{gdb.Symtab_and_line} object
-will be @code{None} and 0 respectively.
-@end defun
-
-@findex gdb.post_event
-@defun gdb.post_event (event)
-Put @var{event}, a callable object taking no arguments, into
-@value{GDBN}'s internal event queue. This callable will be invoked at
-some later point, during @value{GDBN}'s event processing. Events
-posted using @code{post_event} will be run in the order in which they
-were posted; however, there is no way to know when they will be
-processed relative to other events inside @value{GDBN}.
-
-@value{GDBN} is not thread-safe. If your Python program uses multiple
-threads, you must be careful to only call @value{GDBN}-specific
-functions in the main @value{GDBN} thread. @code{post_event} ensures
-this. For example:
-
-@smallexample
-(@value{GDBP}) python
->import threading
->
->class Writer():
-> def __init__(self, message):
-> self.message = message;
-> def __call__(self):
-> gdb.write(self.message)
->
->class MyThread1 (threading.Thread):
-> def run (self):
-> gdb.post_event(Writer("Hello "))
->
->class MyThread2 (threading.Thread):
-> def run (self):
-> gdb.post_event(Writer("World\n"))
->
->MyThread1().start()
->MyThread2().start()
->end
-(@value{GDBP}) Hello World
-@end smallexample
-@end defun
-
-@findex gdb.write
-@defun gdb.write (string @r{[}, stream{]})
-Print a string to @value{GDBN}'s paginated output stream. The
-optional @var{stream} determines the stream to print to. The default
-stream is @value{GDBN}'s standard output stream. Possible stream
-values are:
-
-@table @code
-@findex STDOUT
-@findex gdb.STDOUT
-@item gdb.STDOUT
-@value{GDBN}'s standard output stream.
-
-@findex STDERR
-@findex gdb.STDERR
-@item gdb.STDERR
-@value{GDBN}'s standard error stream.
-
-@findex STDLOG
-@findex gdb.STDLOG
-@item gdb.STDLOG
-@value{GDBN}'s log stream (@pxref{Logging Output}).
-@end table
-
-Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
-call this function and will automatically direct the output to the
-relevant stream.
-@end defun
-
-@findex gdb.flush
-@defun gdb.flush ()
-Flush the buffer of a @value{GDBN} paginated stream so that the
-contents are displayed immediately. @value{GDBN} will flush the
-contents of a stream automatically when it encounters a newline in the
-buffer. The optional @var{stream} determines the stream to flush. The
-default stream is @value{GDBN}'s standard output stream. Possible
-stream values are:
-
-@table @code
-@findex STDOUT
-@findex gdb.STDOUT
-@item gdb.STDOUT
-@value{GDBN}'s standard output stream.
-
-@findex STDERR
-@findex gdb.STDERR
-@item gdb.STDERR
-@value{GDBN}'s standard error stream.
-
-@findex STDLOG
-@findex gdb.STDLOG
-@item gdb.STDLOG
-@value{GDBN}'s log stream (@pxref{Logging Output}).
-
-@end table
-
-Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
-call this function for the relevant stream.
-@end defun
-
-@findex gdb.target_charset
-@defun gdb.target_charset ()
-Return the name of the current target character set (@pxref{Character
-Sets}). This differs from @code{gdb.parameter('target-charset')} in
-that @samp{auto} is never returned.
-@end defun
-
-@findex gdb.target_wide_charset
-@defun gdb.target_wide_charset ()
-Return the name of the current target wide character set
-(@pxref{Character Sets}). This differs from
-@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
-never returned.
-@end defun
-
-@findex gdb.solib_name
-@defun gdb.solib_name (address)
-Return the name of the shared library holding the given @var{address}
-as a string, or @code{None}.
-@end defun
-
-@findex gdb.decode_line
-@defun gdb.decode_line @r{[}expression@r{]}
-Return locations of the line specified by @var{expression}, or of the
-current line if no argument was given. This function returns a Python
-tuple containing two elements. The first element contains a string
-holding any unparsed section of @var{expression} (or @code{None} if
-the expression has been fully parsed). The second element contains
-either @code{None} or another tuple that contains all the locations
-that match the expression represented as @code{gdb.Symtab_and_line}
-objects (@pxref{Symbol Tables In Python}). If @var{expression} is
-provided, it is decoded the way that @value{GDBN}'s inbuilt
-@code{break} or @code{edit} commands do (@pxref{Specify Location}).
-@end defun
-
-@defun gdb.prompt_hook (current_prompt)
-@anchor{prompt_hook}
-
-If @var{prompt_hook} is callable, @value{GDBN} will call the method
-assigned to this operation before a prompt is displayed by
-@value{GDBN}.
-
-The parameter @code{current_prompt} contains the current @value{GDBN}
-prompt. This method must return a Python string, or @code{None}. If
-a string is returned, the @value{GDBN} prompt will be set to that
-string. If @code{None} is returned, @value{GDBN} will continue to use
-the current prompt.
-
-Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
-such as those used by readline for command input, and annotation
-related prompts are prohibited from being changed.
-@end defun
-
-@node Exception Handling
-@subsubsection Exception Handling
-@cindex python exceptions
-@cindex exceptions, python
-
-When executing the @code{python} command, Python exceptions
-uncaught within the Python code are translated to calls to
-@value{GDBN} error-reporting mechanism. If the command that called
-@code{python} does not handle the error, @value{GDBN} will
-terminate it and print an error message containing the Python
-exception name, the associated value, and the Python call stack
-backtrace at the point where the exception was raised. Example:
-
-@smallexample
-(@value{GDBP}) python print foo
-Traceback (most recent call last):
- File "<string>", line 1, in <module>
-NameError: name 'foo' is not defined
-@end smallexample
-
-@value{GDBN} errors that happen in @value{GDBN} commands invoked by
-Python code are converted to Python exceptions. The type of the
-Python exception depends on the error.
-
-@ftable @code
-@item gdb.error
-This is the base class for most exceptions generated by @value{GDBN}.
-It is derived from @code{RuntimeError}, for compatibility with earlier
-versions of @value{GDBN}.
-
-If an error occurring in @value{GDBN} does not fit into some more
-specific category, then the generated exception will have this type.
-
-@item gdb.MemoryError
-This is a subclass of @code{gdb.error} which is thrown when an
-operation tried to access invalid memory in the inferior.
-
-@item KeyboardInterrupt
-User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
-prompt) is translated to a Python @code{KeyboardInterrupt} exception.
-@end ftable
-
-In all cases, your exception handler will see the @value{GDBN} error
-message as its value and the Python call stack backtrace at the Python
-statement closest to where the @value{GDBN} error occured as the
-traceback.
-
-@findex gdb.GdbError
-When implementing @value{GDBN} commands in Python via @code{gdb.Command},
-it is useful to be able to throw an exception that doesn't cause a
-traceback to be printed. For example, the user may have invoked the
-command incorrectly. Use the @code{gdb.GdbError} exception
-to handle this case. Example:
-
-@smallexample
-(gdb) python
->class HelloWorld (gdb.Command):
-> """Greet the whole world."""
-> def __init__ (self):
-> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
-> def invoke (self, args, from_tty):
-> argv = gdb.string_to_argv (args)
-> if len (argv) != 0:
-> raise gdb.GdbError ("hello-world takes no arguments")
-> print "Hello, World!"
->HelloWorld ()
->end
-(gdb) hello-world 42
-hello-world takes no arguments
-@end smallexample
-
-@node Values From Inferior
-@subsubsection Values From Inferior
-@cindex values from inferior, with Python
-@cindex python, working with values from inferior
-
-@cindex @code{gdb.Value}
-@value{GDBN} provides values it obtains from the inferior program in
-an object of type @code{gdb.Value}. @value{GDBN} uses this object
-for its internal bookkeeping of the inferior's values, and for
-fetching values when necessary.
-
-Inferior values that are simple scalars can be used directly in
-Python expressions that are valid for the value's data type. Here's
-an example for an integer or floating-point value @code{some_val}:
-
-@smallexample
-bar = some_val + 2
-@end smallexample
-
-@noindent
-As result of this, @code{bar} will also be a @code{gdb.Value} object
-whose values are of the same type as those of @code{some_val}.
-
-Inferior values that are structures or instances of some class can
-be accessed using the Python @dfn{dictionary syntax}. For example, if
-@code{some_val} is a @code{gdb.Value} instance holding a structure, you
-can access its @code{foo} element with:
-
-@smallexample
-bar = some_val['foo']
-@end smallexample
-
-Again, @code{bar} will also be a @code{gdb.Value} object.
-
-A @code{gdb.Value} that represents a function can be executed via
-inferior function call. Any arguments provided to the call must match
-the function's prototype, and must be provided in the order specified
-by that prototype.
-
-For example, @code{some_val} is a @code{gdb.Value} instance
-representing a function that takes two integers as arguments. To
-execute this function, call it like so:
-
-@smallexample
-result = some_val (10,20)
-@end smallexample
-
-Any values returned from a function call will be stored as a
-@code{gdb.Value}.
-
-The following attributes are provided:
-
-@defvar Value.address
-If this object is addressable, this read-only attribute holds a
-@code{gdb.Value} object representing the address. Otherwise,
-this attribute holds @code{None}.
-@end defvar
-
-@cindex optimized out value in Python
-@defvar Value.is_optimized_out
-This read-only boolean attribute is true if the compiler optimized out
-this value, thus it is not available for fetching from the inferior.
-@end defvar
-
-@defvar Value.type
-The type of this @code{gdb.Value}. The value of this attribute is a
-@code{gdb.Type} object (@pxref{Types In Python}).
-@end defvar
-
-@defvar Value.dynamic_type
-The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
-type information (@acronym{RTTI}) to determine the dynamic type of the
-value. If this value is of class type, it will return the class in
-which the value is embedded, if any. If this value is of pointer or
-reference to a class type, it will compute the dynamic type of the
-referenced object, and return a pointer or reference to that type,
-respectively. In all other cases, it will return the value's static
-type.
-
-Note that this feature will only work when debugging a C@t{++} program
-that includes @acronym{RTTI} for the object in question. Otherwise,
-it will just return the static type of the value as in @kbd{ptype foo}
-(@pxref{Symbols, ptype}).
-@end defvar
-
-@defvar Value.is_lazy
-The value of this read-only boolean attribute is @code{True} if this
-@code{gdb.Value} has not yet been fetched from the inferior.
-@value{GDBN} does not fetch values until necessary, for efficiency.
-For example:
-
-@smallexample
-myval = gdb.parse_and_eval ('somevar')
-@end smallexample
-
-The value of @code{somevar} is not fetched at this time. It will be
-fetched when the value is needed, or when the @code{fetch_lazy}
-method is invoked.
-@end defvar
-
-The following methods are provided:
-
-@defun Value.__init__ (@var{val})
-Many Python values can be converted directly to a @code{gdb.Value} via
-this object initializer. Specifically:
-
-@table @asis
-@item Python boolean
-A Python boolean is converted to the boolean type from the current
-language.
-
-@item Python integer
-A Python integer is converted to the C @code{long} type for the
-current architecture.
-
-@item Python long
-A Python long is converted to the C @code{long long} type for the
-current architecture.
-
-@item Python float
-A Python float is converted to the C @code{double} type for the
-current architecture.
-
-@item Python string
-A Python string is converted to a target string, using the current
-target encoding.
-
-@item @code{gdb.Value}
-If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
-
-@item @code{gdb.LazyString}
-If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
-Python}), then the lazy string's @code{value} method is called, and
-its result is used.
-@end table
-@end defun
-
-@defun Value.cast (type)
-Return a new instance of @code{gdb.Value} that is the result of
-casting this instance to the type described by @var{type}, which must
-be a @code{gdb.Type} object. If the cast cannot be performed for some
-reason, this method throws an exception.
-@end defun
-
-@defun Value.dereference ()
-For pointer data types, this method returns a new @code{gdb.Value} object
-whose contents is the object pointed to by the pointer. For example, if
-@code{foo} is a C pointer to an @code{int}, declared in your C program as
-
-@smallexample
-int *foo;
-@end smallexample
-
-@noindent
-then you can use the corresponding @code{gdb.Value} to access what
-@code{foo} points to like this:
-
-@smallexample
-bar = foo.dereference ()
-@end smallexample
-
-The result @code{bar} will be a @code{gdb.Value} object holding the
-value pointed to by @code{foo}.
-
-A similar function @code{Value.referenced_value} exists which also
-returns @code{gdb.Value} objects corresonding to the values pointed to
-by pointer values (and additionally, values referenced by reference
-values). However, the behavior of @code{Value.dereference}
-differs from @code{Value.referenced_value} by the fact that the
-behavior of @code{Value.dereference} is identical to applying the C
-unary operator @code{*} on a given value. For example, consider a
-reference to a pointer @code{ptrref}, declared in your C@t{++} program
-as
-
-@smallexample
-typedef int *intptr;
-...
-int val = 10;
-intptr ptr = &val;
-intptr &ptrref = ptr;
-@end smallexample
-
-Though @code{ptrref} is a reference value, one can apply the method
-@code{Value.dereference} to the @code{gdb.Value} object corresponding
-to it and obtain a @code{gdb.Value} which is identical to that
-corresponding to @code{val}. However, if you apply the method
-@code{Value.referenced_value}, the result would be a @code{gdb.Value}
-object identical to that corresponding to @code{ptr}.
-
-@smallexample
-py_ptrref = gdb.parse_and_eval ("ptrref")
-py_val = py_ptrref.dereference ()
-py_ptr = py_ptrref.referenced_value ()
-@end smallexample
-
-The @code{gdb.Value} object @code{py_val} is identical to that
-corresponding to @code{val}, and @code{py_ptr} is identical to that
-corresponding to @code{ptr}. In general, @code{Value.dereference} can
-be applied whenever the C unary operator @code{*} can be applied
-to the corresponding C value. For those cases where applying both
-@code{Value.dereference} and @code{Value.referenced_value} is allowed,
-the results obtained need not be identical (as we have seen in the above
-example). The results are however identical when applied on
-@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
-objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
-@end defun
-
-@defun Value.referenced_value ()
-For pointer or reference data types, this method returns a new
-@code{gdb.Value} object corresponding to the value referenced by the
-pointer/reference value. For pointer data types,
-@code{Value.dereference} and @code{Value.referenced_value} produce
-identical results. The difference between these methods is that
-@code{Value.dereference} cannot get the values referenced by reference
-values. For example, consider a reference to an @code{int}, declared
-in your C@t{++} program as
-
-@smallexample
-int val = 10;
-int &ref = val;
-@end smallexample
-
-@noindent
-then applying @code{Value.dereference} to the @code{gdb.Value} object
-corresponding to @code{ref} will result in an error, while applying
-@code{Value.referenced_value} will result in a @code{gdb.Value} object
-identical to that corresponding to @code{val}.
-
-@smallexample
-py_ref = gdb.parse_and_eval ("ref")
-er_ref = py_ref.dereference () # Results in error
-py_val = py_ref.referenced_value () # Returns the referenced value
-@end smallexample
-
-The @code{gdb.Value} object @code{py_val} is identical to that
-corresponding to @code{val}.
-@end defun
-
-@defun Value.dynamic_cast (type)
-Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
-operator were used. Consult a C@t{++} reference for details.
-@end defun
-
-@defun Value.reinterpret_cast (type)
-Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
-operator were used. Consult a C@t{++} reference for details.
-@end defun
-
-@defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
-If this @code{gdb.Value} represents a string, then this method
-converts the contents to a Python string. Otherwise, this method will
-throw an exception.
-
-Strings are recognized in a language-specific way; whether a given
-@code{gdb.Value} represents a string is determined by the current
-language.
-
-For C-like languages, a value is a string if it is a pointer to or an
-array of characters or ints. The string is assumed to be terminated
-by a zero of the appropriate width. However if the optional length
-argument is given, the string will be converted to that given length,
-ignoring any embedded zeros that the string may contain.
-
-If the optional @var{encoding} argument is given, it must be a string
-naming the encoding of the string in the @code{gdb.Value}, such as
-@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
-the same encodings as the corresponding argument to Python's
-@code{string.decode} method, and the Python codec machinery will be used
-to convert the string. If @var{encoding} is not given, or if
-@var{encoding} is the empty string, then either the @code{target-charset}
-(@pxref{Character Sets}) will be used, or a language-specific encoding
-will be used, if the current language is able to supply one.
-
-The optional @var{errors} argument is the same as the corresponding
-argument to Python's @code{string.decode} method.
-
-If the optional @var{length} argument is given, the string will be
-fetched and converted to the given length.
-@end defun
-
-@defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
-If this @code{gdb.Value} represents a string, then this method
-converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
-In Python}). Otherwise, this method will throw an exception.
-
-If the optional @var{encoding} argument is given, it must be a string
-naming the encoding of the @code{gdb.LazyString}. Some examples are:
-@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
-@var{encoding} argument is an encoding that @value{GDBN} does
-recognize, @value{GDBN} will raise an error.
-
-When a lazy string is printed, the @value{GDBN} encoding machinery is
-used to convert the string during printing. If the optional
-@var{encoding} argument is not provided, or is an empty string,
-@value{GDBN} will automatically select the encoding most suitable for
-the string type. For further information on encoding in @value{GDBN}
-please see @ref{Character Sets}.
-
-If the optional @var{length} argument is given, the string will be
-fetched and encoded to the length of characters specified. If
-the @var{length} argument is not provided, the string will be fetched
-and encoded until a null of appropriate width is found.
-@end defun
-
-@defun Value.fetch_lazy ()
-If the @code{gdb.Value} object is currently a lazy value
-(@code{gdb.Value.is_lazy} is @code{True}), then the value is
-fetched from the inferior. Any errors that occur in the process
-will produce a Python exception.
-
-If the @code{gdb.Value} object is not a lazy value, this method
-has no effect.
-
-This method does not return a value.
-@end defun
-
-
-@node Types In Python
-@subsubsection Types In Python
-@cindex types in Python
-@cindex Python, working with types
-
-@tindex gdb.Type
-@value{GDBN} represents types from the inferior using the class
-@code{gdb.Type}.
-
-The following type-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.lookup_type
-@defun gdb.lookup_type (name @r{[}, block@r{]})
-This function looks up a type by name. @var{name} is the name of the
-type to look up. It must be a string.
-
-If @var{block} is given, then @var{name} is looked up in that scope.
-Otherwise, it is searched for globally.
-
-Ordinarily, this function will return an instance of @code{gdb.Type}.
-If the named type cannot be found, it will throw an exception.
-@end defun
-
-If the type is a structure or class type, or an enum type, the fields
-of that type can be accessed using the Python @dfn{dictionary syntax}.
-For example, if @code{some_type} is a @code{gdb.Type} instance holding
-a structure type, you can access its @code{foo} field with:
-
-@smallexample
-bar = some_type['foo']
-@end smallexample
-
-@code{bar} will be a @code{gdb.Field} object; see below under the
-description of the @code{Type.fields} method for a description of the
-@code{gdb.Field} class.
-
-An instance of @code{Type} has the following attributes:
-
-@defvar Type.code
-The type code for this type. The type code will be one of the
-@code{TYPE_CODE_} constants defined below.
-@end defvar
-
-@defvar Type.sizeof
-The size of this type, in target @code{char} units. Usually, a
-target's @code{char} type will be an 8-bit byte. However, on some
-unusual platforms, this type may have a different size.
-@end defvar
-
-@defvar Type.tag
-The tag name for this type. The tag name is the name after
-@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
-languages have this concept. If this type has no tag name, then
-@code{None} is returned.
-@end defvar
-
-The following methods are provided:
-
-@defun Type.fields ()
-For structure and union types, this method returns the fields. Range
-types have two fields, the minimum and maximum values. Enum types
-have one field per enum constant. Function and method types have one
-field per parameter. The base types of C@t{++} classes are also
-represented as fields. If the type has no fields, or does not fit
-into one of these categories, an empty sequence will be returned.
-
-Each field is a @code{gdb.Field} object, with some pre-defined attributes:
-@table @code
-@item bitpos
-This attribute is not available for @code{static} fields (as in
-C@t{++} or Java). For non-@code{static} fields, the value is the bit
-position of the field. For @code{enum} fields, the value is the
-enumeration member's integer representation.
-
-@item name
-The name of the field, or @code{None} for anonymous fields.
-
-@item artificial
-This is @code{True} if the field is artificial, usually meaning that
-it was provided by the compiler and not the user. This attribute is
-always provided, and is @code{False} if the field is not artificial.
-
-@item is_base_class
-This is @code{True} if the field represents a base class of a C@t{++}
-structure. This attribute is always provided, and is @code{False}
-if the field is not a base class of the type that is the argument of
-@code{fields}, or if that type was not a C@t{++} class.
-
-@item bitsize
-If the field is packed, or is a bitfield, then this will have a
-non-zero value, which is the size of the field in bits. Otherwise,
-this will be zero; in this case the field's size is given by its type.
-
-@item type
-The type of the field. This is usually an instance of @code{Type},
-but it can be @code{None} in some situations.
-@end table
-@end defun
-
-@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
-Return a new @code{gdb.Type} object which represents an array of this
-type. If one argument is given, it is the inclusive upper bound of
-the array; in this case the lower bound is zero. If two arguments are
-given, the first argument is the lower bound of the array, and the
-second argument is the upper bound of the array. An array's length
-must not be negative, but the bounds can be.
-@end defun
-
-@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
-Return a new @code{gdb.Type} object which represents a vector of this
-type. If one argument is given, it is the inclusive upper bound of
-the vector; in this case the lower bound is zero. If two arguments are
-given, the first argument is the lower bound of the vector, and the
-second argument is the upper bound of the vector. A vector's length
-must not be negative, but the bounds can be.
-
-The difference between an @code{array} and a @code{vector} is that
-arrays behave like in C: when used in expressions they decay to a pointer
-to the first element whereas vectors are treated as first class values.
-@end defun
-
-@defun Type.const ()
-Return a new @code{gdb.Type} object which represents a
-@code{const}-qualified variant of this type.
-@end defun
-
-@defun Type.volatile ()
-Return a new @code{gdb.Type} object which represents a
-@code{volatile}-qualified variant of this type.
-@end defun
-
-@defun Type.unqualified ()
-Return a new @code{gdb.Type} object which represents an unqualified
-variant of this type. That is, the result is neither @code{const} nor
-@code{volatile}.
-@end defun
-
-@defun Type.range ()
-Return a Python @code{Tuple} object that contains two elements: the
-low bound of the argument type and the high bound of that type. If
-the type does not have a range, @value{GDBN} will raise a
-@code{gdb.error} exception (@pxref{Exception Handling}).
-@end defun
-
-@defun Type.reference ()
-Return a new @code{gdb.Type} object which represents a reference to this
-type.
-@end defun
-
-@defun Type.pointer ()
-Return a new @code{gdb.Type} object which represents a pointer to this
-type.
-@end defun
-
-@defun Type.strip_typedefs ()
-Return a new @code{gdb.Type} that represents the real type,
-after removing all layers of typedefs.
-@end defun
-
-@defun Type.target ()
-Return a new @code{gdb.Type} object which represents the target type
-of this type.
-
-For a pointer type, the target type is the type of the pointed-to
-object. For an array type (meaning C-like arrays), the target type is
-the type of the elements of the array. For a function or method type,
-the target type is the type of the return value. For a complex type,
-the target type is the type of the elements. For a typedef, the
-target type is the aliased type.
-
-If the type does not have a target, this method will throw an
-exception.
-@end defun
-
-@defun Type.template_argument (n @r{[}, block@r{]})
-If this @code{gdb.Type} is an instantiation of a template, this will
-return a new @code{gdb.Type} which represents the type of the
-@var{n}th template argument.
-
-If this @code{gdb.Type} is not a template type, this will throw an
-exception. Ordinarily, only C@t{++} code will have template types.
-
-If @var{block} is given, then @var{name} is looked up in that scope.
-Otherwise, it is searched for globally.
-@end defun
-
-
-Each type has a code, which indicates what category this type falls
-into. The available type categories are represented by constants
-defined in the @code{gdb} module:
-
-@table @code
-@findex TYPE_CODE_PTR
-@findex gdb.TYPE_CODE_PTR
-@item gdb.TYPE_CODE_PTR
-The type is a pointer.
-
-@findex TYPE_CODE_ARRAY
-@findex gdb.TYPE_CODE_ARRAY
-@item gdb.TYPE_CODE_ARRAY
-The type is an array.
-
-@findex TYPE_CODE_STRUCT
-@findex gdb.TYPE_CODE_STRUCT
-@item gdb.TYPE_CODE_STRUCT
-The type is a structure.
-
-@findex TYPE_CODE_UNION
-@findex gdb.TYPE_CODE_UNION
-@item gdb.TYPE_CODE_UNION
-The type is a union.
-
-@findex TYPE_CODE_ENUM
-@findex gdb.TYPE_CODE_ENUM
-@item gdb.TYPE_CODE_ENUM
-The type is an enum.
-
-@findex TYPE_CODE_FLAGS
-@findex gdb.TYPE_CODE_FLAGS
-@item gdb.TYPE_CODE_FLAGS
-A bit flags type, used for things such as status registers.
-
-@findex TYPE_CODE_FUNC
-@findex gdb.TYPE_CODE_FUNC
-@item gdb.TYPE_CODE_FUNC
-The type is a function.
-
-@findex TYPE_CODE_INT
-@findex gdb.TYPE_CODE_INT
-@item gdb.TYPE_CODE_INT
-The type is an integer type.
-
-@findex TYPE_CODE_FLT
-@findex gdb.TYPE_CODE_FLT
-@item gdb.TYPE_CODE_FLT
-A floating point type.
-
-@findex TYPE_CODE_VOID
-@findex gdb.TYPE_CODE_VOID
-@item gdb.TYPE_CODE_VOID
-The special type @code{void}.
-
-@findex TYPE_CODE_SET
-@findex gdb.TYPE_CODE_SET
-@item gdb.TYPE_CODE_SET
-A Pascal set type.
-
-@findex TYPE_CODE_RANGE
-@findex gdb.TYPE_CODE_RANGE
-@item gdb.TYPE_CODE_RANGE
-A range type, that is, an integer type with bounds.
-
-@findex TYPE_CODE_STRING
-@findex gdb.TYPE_CODE_STRING
-@item gdb.TYPE_CODE_STRING
-A string type. Note that this is only used for certain languages with
-language-defined string types; C strings are not represented this way.
-
-@findex TYPE_CODE_BITSTRING
-@findex gdb.TYPE_CODE_BITSTRING
-@item gdb.TYPE_CODE_BITSTRING
-A string of bits. It is deprecated.
-
-@findex TYPE_CODE_ERROR
-@findex gdb.TYPE_CODE_ERROR
-@item gdb.TYPE_CODE_ERROR
-An unknown or erroneous type.
-
-@findex TYPE_CODE_METHOD
-@findex gdb.TYPE_CODE_METHOD
-@item gdb.TYPE_CODE_METHOD
-A method type, as found in C@t{++} or Java.
-
-@findex TYPE_CODE_METHODPTR
-@findex gdb.TYPE_CODE_METHODPTR
-@item gdb.TYPE_CODE_METHODPTR
-A pointer-to-member-function.
-
-@findex TYPE_CODE_MEMBERPTR
-@findex gdb.TYPE_CODE_MEMBERPTR
-@item gdb.TYPE_CODE_MEMBERPTR
-A pointer-to-member.
-
-@findex TYPE_CODE_REF
-@findex gdb.TYPE_CODE_REF
-@item gdb.TYPE_CODE_REF
-A reference type.
-
-@findex TYPE_CODE_CHAR
-@findex gdb.TYPE_CODE_CHAR
-@item gdb.TYPE_CODE_CHAR
-A character type.
-
-@findex TYPE_CODE_BOOL
-@findex gdb.TYPE_CODE_BOOL
-@item gdb.TYPE_CODE_BOOL
-A boolean type.
-
-@findex TYPE_CODE_COMPLEX
-@findex gdb.TYPE_CODE_COMPLEX
-@item gdb.TYPE_CODE_COMPLEX
-A complex float type.
-
-@findex TYPE_CODE_TYPEDEF
-@findex gdb.TYPE_CODE_TYPEDEF
-@item gdb.TYPE_CODE_TYPEDEF
-A typedef to some other type.
-
-@findex TYPE_CODE_NAMESPACE
-@findex gdb.TYPE_CODE_NAMESPACE
-@item gdb.TYPE_CODE_NAMESPACE
-A C@t{++} namespace.
-
-@findex TYPE_CODE_DECFLOAT
-@findex gdb.TYPE_CODE_DECFLOAT
-@item gdb.TYPE_CODE_DECFLOAT
-A decimal floating point type.
-
-@findex TYPE_CODE_INTERNAL_FUNCTION
-@findex gdb.TYPE_CODE_INTERNAL_FUNCTION
-@item gdb.TYPE_CODE_INTERNAL_FUNCTION
-A function internal to @value{GDBN}. This is the type used to represent
-convenience functions.
-@end table
-
-Further support for types is provided in the @code{gdb.types}
-Python module (@pxref{gdb.types}).
-
-@node Pretty Printing API
-@subsubsection Pretty Printing API
-
-An example output is provided (@pxref{Pretty Printing}).
-
-A pretty-printer is just an object that holds a value and implements a
-specific interface, defined here.
-
-@defun pretty_printer.children (self)
-@value{GDBN} will call this method on a pretty-printer to compute the
-children of the pretty-printer's value.
-
-This method must return an object conforming to the Python iterator
-protocol. Each item returned by the iterator must be a tuple holding
-two elements. The first element is the ``name'' of the child; the
-second element is the child's value. The value can be any Python
-object which is convertible to a @value{GDBN} value.
-
-This method is optional. If it does not exist, @value{GDBN} will act
-as though the value has no children.
-@end defun
-
-@defun pretty_printer.display_hint (self)
-The CLI may call this method and use its result to change the
-formatting of a value. The result will also be supplied to an MI
-consumer as a @samp{displayhint} attribute of the variable being
-printed.
-
-This method is optional. If it does exist, this method must return a
-string.
-
-Some display hints are predefined by @value{GDBN}:
-
-@table @samp
-@item array
-Indicate that the object being printed is ``array-like''. The CLI
-uses this to respect parameters such as @code{set print elements} and
-@code{set print array}.
-
-@item map
-Indicate that the object being printed is ``map-like'', and that the
-children of this value can be assumed to alternate between keys and
-values.
-
-@item string
-Indicate that the object being printed is ``string-like''. If the
-printer's @code{to_string} method returns a Python string of some
-kind, then @value{GDBN} will call its internal language-specific
-string-printing function to format the string. For the CLI this means
-adding quotation marks, possibly escaping some characters, respecting
-@code{set print elements}, and the like.
-@end table
-@end defun
-
-@defun pretty_printer.to_string (self)
-@value{GDBN} will call this method to display the string
-representation of the value passed to the object's constructor.
-
-When printing from the CLI, if the @code{to_string} method exists,
-then @value{GDBN} will prepend its result to the values returned by
-@code{children}. Exactly how this formatting is done is dependent on
-the display hint, and may change as more hints are added. Also,
-depending on the print settings (@pxref{Print Settings}), the CLI may
-print just the result of @code{to_string} in a stack trace, omitting
-the result of @code{children}.
-
-If this method returns a string, it is printed verbatim.
-
-Otherwise, if this method returns an instance of @code{gdb.Value},
-then @value{GDBN} prints this value. This may result in a call to
-another pretty-printer.
-
-If instead the method returns a Python value which is convertible to a
-@code{gdb.Value}, then @value{GDBN} performs the conversion and prints
-the resulting value. Again, this may result in a call to another
-pretty-printer. Python scalars (integers, floats, and booleans) and
-strings are convertible to @code{gdb.Value}; other types are not.
-
-Finally, if this method returns @code{None} then no further operations
-are peformed in this method and nothing is printed.
-
-If the result is not one of these types, an exception is raised.
-@end defun
-
-@value{GDBN} provides a function which can be used to look up the
-default pretty-printer for a @code{gdb.Value}:
-
-@findex gdb.default_visualizer
-@defun gdb.default_visualizer (value)
-This function takes a @code{gdb.Value} object as an argument. If a
-pretty-printer for this value exists, then it is returned. If no such
-printer exists, then this returns @code{None}.
-@end defun
-
-@node Selecting Pretty-Printers
-@subsubsection Selecting Pretty-Printers
-
-The Python list @code{gdb.pretty_printers} contains an array of
-functions or callable objects that have been registered via addition
-as a pretty-printer. Printers in this list are called @code{global}
-printers, they're available when debugging all inferiors.
-Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
-Each @code{gdb.Objfile} also contains a @code{pretty_printers}
-attribute.
-
-Each function on these lists is passed a single @code{gdb.Value}
-argument and should return a pretty-printer object conforming to the
-interface definition above (@pxref{Pretty Printing API}). If a function
-cannot create a pretty-printer for the value, it should return
-@code{None}.
-
-@value{GDBN} first checks the @code{pretty_printers} attribute of each
-@code{gdb.Objfile} in the current program space and iteratively calls
-each enabled lookup routine in the list for that @code{gdb.Objfile}
-until it receives a pretty-printer object.
-If no pretty-printer is found in the objfile lists, @value{GDBN} then
-searches the pretty-printer list of the current program space,
-calling each enabled function until an object is returned.
-After these lists have been exhausted, it tries the global
-@code{gdb.pretty_printers} list, again calling each enabled function until an
-object is returned.
-
-The order in which the objfiles are searched is not specified. For a
-given list, functions are always invoked from the head of the list,
-and iterated over sequentially until the end of the list, or a printer
-object is returned.
-
-For various reasons a pretty-printer may not work.
-For example, the underlying data structure may have changed and
-the pretty-printer is out of date.
-
-The consequences of a broken pretty-printer are severe enough that
-@value{GDBN} provides support for enabling and disabling individual
-printers. For example, if @code{print frame-arguments} is on,
-a backtrace can become highly illegible if any argument is printed
-with a broken printer.
-
-Pretty-printers are enabled and disabled by attaching an @code{enabled}
-attribute to the registered function or callable object. If this attribute
-is present and its value is @code{False}, the printer is disabled, otherwise
-the printer is enabled.
-
-@node Writing a Pretty-Printer
-@subsubsection Writing a Pretty-Printer
-@cindex writing a pretty-printer
-
-A pretty-printer consists of two parts: a lookup function to detect
-if the type is supported, and the printer itself.
-
-Here is an example showing how a @code{std::string} printer might be
-written. @xref{Pretty Printing API}, for details on the API this class
-must provide.
-
-@smallexample
-class StdStringPrinter(object):
- "Print a std::string"
-
- def __init__(self, val):
- self.val = val
-
- def to_string(self):
- return self.val['_M_dataplus']['_M_p']
-
- def display_hint(self):
- return 'string'
-@end smallexample
-
-And here is an example showing how a lookup function for the printer
-example above might be written.
-
-@smallexample
-def str_lookup_function(val):
- lookup_tag = val.type.tag
- if lookup_tag == None:
- return None
- regex = re.compile("^std::basic_string<char,.*>$")
- if regex.match(lookup_tag):
- return StdStringPrinter(val)
- return None
-@end smallexample
-
-The example lookup function extracts the value's type, and attempts to
-match it to a type that it can pretty-print. If it is a type the
-printer can pretty-print, it will return a printer object. If not, it
-returns @code{None}.
-
-We recommend that you put your core pretty-printers into a Python
-package. If your pretty-printers are for use with a library, we
-further recommend embedding a version number into the package name.
-This practice will enable @value{GDBN} to load multiple versions of
-your pretty-printers at the same time, because they will have
-different names.
-
-You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
-can be evaluated multiple times without changing its meaning. An
-ideal auto-load file will consist solely of @code{import}s of your
-printer modules, followed by a call to a register pretty-printers with
-the current objfile.
-
-Taken as a whole, this approach will scale nicely to multiple
-inferiors, each potentially using a different library version.
-Embedding a version number in the Python package name will ensure that
-@value{GDBN} is able to load both sets of printers simultaneously.
-Then, because the search for pretty-printers is done by objfile, and
-because your auto-loaded code took care to register your library's
-printers with a specific objfile, @value{GDBN} will find the correct
-printers for the specific version of the library used by each
-inferior.
-
-To continue the @code{std::string} example (@pxref{Pretty Printing API}),
-this code might appear in @code{gdb.libstdcxx.v6}:
-
-@smallexample
-def register_printers(objfile):
- objfile.pretty_printers.append(str_lookup_function)
-@end smallexample
-
-@noindent
-And then the corresponding contents of the auto-load file would be:
-
-@smallexample
-import gdb.libstdcxx.v6
-gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
-@end smallexample
-
-The previous example illustrates a basic pretty-printer.
-There are a few things that can be improved on.
-The printer doesn't have a name, making it hard to identify in a
-list of installed printers. The lookup function has a name, but
-lookup functions can have arbitrary, even identical, names.
-
-Second, the printer only handles one type, whereas a library typically has
-several types. One could install a lookup function for each desired type
-in the library, but one could also have a single lookup function recognize
-several types. The latter is the conventional way this is handled.
-If a pretty-printer can handle multiple data types, then its
-@dfn{subprinters} are the printers for the individual data types.
-
-The @code{gdb.printing} module provides a formal way of solving these
-problems (@pxref{gdb.printing}).
-Here is another example that handles multiple types.
-
-These are the types we are going to pretty-print:
-
-@smallexample
-struct foo @{ int a, b; @};
-struct bar @{ struct foo x, y; @};
-@end smallexample
-
-Here are the printers:
-
-@smallexample
-class fooPrinter:
- """Print a foo object."""
-
- def __init__(self, val):
- self.val = val
-
- def to_string(self):
- return ("a=<" + str(self.val["a"]) +
- "> b=<" + str(self.val["b"]) + ">")
-
-class barPrinter:
- """Print a bar object."""
-
- def __init__(self, val):
- self.val = val
-
- def to_string(self):
- return ("x=<" + str(self.val["x"]) +
- "> y=<" + str(self.val["y"]) + ">")
-@end smallexample
-
-This example doesn't need a lookup function, that is handled by the
-@code{gdb.printing} module. Instead a function is provided to build up
-the object that handles the lookup.
-
-@smallexample
-import gdb.printing
-
-def build_pretty_printer():
- pp = gdb.printing.RegexpCollectionPrettyPrinter(
- "my_library")
- pp.add_printer('foo', '^foo$', fooPrinter)
- pp.add_printer('bar', '^bar$', barPrinter)
- return pp
-@end smallexample
-
-And here is the autoload support:
-
-@smallexample
-import gdb.printing
-import my_library
-gdb.printing.register_pretty_printer(
- gdb.current_objfile(),
- my_library.build_pretty_printer())
-@end smallexample
-
-Finally, when this printer is loaded into @value{GDBN}, here is the
-corresponding output of @samp{info pretty-printer}:
-
-@smallexample
-(gdb) info pretty-printer
-my_library.so:
- my_library
- foo
- bar
-@end smallexample
-
-@node Type Printing API
-@subsubsection Type Printing API
-@cindex type printing API for Python
-
-@value{GDBN} provides a way for Python code to customize type display.
-This is mainly useful for substituting canonical typedef names for
-types.
-
-@cindex type printer
-A @dfn{type printer} is just a Python object conforming to a certain
-protocol. A simple base class implementing the protocol is provided;
-see @ref{gdb.types}. A type printer must supply at least:
-
-@defivar type_printer enabled
-A boolean which is True if the printer is enabled, and False
-otherwise. This is manipulated by the @code{enable type-printer}
-and @code{disable type-printer} commands.
-@end defivar
-
-@defivar type_printer name
-The name of the type printer. This must be a string. This is used by
-the @code{enable type-printer} and @code{disable type-printer}
-commands.
-@end defivar
-
-@defmethod type_printer instantiate (self)
-This is called by @value{GDBN} at the start of type-printing. It is
-only called if the type printer is enabled. This method must return a
-new object that supplies a @code{recognize} method, as described below.
-@end defmethod
-
-
-When displaying a type, say via the @code{ptype} command, @value{GDBN}
-will compute a list of type recognizers. This is done by iterating
-first over the per-objfile type printers (@pxref{Objfiles In Python}),
-followed by the per-progspace type printers (@pxref{Progspaces In
-Python}), and finally the global type printers.
-
-@value{GDBN} will call the @code{instantiate} method of each enabled
-type printer. If this method returns @code{None}, then the result is
-ignored; otherwise, it is appended to the list of recognizers.
-
-Then, when @value{GDBN} is going to display a type name, it iterates
-over the list of recognizers. For each one, it calls the recognition
-function, stopping if the function returns a non-@code{None} value.
-The recognition function is defined as:
-
-@defmethod type_recognizer recognize (self, type)
-If @var{type} is not recognized, return @code{None}. Otherwise,
-return a string which is to be printed as the name of @var{type}.
-@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
-Python}).
-@end defmethod
-
-@value{GDBN} uses this two-pass approach so that type printers can
-efficiently cache information without holding on to it too long. For
-example, it can be convenient to look up type information in a type
-printer and hold it for a recognizer's lifetime; if a single pass were
-done then type printers would have to make use of the event system in
-order to avoid holding information that could become stale as the
-inferior changed.
-
-@node Frame Filter API
-@subsubsection Filtering Frames.
-@cindex frame filters api
-
-Frame filters are Python objects that manipulate the visibility of a
-frame or frames when a backtrace (@pxref{Backtrace}) is printed by
-@value{GDBN}.
-
-Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
-commands (@pxref{GDB/MI}), those that return a collection of frames
-are affected. The commands that work with frame filters are:
-
-@code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
-@code{-stack-list-frames}
-(@pxref{-stack-list-frames,, The -stack-list-frames command}),
-@code{-stack-list-variables} (@pxref{-stack-list-variables,, The
--stack-list-variables command}), @code{-stack-list-arguments}
-@pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
-@code{-stack-list-locals} (@pxref{-stack-list-locals,, The
--stack-list-locals command}).
-
-A frame filter works by taking an iterator as an argument, applying
-actions to the contents of that iterator, and returning another
-iterator (or, possibly, the same iterator it was provided in the case
-where the filter does not perform any operations). Typically, frame
-filters utilize tools such as the Python's @code{itertools} module to
-work with and create new iterators from the source iterator.
-Regardless of how a filter chooses to apply actions, it must not alter
-the underlying @value{GDBN} frame or frames, or attempt to alter the
-call-stack within @value{GDBN}. This preserves data integrity within
-@value{GDBN}. Frame filters are executed on a priority basis and care
-should be taken that some frame filters may have been executed before,
-and that some frame filters will be executed after.
-
-An important consideration when designing frame filters, and well
-worth reflecting upon, is that frame filters should avoid unwinding
-the call stack if possible. Some stacks can run very deep, into the
-tens of thousands in some cases. To search every frame when a frame
-filter executes may be too expensive at that step. The frame filter
-cannot know how many frames it has to iterate over, and it may have to
-iterate through them all. This ends up duplicating effort as
-@value{GDBN} performs this iteration when it prints the frames. If
-the filter can defer unwinding frames until frame decorators are
-executed, after the last filter has executed, it should. @xref{Frame
-Decorator API}, for more information on decorators. Also, there are
-examples for both frame decorators and filters in later chapters.
-@xref{Writing a Frame Filter}, for more information.
-
-The Python dictionary @code{gdb.frame_filters} contains key/object
-pairings that comprise a frame filter. Frame filters in this
-dictionary are called @code{global} frame filters, and they are
-available when debugging all inferiors. These frame filters must
-register with the dictionary directly. In addition to the
-@code{global} dictionary, there are other dictionaries that are loaded
-with different inferiors via auto-loading (@pxref{Python
-Auto-loading}). The two other areas where frame filter dictionaries
-can be found are: @code{gdb.Progspace} which contains a
-@code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
-object which also contains a @code{frame_filters} dictionary
-attribute.
-
-When a command is executed from @value{GDBN} that is compatible with
-frame filters, @value{GDBN} combines the @code{global},
-@code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
-loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
-several frames, and thus several object files, might be in use.
-@value{GDBN} then prunes any frame filter whose @code{enabled}
-attribute is @code{False}. This pruned list is then sorted according
-to the @code{priority} attribute in each filter.
-
-Once the dictionaries are combined, pruned and sorted, @value{GDBN}
-creates an iterator which wraps each frame in the call stack in a
-@code{FrameDecorator} object, and calls each filter in order. The
-output from the previous filter will always be the input to the next
-filter, and so on.
-
-Frame filters have a mandatory interface which each frame filter must
-implement, defined here:
-
-@defun FrameFilter.filter (iterator)
-@value{GDBN} will call this method on a frame filter when it has
-reached the order in the priority list for that filter.
-
-For example, if there are four frame filters:
-
-@smallexample
-Name Priority
-
-Filter1 5
-Filter2 10
-Filter3 100
-Filter4 1
-@end smallexample
-
-The order that the frame filters will be called is:
-
-@smallexample
-Filter3 -> Filter2 -> Filter1 -> Filter4
-@end smallexample
-
-Note that the output from @code{Filter3} is passed to the input of
-@code{Filter2}, and so on.
-
-This @code{filter} method is passed a Python iterator. This iterator
-contains a sequence of frame decorators that wrap each
-@code{gdb.Frame}, or a frame decorator that wraps another frame
-decorator. The first filter that is executed in the sequence of frame
-filters will receive an iterator entirely comprised of default
-@code{FrameDecorator} objects. However, after each frame filter is
-executed, the previous frame filter may have wrapped some or all of
-the frame decorators with their own frame decorator. As frame
-decorators must also conform to a mandatory interface, these
-decorators can be assumed to act in a uniform manner (@pxref{Frame
-Decorator API}).
-
-This method must return an object conforming to the Python iterator
-protocol. Each item in the iterator must be an object conforming to
-the frame decorator interface. If a frame filter does not wish to
-perform any operations on this iterator, it should return that
-iterator untouched.
-
-This method is not optional. If it does not exist, @value{GDBN} will
-raise and print an error.
-@end defun
-
-@defvar FrameFilter.name
-The @code{name} attribute must be Python string which contains the
-name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
-Management}). This attribute may contain any combination of letters
-or numbers. Care should be taken to ensure that it is unique. This
-attribute is mandatory.
-@end defvar
-
-@defvar FrameFilter.enabled
-The @code{enabled} attribute must be Python boolean. This attribute
-indicates to @value{GDBN} whether the frame filter is enabled, and
-should be considered when frame filters are executed. If
-@code{enabled} is @code{True}, then the frame filter will be executed
-when any of the backtrace commands detailed earlier in this chapter
-are executed. If @code{enabled} is @code{False}, then the frame
-filter will not be executed. This attribute is mandatory.
-@end defvar
-
-@defvar FrameFilter.priority
-The @code{priority} attribute must be Python integer. This attribute
-controls the order of execution in relation to other frame filters.
-There are no imposed limits on the range of @code{priority} other than
-it must be a valid integer. The higher the @code{priority} attribute,
-the sooner the frame filter will be executed in relation to other
-frame filters. Although @code{priority} can be negative, it is
-recommended practice to assume zero is the lowest priority that a
-frame filter can be assigned. Frame filters that have the same
-priority are executed in unsorted order in that priority slot. This
-attribute is mandatory.
-@end defvar
-
-@node Frame Decorator API
-@subsubsection Decorating Frames.
-@cindex frame decorator api
-
-Frame decorators are sister objects to frame filters (@pxref{Frame
-Filter API}). Frame decorators are applied by a frame filter and can
-only be used in conjunction with frame filters.
-
-The purpose of a frame decorator is to customize the printed content
-of each @code{gdb.Frame} in commands where frame filters are executed.
-This concept is called decorating a frame. Frame decorators decorate
-a @code{gdb.Frame} with Python code contained within each API call.
-This separates the actual data contained in a @code{gdb.Frame} from
-the decorated data produced by a frame decorator. This abstraction is
-necessary to maintain integrity of the data contained in each
-@code{gdb.Frame}.
-
-Frame decorators have a mandatory interface, defined below.
-
-@value{GDBN} already contains a frame decorator called
-@code{FrameDecorator}. This contains substantial amounts of
-boilerplate code to decorate the content of a @code{gdb.Frame}. It is
-recommended that other frame decorators inherit and extend this
-object, and only to override the methods needed.
-
-@defun FrameDecorator.elided (self)
-
-The @code{elided} method groups frames together in a hierarchical
-system. An example would be an interpreter, where multiple low-level
-frames make up a single call in the interpreted language. In this
-example, the frame filter would elide the low-level frames and present
-a single high-level frame, representing the call in the interpreted
-language, to the user.
-
-The @code{elided} function must return an iterable and this iterable
-must contain the frames that are being elided wrapped in a suitable
-frame decorator. If no frames are being elided this function may
-return an empty iterable, or @code{None}. Elided frames are indented
-from normal frames in a @code{CLI} backtrace, or in the case of
-@code{GDB/MI}, are placed in the @code{children} field of the eliding
-frame.
-
-It is the frame filter's task to also filter out the elided frames from
-the source iterator. This will avoid printing the frame twice.
-@end defun
-
-@defun FrameDecorator.function (self)
-
-This method returns the name of the function in the frame that is to
-be printed.
-
-This method must return a Python string describing the function, or
-@code{None}.
-
-If this function returns @code{None}, @value{GDBN} will not print any
-data for this field.
-@end defun
-
-@defun FrameDecorator.address (self)
-
-This method returns the address of the frame that is to be printed.
-
-This method must return a Python numeric integer type of sufficient
-size to describe the address of the frame, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.filename (self)
-
-This method returns the filename and path associated with this frame.
-
-This method must return a Python string containing the filename and
-the path to the object file backing the frame, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.line (self):
-
-This method returns the line number associated with the current
-position within the function addressed by this frame.
-
-This method must return a Python integer type, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.frame_args (self)
-@anchor{frame_args}
-
-This method must return an iterable, or @code{None}. Returning an
-empty iterable, or @code{None} means frame arguments will not be
-printed for this frame. This iterable must contain objects that
-implement two methods, described here.
-
-This object must implement a @code{argument} method which takes a
-single @code{self} parameter and must return a @code{gdb.Symbol}
-(@pxref{Symbols In Python}), or a Python string. The object must also
-implement a @code{value} method which takes a single @code{self}
-parameter and must return a @code{gdb.Value} (@pxref{Values From
-Inferior}), a Python value, or @code{None}. If the @code{value}
-method returns @code{None}, and the @code{argument} method returns a
-@code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
-the @code{gdb.Symbol} automatically.
-
-A brief example:
-
-@smallexample
-class SymValueWrapper():
-
- def __init__(self, symbol, value):
- self.sym = symbol
- self.val = value
-
- def value(self):
- return self.val
-
- def symbol(self):
- return self.sym
-
-class SomeFrameDecorator()
-...
-...
- def frame_args(self):
- args = []
- try:
- block = self.inferior_frame.block()
- except:
- return None
-
- # Iterate over all symbols in a block. Only add
- # symbols that are arguments.
- for sym in block:
- if not sym.is_argument:
- continue
- args.append(SymValueWrapper(sym,None))
-
- # Add example synthetic argument.
- args.append(SymValueWrapper(``foo'', 42))
-
- return args
-@end smallexample
-@end defun
-
-@defun FrameDecorator.frame_locals (self)
-
-This method must return an iterable or @code{None}. Returning an
-empty iterable, or @code{None} means frame local arguments will not be
-printed for this frame.
-
-The object interface, the description of the various strategies for
-reading frame locals, and the example are largely similar to those
-described in the @code{frame_args} function, (@pxref{frame_args,,The
-frame filter frame_args function}). Below is a modified example:
-
-@smallexample
-class SomeFrameDecorator()
-...
-...
- def frame_locals(self):
- vars = []
- try:
- block = self.inferior_frame.block()
- except:
- return None
-
- # Iterate over all symbols in a block. Add all
- # symbols, except arguments.
- for sym in block:
- if sym.is_argument:
- continue
- vars.append(SymValueWrapper(sym,None))
-
- # Add an example of a synthetic local variable.
- vars.append(SymValueWrapper(``bar'', 99))
-
- return vars
-@end smallexample
-@end defun
-
-@defun FrameDecorator.inferior_frame (self):
-
-This method must return the underlying @code{gdb.Frame} that this
-frame decorator is decorating. @value{GDBN} requires the underlying
-frame for internal frame information to determine how to print certain
-values when printing a frame.
-@end defun
-
-@node Writing a Frame Filter
-@subsubsection Writing a Frame Filter
-@cindex writing a frame filter
-
-There are three basic elements that a frame filter must implement: it
-must correctly implement the documented interface (@pxref{Frame Filter
-API}), it must register itself with @value{GDBN}, and finally, it must
-decide if it is to work on the data provided by @value{GDBN}. In all
-cases, whether it works on the iterator or not, each frame filter must
-return an iterator. A bare-bones frame filter follows the pattern in
-the following example.
-
-@smallexample
-import gdb
-
-class FrameFilter():
-
- def __init__(self):
- # Frame filter attribute creation.
- #
- # 'name' is the name of the filter that GDB will display.
- #
- # 'priority' is the priority of the filter relative to other
- # filters.
- #
- # 'enabled' is a boolean that indicates whether this filter is
- # enabled and should be executed.
-
- self.name = "Foo"
- self.priority = 100
- self.enabled = True
-
- # Register this frame filter with the global frame_filters
- # dictionary.
- gdb.frame_filters[self.name] = self
-
- def filter(self, frame_iter):
- # Just return the iterator.
- return frame_iter
-@end smallexample
-
-The frame filter in the example above implements the three
-requirements for all frame filters. It implements the API, self
-registers, and makes a decision on the iterator (in this case, it just
-returns the iterator untouched).
-
-The first step is attribute creation and assignment, and as shown in
-the comments the filter assigns the following attributes: @code{name},
-@code{priority} and whether the filter should be enabled with the
-@code{enabled} attribute.
-
-The second step is registering the frame filter with the dictionary or
-dictionaries that the frame filter has interest in. As shown in the
-comments, this filter just registers itself with the global dictionary
-@code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
-is a dictionary that is initialized in the @code{gdb} module when
-@value{GDBN} starts. What dictionary a filter registers with is an
-important consideration. Generally, if a filter is specific to a set
-of code, it should be registered either in the @code{objfile} or
-@code{progspace} dictionaries as they are specific to the program
-currently loaded in @value{GDBN}. The global dictionary is always
-present in @value{GDBN} and is never unloaded. Any filters registered
-with the global dictionary will exist until @value{GDBN} exits. To
-avoid filters that may conflict, it is generally better to register
-frame filters against the dictionaries that more closely align with
-the usage of the filter currently in question. @xref{Python
-Auto-loading}, for further information on auto-loading Python scripts.
-
-@value{GDBN} takes a hands-off approach to frame filter registration,
-therefore it is the frame filter's responsibility to ensure
-registration has occurred, and that any exceptions are handled
-appropriately. In particular, you may wish to handle exceptions
-relating to Python dictionary key uniqueness. It is mandatory that
-the dictionary key is the same as frame filter's @code{name}
-attribute. When a user manages frame filters (@pxref{Frame Filter
-Management}), the names @value{GDBN} will display are those contained
-in the @code{name} attribute.
-
-The final step of this example is the implementation of the
-@code{filter} method. As shown in the example comments, we define the
-@code{filter} method and note that the method must take an iterator,
-and also must return an iterator. In this bare-bones example, the
-frame filter is not very useful as it just returns the iterator
-untouched. However this is a valid operation for frame filters that
-have the @code{enabled} attribute set, but decide not to operate on
-any frames.
-
-In the next example, the frame filter operates on all frames and
-utilizes a frame decorator to perform some work on the frames.
-@xref{Frame Decorator API}, for further information on the frame
-decorator interface.
-
-This example works on inlined frames. It highlights frames which are
-inlined by tagging them with an ``[inlined]'' tag. By applying a
-frame decorator to all frames with the Python @code{itertools imap}
-method, the example defers actions to the frame decorator. Frame
-decorators are only processed when @value{GDBN} prints the backtrace.
-
-This introduces a new decision making topic: whether to perform
-decision making operations at the filtering step, or at the printing
-step. In this example's approach, it does not perform any filtering
-decisions at the filtering step beyond mapping a frame decorator to
-each frame. This allows the actual decision making to be performed
-when each frame is printed. This is an important consideration, and
-well worth reflecting upon when designing a frame filter. An issue
-that frame filters should avoid is unwinding the stack if possible.
-Some stacks can run very deep, into the tens of thousands in some
-cases. To search every frame to determine if it is inlined ahead of
-time may be too expensive at the filtering step. The frame filter
-cannot know how many frames it has to iterate over, and it would have
-to iterate through them all. This ends up duplicating effort as
-@value{GDBN} performs this iteration when it prints the frames.
-
-In this example decision making can be deferred to the printing step.
-As each frame is printed, the frame decorator can examine each frame
-in turn when @value{GDBN} iterates. From a performance viewpoint,
-this is the most appropriate decision to make as it avoids duplicating
-the effort that the printing step would undertake anyway. Also, if
-there are many frame filters unwinding the stack during filtering, it
-can substantially delay the printing of the backtrace which will
-result in large memory usage, and a poor user experience.
-
-@smallexample
-class InlineFilter():
-
- def __init__(self):
- self.name = "InlinedFrameFilter"
- self.priority = 100
- self.enabled = True
- gdb.frame_filters[self.name] = self
-
- def filter(self, frame_iter):
- frame_iter = itertools.imap(InlinedFrameDecorator,
- frame_iter)
- return frame_iter
-@end smallexample
-
-This frame filter is somewhat similar to the earlier example, except
-that the @code{filter} method applies a frame decorator object called
-@code{InlinedFrameDecorator} to each element in the iterator. The
-@code{imap} Python method is light-weight. It does not proactively
-iterate over the iterator, but rather creates a new iterator which
-wraps the existing one.
-
-Below is the frame decorator for this example.
-
-@smallexample
-class InlinedFrameDecorator(FrameDecorator):
-
- def __init__(self, fobj):
- super(InlinedFrameDecorator, self).__init__(fobj)
-
- def function(self):
- frame = fobj.inferior_frame()
- name = str(frame.name())
-
- if frame.type() == gdb.INLINE_FRAME:
- name = name + " [inlined]"
-
- return name
-@end smallexample
-
-This frame decorator only defines and overrides the @code{function}
-method. It lets the supplied @code{FrameDecorator}, which is shipped
-with @value{GDBN}, perform the other work associated with printing
-this frame.
-
-The combination of these two objects create this output from a
-backtrace:
-
-@smallexample
-#0 0x004004e0 in bar () at inline.c:11
-#1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
-#2 0x00400566 in main () at inline.c:31
-@end smallexample
-
-So in the case of this example, a frame decorator is applied to all
-frames, regardless of whether they may be inlined or not. As
-@value{GDBN} iterates over the iterator produced by the frame filters,
-@value{GDBN} executes each frame decorator which then makes a decision
-on what to print in the @code{function} callback. Using a strategy
-like this is a way to defer decisions on the frame content to printing
-time.
-
-@subheading Eliding Frames
-
-It might be that the above example is not desirable for representing
-inlined frames, and a hierarchical approach may be preferred. If we
-want to hierarchically represent frames, the @code{elided} frame
-decorator interface might be preferable.
-
-This example approaches the issue with the @code{elided} method. This
-example is quite long, but very simplistic. It is out-of-scope for
-this section to write a complete example that comprehensively covers
-all approaches of finding and printing inlined frames. However, this
-example illustrates the approach an author might use.
-
-This example comprises of three sections.
-
-@smallexample
-class InlineFrameFilter():
-
- def __init__(self):
- self.name = "InlinedFrameFilter"
- self.priority = 100
- self.enabled = True
- gdb.frame_filters[self.name] = self
-
- def filter(self, frame_iter):
- return ElidingInlineIterator(frame_iter)
-@end smallexample
-
-This frame filter is very similar to the other examples. The only
-difference is this frame filter is wrapping the iterator provided to
-it (@code{frame_iter}) with a custom iterator called
-@code{ElidingInlineIterator}. This again defers actions to when
-@value{GDBN} prints the backtrace, as the iterator is not traversed
-until printing.
-
-The iterator for this example is as follows. It is in this section of
-the example where decisions are made on the content of the backtrace.
-
-@smallexample
-class ElidingInlineIterator:
- def __init__(self, ii):
- self.input_iterator = ii
-
- def __iter__(self):
- return self
-
- def next(self):
- frame = next(self.input_iterator)
-
- if frame.inferior_frame().type() != gdb.INLINE_FRAME:
- return frame
-
- try:
- eliding_frame = next(self.input_iterator)
- except StopIteration:
- return frame
- return ElidingFrameDecorator(eliding_frame, [frame])
-@end smallexample
-
-This iterator implements the Python iterator protocol. When the
-@code{next} function is called (when @value{GDBN} prints each frame),
-the iterator checks if this frame decorator, @code{frame}, is wrapping
-an inlined frame. If it is not, it returns the existing frame decorator
-untouched. If it is wrapping an inlined frame, it assumes that the
-inlined frame was contained within the next oldest frame,
-@code{eliding_frame}, which it fetches. It then creates and returns a
-frame decorator, @code{ElidingFrameDecorator}, which contains both the
-elided frame, and the eliding frame.
-
-@smallexample
-class ElidingInlineDecorator(FrameDecorator):
-
- def __init__(self, frame, elided_frames):
- super(ElidingInlineDecorator, self).__init__(frame)
- self.frame = frame
- self.elided_frames = elided_frames
-
- def elided(self):
- return iter(self.elided_frames)
-@end smallexample
-
-This frame decorator overrides one function and returns the inlined
-frame in the @code{elided} method. As before it lets
-@code{FrameDecorator} do the rest of the work involved in printing
-this frame. This produces the following output.
-
-@smallexample
-#0 0x004004e0 in bar () at inline.c:11
-#2 0x00400529 in main () at inline.c:25
- #1 0x00400529 in max (b=6, a=12) at inline.c:15
-@end smallexample
-
-In that output, @code{max} which has been inlined into @code{main} is
-printed hierarchically. Another approach would be to combine the
-@code{function} method, and the @code{elided} method to both print a
-marker in the inlined frame, and also show the hierarchical
-relationship.
-
-@node Inferiors In Python
-@subsubsection Inferiors In Python
-@cindex inferiors in Python
-
-@findex gdb.Inferior
-Programs which are being run under @value{GDBN} are called inferiors
-(@pxref{Inferiors and Programs}). Python scripts can access
-information about and manipulate inferiors controlled by @value{GDBN}
-via objects of the @code{gdb.Inferior} class.
-
-The following inferior-related functions are available in the @code{gdb}
-module:
-
-@defun gdb.inferiors ()
-Return a tuple containing all inferior objects.
-@end defun
-
-@defun gdb.selected_inferior ()
-Return an object representing the current inferior.
-@end defun
-
-A @code{gdb.Inferior} object has the following attributes:
-
-@defvar Inferior.num
-ID of inferior, as assigned by GDB.
-@end defvar
-
-@defvar Inferior.pid
-Process ID of the inferior, as assigned by the underlying operating
-system.
-@end defvar
-
-@defvar Inferior.was_attached
-Boolean signaling whether the inferior was created using `attach', or
-started by @value{GDBN} itself.
-@end defvar
-
-A @code{gdb.Inferior} object has the following methods:
-
-@defun Inferior.is_valid ()
-Returns @code{True} if the @code{gdb.Inferior} object is valid,
-@code{False} if not. A @code{gdb.Inferior} object will become invalid
-if the inferior no longer exists within @value{GDBN}. All other
-@code{gdb.Inferior} methods will throw an exception if it is invalid
-at the time the method is called.
-@end defun
-
-@defun Inferior.threads ()
-This method returns a tuple holding all the threads which are valid
-when it is called. If there are no valid threads, the method will
-return an empty tuple.
-@end defun
-
-@findex Inferior.read_memory
-@defun Inferior.read_memory (address, length)
-Read @var{length} bytes of memory from the inferior, starting at
-@var{address}. Returns a buffer object, which behaves much like an array
-or a string. It can be modified and given to the
-@code{Inferior.write_memory} function. In @code{Python} 3, the return
-value is a @code{memoryview} object.
-@end defun
-
-@findex Inferior.write_memory
-@defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
-Write the contents of @var{buffer} to the inferior, starting at
-@var{address}. The @var{buffer} parameter must be a Python object
-which supports the buffer protocol, i.e., a string, an array or the
-object returned from @code{Inferior.read_memory}. If given, @var{length}
-determines the number of bytes from @var{buffer} to be written.
-@end defun
-
-@findex gdb.search_memory
-@defun Inferior.search_memory (address, length, pattern)
-Search a region of the inferior memory starting at @var{address} with
-the given @var{length} using the search pattern supplied in
-@var{pattern}. The @var{pattern} parameter must be a Python object
-which supports the buffer protocol, i.e., a string, an array or the
-object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
-containing the address where the pattern was found, or @code{None} if
-the pattern could not be found.
-@end defun
-
-@node Events In Python
-@subsubsection Events In Python
-@cindex inferior events in Python
-
-@value{GDBN} provides a general event facility so that Python code can be
-notified of various state changes, particularly changes that occur in
-the inferior.
-
-An @dfn{event} is just an object that describes some state change. The
-type of the object and its attributes will vary depending on the details
-of the change. All the existing events are described below.
-
-In order to be notified of an event, you must register an event handler
-with an @dfn{event registry}. An event registry is an object in the
-@code{gdb.events} module which dispatches particular events. A registry
-provides methods to register and unregister event handlers:
-
-@defun EventRegistry.connect (object)
-Add the given callable @var{object} to the registry. This object will be
-called when an event corresponding to this registry occurs.
-@end defun
-
-@defun EventRegistry.disconnect (object)
-Remove the given @var{object} from the registry. Once removed, the object
-will no longer receive notifications of events.
-@end defun
-
-Here is an example:
-
-@smallexample
-def exit_handler (event):
- print "event type: exit"
- print "exit code: %d" % (event.exit_code)
-
-gdb.events.exited.connect (exit_handler)
-@end smallexample
-
-In the above example we connect our handler @code{exit_handler} to the
-registry @code{events.exited}. Once connected, @code{exit_handler} gets
-called when the inferior exits. The argument @dfn{event} in this example is
-of type @code{gdb.ExitedEvent}. As you can see in the example the
-@code{ExitedEvent} object has an attribute which indicates the exit code of
-the inferior.
-
-The following is a listing of the event registries that are available and
-details of the events they emit:
-
-@table @code
-
-@item events.cont
-Emits @code{gdb.ThreadEvent}.
-
-Some events can be thread specific when @value{GDBN} is running in non-stop
-mode. When represented in Python, these events all extend
-@code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
-events which are emitted by this or other modules might extend this event.
-Examples of these events are @code{gdb.BreakpointEvent} and
-@code{gdb.ContinueEvent}.
-
-@defvar ThreadEvent.inferior_thread
-In non-stop mode this attribute will be set to the specific thread which was
-involved in the emitted event. Otherwise, it will be set to @code{None}.
-@end defvar
-
-Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
-
-This event indicates that the inferior has been continued after a stop. For
-inherited attribute refer to @code{gdb.ThreadEvent} above.
-
-@item events.exited
-Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
-@code{events.ExitedEvent} has two attributes:
-@defvar ExitedEvent.exit_code
-An integer representing the exit code, if available, which the inferior
-has returned. (The exit code could be unavailable if, for example,
-@value{GDBN} detaches from the inferior.) If the exit code is unavailable,
-the attribute does not exist.
-@end defvar
-@defvar ExitedEvent inferior
-A reference to the inferior which triggered the @code{exited} event.
-@end defvar
-
-@item events.stop
-Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
-
-Indicates that the inferior has stopped. All events emitted by this registry
-extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
-will indicate the stopped thread when @value{GDBN} is running in non-stop
-mode. Refer to @code{gdb.ThreadEvent} above for more details.
-
-Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
-
-This event indicates that the inferior or one of its threads has received as
-signal. @code{gdb.SignalEvent} has the following attributes:
-
-@defvar SignalEvent.stop_signal
-A string representing the signal received by the inferior. A list of possible
-signal values can be obtained by running the command @code{info signals} in
-the @value{GDBN} command prompt.
-@end defvar
-
-Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
-
-@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
-been hit, and has the following attributes:
-
-@defvar BreakpointEvent.breakpoints
-A sequence containing references to all the breakpoints (type
-@code{gdb.Breakpoint}) that were hit.
-@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
-@end defvar
-@defvar BreakpointEvent.breakpoint
-A reference to the first breakpoint that was hit.
-This function is maintained for backward compatibility and is now deprecated
-in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
-@end defvar
-
-@item events.new_objfile
-Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
-been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
-
-@defvar NewObjFileEvent.new_objfile
-A reference to the object file (@code{gdb.Objfile}) which has been loaded.
-@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
-@end defvar
-
-@end table
-
-@node Threads In Python
-@subsubsection Threads In Python
-@cindex threads in python
-
-@findex gdb.InferiorThread
-Python scripts can access information about, and manipulate inferior threads
-controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
-
-The following thread-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.selected_thread
-@defun gdb.selected_thread ()
-This function returns the thread object for the selected thread. If there
-is no selected thread, this will return @code{None}.
-@end defun
-
-A @code{gdb.InferiorThread} object has the following attributes:
-
-@defvar InferiorThread.name
-The name of the thread. If the user specified a name using
-@code{thread name}, then this returns that name. Otherwise, if an
-OS-supplied name is available, then it is returned. Otherwise, this
-returns @code{None}.
-
-This attribute can be assigned to. The new value must be a string
-object, which sets the new name, or @code{None}, which removes any
-user-specified thread name.
-@end defvar
-
-@defvar InferiorThread.num
-ID of the thread, as assigned by GDB.
-@end defvar
-
-@defvar InferiorThread.ptid
-ID of the thread, as assigned by the operating system. This attribute is a
-tuple containing three integers. The first is the Process ID (PID); the second
-is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
-Either the LWPID or TID may be 0, which indicates that the operating system
-does not use that identifier.
-@end defvar
-
-A @code{gdb.InferiorThread} object has the following methods:
-
-@defun InferiorThread.is_valid ()
-Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
-@code{False} if not. A @code{gdb.InferiorThread} object will become
-invalid if the thread exits, or the inferior that the thread belongs
-is deleted. All other @code{gdb.InferiorThread} methods will throw an
-exception if it is invalid at the time the method is called.
-@end defun
-
-@defun InferiorThread.switch ()
-This changes @value{GDBN}'s currently selected thread to the one represented
-by this object.
-@end defun
-
-@defun InferiorThread.is_stopped ()
-Return a Boolean indicating whether the thread is stopped.
-@end defun
-
-@defun InferiorThread.is_running ()
-Return a Boolean indicating whether the thread is running.
-@end defun
-
-@defun InferiorThread.is_exited ()
-Return a Boolean indicating whether the thread is exited.
-@end defun
-
-@node Commands In Python
-@subsubsection Commands In Python
-
-@cindex commands in python
-@cindex python commands
-You can implement new @value{GDBN} CLI commands in Python. A CLI
-command is implemented using an instance of the @code{gdb.Command}
-class, most commonly using a subclass.
-
-@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
-The object initializer for @code{Command} registers the new command
-with @value{GDBN}. This initializer is normally invoked from the
-subclass' own @code{__init__} method.
-
-@var{name} is the name of the command. If @var{name} consists of
-multiple words, then the initial words are looked for as prefix
-commands. In this case, if one of the prefix commands does not exist,
-an exception is raised.
-
-There is no support for multi-line commands.
-
-@var{command_class} should be one of the @samp{COMMAND_} constants
-defined below. This argument tells @value{GDBN} how to categorize the
-new command in the help system.
-
-@var{completer_class} is an optional argument. If given, it should be
-one of the @samp{COMPLETE_} constants defined below. This argument
-tells @value{GDBN} how to perform completion for this command. If not
-given, @value{GDBN} will attempt to complete using the object's
-@code{complete} method (see below); if no such method is found, an
-error will occur when completion is attempted.
-
-@var{prefix} is an optional argument. If @code{True}, then the new
-command is a prefix command; sub-commands of this command may be
-registered.
-
-The help text for the new command is taken from the Python
-documentation string for the command's class, if there is one. If no
-documentation string is provided, the default value ``This command is
-not documented.'' is used.
-@end defun
-
-@cindex don't repeat Python command
-@defun Command.dont_repeat ()
-By default, a @value{GDBN} command is repeated when the user enters a
-blank line at the command prompt. A command can suppress this
-behavior by invoking the @code{dont_repeat} method. This is similar
-to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
-@end defun
-
-@defun Command.invoke (argument, from_tty)
-This method is called by @value{GDBN} when this command is invoked.
-
-@var{argument} is a string. It is the argument to the command, after
-leading and trailing whitespace has been stripped.
-
-@var{from_tty} is a boolean argument. When true, this means that the
-command was entered by the user at the terminal; when false it means
-that the command came from elsewhere.
-
-If this method throws an exception, it is turned into a @value{GDBN}
-@code{error} call. Otherwise, the return value is ignored.
-
-@findex gdb.string_to_argv
-To break @var{argument} up into an argv-like string use
-@code{gdb.string_to_argv}. This function behaves identically to
-@value{GDBN}'s internal argument lexer @code{buildargv}.
-It is recommended to use this for consistency.
-Arguments are separated by spaces and may be quoted.
-Example:
-
-@smallexample
-print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
-['1', '2 "3', '4 "5', "6 '7"]
-@end smallexample
-
-@end defun
-
-@cindex completion of Python commands
-@defun Command.complete (text, word)
-This method is called by @value{GDBN} when the user attempts
-completion on this command. All forms of completion are handled by
-this method, that is, the @key{TAB} and @key{M-?} key bindings
-(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
-complete}).
-
-The arguments @var{text} and @var{word} are both strings. @var{text}
-holds the complete command line up to the cursor's location.
-@var{word} holds the last word of the command line; this is computed
-using a word-breaking heuristic.
-
-The @code{complete} method can return several values:
-@itemize @bullet
-@item
-If the return value is a sequence, the contents of the sequence are
-used as the completions. It is up to @code{complete} to ensure that the
-contents actually do complete the word. A zero-length sequence is
-allowed, it means that there were no completions available. Only
-string elements of the sequence are used; other elements in the
-sequence are ignored.
-
-@item
-If the return value is one of the @samp{COMPLETE_} constants defined
-below, then the corresponding @value{GDBN}-internal completion
-function is invoked, and its result is used.
-
-@item
-All other results are treated as though there were no available
-completions.
-@end itemize
-@end defun
-
-When a new command is registered, it must be declared as a member of
-some general class of commands. This is used to classify top-level
-commands in the on-line help system; note that prefix commands are not
-listed under their own category but rather that of their top-level
-command. The available classifications are represented by constants
-defined in the @code{gdb} module:
-
-@table @code
-@findex COMMAND_NONE
-@findex gdb.COMMAND_NONE
-@item gdb.COMMAND_NONE
-The command does not belong to any particular class. A command in
-this category will not be displayed in any of the help categories.
-
-@findex COMMAND_RUNNING
-@findex gdb.COMMAND_RUNNING
-@item gdb.COMMAND_RUNNING
-The command is related to running the inferior. For example,
-@code{start}, @code{step}, and @code{continue} are in this category.
-Type @kbd{help running} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_DATA
-@findex gdb.COMMAND_DATA
-@item gdb.COMMAND_DATA
-The command is related to data or variables. For example,
-@code{call}, @code{find}, and @code{print} are in this category. Type
-@kbd{help data} at the @value{GDBN} prompt to see a list of commands
-in this category.
-
-@findex COMMAND_STACK
-@findex gdb.COMMAND_STACK
-@item gdb.COMMAND_STACK
-The command has to do with manipulation of the stack. For example,
-@code{backtrace}, @code{frame}, and @code{return} are in this
-category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
-list of commands in this category.
-
-@findex COMMAND_FILES
-@findex gdb.COMMAND_FILES
-@item gdb.COMMAND_FILES
-This class is used for file-related commands. For example,
-@code{file}, @code{list} and @code{section} are in this category.
-Type @kbd{help files} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_SUPPORT
-@findex gdb.COMMAND_SUPPORT
-@item gdb.COMMAND_SUPPORT
-This should be used for ``support facilities'', generally meaning
-things that are useful to the user when interacting with @value{GDBN},
-but not related to the state of the inferior. For example,
-@code{help}, @code{make}, and @code{shell} are in this category. Type
-@kbd{help support} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_STATUS
-@findex gdb.COMMAND_STATUS
-@item gdb.COMMAND_STATUS
-The command is an @samp{info}-related command, that is, related to the
-state of @value{GDBN} itself. For example, @code{info}, @code{macro},
-and @code{show} are in this category. Type @kbd{help status} at the
-@value{GDBN} prompt to see a list of commands in this category.
-
-@findex COMMAND_BREAKPOINTS
-@findex gdb.COMMAND_BREAKPOINTS
-@item gdb.COMMAND_BREAKPOINTS
-The command has to do with breakpoints. For example, @code{break},
-@code{clear}, and @code{delete} are in this category. Type @kbd{help
-breakpoints} at the @value{GDBN} prompt to see a list of commands in
-this category.
-
-@findex COMMAND_TRACEPOINTS
-@findex gdb.COMMAND_TRACEPOINTS
-@item gdb.COMMAND_TRACEPOINTS
-The command has to do with tracepoints. For example, @code{trace},
-@code{actions}, and @code{tfind} are in this category. Type
-@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_USER
-@findex gdb.COMMAND_USER
-@item gdb.COMMAND_USER
-The command is a general purpose command for the user, and typically
-does not fit in one of the other categories.
-Type @kbd{help user-defined} at the @value{GDBN} prompt to see
-a list of commands in this category, as well as the list of gdb macros
-(@pxref{Sequences}).
-
-@findex COMMAND_OBSCURE
-@findex gdb.COMMAND_OBSCURE
-@item gdb.COMMAND_OBSCURE
-The command is only used in unusual circumstances, or is not of
-general interest to users. For example, @code{checkpoint},
-@code{fork}, and @code{stop} are in this category. Type @kbd{help
-obscure} at the @value{GDBN} prompt to see a list of commands in this
-category.
-
-@findex COMMAND_MAINTENANCE
-@findex gdb.COMMAND_MAINTENANCE
-@item gdb.COMMAND_MAINTENANCE
-The command is only useful to @value{GDBN} maintainers. The
-@code{maintenance} and @code{flushregs} commands are in this category.
-Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
-commands in this category.
-@end table
-
-A new command can use a predefined completion function, either by
-specifying it via an argument at initialization, or by returning it
-from the @code{complete} method. These predefined completion
-constants are all defined in the @code{gdb} module:
-
-@table @code
-@findex COMPLETE_NONE
-@findex gdb.COMPLETE_NONE
-@item gdb.COMPLETE_NONE
-This constant means that no completion should be done.
-
-@findex COMPLETE_FILENAME
-@findex gdb.COMPLETE_FILENAME
-@item gdb.COMPLETE_FILENAME
-This constant means that filename completion should be performed.
-
-@findex COMPLETE_LOCATION
-@findex gdb.COMPLETE_LOCATION
-@item gdb.COMPLETE_LOCATION
-This constant means that location completion should be done.
-@xref{Specify Location}.
-
-@findex COMPLETE_COMMAND
-@findex gdb.COMPLETE_COMMAND
-@item gdb.COMPLETE_COMMAND
-This constant means that completion should examine @value{GDBN}
-command names.
-
-@findex COMPLETE_SYMBOL
-@findex gdb.COMPLETE_SYMBOL
-@item gdb.COMPLETE_SYMBOL
-This constant means that completion should be done using symbol names
-as the source.
-
-@findex COMPLETE_EXPRESSION
-@findex gdb.COMPLETE_EXPRESSION
-@item gdb.COMPLETE_EXPRESSION
-This constant means that completion should be done on expressions.
-Often this means completing on symbol names, but some language
-parsers also have support for completing on field names.
-@end table
-
-The following code snippet shows how a trivial CLI command can be
-implemented in Python:
-
-@smallexample
-class HelloWorld (gdb.Command):
- """Greet the whole world."""
-
- def __init__ (self):
- super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
-
- def invoke (self, arg, from_tty):
- print "Hello, World!"
-
-HelloWorld ()
-@end smallexample
-
-The last line instantiates the class, and is necessary to trigger the
-registration of the command with @value{GDBN}. Depending on how the
-Python code is read into @value{GDBN}, you may need to import the
-@code{gdb} module explicitly.
-
-@node Parameters In Python
-@subsubsection Parameters In Python
-
-@cindex parameters in python
-@cindex python parameters
-@tindex gdb.Parameter
-@tindex Parameter
-You can implement new @value{GDBN} parameters using Python. A new
-parameter is implemented as an instance of the @code{gdb.Parameter}
-class.
-
-Parameters are exposed to the user via the @code{set} and
-@code{show} commands. @xref{Help}.
-
-There are many parameters that already exist and can be set in
-@value{GDBN}. Two examples are: @code{set follow fork} and
-@code{set charset}. Setting these parameters influences certain
-behavior in @value{GDBN}. Similarly, you can define parameters that
-can be used to influence behavior in custom Python scripts and commands.
-
-@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
-The object initializer for @code{Parameter} registers the new
-parameter with @value{GDBN}. This initializer is normally invoked
-from the subclass' own @code{__init__} method.
-
-@var{name} is the name of the new parameter. If @var{name} consists
-of multiple words, then the initial words are looked for as prefix
-parameters. An example of this can be illustrated with the
-@code{set print} set of parameters. If @var{name} is
-@code{print foo}, then @code{print} will be searched as the prefix
-parameter. In this case the parameter can subsequently be accessed in
-@value{GDBN} as @code{set print foo}.
-
-If @var{name} consists of multiple words, and no prefix parameter group
-can be found, an exception is raised.
-
-@var{command-class} should be one of the @samp{COMMAND_} constants
-(@pxref{Commands In Python}). This argument tells @value{GDBN} how to
-categorize the new parameter in the help system.
-
-@var{parameter-class} should be one of the @samp{PARAM_} constants
-defined below. This argument tells @value{GDBN} the type of the new
-parameter; this information is used for input validation and
-completion.
-
-If @var{parameter-class} is @code{PARAM_ENUM}, then
-@var{enum-sequence} must be a sequence of strings. These strings
-represent the possible values for the parameter.
-
-If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
-of a fourth argument will cause an exception to be thrown.
-
-The help text for the new parameter is taken from the Python
-documentation string for the parameter's class, if there is one. If
-there is no documentation string, a default value is used.
-@end defun
-
-@defvar Parameter.set_doc
-If this attribute exists, and is a string, then its value is used as
-the help text for this parameter's @code{set} command. The value is
-examined when @code{Parameter.__init__} is invoked; subsequent changes
-have no effect.
-@end defvar
-
-@defvar Parameter.show_doc
-If this attribute exists, and is a string, then its value is used as
-the help text for this parameter's @code{show} command. The value is
-examined when @code{Parameter.__init__} is invoked; subsequent changes
-have no effect.
-@end defvar
-
-@defvar Parameter.value
-The @code{value} attribute holds the underlying value of the
-parameter. It can be read and assigned to just as any other
-attribute. @value{GDBN} does validation when assignments are made.
-@end defvar
-
-There are two methods that should be implemented in any
-@code{Parameter} class. These are:
-
-@defun Parameter.get_set_string (self)
-@value{GDBN} will call this method when a @var{parameter}'s value has
-been changed via the @code{set} API (for example, @kbd{set foo off}).
-The @code{value} attribute has already been populated with the new
-value and may be used in output. This method must return a string.
-@end defun
-
-@defun Parameter.get_show_string (self, svalue)
-@value{GDBN} will call this method when a @var{parameter}'s
-@code{show} API has been invoked (for example, @kbd{show foo}). The
-argument @code{svalue} receives the string representation of the
-current value. This method must return a string.
-@end defun
-
-When a new parameter is defined, its type must be specified. The
-available types are represented by constants defined in the @code{gdb}
-module:
-
-@table @code
-@findex PARAM_BOOLEAN
-@findex gdb.PARAM_BOOLEAN
-@item gdb.PARAM_BOOLEAN
-The value is a plain boolean. The Python boolean values, @code{True}
-and @code{False} are the only valid values.
-
-@findex PARAM_AUTO_BOOLEAN
-@findex gdb.PARAM_AUTO_BOOLEAN
-@item gdb.PARAM_AUTO_BOOLEAN
-The value has three possible states: true, false, and @samp{auto}. In
-Python, true and false are represented using boolean constants, and
-@samp{auto} is represented using @code{None}.
-
-@findex PARAM_UINTEGER
-@findex gdb.PARAM_UINTEGER
-@item gdb.PARAM_UINTEGER
-The value is an unsigned integer. The value of 0 should be
-interpreted to mean ``unlimited''.
-
-@findex PARAM_INTEGER
-@findex gdb.PARAM_INTEGER
-@item gdb.PARAM_INTEGER
-The value is a signed integer. The value of 0 should be interpreted
-to mean ``unlimited''.
-
-@findex PARAM_STRING
-@findex gdb.PARAM_STRING
-@item gdb.PARAM_STRING
-The value is a string. When the user modifies the string, any escape
-sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
-translated into corresponding characters and encoded into the current
-host charset.
-
-@findex PARAM_STRING_NOESCAPE
-@findex gdb.PARAM_STRING_NOESCAPE
-@item gdb.PARAM_STRING_NOESCAPE
-The value is a string. When the user modifies the string, escapes are
-passed through untranslated.
-
-@findex PARAM_OPTIONAL_FILENAME
-@findex gdb.PARAM_OPTIONAL_FILENAME
-@item gdb.PARAM_OPTIONAL_FILENAME
-The value is a either a filename (a string), or @code{None}.
-
-@findex PARAM_FILENAME
-@findex gdb.PARAM_FILENAME
-@item gdb.PARAM_FILENAME
-The value is a filename. This is just like
-@code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
-
-@findex PARAM_ZINTEGER
-@findex gdb.PARAM_ZINTEGER
-@item gdb.PARAM_ZINTEGER
-The value is an integer. This is like @code{PARAM_INTEGER}, except 0
-is interpreted as itself.
-
-@findex PARAM_ENUM
-@findex gdb.PARAM_ENUM
-@item gdb.PARAM_ENUM
-The value is a string, which must be one of a collection string
-constants provided when the parameter is created.
-@end table
-
-@node Functions In Python
-@subsubsection Writing new convenience functions
-
-@cindex writing convenience functions
-@cindex convenience functions in python
-@cindex python convenience functions
-@tindex gdb.Function
-@tindex Function
-You can implement new convenience functions (@pxref{Convenience Vars})
-in Python. A convenience function is an instance of a subclass of the
-class @code{gdb.Function}.
-
-@defun Function.__init__ (name)
-The initializer for @code{Function} registers the new function with
-@value{GDBN}. The argument @var{name} is the name of the function,
-a string. The function will be visible to the user as a convenience
-variable of type @code{internal function}, whose name is the same as
-the given @var{name}.
-
-The documentation for the new function is taken from the documentation
-string for the new class.
-@end defun
-
-@defun Function.invoke (@var{*args})
-When a convenience function is evaluated, its arguments are converted
-to instances of @code{gdb.Value}, and then the function's
-@code{invoke} method is called. Note that @value{GDBN} does not
-predetermine the arity of convenience functions. Instead, all
-available arguments are passed to @code{invoke}, following the
-standard Python calling convention. In particular, a convenience
-function can have default values for parameters without ill effect.
-
-The return value of this method is used as its value in the enclosing
-expression. If an ordinary Python value is returned, it is converted
-to a @code{gdb.Value} following the usual rules.
-@end defun
-
-The following code snippet shows how a trivial convenience function can
-be implemented in Python:
-
-@smallexample
-class Greet (gdb.Function):
- """Return string to greet someone.
-Takes a name as argument."""
-
- def __init__ (self):
- super (Greet, self).__init__ ("greet")
-
- def invoke (self, name):
- return "Hello, %s!" % name.string ()
-
-Greet ()
-@end smallexample
-
-The last line instantiates the class, and is necessary to trigger the
-registration of the function with @value{GDBN}. Depending on how the
-Python code is read into @value{GDBN}, you may need to import the
-@code{gdb} module explicitly.
-
-Now you can use the function in an expression:
-
-@smallexample
-(gdb) print $greet("Bob")
-$1 = "Hello, Bob!"
-@end smallexample
-
-@node Progspaces In Python
-@subsubsection Program Spaces In Python
-
-@cindex progspaces in python
-@tindex gdb.Progspace
-@tindex Progspace
-A program space, or @dfn{progspace}, represents a symbolic view
-of an address space.
-It consists of all of the objfiles of the program.
-@xref{Objfiles In Python}.
-@xref{Inferiors and Programs, program spaces}, for more details
-about program spaces.
-
-The following progspace-related functions are available in the
-@code{gdb} module:
-
-@findex gdb.current_progspace
-@defun gdb.current_progspace ()
-This function returns the program space of the currently selected inferior.
-@xref{Inferiors and Programs}.
-@end defun
-
-@findex gdb.progspaces
-@defun gdb.progspaces ()
-Return a sequence of all the progspaces currently known to @value{GDBN}.
-@end defun
-
-Each progspace is represented by an instance of the @code{gdb.Progspace}
-class.
-
-@defvar Progspace.filename
-The file name of the progspace as a string.
-@end defvar
-
-@defvar Progspace.pretty_printers
-The @code{pretty_printers} attribute is a list of functions. It is
-used to look up pretty-printers. A @code{Value} is passed to each
-function in order; if the function returns @code{None}, then the
-search continues. Otherwise, the return value should be an object
-which is used to format the value. @xref{Pretty Printing API}, for more
-information.
-@end defvar
-
-@defvar Progspace.type_printers
-The @code{type_printers} attribute is a list of type printer objects.
-@xref{Type Printing API}, for more information.
-@end defvar
-
-@defvar Progspace.frame_filters
-The @code{frame_filters} attribute is a dictionary of frame filter
-objects. @xref{Frame Filter API}, for more information.
-@end defvar
-
-@node Objfiles In Python
-@subsubsection Objfiles In Python
-
-@cindex objfiles in python
-@tindex gdb.Objfile
-@tindex Objfile
-@value{GDBN} loads symbols for an inferior from various
-symbol-containing files (@pxref{Files}). These include the primary
-executable file, any shared libraries used by the inferior, and any
-separate debug info files (@pxref{Separate Debug Files}).
-@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
-
-The following objfile-related functions are available in the
-@code{gdb} module:
-
-@findex gdb.current_objfile
-@defun gdb.current_objfile ()
-When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
-sets the ``current objfile'' to the corresponding objfile. This
-function returns the current objfile. If there is no current objfile,
-this function returns @code{None}.
-@end defun
-
-@findex gdb.objfiles
-@defun gdb.objfiles ()
-Return a sequence of all the objfiles current known to @value{GDBN}.
-@xref{Objfiles In Python}.
-@end defun
-
-Each objfile is represented by an instance of the @code{gdb.Objfile}
-class.
-
-@defvar Objfile.filename
-The file name of the objfile as a string.
-@end defvar
-
-@defvar Objfile.pretty_printers
-The @code{pretty_printers} attribute is a list of functions. It is
-used to look up pretty-printers. A @code{Value} is passed to each
-function in order; if the function returns @code{None}, then the
-search continues. Otherwise, the return value should be an object
-which is used to format the value. @xref{Pretty Printing API}, for more
-information.
-@end defvar
-
-@defvar Objfile.type_printers
-The @code{type_printers} attribute is a list of type printer objects.
-@xref{Type Printing API}, for more information.
-@end defvar
-
-@defvar Objfile.frame_filters
-The @code{frame_filters} attribute is a dictionary of frame filter
-objects. @xref{Frame Filter API}, for more information.
-@end defvar
-
-A @code{gdb.Objfile} object has the following methods:
-
-@defun Objfile.is_valid ()
-Returns @code{True} if the @code{gdb.Objfile} object is valid,
-@code{False} if not. A @code{gdb.Objfile} object can become invalid
-if the object file it refers to is not loaded in @value{GDBN} any
-longer. All other @code{gdb.Objfile} methods will throw an exception
-if it is invalid at the time the method is called.
-@end defun
-
-@node Frames In Python
-@subsubsection Accessing inferior stack frames from Python.
-
-@cindex frames in python
-When the debugged program stops, @value{GDBN} is able to analyze its call
-stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
-represents a frame in the stack. A @code{gdb.Frame} object is only valid
-while its corresponding frame exists in the inferior's stack. If you try
-to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
-exception (@pxref{Exception Handling}).
-
-Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
-operator, like:
-
-@smallexample
-(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
-True
-@end smallexample
-
-The following frame-related functions are available in the @code{gdb} module:
-
-@findex gdb.selected_frame
-@defun gdb.selected_frame ()
-Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
-@end defun
-
-@findex gdb.newest_frame
-@defun gdb.newest_frame ()
-Return the newest frame object for the selected thread.
-@end defun
-
-@defun gdb.frame_stop_reason_string (reason)
-Return a string explaining the reason why @value{GDBN} stopped unwinding
-frames, as expressed by the given @var{reason} code (an integer, see the
-@code{unwind_stop_reason} method further down in this section).
-@end defun
-
-A @code{gdb.Frame} object has the following methods:
-
-@defun Frame.is_valid ()
-Returns true if the @code{gdb.Frame} object is valid, false if not.
-A frame object can become invalid if the frame it refers to doesn't
-exist anymore in the inferior. All @code{gdb.Frame} methods will throw
-an exception if it is invalid at the time the method is called.
-@end defun
-
-@defun Frame.name ()
-Returns the function name of the frame, or @code{None} if it can't be
-obtained.
-@end defun
-
-@defun Frame.architecture ()
-Returns the @code{gdb.Architecture} object corresponding to the frame's
-architecture. @xref{Architectures In Python}.
-@end defun
-
-@defun Frame.type ()
-Returns the type of the frame. The value can be one of:
-@table @code
-@item gdb.NORMAL_FRAME
-An ordinary stack frame.
-
-@item gdb.DUMMY_FRAME
-A fake stack frame that was created by @value{GDBN} when performing an
-inferior function call.
-
-@item gdb.INLINE_FRAME
-A frame representing an inlined function. The function was inlined
-into a @code{gdb.NORMAL_FRAME} that is older than this one.
-
-@item gdb.TAILCALL_FRAME
-A frame representing a tail call. @xref{Tail Call Frames}.
-
-@item gdb.SIGTRAMP_FRAME
-A signal trampoline frame. This is the frame created by the OS when
-it calls into a signal handler.
-
-@item gdb.ARCH_FRAME
-A fake stack frame representing a cross-architecture call.
-
-@item gdb.SENTINEL_FRAME
-This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
-newest frame.
-@end table
-@end defun
-
-@defun Frame.unwind_stop_reason ()
-Return an integer representing the reason why it's not possible to find
-more frames toward the outermost frame. Use
-@code{gdb.frame_stop_reason_string} to convert the value returned by this
-function to a string. The value can be one of:
-
-@table @code
-@item gdb.FRAME_UNWIND_NO_REASON
-No particular reason (older frames should be available).
-
-@item gdb.FRAME_UNWIND_NULL_ID
-The previous frame's analyzer returns an invalid result. This is no
-longer used by @value{GDBN}, and is kept only for backward
-compatibility.
-
-@item gdb.FRAME_UNWIND_OUTERMOST
-This frame is the outermost.
-
-@item gdb.FRAME_UNWIND_UNAVAILABLE
-Cannot unwind further, because that would require knowing the
-values of registers or memory that have not been collected.
-
-@item gdb.FRAME_UNWIND_INNER_ID
-This frame ID looks like it ought to belong to a NEXT frame,
-but we got it for a PREV frame. Normally, this is a sign of
-unwinder failure. It could also indicate stack corruption.
-
-@item gdb.FRAME_UNWIND_SAME_ID
-This frame has the same ID as the previous one. That means
-that unwinding further would almost certainly give us another
-frame with exactly the same ID, so break the chain. Normally,
-this is a sign of unwinder failure. It could also indicate
-stack corruption.
-
-@item gdb.FRAME_UNWIND_NO_SAVED_PC
-The frame unwinder did not find any saved PC, but we needed
-one to unwind further.
-
-@item gdb.FRAME_UNWIND_FIRST_ERROR
-Any stop reason greater or equal to this value indicates some kind
-of error. This special value facilitates writing code that tests
-for errors in unwinding in a way that will work correctly even if
-the list of the other values is modified in future @value{GDBN}
-versions. Using it, you could write:
-@smallexample
-reason = gdb.selected_frame().unwind_stop_reason ()
-reason_str = gdb.frame_stop_reason_string (reason)
-if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
- print "An error occured: %s" % reason_str
-@end smallexample
-@end table
-
-@end defun
-
-@defun Frame.pc ()
-Returns the frame's resume address.
-@end defun
-
-@defun Frame.block ()
-Return the frame's code block. @xref{Blocks In Python}.
-@end defun
-
-@defun Frame.function ()
-Return the symbol for the function corresponding to this frame.
-@xref{Symbols In Python}.
-@end defun
-
-@defun Frame.older ()
-Return the frame that called this frame.
-@end defun
-
-@defun Frame.newer ()
-Return the frame called by this frame.
-@end defun
-
-@defun Frame.find_sal ()
-Return the frame's symtab and line object.
-@xref{Symbol Tables In Python}.
-@end defun
-
-@defun Frame.read_var (variable @r{[}, block@r{]})
-Return the value of @var{variable} in this frame. If the optional
-argument @var{block} is provided, search for the variable from that
-block; otherwise start at the frame's current block (which is
-determined by the frame's current program counter). @var{variable}
-must be a string or a @code{gdb.Symbol} object. @var{block} must be a
-@code{gdb.Block} object.
-@end defun
-
-@defun Frame.select ()
-Set this frame to be the selected frame. @xref{Stack, ,Examining the
-Stack}.
-@end defun
-
-@node Blocks In Python
-@subsubsection Accessing blocks from Python.
-
-@cindex blocks in python
-@tindex gdb.Block
-
-In @value{GDBN}, symbols are stored in blocks. A block corresponds
-roughly to a scope in the source code. Blocks are organized
-hierarchically, and are represented individually in Python as a
-@code{gdb.Block}. Blocks rely on debugging information being
-available.
-
-A frame has a block. Please see @ref{Frames In Python}, for a more
-in-depth discussion of frames.
-
-The outermost block is known as the @dfn{global block}. The global
-block typically holds public global variables and functions.
-
-The block nested just inside the global block is the @dfn{static
-block}. The static block typically holds file-scoped variables and
-functions.
-
-@value{GDBN} provides a method to get a block's superblock, but there
-is currently no way to examine the sub-blocks of a block, or to
-iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
-Python}).
-
-Here is a short example that should help explain blocks:
-
-@smallexample
-/* This is in the global block. */
-int global;
-
-/* This is in the static block. */
-static int file_scope;
-
-/* 'function' is in the global block, and 'argument' is
- in a block nested inside of 'function'. */
-int function (int argument)
-@{
- /* 'local' is in a block inside 'function'. It may or may
- not be in the same block as 'argument'. */
- int local;
-
- @{
- /* 'inner' is in a block whose superblock is the one holding
- 'local'. */
- int inner;
-
- /* If this call is expanded by the compiler, you may see
- a nested block here whose function is 'inline_function'
- and whose superblock is the one holding 'inner'. */
- inline_function ();
- @}
-@}
-@end smallexample
-
-A @code{gdb.Block} is iterable. The iterator returns the symbols
-(@pxref{Symbols In Python}) local to the block. Python programs
-should not assume that a specific block object will always contain a
-given symbol, since changes in @value{GDBN} features and
-infrastructure may cause symbols move across blocks in a symbol
-table.
-
-The following block-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.block_for_pc
-@defun gdb.block_for_pc (pc)
-Return the innermost @code{gdb.Block} containing the given @var{pc}
-value. If the block cannot be found for the @var{pc} value specified,
-the function will return @code{None}.
-@end defun
-
-A @code{gdb.Block} object has the following methods:
-
-@defun Block.is_valid ()
-Returns @code{True} if the @code{gdb.Block} object is valid,
-@code{False} if not. A block object can become invalid if the block it
-refers to doesn't exist anymore in the inferior. All other
-@code{gdb.Block} methods will throw an exception if it is invalid at
-the time the method is called. The block's validity is also checked
-during iteration over symbols of the block.
-@end defun
-
-A @code{gdb.Block} object has the following attributes:
-
-@defvar Block.start
-The start address of the block. This attribute is not writable.
-@end defvar
-
-@defvar Block.end
-The end address of the block. This attribute is not writable.
-@end defvar
-
-@defvar Block.function
-The name of the block represented as a @code{gdb.Symbol}. If the
-block is not named, then this attribute holds @code{None}. This
-attribute is not writable.
-
-For ordinary function blocks, the superblock is the static block.
-However, you should note that it is possible for a function block to
-have a superblock that is not the static block -- for instance this
-happens for an inlined function.
-@end defvar
-
-@defvar Block.superblock
-The block containing this block. If this parent block does not exist,
-this attribute holds @code{None}. This attribute is not writable.
-@end defvar
-
-@defvar Block.global_block
-The global block associated with this block. This attribute is not
-writable.
-@end defvar
-
-@defvar Block.static_block
-The static block associated with this block. This attribute is not
-writable.
-@end defvar
-
-@defvar Block.is_global
-@code{True} if the @code{gdb.Block} object is a global block,
-@code{False} if not. This attribute is not
-writable.
-@end defvar
-
-@defvar Block.is_static
-@code{True} if the @code{gdb.Block} object is a static block,
-@code{False} if not. This attribute is not writable.
-@end defvar
-
-@node Symbols In Python
-@subsubsection Python representation of Symbols.
-
-@cindex symbols in python
-@tindex gdb.Symbol
-
-@value{GDBN} represents every variable, function and type as an
-entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
-Similarly, Python represents these symbols in @value{GDBN} with the
-@code{gdb.Symbol} object.
-
-The following symbol-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.lookup_symbol
-@defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
-This function searches for a symbol by name. The search scope can be
-restricted to the parameters defined in the optional domain and block
-arguments.
-
-@var{name} is the name of the symbol. It must be a string. The
-optional @var{block} argument restricts the search to symbols visible
-in that @var{block}. The @var{block} argument must be a
-@code{gdb.Block} object. If omitted, the block for the current frame
-is used. The optional @var{domain} argument restricts
-the search to the domain type. The @var{domain} argument must be a
-domain constant defined in the @code{gdb} module and described later
-in this chapter.
-
-The result is a tuple of two elements.
-The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
-is not found.
-If the symbol is found, the second element is @code{True} if the symbol
-is a field of a method's object (e.g., @code{this} in C@t{++}),
-otherwise it is @code{False}.
-If the symbol is not found, the second element is @code{False}.
-@end defun
-
-@findex gdb.lookup_global_symbol
-@defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
-This function searches for a global symbol by name.
-The search scope can be restricted to by the domain argument.
-
-@var{name} is the name of the symbol. It must be a string.
-The optional @var{domain} argument restricts the search to the domain type.
-The @var{domain} argument must be a domain constant defined in the @code{gdb}
-module and described later in this chapter.
-
-The result is a @code{gdb.Symbol} object or @code{None} if the symbol
-is not found.
-@end defun
-
-A @code{gdb.Symbol} object has the following attributes:
-
-@defvar Symbol.type
-The type of the symbol or @code{None} if no type is recorded.
-This attribute is represented as a @code{gdb.Type} object.
-@xref{Types In Python}. This attribute is not writable.
-@end defvar
-
-@defvar Symbol.symtab
-The symbol table in which the symbol appears. This attribute is
-represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
-Python}. This attribute is not writable.
-@end defvar
-
-@defvar Symbol.line
-The line number in the source code at which the symbol was defined.
-This is an integer.
-@end defvar
-
-@defvar Symbol.name
-The name of the symbol as a string. This attribute is not writable.
-@end defvar
-
-@defvar Symbol.linkage_name
-The name of the symbol, as used by the linker (i.e., may be mangled).
-This attribute is not writable.
-@end defvar
-
-@defvar Symbol.print_name
-The name of the symbol in a form suitable for output. This is either
-@code{name} or @code{linkage_name}, depending on whether the user
-asked @value{GDBN} to display demangled or mangled names.
-@end defvar
-
-@defvar Symbol.addr_class
-The address class of the symbol. This classifies how to find the value
-of a symbol. Each address class is a constant defined in the
-@code{gdb} module and described later in this chapter.
-@end defvar
-
-@defvar Symbol.needs_frame
-This is @code{True} if evaluating this symbol's value requires a frame
-(@pxref{Frames In Python}) and @code{False} otherwise. Typically,
-local variables will require a frame, but other symbols will not.
-@end defvar
-
-@defvar Symbol.is_argument
-@code{True} if the symbol is an argument of a function.
-@end defvar
-
-@defvar Symbol.is_constant
-@code{True} if the symbol is a constant.
-@end defvar
-
-@defvar Symbol.is_function
-@code{True} if the symbol is a function or a method.
-@end defvar
-
-@defvar Symbol.is_variable
-@code{True} if the symbol is a variable.
-@end defvar
-
-A @code{gdb.Symbol} object has the following methods:
-
-@defun Symbol.is_valid ()
-Returns @code{True} if the @code{gdb.Symbol} object is valid,
-@code{False} if not. A @code{gdb.Symbol} object can become invalid if
-the symbol it refers to does not exist in @value{GDBN} any longer.
-All other @code{gdb.Symbol} methods will throw an exception if it is
-invalid at the time the method is called.
-@end defun
-
-@defun Symbol.value (@r{[}frame@r{]})
-Compute the value of the symbol, as a @code{gdb.Value}. For
-functions, this computes the address of the function, cast to the
-appropriate type. If the symbol requires a frame in order to compute
-its value, then @var{frame} must be given. If @var{frame} is not
-given, or if @var{frame} is invalid, then this method will throw an
-exception.
-@end defun
-
-The available domain categories in @code{gdb.Symbol} are represented
-as constants in the @code{gdb} module:
-
-@table @code
-@findex SYMBOL_UNDEF_DOMAIN
-@findex gdb.SYMBOL_UNDEF_DOMAIN
-@item gdb.SYMBOL_UNDEF_DOMAIN
-This is used when a domain has not been discovered or none of the
-following domains apply. This usually indicates an error either
-in the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_VAR_DOMAIN
-@findex gdb.SYMBOL_VAR_DOMAIN
-@item gdb.SYMBOL_VAR_DOMAIN
-This domain contains variables, function names, typedef names and enum
-type values.
-@findex SYMBOL_STRUCT_DOMAIN
-@findex gdb.SYMBOL_STRUCT_DOMAIN
-@item gdb.SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
-@findex SYMBOL_LABEL_DOMAIN
-@findex gdb.SYMBOL_LABEL_DOMAIN
-@item gdb.SYMBOL_LABEL_DOMAIN
-This domain contains names of labels (for gotos).
-@findex SYMBOL_VARIABLES_DOMAIN
-@findex gdb.SYMBOL_VARIABLES_DOMAIN
-@item gdb.SYMBOL_VARIABLES_DOMAIN
-This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
-contains everything minus functions and types.
-@findex SYMBOL_FUNCTIONS_DOMAIN
-@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
-@item gdb.SYMBOL_FUNCTION_DOMAIN
-This domain contains all functions.
-@findex SYMBOL_TYPES_DOMAIN
-@findex gdb.SYMBOL_TYPES_DOMAIN
-@item gdb.SYMBOL_TYPES_DOMAIN
-This domain contains all types.
-@end table
-
-The available address class categories in @code{gdb.Symbol} are represented
-as constants in the @code{gdb} module:
-
-@table @code
-@findex SYMBOL_LOC_UNDEF
-@findex gdb.SYMBOL_LOC_UNDEF
-@item gdb.SYMBOL_LOC_UNDEF
-If this is returned by address class, it indicates an error either in
-the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_LOC_CONST
-@findex gdb.SYMBOL_LOC_CONST
-@item gdb.SYMBOL_LOC_CONST
-Value is constant int.
-@findex SYMBOL_LOC_STATIC
-@findex gdb.SYMBOL_LOC_STATIC
-@item gdb.SYMBOL_LOC_STATIC
-Value is at a fixed address.
-@findex SYMBOL_LOC_REGISTER
-@findex gdb.SYMBOL_LOC_REGISTER
-@item gdb.SYMBOL_LOC_REGISTER
-Value is in a register.
-@findex SYMBOL_LOC_ARG
-@findex gdb.SYMBOL_LOC_ARG
-@item gdb.SYMBOL_LOC_ARG
-Value is an argument. This value is at the offset stored within the
-symbol inside the frame's argument list.
-@findex SYMBOL_LOC_REF_ARG
-@findex gdb.SYMBOL_LOC_REF_ARG
-@item gdb.SYMBOL_LOC_REF_ARG
-Value address is stored in the frame's argument list. Just like
-@code{LOC_ARG} except that the value's address is stored at the
-offset, not the value itself.
-@findex SYMBOL_LOC_REGPARM_ADDR
-@findex gdb.SYMBOL_LOC_REGPARM_ADDR
-@item gdb.SYMBOL_LOC_REGPARM_ADDR
-Value is a specified register. Just like @code{LOC_REGISTER} except
-the register holds the address of the argument instead of the argument
-itself.
-@findex SYMBOL_LOC_LOCAL
-@findex gdb.SYMBOL_LOC_LOCAL
-@item gdb.SYMBOL_LOC_LOCAL
-Value is a local variable.
-@findex SYMBOL_LOC_TYPEDEF
-@findex gdb.SYMBOL_LOC_TYPEDEF
-@item gdb.SYMBOL_LOC_TYPEDEF
-Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
-have this class.
-@findex SYMBOL_LOC_BLOCK
-@findex gdb.SYMBOL_LOC_BLOCK
-@item gdb.SYMBOL_LOC_BLOCK
-Value is a block.
-@findex SYMBOL_LOC_CONST_BYTES
-@findex gdb.SYMBOL_LOC_CONST_BYTES
-@item gdb.SYMBOL_LOC_CONST_BYTES
-Value is a byte-sequence.
-@findex SYMBOL_LOC_UNRESOLVED
-@findex gdb.SYMBOL_LOC_UNRESOLVED
-@item gdb.SYMBOL_LOC_UNRESOLVED
-Value is at a fixed address, but the address of the variable has to be
-determined from the minimal symbol table whenever the variable is
-referenced.
-@findex SYMBOL_LOC_OPTIMIZED_OUT
-@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
-@item gdb.SYMBOL_LOC_OPTIMIZED_OUT
-The value does not actually exist in the program.
-@findex SYMBOL_LOC_COMPUTED
-@findex gdb.SYMBOL_LOC_COMPUTED
-@item gdb.SYMBOL_LOC_COMPUTED
-The value's address is a computed location.
-@end table
-
-@node Symbol Tables In Python
-@subsubsection Symbol table representation in Python.
-
-@cindex symbol tables in python
-@tindex gdb.Symtab
-@tindex gdb.Symtab_and_line
-
-Access to symbol table data maintained by @value{GDBN} on the inferior
-is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
-@code{gdb.Symtab}. Symbol table and line data for a frame is returned
-from the @code{find_sal} method in @code{gdb.Frame} object.
-@xref{Frames In Python}.
-
-For more information on @value{GDBN}'s symbol table management, see
-@ref{Symbols, ,Examining the Symbol Table}, for more information.
-
-A @code{gdb.Symtab_and_line} object has the following attributes:
-
-@defvar Symtab_and_line.symtab
-The symbol table object (@code{gdb.Symtab}) for this frame.
-This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.pc
-Indicates the start of the address range occupied by code for the
-current source line. This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.last
-Indicates the end of the address range occupied by code for the current
-source line. This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.line
-Indicates the current line number for this object. This
-attribute is not writable.
-@end defvar
-
-A @code{gdb.Symtab_and_line} object has the following methods:
-
-@defun Symtab_and_line.is_valid ()
-Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
-@code{False} if not. A @code{gdb.Symtab_and_line} object can become
-invalid if the Symbol table and line object it refers to does not
-exist in @value{GDBN} any longer. All other
-@code{gdb.Symtab_and_line} methods will throw an exception if it is
-invalid at the time the method is called.
-@end defun
-
-A @code{gdb.Symtab} object has the following attributes:
-
-@defvar Symtab.filename
-The symbol table's source filename. This attribute is not writable.
-@end defvar
-
-@defvar Symtab.objfile
-The symbol table's backing object file. @xref{Objfiles In Python}.
-This attribute is not writable.
-@end defvar
-
-A @code{gdb.Symtab} object has the following methods:
-
-@defun Symtab.is_valid ()
-Returns @code{True} if the @code{gdb.Symtab} object is valid,
-@code{False} if not. A @code{gdb.Symtab} object can become invalid if
-the symbol table it refers to does not exist in @value{GDBN} any
-longer. All other @code{gdb.Symtab} methods will throw an exception
-if it is invalid at the time the method is called.
-@end defun
-
-@defun Symtab.fullname ()
-Return the symbol table's source absolute file name.
-@end defun
-
-@defun Symtab.global_block ()
-Return the global block of the underlying symbol table.
-@xref{Blocks In Python}.
-@end defun
-
-@defun Symtab.static_block ()
-Return the static block of the underlying symbol table.
-@xref{Blocks In Python}.
-@end defun
-
-@defun Symtab.linetable ()
-Return the line table associated with the symbol table.
-@xref{Line Tables In Python}.
-@end defun
-
-@node Line Tables In Python
-@subsubsection Manipulating line tables using Python
-
-@cindex line tables in python
-@tindex gdb.LineTable
-
-Python code can request and inspect line table information from a
-symbol table that is loaded in @value{GDBN}. A line table is a
-mapping of source lines to their executable locations in memory. To
-acquire the line table information for a particular symbol table, use
-the @code{linetable} function (@pxref{Symbol Tables In Python}).
-
-A @code{gdb.LineTable} is iterable. The iterator returns
-@code{LineTableEntry} objects that correspond to the source line and
-address for each line table entry. @code{LineTableEntry} objects have
-the following attributes:
-
-@defvar LineTableEntry.line
-The source line number for this line table entry. This number
-corresponds to the actual line of source. This attribute is not
-writable.
-@end defvar
-
-@defvar LineTableEntry.pc
-The address that is associated with the line table entry where the
-executable code for that source line resides in memory. This
-attribute is not writable.
-@end defvar
-
-As there can be multiple addresses for a single source line, you may
-receive multiple @code{LineTableEntry} objects with matching
-@code{line} attributes, but with different @code{pc} attributes. The
-iterator is sorted in ascending @code{pc} order. Here is a small
-example illustrating iterating over a line table.
-
-@smallexample
-symtab = gdb.selected_frame().find_sal().symtab
-linetable = symtab.linetable()
-for line in linetable:
- print "Line: "+str(line.line)+" Address: "+hex(line.pc)
-@end smallexample
-
-This will have the following output:
-
-@smallexample
-Line: 33 Address: 0x4005c8L
-Line: 37 Address: 0x4005caL
-Line: 39 Address: 0x4005d2L
-Line: 40 Address: 0x4005f8L
-Line: 42 Address: 0x4005ffL
-Line: 44 Address: 0x400608L
-Line: 42 Address: 0x40060cL
-Line: 45 Address: 0x400615L
-@end smallexample
-
-In addition to being able to iterate over a @code{LineTable}, it also
-has the following direct access methods:
-
-@defun LineTable.line (line)
-Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
-entries in the line table for the given @var{line}. @var{line} refers
-to the source code line. If there are no entries for that source code
-@var{line}, the Python @code{None} is returned.
-@end defun
-
-@defun LineTable.has_line (line)
-Return a Python @code{Boolean} indicating whether there is an entry in
-the line table for this source line. Return @code{True} if an entry
-is found, or @code{False} if not.
-@end defun
-
-@defun LineTable.source_lines ()
-Return a Python @code{List} of the source line numbers in the symbol
-table. Only lines with executable code locations are returned. The
-contents of the @code{List} will just be the source line entries
-represented as Python @code{Long} values.
-@end defun
-
-@node Breakpoints In Python
-@subsubsection Manipulating breakpoints using Python
-
-@cindex breakpoints in python
-@tindex gdb.Breakpoint
-
-Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
-class.
-
-@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
-Create a new breakpoint. @var{spec} is a string naming the location
-of the breakpoint, or an expression that defines a watchpoint. The
-contents can be any location recognized by the @code{break} command,
-or in the case of a watchpoint, by the @code{watch} command. The
-optional @var{type} denotes the breakpoint to create from the types
-defined later in this chapter. This argument can be either:
-@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
-defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
-argument allows the breakpoint to become invisible to the user. The
-breakpoint will neither be reported when created, nor will it be
-listed in the output from @code{info breakpoints} (but will be listed
-with the @code{maint info breakpoints} command). The optional
-@var{temporary} argument makes the breakpoint a temporary breakpoint.
-Temporary breakpoints are deleted after they have been hit. Any
-further access to the Python breakpoint after it has been hit will
-result in a runtime error (as that breakpoint has now been
-automatically deleted). The optional @var{wp_class} argument defines
-the class of watchpoint to create, if @var{type} is
-@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
-is assumed to be a @code{gdb.WP_WRITE} class.
-@end defun
-
-@defun Breakpoint.stop (self)
-The @code{gdb.Breakpoint} class can be sub-classed and, in
-particular, you may choose to implement the @code{stop} method.
-If this method is defined in a sub-class of @code{gdb.Breakpoint},
-it will be called when the inferior reaches any location of a
-breakpoint which instantiates that sub-class. If the method returns
-@code{True}, the inferior will be stopped at the location of the
-breakpoint, otherwise the inferior will continue.
-
-If there are multiple breakpoints at the same location with a
-@code{stop} method, each one will be called regardless of the
-return status of the previous. This ensures that all @code{stop}
-methods have a chance to execute at that location. In this scenario
-if one of the methods returns @code{True} but the others return
-@code{False}, the inferior will still be stopped.
-
-You should not alter the execution state of the inferior (i.e.@:, step,
-next, etc.), alter the current frame context (i.e.@:, change the current
-active frame), or alter, add or delete any breakpoint. As a general
-rule, you should not alter any data within @value{GDBN} or the inferior
-at this time.
-
-Example @code{stop} implementation:
-
-@smallexample
-class MyBreakpoint (gdb.Breakpoint):
- def stop (self):
- inf_val = gdb.parse_and_eval("foo")
- if inf_val == 3:
- return True
- return False
-@end smallexample
-@end defun
-
-The available watchpoint types represented by constants are defined in the
-@code{gdb} module:
-
-@table @code
-@findex WP_READ
-@findex gdb.WP_READ
-@item gdb.WP_READ
-Read only watchpoint.
-
-@findex WP_WRITE
-@findex gdb.WP_WRITE
-@item gdb.WP_WRITE
-Write only watchpoint.
-
-@findex WP_ACCESS
-@findex gdb.WP_ACCESS
-@item gdb.WP_ACCESS
-Read/Write watchpoint.
-@end table
-
-@defun Breakpoint.is_valid ()
-Return @code{True} if this @code{Breakpoint} object is valid,
-@code{False} otherwise. A @code{Breakpoint} object can become invalid
-if the user deletes the breakpoint. In this case, the object still
-exists, but the underlying breakpoint does not. In the cases of
-watchpoint scope, the watchpoint remains valid even if execution of the
-inferior leaves the scope of that watchpoint.
-@end defun
-
-@defun Breakpoint.delete
-Permanently deletes the @value{GDBN} breakpoint. This also
-invalidates the Python @code{Breakpoint} object. Any further access
-to this object's attributes or methods will raise an error.
-@end defun
-
-@defvar Breakpoint.enabled
-This attribute is @code{True} if the breakpoint is enabled, and
-@code{False} otherwise. This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.silent
-This attribute is @code{True} if the breakpoint is silent, and
-@code{False} otherwise. This attribute is writable.
-
-Note that a breakpoint can also be silent if it has commands and the
-first command is @code{silent}. This is not reported by the
-@code{silent} attribute.
-@end defvar
-
-@defvar Breakpoint.thread
-If the breakpoint is thread-specific, this attribute holds the thread
-id. If the breakpoint is not thread-specific, this attribute is
-@code{None}. This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.task
-If the breakpoint is Ada task-specific, this attribute holds the Ada task
-id. If the breakpoint is not task-specific (or the underlying
-language is not Ada), this attribute is @code{None}. This attribute
-is writable.
-@end defvar
-
-@defvar Breakpoint.ignore_count
-This attribute holds the ignore count for the breakpoint, an integer.
-This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.number
-This attribute holds the breakpoint's number --- the identifier used by
-the user to manipulate the breakpoint. This attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.type
-This attribute holds the breakpoint's type --- the identifier used to
-determine the actual breakpoint type or use-case. This attribute is not
-writable.
-@end defvar
-
-@defvar Breakpoint.visible
-This attribute tells whether the breakpoint is visible to the user
-when set, or when the @samp{info breakpoints} command is run. This
-attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.temporary
-This attribute indicates whether the breakpoint was created as a
-temporary breakpoint. Temporary breakpoints are automatically deleted
-after that breakpoint has been hit. Access to this attribute, and all
-other attributes and functions other than the @code{is_valid}
-function, will result in an error after the breakpoint has been hit
-(as it has been automatically deleted). This attribute is not
-writable.
-@end defvar
-
-The available types are represented by constants defined in the @code{gdb}
-module:
-
-@table @code
-@findex BP_BREAKPOINT
-@findex gdb.BP_BREAKPOINT
-@item gdb.BP_BREAKPOINT
-Normal code breakpoint.
-
-@findex BP_WATCHPOINT
-@findex gdb.BP_WATCHPOINT
-@item gdb.BP_WATCHPOINT
-Watchpoint breakpoint.
-
-@findex BP_HARDWARE_WATCHPOINT
-@findex gdb.BP_HARDWARE_WATCHPOINT
-@item gdb.BP_HARDWARE_WATCHPOINT
-Hardware assisted watchpoint.
-
-@findex BP_READ_WATCHPOINT
-@findex gdb.BP_READ_WATCHPOINT
-@item gdb.BP_READ_WATCHPOINT
-Hardware assisted read watchpoint.
-
-@findex BP_ACCESS_WATCHPOINT
-@findex gdb.BP_ACCESS_WATCHPOINT
-@item gdb.BP_ACCESS_WATCHPOINT
-Hardware assisted access watchpoint.
-@end table
-
-@defvar Breakpoint.hit_count
-This attribute holds the hit count for the breakpoint, an integer.
-This attribute is writable, but currently it can only be set to zero.
-@end defvar
-
-@defvar Breakpoint.location
-This attribute holds the location of the breakpoint, as specified by
-the user. It is a string. If the breakpoint does not have a location
-(that is, it is a watchpoint) the attribute's value is @code{None}. This
-attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.expression
-This attribute holds a breakpoint expression, as specified by
-the user. It is a string. If the breakpoint does not have an
-expression (the breakpoint is not a watchpoint) the attribute's value
-is @code{None}. This attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.condition
-This attribute holds the condition of the breakpoint, as specified by
-the user. It is a string. If there is no condition, this attribute's
-value is @code{None}. This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.commands
-This attribute holds the commands attached to the breakpoint. If
-there are commands, this attribute's value is a string holding all the
-commands, separated by newlines. If there are no commands, this
-attribute is @code{None}. This attribute is not writable.
-@end defvar
-
-@node Finish Breakpoints in Python
-@subsubsection Finish Breakpoints
-
-@cindex python finish breakpoints
-@tindex gdb.FinishBreakpoint
-
-A finish breakpoint is a temporary breakpoint set at the return address of
-a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
-extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
-and deleted when the execution will run out of the breakpoint scope (i.e.@:
-@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
-Finish breakpoints are thread specific and must be create with the right
-thread selected.
-
-@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
-Create a finish breakpoint at the return address of the @code{gdb.Frame}
-object @var{frame}. If @var{frame} is not provided, this defaults to the
-newest frame. The optional @var{internal} argument allows the breakpoint to
-become invisible to the user. @xref{Breakpoints In Python}, for further
-details about this argument.
-@end defun
-
-@defun FinishBreakpoint.out_of_scope (self)
-In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
-@code{return} command, @dots{}), a function may not properly terminate, and
-thus never hit the finish breakpoint. When @value{GDBN} notices such a
-situation, the @code{out_of_scope} callback will be triggered.
-
-You may want to sub-class @code{gdb.FinishBreakpoint} and override this
-method:
-
-@smallexample
-class MyFinishBreakpoint (gdb.FinishBreakpoint)
- def stop (self):
- print "normal finish"
- return True
-
- def out_of_scope ():
- print "abnormal finish"
-@end smallexample
-@end defun
-
-@defvar FinishBreakpoint.return_value
-When @value{GDBN} is stopped at a finish breakpoint and the frame
-used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
-attribute will contain a @code{gdb.Value} object corresponding to the return
-value of the function. The value will be @code{None} if the function return
-type is @code{void} or if the return value was not computable. This attribute
-is not writable.
-@end defvar
-
-@node Lazy Strings In Python
-@subsubsection Python representation of lazy strings.
-
-@cindex lazy strings in python
-@tindex gdb.LazyString
-
-A @dfn{lazy string} is a string whose contents is not retrieved or
-encoded until it is needed.
-
-A @code{gdb.LazyString} is represented in @value{GDBN} as an
-@code{address} that points to a region of memory, an @code{encoding}
-that will be used to encode that region of memory, and a @code{length}
-to delimit the region of memory that represents the string. The
-difference between a @code{gdb.LazyString} and a string wrapped within
-a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
-differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
-retrieved and encoded during printing, while a @code{gdb.Value}
-wrapping a string is immediately retrieved and encoded on creation.
-
-A @code{gdb.LazyString} object has the following functions:
-
-@defun LazyString.value ()
-Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
-will point to the string in memory, but will lose all the delayed
-retrieval, encoding and handling that @value{GDBN} applies to a
-@code{gdb.LazyString}.
-@end defun
-
-@defvar LazyString.address
-This attribute holds the address of the string. This attribute is not
-writable.
-@end defvar
-
-@defvar LazyString.length
-This attribute holds the length of the string in characters. If the
-length is -1, then the string will be fetched and encoded up to the
-first null of appropriate width. This attribute is not writable.
-@end defvar
-
-@defvar LazyString.encoding
-This attribute holds the encoding that will be applied to the string
-when the string is printed by @value{GDBN}. If the encoding is not
-set, or contains an empty string, then @value{GDBN} will select the
-most appropriate encoding when the string is printed. This attribute
-is not writable.
-@end defvar
-
-@defvar LazyString.type
-This attribute holds the type that is represented by the lazy string's
-type. For a lazy string this will always be a pointer type. To
-resolve this to the lazy string's character type, use the type's
-@code{target} method. @xref{Types In Python}. This attribute is not
-writable.
-@end defvar
-
-@node Architectures In Python
-@subsubsection Python representation of architectures
-@cindex Python architectures
-
-@value{GDBN} uses architecture specific parameters and artifacts in a
-number of its various computations. An architecture is represented
-by an instance of the @code{gdb.Architecture} class.
-
-A @code{gdb.Architecture} class has the following methods:
-
-@defun Architecture.name ()
-Return the name (string value) of the architecture.
-@end defun
-
-@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
-Return a list of disassembled instructions starting from the memory
-address @var{start_pc}. The optional arguments @var{end_pc} and
-@var{count} determine the number of instructions in the returned list.
-If both the optional arguments @var{end_pc} and @var{count} are
-specified, then a list of at most @var{count} disassembled instructions
-whose start address falls in the closed memory address interval from
-@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
-specified, but @var{count} is specified, then @var{count} number of
-instructions starting from the address @var{start_pc} are returned. If
-@var{count} is not specified but @var{end_pc} is specified, then all
-instructions whose start address falls in the closed memory address
-interval from @var{start_pc} to @var{end_pc} are returned. If neither
-@var{end_pc} nor @var{count} are specified, then a single instruction at
-@var{start_pc} is returned. For all of these cases, each element of the
-returned list is a Python @code{dict} with the following string keys:
-
-@table @code
-
-@item addr
-The value corresponding to this key is a Python long integer capturing
-the memory address of the instruction.
-
-@item asm
-The value corresponding to this key is a string value which represents
-the instruction with assembly language mnemonics. The assembly
-language flavor used is the same as that specified by the current CLI
-variable @code{disassembly-flavor}. @xref{Machine Code}.
-
-@item length
-The value corresponding to this key is the length (integer value) of the
-instruction in bytes.
-
-@end table
-@end defun
-
-@node Python Auto-loading
-@subsection Python Auto-loading
-@cindex Python auto-loading
-
-When a new object file is read (for example, due to the @code{file}
-command, or because the inferior has loaded a shared library),
-@value{GDBN} will look for Python support scripts in several ways:
-@file{@var{objfile}-gdb.py} (@pxref{objfile-gdb.py file})
-and @code{.debug_gdb_scripts} section
-(@pxref{dotdebug_gdb_scripts section}).
-
The auto-loading feature is useful for supplying application-specific
-debugging commands and scripts.
+debugging commands and features.
Auto-loading can be enabled or disabled,
and the list of auto-loaded scripts can be printed.
+See the @samp{auto-loading} section of each extension language
+for more information.
+For @value{GDBN} command files see @ref{Auto-loading sequences}.
+For Python files see @ref{Python Auto-loading}.
-@table @code
-@anchor{set auto-load python-scripts}
-@kindex set auto-load python-scripts
-@item set auto-load python-scripts [on|off]
-Enable or disable the auto-loading of Python scripts.
-
-@anchor{show auto-load python-scripts}
-@kindex show auto-load python-scripts
-@item show auto-load python-scripts
-Show whether auto-loading of Python scripts is enabled or disabled.
-
-@anchor{info auto-load python-scripts}
-@kindex info auto-load python-scripts
-@cindex print list of auto-loaded Python scripts
-@item info auto-load python-scripts [@var{regexp}]
-Print the list of all Python scripts that @value{GDBN} auto-loaded.
-
-Also printed is the list of Python scripts that were mentioned in
-the @code{.debug_gdb_scripts} section and were not found
-(@pxref{dotdebug_gdb_scripts section}).
-This is useful because their names are not printed when @value{GDBN}
-tries to load them and fails. There may be many of them, and printing
-an error message for each one is problematic.
+Note that loading of this script file also requires accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-If @var{regexp} is supplied only Python scripts with matching names are printed.
+@node objfile-gdbdotext file
+@subsection The @file{@var{objfile}-gdb.@var{ext}} file
+@cindex @file{@var{objfile}-gdb.gdb}
+@cindex @file{@var{objfile}-gdb.py}
+@cindex @file{@var{objfile}-gdb.scm}
-Example:
+When a new object file is read, @value{GDBN} looks for a file named
+@file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below),
+where @var{objfile} is the object file's name and
+where @var{ext} is the file extension for the extension language:
-@smallexample
-(gdb) info auto-load python-scripts
-Loaded Script
-Yes py-section-script.py
- full name: /tmp/py-section-script.py
-No my-foo-pretty-printers.py
-@end smallexample
+@table @code
+@item @file{@var{objfile}-gdb.gdb}
+GDB's own command language
+@item @file{@var{objfile}-gdb.py}
+Python
+@item @file{@var{objfile}-gdb.scm}
+Guile
@end table
-When reading an auto-loaded file, @value{GDBN} sets the
-@dfn{current objfile}. This is available via the @code{gdb.current_objfile}
-function (@pxref{Objfiles In Python}). This can be useful for
-registering objfile-specific pretty-printers and frame-filters.
-
-@menu
-* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
-* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
-* Which flavor to choose?::
-@end menu
-
-@node objfile-gdb.py file
-@subsubsection The @file{@var{objfile}-gdb.py} file
-@cindex @file{@var{objfile}-gdb.py}
-
-When a new object file is read, @value{GDBN} looks for
-a file named @file{@var{objfile}-gdb.py} (we call it @var{script-name} below),
-where @var{objfile} is the object file's real name, formed by ensuring
-that the file name is absolute, following all symlinks, and resolving
-@code{.} and @code{..} components. If this file exists and is
-readable, @value{GDBN} will evaluate it as a Python script.
+@var{script-name} is formed by ensuring that the file name of @var{objfile}
+is absolute, following all symlinks, and resolving @code{.} and @code{..}
+components, and appending the @file{-gdb.@var{ext}} suffix.
+If this file exists and is readable, @value{GDBN} will evaluate it as a
+script in the specified extension language.
If this file does not exist, then @value{GDBN} will look for
@var{script-name} file in all of the directories as specified below.
-Note that loading of this script file also requires accordingly configured
+Note that loading of these files requires an accordingly configured
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
For object files using @file{.exe} suffix @value{GDBN} tries to load first the
@kindex show auto-load scripts-directory
@item show auto-load scripts-directory
Show @value{GDBN} auto-loaded scripts location.
+
+@anchor{add-auto-load-scripts-directory}
+@kindex add-auto-load-scripts-directory
+@item add-auto-load-scripts-directory @r{[}@var{directories}@dots{}@r{]}
+Add an entry (or list of entries) to the list of auto-loaded scripts locations.
+Multiple entries may be delimited by the host platform path separator in use.
@end table
@value{GDBN} does not track which files it has already auto-loaded this way.
@value{GDBN} will load the associated script every time the corresponding
@var{objfile} is opened.
-So your @file{-gdb.py} file should be careful to avoid errors if it
+So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it
is evaluated more than once.
@node dotdebug_gdb_scripts section
-@subsubsection The @code{.debug_gdb_scripts} section
+@subsection The @code{.debug_gdb_scripts} section
@cindex @code{.debug_gdb_scripts} section
For systems using file formats like ELF and COFF,
when @value{GDBN} loads a new object file
-it will look for a special section named @samp{.debug_gdb_scripts}.
-If this section exists, its contents is a list of names of scripts to load.
+it will look for a special section named @code{.debug_gdb_scripts}.
+If this section exists, its contents is a list of null-terminated entries
+specifying scripts to load. Each entry begins with a non-null prefix byte that
+specifies the kind of entry, typically the extension language and whether the
+script is in a file or inlined in @code{.debug_gdb_scripts}.
+
+The following entries are supported:
+
+@table @code
+@item SECTION_SCRIPT_ID_PYTHON_FILE = 1
+@item SECTION_SCRIPT_ID_SCHEME_FILE = 3
+@item SECTION_SCRIPT_ID_PYTHON_TEXT = 4
+@item SECTION_SCRIPT_ID_SCHEME_TEXT = 6
+@end table
+
+@subsubsection Script File Entries
-@value{GDBN} will look for each specified script file first in the
-current directory and then along the source search path
+If the entry specifies a file, @value{GDBN} will look for the file first
+in the current directory and then along the source search path
(@pxref{Source Path, ,Specifying Source Directories}),
except that @file{$cdir} is not searched, since the compilation
directory is not relevant to scripts.
-Entries can be placed in section @code{.debug_gdb_scripts} with,
-for example, this GCC macro:
+File entries can be placed in section @code{.debug_gdb_scripts} with,
+for example, this GCC macro for Python scripts.
@example
/* Note: The "MS" section flags are to remove duplicates. */
-#define DEFINE_GDB_SCRIPT(script_name) \
+#define DEFINE_GDB_PY_SCRIPT(script_name) \
asm("\
.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
-.byte 1\n\
+.byte 1 /* Python */\n\
.asciz \"" script_name "\"\n\
.popsection \n\
");
@end example
@noindent
+For Guile scripts, replace @code{.byte 1} with @code{.byte 3}.
Then one can reference the macro in a header or source file like this:
@example
-DEFINE_GDB_SCRIPT ("my-app-scripts.py")
+DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py")
@end example
The script name may include directories if desired.
Note that loading of this script file also requires accordingly configured
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-If the macro is put in a header, any application or library
-using this header will get a reference to the specified script.
+If the macro invocation is put in a header, any application or library
+using this header will get a reference to the specified script,
+and with the use of @code{"MS"} attributes on the section, the linker
+will remove duplicates.
+
+@subsubsection Script Text Entries
+
+Script text entries allow to put the executable script in the entry
+itself instead of loading it from a file.
+The first line of the entry, everything after the prefix byte and up to
+the first newline (@code{0xa}) character, is the script name, and must not
+contain any kind of space character, e.g., spaces or tabs.
+The rest of the entry, up to the trailing null byte, is the script to
+execute in the specified language. The name needs to be unique among
+all script names, as @value{GDBN} executes each script only once based
+on its name.
+
+Here is an example from file @file{py-section-script.c} in the @value{GDBN}
+testsuite.
+
+@example
+#include "symcat.h"
+#include "gdb/section-scripts.h"
+asm(
+".pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n"
+".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n"
+".ascii \"gdb.inlined-script\\n\"\n"
+".ascii \"class test_cmd (gdb.Command):\\n\"\n"
+".ascii \" def __init__ (self):\\n\"\n"
+".ascii \" super (test_cmd, self).__init__ ("
+ "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n"
+".ascii \" def invoke (self, arg, from_tty):\\n\"\n"
+".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n"
+".ascii \"test_cmd ()\\n\"\n"
+".byte 0\n"
+".popsection\n"
+);
+@end example
+
+Loading of inlined scripts requires a properly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+The path to specify in @code{auto-load safe-path} is the path of the file
+containing the @code{.debug_gdb_scripts} section.
@node Which flavor to choose?
-@subsubsection Which flavor to choose?
+@subsection Which flavor to choose?
-Given the multiple ways of auto-loading Python scripts, it might not always
+Given the multiple ways of auto-loading extensions, it might not always
be clear which one to choose. This section provides some guidance.
-Benefits of the @file{-gdb.py} way:
+@noindent
+Benefits of the @file{-gdb.@var{ext}} way:
@itemize @bullet
@item
Doesn't require source code additions.
@end itemize
+@noindent
Benefits of the @code{.debug_gdb_scripts} way:
@itemize @bullet
@item
Works with static linking.
-Scripts for libraries done the @file{-gdb.py} way require an objfile to
+Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to
trigger their loading. When an application is statically linked the only
objfile available is the executable, and it is cumbersome to attach all the
-scripts from all the input libraries to the executable's @file{-gdb.py} script.
+scripts from all the input libraries to the executable's
+@file{-gdb.@var{ext}} script.
@item
Works with classes that are entirely inlined.
Some classes can be entirely inlined, and thus there may not be an associated
-shared library to attach a @file{-gdb.py} script to.
+shared library to attach a @file{-gdb.@var{ext}} script to.
@item
Scripts needn't be copied out of the source tree.
In some circumstances, apps can be built out of large collections of internal
libraries, and the build infrastructure necessary to install the
-@file{-gdb.py} scripts in a place where @value{GDBN} can find them is
+@file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is
cumbersome. It may be easier to specify the scripts in the
@code{.debug_gdb_scripts} section as relative paths, and add a path to the
top of the source tree to the source search path.
@end itemize
-@node Python modules
-@subsection Python modules
-@cindex python modules
-
-@value{GDBN} comes with several modules to assist writing Python code.
-
-@menu
-* gdb.printing:: Building and registering pretty-printers.
-* gdb.types:: Utilities for working with types.
-* gdb.prompt:: Utilities for prompt value substitution.
-@end menu
-
-@node gdb.printing
-@subsubsection gdb.printing
-@cindex gdb.printing
+@node Multiple Extension Languages
+@section Multiple Extension Languages
-This module provides a collection of utilities for working with
-pretty-printers.
-
-@table @code
-@item PrettyPrinter (@var{name}, @var{subprinters}=None)
-This class specifies the API that makes @samp{info pretty-printer},
-@samp{enable pretty-printer} and @samp{disable pretty-printer} work.
-Pretty-printers should generally inherit from this class.
+The Guile and Python extension languages do not share any state,
+and generally do not interfere with each other.
+There are some things to be aware of, however.
-@item SubPrettyPrinter (@var{name})
-For printers that handle multiple types, this class specifies the
-corresponding API for the subprinters.
+@subsection Python comes first
-@item RegexpCollectionPrettyPrinter (@var{name})
-Utility class for handling multiple printers, all recognized via
-regular expressions.
-@xref{Writing a Pretty-Printer}, for an example.
-
-@item FlagEnumerationPrinter (@var{name})
-A pretty-printer which handles printing of @code{enum} values. Unlike
-@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
-work properly when there is some overlap between the enumeration
-constants. @var{name} is the name of the printer and also the name of
-the @code{enum} type to look up.
-
-@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
-Register @var{printer} with the pretty-printer list of @var{obj}.
-If @var{replace} is @code{True} then any existing copy of the printer
-is replaced. Otherwise a @code{RuntimeError} exception is raised
-if a printer with the same name already exists.
-@end table
-
-@node gdb.types
-@subsubsection gdb.types
-@cindex gdb.types
-
-This module provides a collection of utilities for working with
-@code{gdb.Type} objects.
-
-@table @code
-@item get_basic_type (@var{type})
-Return @var{type} with const and volatile qualifiers stripped,
-and with typedefs and C@t{++} references converted to the underlying type.
-
-C@t{++} example:
-
-@smallexample
-typedef const int const_int;
-const_int foo (3);
-const_int& foo_ref (foo);
-int main () @{ return 0; @}
-@end smallexample
-
-Then in gdb:
-
-@smallexample
-(gdb) start
-(gdb) python import gdb.types
-(gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
-(gdb) python print gdb.types.get_basic_type(foo_ref.type)
-int
-@end smallexample
-
-@item has_field (@var{type}, @var{field})
-Return @code{True} if @var{type}, assumed to be a type with fields
-(e.g., a structure or union), has field @var{field}.
-
-@item make_enum_dict (@var{enum_type})
-Return a Python @code{dictionary} type produced from @var{enum_type}.
-
-@item deep_items (@var{type})
-Returns a Python iterator similar to the standard
-@code{gdb.Type.iteritems} method, except that the iterator returned
-by @code{deep_items} will recursively traverse anonymous struct or
-union fields. For example:
-
-@smallexample
-struct A
-@{
- int a;
- union @{
- int b0;
- int b1;
- @};
-@};
-@end smallexample
-
-@noindent
-Then in @value{GDBN}:
-@smallexample
-(@value{GDBP}) python import gdb.types
-(@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
-(@value{GDBP}) python print struct_a.keys ()
-@{['a', '']@}
-(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
-@{['a', 'b0', 'b1']@}
-@end smallexample
-
-@item get_type_recognizers ()
-Return a list of the enabled type recognizers for the current context.
-This is called by @value{GDBN} during the type-printing process
-(@pxref{Type Printing API}).
-
-@item apply_type_recognizers (recognizers, type_obj)
-Apply the type recognizers, @var{recognizers}, to the type object
-@var{type_obj}. If any recognizer returns a string, return that
-string. Otherwise, return @code{None}. This is called by
-@value{GDBN} during the type-printing process (@pxref{Type Printing
-API}).
-
-@item register_type_printer (locus, printer)
-This is a convenience function to register a type printer.
-@var{printer} is the type printer to register. It must implement the
-type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
-which case the printer is registered with that objfile; a
-@code{gdb.Progspace}, in which case the printer is registered with
-that progspace; or @code{None}, in which case the printer is
-registered globally.
-
-@item TypePrinter
-This is a base class that implements the type printer protocol. Type
-printers are encouraged, but not required, to derive from this class.
-It defines a constructor:
-
-@defmethod TypePrinter __init__ (self, name)
-Initialize the type printer with the given name. The new printer
-starts in the enabled state.
-@end defmethod
-
-@end table
-
-@node gdb.prompt
-@subsubsection gdb.prompt
-@cindex gdb.prompt
-
-This module provides a method for prompt value-substitution.
-
-@table @code
-@item substitute_prompt (@var{string})
-Return @var{string} with escape sequences substituted by values. Some
-escape sequences take arguments. You can specify arguments inside
-``@{@}'' immediately following the escape sequence.
-
-The escape sequences you can pass to this function are:
-
-@table @code
-@item \\
-Substitute a backslash.
-@item \e
-Substitute an ESC character.
-@item \f
-Substitute the selected frame; an argument names a frame parameter.
-@item \n
-Substitute a newline.
-@item \p
-Substitute a parameter's value; the argument names the parameter.
-@item \r
-Substitute a carriage return.
-@item \t
-Substitute the selected thread; an argument names a thread parameter.
-@item \v
-Substitute the version of GDB.
-@item \w
-Substitute the current working directory.
-@item \[
-Begin a sequence of non-printing characters. These sequences are
-typically used with the ESC character, and are not counted in the string
-length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
-blue-colored ``(gdb)'' prompt where the length is five.
-@item \]
-End a sequence of non-printing characters.
-@end table
-
-For example:
-
-@smallexample
-substitute_prompt (``frame: \f,
- print arguments: \p@{print frame-arguments@}'')
-@end smallexample
-
-@exdent will return the string:
-
-@smallexample
-"frame: main, print arguments: scalars"
-@end smallexample
-@end table
+Python was @value{GDBN}'s first extension language, and to avoid breaking
+existing behaviour Python comes first. This is generally solved by the
+``first one wins'' principle. @value{GDBN} maintains a list of enabled
+extension languages, and when it makes a call to an extension language,
+(say to pretty-print a value), it tries each in turn until an extension
+language indicates it has performed the request (e.g., has returned the
+pretty-printed form of a value).
+This extends to errors while performing such requests: If an error happens
+while, for example, trying to pretty-print an object then the error is
+reported and any following extension languages are not tried.
@node Aliases
@section Creating new spellings of existing commands
The TUI mode is enabled by default when you invoke @value{GDBN} as
@samp{@value{GDBP} -tui}.
You can also switch in and out of TUI mode while @value{GDBN} runs by
-using various TUI commands and key bindings, such as @kbd{C-x C-a}.
-@xref{TUI Keys, ,TUI Key Bindings}.
+using various TUI commands and key bindings, such as @command{tui
+enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands}, and
+@ref{TUI Keys, ,TUI Key Bindings}.
@node TUI Overview
@section TUI Overview
possible or desirable to enable curses window management.
@table @code
+@item tui enable
+@kindex tui enable
+Activate TUI mode. The last active TUI window layout will be used if
+TUI mode has prevsiouly been used in the current debugging session,
+otherwise a default layout is used.
+
+@item tui disable
+@kindex tui disable
+Disable TUI mode, returning to the console interpreter.
+
@item info win
@kindex info win
List and give the size of all displayed windows.
-@item layout next
+@item layout @var{name}
@kindex layout
+Changes which TUI windows are displayed. In each layout the command
+window is always displayed, the @var{name} parameter controls which
+additional windows are displayed, and can be any of the following:
+
+@table @code
+@item next
Display the next layout.
-@item layout prev
+@item prev
Display the previous layout.
-@item layout src
-Display the source window only.
+@item src
+Display the source and command windows.
-@item layout asm
-Display the assembly window only.
+@item asm
+Display the assembly and command windows.
-@item layout split
-Display the source and assembly window.
+@item split
+Display the source, assembly, and command windows.
-@item layout regs
-Display the register window together with the source or assembly window.
+@item regs
+When in @code{src} layout display the register, source, and command
+windows. When in @code{asm} or @code{split} layout display the
+register, assembler, and command windows.
+@end table
-@item focus next
+@item focus @var{name}
@kindex focus
+Changes which TUI window is currently active for scrolling. The
+@var{name} parameter can be any of the following:
+
+@table @code
+@item next
Make the next window active for scrolling.
-@item focus prev
+@item prev
Make the previous window active for scrolling.
-@item focus src
+@item src
Make the source window active for scrolling.
-@item focus asm
+@item asm
Make the assembly window active for scrolling.
-@item focus regs
+@item regs
Make the register window active for scrolling.
-@item focus cmd
+@item cmd
Make the command window active for scrolling.
+@end table
@item refresh
@kindex refresh
Refresh the screen. This is similar to typing @kbd{C-L}.
-@item tui reg float
+@item tui reg @var{group}
@kindex tui reg
-Show the floating point registers in the register window.
-
-@item tui reg general
-Show the general registers in the register window.
-
-@item tui reg next
-Show the next register group. The list of register groups as well as
-their order is target specific. The predefined register groups are the
-following: @code{general}, @code{float}, @code{system}, @code{vector},
-@code{all}, @code{save}, @code{restore}.
-
-@item tui reg system
-Show the system registers in the register window.
+Changes the register group displayed in the tui register window to
+@var{group}. If the register window is not currently displayed this
+command will cause the register window to be displayed. The list of
+register groups, as well as their order is target specific. The
+following groups are available on most targets:
+@table @code
+@item next
+Repeatedly selecting this group will cause the display to cycle
+through all of the available register groups.
+
+@item prev
+Repeatedly selecting this group will cause the display to cycle
+through all of the available register groups in the reverse order to
+@var{next}.
+
+@item general
+Display the general registers.
+@item float
+Display the floating point registers.
+@item system
+Display the system registers.
+@item vector
+Display the vector registers.
+@item all
+Display all registers.
+@end table
@item update
@kindex update
@kindex winheight
Change the height of the window @var{name} by @var{count}
lines. Positive counts increase the height, while negative counts
-decrease it.
+decrease it. The @var{name} parameter can be one of @code{src} (the
+source window), @code{cmd} (the command window), @code{asm} (the
+disassembly window), or @code{regs} (the register display window).
@item tabset @var{nchars}
@kindex tabset
-Set the width of tab stops to be @var{nchars} characters.
+Set the width of tab stops to be @var{nchars} characters. This
+setting affects the display of TAB characters in the source and
+assembly windows.
@end table
@node TUI Configuration
* GDB/MI Target Manipulation::
* GDB/MI File Transfer Commands::
* GDB/MI Ada Exceptions Commands::
+* GDB/MI Support Commands::
* GDB/MI Miscellaneous Commands::
@end menu
frontend may be operating on a wrong one. Therefore, each MI command
should explicitly specify which thread and frame to operate on. To
make it possible, each MI command accepts the @samp{--thread} and
-@samp{--frame} options, the value to each is @value{GDBN} identifier
-for thread and frame to operate on.
+@samp{--frame} options, the value to each is @value{GDBN} global
+identifier for thread and frame to operate on.
Usually, each top-level window in a frontend allows the user to select
a thread and a frame, and remembers the user selection for further
even while the target is running. This is called @dfn{asynchronous
command execution} (@pxref{Background Execution}). The frontend may
specify a preferrence for asynchronous execution using the
-@code{-gdb-set target-async 1} command, which should be emitted before
+@code{-gdb-set mi-async 1} command, which should be emitted before
either running the executable or attaching to the target. After the
frontend has started the executable or attached to the target, it can
find if asynchronous execution is enabled using the
@code{-list-target-features} command.
+@table @code
+@item -gdb-set mi-async on
+@item -gdb-set mi-async off
+Set whether MI is in asynchronous mode.
+
+When @code{off}, which is the default, MI execution commands (e.g.,
+@code{-exec-continue}) are foreground commands, and @value{GDBN} waits
+for the program to stop before processing further commands.
+
+When @code{on}, MI execution commands are background execution
+commands (e.g., @code{-exec-continue} becomes the equivalent of the
+@code{c&} CLI command), and so @value{GDBN} is capable of processing
+MI commands even while the target is running.
+
+@item -gdb-show mi-async
+Show whether MI asynchronous mode is enabled.
+@end table
+
+Note: In @value{GDBN} version 7.7 and earlier, this option was called
+@code{target-async} instead of @code{mi-async}, and it had the effect
+of both putting MI in asynchronous mode and making CLI background
+commands possible. CLI background commands are now always possible
+``out of the box'' if the target supports them. The old spelling is
+kept as a deprecated alias for backwards compatibility.
+
Even if @value{GDBN} can accept a command while target is running,
many commands that access the target do not work when the target is
running. Therefore, asynchronous command execution is most useful
@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
@item @var{exec-async-output} @expansion{}
-@code{[ @var{token} ] "*" @var{async-output}}
+@code{[ @var{token} ] "*" @var{async-output nl}}
@item @var{status-async-output} @expansion{}
-@code{[ @var{token} ] "+" @var{async-output}}
+@code{[ @var{token} ] "+" @var{async-output nl}}
@item @var{notify-async-output} @expansion{}
-@code{[ @var{token} ] "=" @var{async-output}}
+@code{[ @var{token} ] "=" @var{async-output nl}}
@item @var{async-output} @expansion{}
-@code{@var{async-class} ( "," @var{result} )* @var{nl}}
+@code{@var{async-class} ( "," @var{result} )*}
@item @var{result-class} @expansion{}
@code{"done" | "running" | "connected" | "error" | "exit"}
@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
@item @var{console-stream-output} @expansion{}
-@code{"~" @var{c-string}}
+@code{"~" @var{c-string nl}}
@item @var{target-stream-output} @expansion{}
-@code{"@@" @var{c-string}}
+@code{"@@" @var{c-string nl}}
@item @var{log-stream-output} @expansion{}
-@code{"&" @var{c-string}}
+@code{"&" @var{c-string nl}}
@item @var{nl} @expansion{}
@code{CR | CR-LF}
@table @code
@item *running,thread-id="@var{thread}"
-The target is now running. The @var{thread} field tells which
-specific thread is now running, and can be @samp{all} if all threads
-are running. The frontend should assume that no interaction with a
-running thread is possible after this notification is produced.
-The frontend should not assume that this notification is output
-only once for any command. @value{GDBN} may emit this notification
-several times, either for different threads, because it cannot resume
-all threads together, or even for a single thread, if the thread must
-be stepped though some code before letting it run freely.
+The target is now running. The @var{thread} field can be the global
+thread ID of the the thread that is now running, and it can be
+@samp{all} if all threads are running. The frontend should assume
+that no interaction with a running thread is possible after this
+notification is produced. The frontend should not assume that this
+notification is output only once for any command. @value{GDBN} may
+emit this notification several times, either for different threads,
+because it cannot resume all threads together, or even for a single
+thread, if the thread must be stepped though some code before letting
+it run freely.
@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
The target has stopped. The @var{reason} field can have one of the
@item syscall-entry
The inferior entered a system call. This is reported when @code{catch
syscall} (@pxref{Set Catchpoints}) has been used.
-@item syscall-entry
+@item syscall-return
The inferior returned from a system call. This is reported when
@code{catch syscall} (@pxref{Set Catchpoints}) has been used.
@item exec
(@pxref{Set Catchpoints}) has been used.
@end table
-The @var{id} field identifies the thread that directly caused the stop
--- for example by hitting a breakpoint. Depending on whether all-stop
+The @var{id} field identifies the global thread ID of the thread
+that directly caused the stop -- for example by hitting a breakpoint.
+Depending on whether all-stop
mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
stop all threads, or only the thread that directly triggered the stop.
If all threads are stopped, the @var{stopped} field will have the
A thread group is no longer associated with a running program,
either because the program has exited, or because it was detached
from. The @var{id} field contains the @value{GDBN} identifier of the
-thread group. @var{code} is the exit code of the inferior; it exists
+thread group. The @var{code} field is the exit code of the inferior; it exists
only when the inferior exited with some code.
@item =thread-created,id="@var{id}",group-id="@var{gid}"
@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
A thread either was created, or has exited. The @var{id} field
-contains the @value{GDBN} identifier of the thread. The @var{gid}
+contains the global @value{GDBN} identifier of the thread. The @var{gid}
field identifies the thread group this thread belongs to.
@item =thread-selected,id="@var{id}"
Note that if a breakpoint is emitted in the result record of a
command, then it will not also be emitted in an async record.
-@item =record-started,thread-group="@var{id}"
+@item =record-started,thread-group="@var{id}",method="@var{method}"[,format="@var{format}"]
@itemx =record-stopped,thread-group="@var{id}"
Execution log recording was either started or stopped on an
inferior. The @var{id} is the @value{GDBN} identifier of the thread
group corresponding to the affected inferior.
+The @var{method} field indicates the method used to record execution. If the
+method in use supports multiple recording formats, @var{format} will be present
+and contain the currently used format. @xref{Process Record and Replay}
+for existing method and format values.
+
@item =cmd-param-changed,param=@var{param},value=@var{value}
Reports that a parameter of the command @code{set @var{param}} is
changed to @var{value}. In the multi-word @code{set} command,
@table @code
@item id
-The numeric id assigned to the thread by @value{GDBN}. This field is
+The global numeric id assigned to the thread by @value{GDBN}. This field is
always present.
@item target-id
@subheading The @code{-break-insert} Command
@findex -break-insert
+@anchor{-break-insert}
@subsubheading Synopsis
@noindent
If specified, @var{location}, can be one of:
-@itemize @bullet
-@item function
-@c @item +offset
-@c @item -offset
-@c @item linenum
-@item filename:linenum
-@item filename:function
-@item *address
-@end itemize
+@table @var
+@item linespec location
+A linespec location. @xref{Linespec Locations}.
+
+@item explicit location
+An explicit location. @sc{gdb/mi} explicit locations are
+analogous to the CLI's explicit locations using the option names
+listed below. @xref{Explicit Locations}.
+
+@table @samp
+@item --source @var{filename}
+The source file name of the location. This option requires the use
+of either @samp{--function} or @samp{--line}.
+
+@item --function @var{function}
+The name of a function or method.
+
+@item --label @var{label}
+The name of a label.
+
+@item --line @var{lineoffset}
+An absolute or relative line offset from the start of the location.
+@end table
+
+@item address location
+An address location, *@var{address}. @xref{Address Locations}.
+@end table
+@noindent
The possible optional parameters of this command are:
@table @samp
@item -i @var{ignore-count}
Initialize the @var{ignore-count}.
@item -p @var{thread-id}
-Restrict the breakpoint to the specified @var{thread-id}.
+Restrict the breakpoint to the thread with the specified global
+@var{thread-id}.
@end table
@subsubheading Result
@end smallexample
@noindent
-If specified, @var{location}, can be one of:
-
-@itemize @bullet
-@item @var{function}
-@c @item +offset
-@c @item -offset
-@c @item @var{linenum}
-@item @var{filename}:@var{linenum}
-@item @var{filename}:function
-@item *@var{address}
-@end itemize
+If supplied, @var{location} may be specified the same way as for
+the @code{-break-insert} command. @xref{-break-insert}.
The possible optional parameters of this command are:
Set the ignore count of the breakpoint (@pxref{Conditions, ignore count})
to @var{ignore-count}.
@item -p @var{thread-id}
-Restrict the breakpoint to the specified @var{thread-id}.
+Restrict the breakpoint to the thread with the specified global
+@var{thread-id}.
@end table
@subsubheading Result
-thread-info [ @var{thread-id} ]
@end smallexample
-Reports information about either a specific thread, if
-the @var{thread-id} parameter is present, or about all
-threads. When printing information about all threads,
-also reports the current thread.
+Reports information about either a specific thread, if the
+@var{thread-id} parameter is present, or about all threads.
+@var{thread-id} is the thread's global thread ID. When printing
+information about all threads, also reports the global ID of the
+current thread.
@subsubheading @value{GDBN} Command
This field exists only for the current thread. It has the value @samp{*}.
@item id
-The identifier that @value{GDBN} uses to refer to the thread.
+The global identifier that @value{GDBN} uses to refer to the thread.
@item target-id
The identifier that the target uses to refer to the thread.
-thread-list-ids
@end smallexample
-Produces a list of the currently known @value{GDBN} thread ids. At the
-end of the list it also prints the total number of such threads.
+Produces a list of the currently known global @value{GDBN} thread ids.
+At the end of the list it also prints the total number of such
+threads.
This command is retained for historical reasons, the
@code{-thread-info} command should be used instead.
@subsubheading Synopsis
@smallexample
- -thread-select @var{threadnum}
+ -thread-select @var{thread-id}
@end smallexample
-Make @var{threadnum} the current thread. It prints the number of the new
-current thread, and the topmost frame for that thread.
+Make thread with global thread number @var{thread-id} the current
+thread. It prints the number of the new current thread, and the
+topmost frame for that thread.
This command is deprecated in favor of explicitly using the
@samp{--thread} option to each command.
The identifier that the target uses to refer to the Ada task.
@item thread-id
-The identifier of the thread corresponding to the Ada task.
+The global thread identifier of the thread corresponding to the Ada
+task.
This field should always exist, as Ada tasks are always implemented
on top of a thread. But if @value{GDBN} cannot find this corresponding
@item thread-id
If a variable object is bound to a specific thread, then this is the
-thread's identifier.
+thread's global identifier.
@item has_more
For a dynamic varobj, this indicates whether there appear to be any
@smallexample
@var{format-spec} @expansion{}
- @{binary | decimal | hexadecimal | octal | natural@}
+ @{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal@}
@end smallexample
The natural format is the default format choosen automatically
based on the variable type (like decimal for an @code{int}, hex
for pointers, etc.).
+The zero-hexadecimal format has a representation similar to hexadecimal
+but with padding zeroes to the left of the value. For example, a 32-bit
+hexadecimal value of 0x1234 would be represented as 0x00001234 in the
+zero-hexadecimal format.
+
For a variable with children, the format is set only on the
variable itself, and the children are not affected.
If values were requested, this is the value.
@item thread-id
-If this variable object is associated with a thread, this is the thread id.
-Otherwise this result is not present.
+If this variable object is associated with a thread, this is the
+thread's global thread id. Otherwise this result is not present.
@item frozen
If the variable object is frozen, this variable will be present with a value of 1.
a varobj is created, and so ordinarily is not needed.
This feature is only available if Python support is enabled. The MI
-command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands})
+command @code{-list-features} (@pxref{GDB/MI Support Commands})
can be used to check this.
@subsubheading Example
This section describes the @sc{gdb/mi} commands that manipulate data:
examine memory and registers, evaluate expressions, etc.
+For details about what an addressable memory unit is,
+@pxref{addressable memory unit}.
+
@c REMOVED FROM THE INTERFACE.
@c @subheading -data-assign
@c Change the value of a program variable. Plenty of side effects.
@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
are displayed.
@item @var{mode}
-is either 0 (meaning only disassembly), 1 (meaning mixed source and
-disassembly), 2 (meaning disassembly with raw opcodes), or 3 (meaning
-mixed source and disassembly with raw opcodes).
+is one of:
+@itemize @bullet
+@item 0 disassembly only
+@item 1 mixed source and disassembly (deprecated)
+@item 2 disassembly with raw opcodes
+@item 3 mixed source and disassembly with raw opcodes (deprecated)
+@item 4 mixed source and disassembly
+@item 5 mixed source and disassembly with raw opcodes
+@end itemize
+
+Modes 1 and 3 are deprecated. The output is ``source centric''
+which hasn't proved useful in practice.
+@xref{Machine Code}, for a discussion of the difference between
+@code{/m} and @code{/s} output of the @code{disassemble} command.
@end table
@subsubheading Result
The text disassembly for this @samp{address}.
@item opcodes
-This field is only present for mode 2. This contains the raw opcode
+This field is only present for modes 2, 3 and 5. This contains the raw opcode
bytes for the @samp{inst} field.
@end table
-For modes 1 and 3 the @samp{asm_insns} list contains tuples named
+For modes 1, 3, 4 and 5 the @samp{asm_insns} list contains tuples named
@samp{src_and_asm_line}, each of which has the following fields:
@table @code
[ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*]
@end smallexample
-Display the registers' contents. @var{fmt} is the format according to
-which the registers' contents are to be returned, followed by an optional
-list of numbers specifying the registers to display. A missing list of
-numbers indicates that the contents of all the registers must be
-returned. The @code{--skip-unavailable} option indicates that only
-the available registers are to be returned.
+Display the registers' contents. The format according to which the
+registers' contents are to be returned is given by @var{fmt}, followed
+by an optional list of numbers specifying the registers to display. A
+missing list of numbers indicates that the contents of all the
+registers must be returned. The @code{--skip-unavailable} option
+indicates that only the available registers are to be returned.
Allowed formats for @var{fmt} are:
@subsubheading Synopsis
@smallexample
- -data-read-memory-bytes [ -o @var{byte-offset} ]
+ -data-read-memory-bytes [ -o @var{offset} ]
@var{address} @var{count}
@end smallexample
@table @samp
@item @var{address}
-An expression specifying the address of the first memory word to be
-read. Complex expressions containing embedded white space should be
+An expression specifying the address of the first addressable memory unit
+to be read. Complex expressions containing embedded white space should be
quoted using the C convention.
@item @var{count}
-The number of bytes to read. This should be an integer literal.
+The number of addressable memory units to read. This should be an integer
+literal.
-@item @var{byte-offset}
-The offsets in bytes relative to @var{address} at which to start
-reading. This should be an integer literal. This option is provided
-so that a frontend is not required to first evaluate address and then
-perform address arithmetics itself.
+@item @var{offset}
+The offset relative to @var{address} at which to start reading. This
+should be an integer literal. This option is provided so that a frontend
+is not required to first evaluate address and then perform address
+arithmetics itself.
@end table
regions. For each one, if reading full region results in an errors,
@value{GDBN} will try to read a subset of the region.
-In general, every single byte in the region may be readable or not,
-and the only way to read every readable byte is to try a read at
+In general, every single memory unit in the region may be readable or not,
+and the only way to read every readable unit is to try a read at
every address, which is not practical. Therefore, @value{GDBN} will
-attempt to read all accessible bytes at either beginning or the end
+attempt to read all accessible memory units at either beginning or the end
of the region, using a binary division scheme. This heuristic works
well for reading accross a memory map boundary. Note that if a region
has a readable range that is neither at the beginning or the end,
@table @samp
@item @var{address}
-An expression specifying the address of the first memory word to be
-read. Complex expressions containing embedded white space should be
-quoted using the C convention.
+An expression specifying the address of the first addressable memory unit
+to be written. Complex expressions containing embedded white space should
+be quoted using the C convention.
@item @var{contents}
-The hex-encoded bytes to write.
+The hex-encoded data to write. It is an error if @var{contents} does
+not represent an integral number of addressable memory units.
@item @var{count}
-Optional argument indicating the number of bytes to be written. If @var{count}
-is greater than @var{contents}' length, @value{GDBN} will repeatedly
-write @var{contents} until it fills @var{count} bytes.
+Optional argument indicating the number of addressable memory units to be
+written. If @var{count} is greater than @var{contents}' length,
+@value{GDBN} will repeatedly write @var{contents} until it fills
+@var{count} memory units.
@end table
Catchpoint Commands}.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Support Commands
+@section @sc{gdb/mi} Support Commands
+
+Since new commands and features get regularly added to @sc{gdb/mi},
+some commands are available to help front-ends query the debugger
+about support for these capabilities. Similarly, it is also possible
+to query @value{GDBN} about target support of certain features.
+
+@subheading The @code{-info-gdb-mi-command} Command
+@cindex @code{-info-gdb-mi-command}
+@findex -info-gdb-mi-command
+
+@subsubheading Synopsis
+
+@smallexample
+ -info-gdb-mi-command @var{cmd_name}
+@end smallexample
+
+Query support for the @sc{gdb/mi} command named @var{cmd_name}.
+
+Note that the dash (@code{-}) starting all @sc{gdb/mi} commands
+is technically not part of the command name (@pxref{GDB/MI Input
+Syntax}), and thus should be omitted in @var{cmd_name}. However,
+for ease of use, this command also accepts the form with the leading
+dash.
+
+@subsubheading @value{GDBN} Command
+
+There is no corresponding @value{GDBN} command.
+
+@subsubheading Result
+
+The result is a tuple. There is currently only one field:
+
+@table @samp
+@item exists
+This field is equal to @code{"true"} if the @sc{gdb/mi} command exists,
+@code{"false"} otherwise.
+
+@end table
+
+@subsubheading Example
+
+Here is an example where the @sc{gdb/mi} command does not exist:
+
+@smallexample
+-info-gdb-mi-command unsupported-command
+^done,command=@{exists="false"@}
+@end smallexample
+
+@noindent
+And here is an example where the @sc{gdb/mi} command is known
+to the debugger:
+
+@smallexample
+-info-gdb-mi-command symbol-list-lines
+^done,command=@{exists="true"@}
+@end smallexample
+
+@subheading The @code{-list-features} Command
+@findex -list-features
+@cindex supported @sc{gdb/mi} features, list
+
+Returns a list of particular features of the MI protocol that
+this version of gdb implements. A feature can be a command,
+or a new field in an output of some command, or even an
+important bugfix. While a frontend can sometimes detect presence
+of a feature at runtime, it is easier to perform detection at debugger
+startup.
+
+The command returns a list of strings, with each string naming an
+available feature. Each returned string is just a name, it does not
+have any internal structure. The list of possible feature names
+is given below.
+
+Example output:
+
+@smallexample
+(gdb) -list-features
+^done,result=["feature1","feature2"]
+@end smallexample
+
+The current list of features is:
+
+@ftable @samp
+@item frozen-varobjs
+Indicates support for the @code{-var-set-frozen} command, as well
+as possible presense of the @code{frozen} field in the output
+of @code{-varobj-create}.
+@item pending-breakpoints
+Indicates support for the @option{-f} option to the @code{-break-insert}
+command.
+@item python
+Indicates Python scripting support, Python-based
+pretty-printing commands, and possible presence of the
+@samp{display_hint} field in the output of @code{-var-list-children}
+@item thread-info
+Indicates support for the @code{-thread-info} command.
+@item data-read-memory-bytes
+Indicates support for the @code{-data-read-memory-bytes} and the
+@code{-data-write-memory-bytes} commands.
+@item breakpoint-notifications
+Indicates that changes to breakpoints and breakpoints created via the
+CLI will be announced via async records.
+@item ada-task-info
+Indicates support for the @code{-ada-task-info} command.
+@item language-option
+Indicates that all @sc{gdb/mi} commands accept the @option{--language}
+option (@pxref{Context management}).
+@item info-gdb-mi-command
+Indicates support for the @code{-info-gdb-mi-command} command.
+@item undefined-command-error-code
+Indicates support for the "undefined-command" error code in error result
+records, produced when trying to execute an undefined @sc{gdb/mi} command
+(@pxref{GDB/MI Result Records}).
+@item exec-run-start-option
+Indicates that the @code{-exec-run} command supports the @option{--start}
+option (@pxref{GDB/MI Program Execution}).
+@end ftable
+
+@subheading The @code{-list-target-features} Command
+@findex -list-target-features
+
+Returns a list of particular features that are supported by the
+target. Those features affect the permitted MI commands, but
+unlike the features reported by the @code{-list-features} command, the
+features depend on which target GDB is using at the moment. Whenever
+a target can change, due to commands such as @code{-target-select},
+@code{-target-attach} or @code{-exec-run}, the list of target features
+may change, and the frontend should obtain it again.
+Example output:
+
+@smallexample
+(gdb) -list-target-features
+^done,result=["async"]
+@end smallexample
+
+The current list of features is:
+
+@table @samp
+@item async
+Indicates that the target is capable of asynchronous command
+execution, which means that @value{GDBN} will accept further commands
+while the target is running.
+
+@item reverse
+Indicates that the target is capable of reverse execution.
+@xref{Reverse Execution}, for more information.
+
+@end table
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
(gdb)
@end smallexample
-@subheading The @code{-info-gdb-mi-command} Command
-@cindex @code{-info-gdb-mi-command}
-@findex -info-gdb-mi-command
-
-@subsubheading Synopsis
-
-@smallexample
- -info-gdb-mi-command @var{cmd_name}
-@end smallexample
-
-Query support for the @sc{gdb/mi} command named @var{cmd_name}.
-
-Note that the dash (@code{-}) starting all @sc{gdb/mi} commands
-is technically not part of the command name (@pxref{GDB/MI Input
-Syntax}), and thus should be omitted in @var{cmd_name}. However,
-for ease of use, this command also accepts the form with the leading
-dash.
-
-@subsubheading @value{GDBN} Command
-
-There is no corresponding @value{GDBN} command.
-
-@subsubheading Result
-
-The result is a tuple. There is currently only one field:
-
-@table @samp
-@item exists
-This field is equal to @code{"true"} if the @sc{gdb/mi} command exists,
-@code{"false"} otherwise.
-
-@end table
-
-@subsubheading Example
-
-Here is an example where the @sc{gdb/mi} command does not exist:
-
-@smallexample
--info-gdb-mi-command unsupported-command
-^done,command=@{exists="false"@}
-@end smallexample
-
-@noindent
-And here is an example where the @sc{gdb/mi} command is known
-to the debugger:
-
-@smallexample
--info-gdb-mi-command symbol-list-lines
-^done,command=@{exists="true"@}
-@end smallexample
-
-@subheading The @code{-list-features} Command
-@findex -list-features
-
-Returns a list of particular features of the MI protocol that
-this version of gdb implements. A feature can be a command,
-or a new field in an output of some command, or even an
-important bugfix. While a frontend can sometimes detect presence
-of a feature at runtime, it is easier to perform detection at debugger
-startup.
-
-The command returns a list of strings, with each string naming an
-available feature. Each returned string is just a name, it does not
-have any internal structure. The list of possible feature names
-is given below.
-
-Example output:
-
-@smallexample
-(gdb) -list-features
-^done,result=["feature1","feature2"]
-@end smallexample
-
-The current list of features is:
-
-@table @samp
-@item frozen-varobjs
-Indicates support for the @code{-var-set-frozen} command, as well
-as possible presense of the @code{frozen} field in the output
-of @code{-varobj-create}.
-@item pending-breakpoints
-Indicates support for the @option{-f} option to the @code{-break-insert}
-command.
-@item python
-Indicates Python scripting support, Python-based
-pretty-printing commands, and possible presence of the
-@samp{display_hint} field in the output of @code{-var-list-children}
-@item thread-info
-Indicates support for the @code{-thread-info} command.
-@item data-read-memory-bytes
-Indicates support for the @code{-data-read-memory-bytes} and the
-@code{-data-write-memory-bytes} commands.
-@item breakpoint-notifications
-Indicates that changes to breakpoints and breakpoints created via the
-CLI will be announced via async records.
-@item ada-task-info
-Indicates support for the @code{-ada-task-info} command.
-@item language-option
-Indicates that all @sc{gdb/mi} commands accept the @option{--language}
-option (@pxref{Context management}).
-@item info-gdb-mi-command
-Indicates support for the @code{-info-gdb-mi-command} command.
-@item undefined-command-error-code
-Indicates support for the "undefined-command" error code in error result
-records, produced when trying to execute an undefined @sc{gdb/mi} command
-(@pxref{GDB/MI Result Records}).
-@end table
-
-@subheading The @code{-list-target-features} Command
-@findex -list-target-features
-
-Returns a list of particular features that are supported by the
-target. Those features affect the permitted MI commands, but
-unlike the features reported by the @code{-list-features} command, the
-features depend on which target GDB is using at the moment. Whenever
-a target can change, due to commands such as @code{-target-select},
-@code{-target-attach} or @code{-exec-run}, the list of target features
-may change, and the frontend should obtain it again.
-Example output:
-
-@smallexample
-(gdb) -list-target-features
-^done,result=["async"]
-@end smallexample
-
-The current list of features is:
-
-@table @samp
-@item async
-Indicates that the target is capable of asynchronous command
-execution, which means that @value{GDBN} will accept further commands
-while the target is running.
-
-@item reverse
-Indicates that the target is capable of reverse execution.
-@xref{Reverse Execution}, for more information.
-
-@end table
-
@subheading The @code{-list-thread-groups} Command
@findex -list-thread-groups
The target-specific process identifier. This field is only present
for thread groups of type @samp{process} and only if the process exists.
+@item exit-code
+The exit code of this group's last exited thread, formatted in octal.
+This field is only present for thread groups of type @samp{process} and
+only if the process is not running.
+
@item num_children
The number of children this thread group has. This field may be
absent for an available thread group.
@smallexample
@value{GDBP}
-info-os
-^done,OSDataTable=@{nr_rows="9",nr_cols="3",
+^done,OSDataTable=@{nr_rows="10",nr_cols="3",
hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@},
@{width="10",alignment="-1",col_name="col1",colhdr="Description"@},
@{width="10",alignment="-1",col_name="col2",colhdr="Title"@}],
-body=[item=@{col0="processes",col1="Listing of all processes",
+body=[item=@{col0="cpus",col1="Listing of all cpus/cores on the system",
+ col2="CPUs"@},
+ item=@{col0="files",col1="Listing of all file descriptors",
+ col2="File descriptors"@},
+ item=@{col0="modules",col1="Listing of all loaded kernel modules",
+ col2="Kernel modules"@},
+ item=@{col0="msg",col1="Listing of all message queues",
+ col2="Message queues"@},
+ item=@{col0="processes",col1="Listing of all processes",
col2="Processes"@},
item=@{col0="procgroups",col1="Listing of all process groups",
col2="Process groups"@},
- item=@{col0="threads",col1="Listing of all threads",
- col2="Threads"@},
- item=@{col0="files",col1="Listing of all file descriptors",
- col2="File descriptors"@},
- item=@{col0="sockets",col1="Listing of all internet-domain sockets",
- col2="Sockets"@},
- item=@{col0="shm",col1="Listing of all shared-memory regions",
- col2="Shared-memory regions"@},
item=@{col0="semaphores",col1="Listing of all semaphores",
col2="Semaphores"@},
- item=@{col0="msg",col1="Listing of all message queues",
- col2="Message queues"@},
- item=@{col0="modules",col1="Listing of all loaded kernel modules",
- col2="Kernel modules"@}]@}
+ item=@{col0="shm",col1="Listing of all shared-memory regions",
+ col2="Shared-memory regions"@},
+ item=@{col0="sockets",col1="Listing of all internet-domain sockets",
+ col2="Sockets"@},
+ item=@{col0="threads",col1="Listing of all threads",
+ col2="Threads"@}]
@value{GDBP}
-info-os processes
^done,OSDataTable=@{nr_rows="190",nr_cols="4",
@noindent
where @var{name} is the name of the signal, such as @code{SIGILL} or
@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
-as @code{Illegal Instruction} or @code{Segmentation fault}.
+as @code{Illegal Instruction} or @code{Segmentation fault}. The arguments
@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
user's benefit and have no particular format.
@var{middle} is @samp{middle} if @var{addr} is in the middle of the
line, or @samp{beg} if @var{addr} is at the beginning of the line, and
@var{addr} is the address in the target program associated with the
-source which is being displayed. @var{addr} is in the form @samp{0x}
+source which is being displayed. The @var{addr} is in the form @samp{0x}
followed by one or more lowercase hex digits (note that this does not
depend on the language).
@table @code
@item jit-reader-load @var{reader}
-Load the JIT reader named @var{reader}. @var{reader} is a shared
+Load the JIT reader named @var{reader}, which is a shared
object specified as either an absolute or a relative file name. In
the latter case, @value{GDBN} will try to load the reader from a
pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX
@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head}
Installs a new fast tracepoint described by @var{tracepoint_object}
-(@pxref{tracepoint object}). @var{gdb_jump_pad_head}, 8-byte long, is the
+(@pxref{tracepoint object}). The @var{gdb_jump_pad_head}, 8-byte long, is the
head of @dfn{jumppad}, which is used to jump to data collection routine
in IPA finally.
@table @samp
@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump}
@var{target_address} is address of tracepoint in the inferior.
-@var{gdb_jump_pad_head} is updated head of jumppad. Both of
+The @var{gdb_jump_pad_head} is updated head of jumppad. Both of
@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long.
-@var{fjump} contains a sequence of instructions jump to jumppad entry.
-@var{fjump_size}, 4-byte long, is the size of @var{fjump}.
+The @var{fjump} contains a sequence of instructions jump to jumppad entry.
+The @var{fjump_size}, 4-byte long, is the size of @var{fjump}.
@item E @var{NN}
for an error
@item
Traceframe info (@pxref{Traceframe Info Format})
@item
-Branch trace (@pxref{Branch Trace Format})
+Branch trace (@pxref{Branch Trace Format},
+@pxref{Branch Trace Configuration Format})
@end itemize
@item zlib
@end table
-@kindex maint info bfds
-@item maint info bfds
-This prints information about each @code{bfd} object that is known to
-@value{GDBN}. @xref{Top, , BFD, bfd, The Binary File Descriptor Library}.
+@kindex maint info btrace
+@item maint info btrace
+Pint information about raw branch tracing data.
+
+@kindex maint btrace packet-history
+@item maint btrace packet-history
+Print the raw branch trace packets that are used to compute the
+execution history for the @samp{record btrace} command. Both the
+information and the format in which it is printed depend on the btrace
+recording format.
+
+@table @code
+@item bts
+For the BTS recording format, print a list of blocks of sequential
+code. For each block, the following information is printed:
+
+@table @asis
+@item Block number
+Newer blocks have higher numbers. The oldest block has number zero.
+@item Lowest @samp{PC}
+@item Highest @samp{PC}
+@end table
+
+@item pt
+For the Intel Processor Trace recording format, print a list of
+Intel Processor Trace packets. For each packet, the following
+information is printed:
+
+@table @asis
+@item Packet number
+Newer packets have higher numbers. The oldest packet has number zero.
+@item Trace offset
+The packet's offset in the trace stream.
+@item Packet opcode and payload
+@end table
+@end table
+
+@kindex maint btrace clear-packet-history
+@item maint btrace clear-packet-history
+Discards the cached packet history printed by the @samp{maint btrace
+packet-history} command. The history will be computed again when
+needed.
+
+@kindex maint btrace clear
+@item maint btrace clear
+Discard the branch trace data. The data will be fetched anew and the
+branch trace will be recomputed when needed.
+
+This implicitly truncates the branch trace to a single branch trace
+buffer. When updating branch trace incrementally, the branch trace
+available to @value{GDBN} may be bigger than a single branch trace
+buffer.
+
+@kindex maint set btrace pt skip-pad
+@item maint set btrace pt skip-pad
+@kindex maint show btrace pt skip-pad
+@item maint show btrace pt skip-pad
+Control whether @value{GDBN} will skip PAD packets when computing the
+packet history.
@kindex set displaced-stepping
@kindex show displaced-stepping
If @var{regexp} is specified, only expand symbol tables for file
names matching @var{regexp}.
+@kindex maint set catch-demangler-crashes
+@kindex maint show catch-demangler-crashes
+@cindex demangler crashes
+@item maint set catch-demangler-crashes [on|off]
+@itemx maint show catch-demangler-crashes
+Control whether @value{GDBN} should attempt to catch crashes in the
+symbol name demangler. The default is to attempt to catch crashes.
+If enabled, the first time a crash is caught, a core file is created,
+the offending symbol is displayed and the user is presented with the
+option to terminate the current session.
+
@kindex maint cplus first_component
@item maint cplus first_component @var{name}
Print the first C@t{++} class/namespace component of @var{name}.
@item maint cplus namespace
Print the list of possible C@t{++} namespaces.
-@kindex maint demangle
-@item maint demangle @var{name}
-Demangle a C@t{++} or Objective-C mangled @var{name}.
-
@kindex maint deprecate
@kindex maint undeprecate
@cindex deprecated commands
@kindex maint internal-error
@kindex maint internal-warning
+@kindex maint demangler-warning
+@cindex demangler crashes
@item maint internal-error @r{[}@var{message-text}@r{]}
@itemx maint internal-warning @r{[}@var{message-text}@r{]}
-Cause @value{GDBN} to call the internal function @code{internal_error}
-or @code{internal_warning} and hence behave as though an internal error
-or internal warning has been detected. In addition to reporting the
-internal problem, these functions give the user the opportunity to
-either quit @value{GDBN} or create a core file of the current
+@itemx maint demangler-warning @r{[}@var{message-text}@r{]}
+
+Cause @value{GDBN} to call the internal function @code{internal_error},
+@code{internal_warning} or @code{demangler_warning} and hence behave
+as though an internal problem has been detected. In addition to
+reporting the internal problem, these functions give the user the
+opportunity to either quit @value{GDBN} or (for @code{internal_error}
+and @code{internal_warning}) create a core file of the current
@value{GDBN} session.
These commands take an optional parameter @var{message-text} that is
@cindex @value{GDBN} internal error
@cindex internal errors, control of @value{GDBN} behavior
+@cindex demangler crashes
@kindex maint set internal-error
@kindex maint show internal-error
@kindex maint set internal-warning
@kindex maint show internal-warning
+@kindex maint set demangler-warning
+@kindex maint show demangler-warning
@item maint set internal-error @var{action} [ask|yes|no]
@itemx maint show internal-error @var{action}
@itemx maint set internal-warning @var{action} [ask|yes|no]
@itemx maint show internal-warning @var{action}
+@itemx maint set demangler-warning @var{action} [ask|yes|no]
+@itemx maint show demangler-warning @var{action}
When @value{GDBN} reports an internal problem (error or warning) it
gives the user the opportunity to both quit @value{GDBN} and create a
core file of the current @value{GDBN} session. These commands let you
@item corefile
You can specify that @value{GDBN} should always (yes) or never (no)
-create a core file. The default is to ask the user what to do.
+create a core file. The default is to ask the user what to do. Note
+that there is no @code{corefile} option for @code{demangler-warning}:
+demangler warnings always create a core file and this cannot be
+disabled.
@end table
@kindex maint packet
The program being debugged stopped while in a function called from GDB.
@dots{}
(@value{GDBP}) @kbd{maint print dummy-frames}
-0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
- top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@}
- call_lo=0x01014000 call_hi=0x01014001
+0xa8206d8: id=@{stack=0xbfffe734,code=0xbfffe73f,!special@}, ptid=process 9353
(@value{GDBP})
@end smallexample
match @var{regexp}. For each object file, this command prints its name,
address in memory, and all of its psymtabs and symtabs.
+@kindex maint print user-registers
+@cindex user registers
+@item maint print user-registers
+List all currently available @dfn{user registers}. User registers
+typically provide alternate names for actual hardware registers. They
+include the four ``standard'' registers @code{$fp}, @code{$pc},
+@code{$sp}, and @code{$ps}. @xref{standard registers}. User
+registers can be used in expressions in the same way as the canonical
+register names, but only the latter are listed by the @code{info
+registers} and @code{maint print registers} commands.
+
@kindex maint print section-scripts
@cindex info for known .debug_gdb_scripts-loaded scripts
@item maint print section-scripts [@var{regexp}]
a recursive definition of the data type as stored in @value{GDBN}'s
data structures, including its flags and contained types.
-@kindex maint set dwarf2 always-disassemble
-@kindex maint show dwarf2 always-disassemble
-@item maint set dwarf2 always-disassemble
-@item maint show dwarf2 always-disassemble
+@kindex maint selftest
+@cindex self tests
+Run any self tests that were compiled in to @value{GDBN}. This will
+print a message showing how many tests were run, and how many failed.
+
+@kindex maint set dwarf always-disassemble
+@kindex maint show dwarf always-disassemble
+@item maint set dwarf always-disassemble
+@item maint show dwarf always-disassemble
Control the behavior of @code{info address} when using DWARF debugging
information.
For more information on these expressions, see
@uref{http://www.dwarfstd.org/, the DWARF standard}.
-@kindex maint set dwarf2 max-cache-age
-@kindex maint show dwarf2 max-cache-age
-@item maint set dwarf2 max-cache-age
-@itemx maint show dwarf2 max-cache-age
-Control the DWARF 2 compilation unit cache.
+@kindex maint set dwarf max-cache-age
+@kindex maint show dwarf max-cache-age
+@item maint set dwarf max-cache-age
+@itemx maint show dwarf max-cache-age
+Control the DWARF compilation unit cache.
-@cindex DWARF 2 compilation units cache
+@cindex DWARF compilation units cache
In object files with inter-compilation-unit references, such as those
-produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
+produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF
reader needs to frequently refer to previously read compilation units.
This setting controls how long a compilation unit will remain in the
cache if it is not referenced. A higher limit means that cached
at thread local base, when using the @samp{info w32 thread-information-block}
command.
+@kindex maint set target-async
+@kindex maint show target-async
+@item maint set target-async
+@itemx maint show target-async
+This controls whether @value{GDBN} targets operate in synchronous or
+asynchronous mode (@pxref{Background Execution}). Normally the
+default is asynchronous, if it is available; but this can be changed
+to more easily debug problems occurring only in synchronous mode.
+
+@kindex maint set target-non-stop @var{mode} [on|off|auto]
+@kindex maint show target-non-stop
+@item maint set target-non-stop
+@itemx maint show target-non-stop
+
+This controls whether @value{GDBN} targets always operate in non-stop
+mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop
+Mode}). The default is @code{auto}, meaning non-stop mode is enabled
+if supported by the target.
+
+@table @code
+@item maint set target-non-stop auto
+This is the default mode. @value{GDBN} controls the target in
+non-stop mode if the target supports it.
+
+@item maint set target-non-stop on
+@value{GDBN} controls the target in non-stop mode even if the target
+does not indicate support.
+
+@item maint set target-non-stop off
+@value{GDBN} does not control the target in non-stop mode even if the
+target supports it.
+@end table
+
@kindex maint set per-command
@kindex maint show per-command
@item maint set per-command
* Thread List Format::
* Traceframe Info Format::
* Branch Trace Format::
+* Branch Trace Configuration Format::
@end menu
@node Overview
@item ?
@cindex @samp{?} packet
+@anchor{? packet}
Indicate the reason the target halted. The reply is the same as for
step and continue. This packet has a special interpretation when the
target is in non-stop mode; see @ref{Remote Non-Stop}.
@item c @r{[}@var{addr}@r{]}
@cindex @samp{c} packet
-Continue. @var{addr} is address to resume. If @var{addr} is omitted,
-resume at current address.
+Continue at @var{addr}, which is the address to resume. If @var{addr}
+is omitted, resume at current address.
This packet is deprecated for multi-threading support. @xref{vCont
packet}.
@item H @var{op} @var{thread-id}
@cindex @samp{H} packet
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
-@samp{G}, et.al.). @var{op} depends on the operation to be performed:
-it should be @samp{c} for step and continue operations (note that this
+@samp{G}, et.al.). Depending on the operation to be performed, @var{op}
+should be @samp{c} for step and continue operations (note that this
is deprecated, supporting the @samp{vCont} command is a better
-option), @samp{g} for other operations. The thread designator
+option), and @samp{g} for other operations. The thread designator
@var{thread-id} has the format and interpretation described in
@ref{thread-id syntax}.
@cindex @samp{k} packet
Kill request.
-FIXME: @emph{There is no description of how to operate when a specific
-thread context has been selected (i.e.@: does 'k' kill only that
-thread?)}.
+The exact effect of this packet is not specified.
+
+For a bare-metal target, it may power cycle or reset the target
+system. For that reason, the @samp{k} packet has no reply.
+
+For a single-process target, it may kill that process if possible.
+
+A multiple-process target may choose to kill just one process, or all
+that are under @value{GDBN}'s control. For more precise control, use
+the vKill packet (@pxref{vKill packet}).
+
+If the target system immediately closes the connection in response to
+@samp{k}, @value{GDBN} does not consider the lack of packet
+acknowledgment to be an error, and assumes the kill was successful.
+
+If connected using @kbd{target extended-remote}, and the target does
+not close the connection in response to a kill request, @value{GDBN}
+probes the target state as if a new connection was opened
+(@pxref{? packet}).
@item m @var{addr},@var{length}
@cindex @samp{m} packet
-Read @var{length} bytes of memory starting at address @var{addr}.
-Note that @var{addr} may not be aligned to any particular boundary.
+Read @var{length} addressable memory units starting at address @var{addr}
+(@pxref{addressable memory unit}). Note that @var{addr} may not be aligned to
+any particular boundary.
The stub need not use any particular size or alignment when gathering
data from memory for the response; even if @var{addr} is word-aligned
Reply:
@table @samp
@item @var{XX@dots{}}
-Memory contents; each byte is transmitted as a two-digit hexadecimal
-number. The reply may contain fewer bytes than requested if the
+Memory contents; each byte is transmitted as a two-digit hexadecimal number.
+The reply may contain fewer addressable memory units than requested if the
server was able to read only part of the region of memory.
@item E @var{NN}
@var{NN} is errno
@item M @var{addr},@var{length}:@var{XX@dots{}}
@cindex @samp{M} packet
-Write @var{length} bytes of memory starting at address @var{addr}.
-@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
-hexadecimal number.
+Write @var{length} addressable memory units starting at address @var{addr}
+(@pxref{addressable memory unit}). The data is given by @var{XX@dots{}}; each
+byte is transmitted as a two-digit hexadecimal number.
Reply:
@table @samp
@item R @var{XX}
@cindex @samp{R} packet
-Restart the program being debugged. @var{XX}, while needed, is ignored.
+Restart the program being debugged. The @var{XX}, while needed, is ignored.
This packet is only available in extended mode (@pxref{extended mode}).
The @samp{R} packet has no reply.
@item s @r{[}@var{addr}@r{]}
@cindex @samp{s} packet
-Single step. @var{addr} is the address at which to resume. If
+Single step, resuming at @var{addr}. If
@var{addr} is omitted, resume at same address.
This packet is deprecated for multi-threading support. @xref{vCont
@item t @var{addr}:@var{PP},@var{MM}
@cindex @samp{t} packet
Search backwards starting at address @var{addr} for a match with pattern
-@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
-@var{addr} must be at least 3 digits.
+@var{PP} and mask @var{MM}, both of which are are 4 byte long.
+There must be at least 3 digits in @var{addr}.
@item T @var{thread-id}
@cindex @samp{T} packet
The @samp{vCont} packet is not supported.
@end table
+@anchor{vCtrlC packet}
+@item vCtrlC
+@cindex @samp{vCtrlC} packet
+Interrupt remote target as if a control-C was pressed on the remote
+terminal. This is the equivalent to reacting to the @code{^C}
+(@samp{\003}, the control-C character) character in all-stop mode
+while the target is running, except this works in non-stop mode.
+@xref{interrupting remote targets}, for more info on the all-stop
+variant.
+
+Reply:
+@table @samp
+@item E @var{nn}
+for an error
+@item OK
+for success
+@end table
+
@item vFile:@var{operation}:@var{parameter}@dots{}
@cindex @samp{vFile} packet
Perform a file operation on the target system. For details,
@item vKill;@var{pid}
@cindex @samp{vKill} packet
-Kill the process with the specified process ID. @var{pid} is a
+@anchor{vKill packet}
+Kill the process with the specified process ID @var{pid}, which is a
hexadecimal integer identifying the process. This packet is used in
preference to @samp{k} when multiprocess protocol extensions are
supported; see @ref{multiprocess extensions}.
@anchor{X packet}
@cindex @samp{X} packet
Write data to memory, where the data is transmitted in binary.
-@var{addr} is address, @var{length} is number of bytes,
+Memory is specified by its address @var{addr} and number of addressable memory
+units @var{length} (@pxref{addressable memory unit});
@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
Reply:
conditions that should be taken into consideration when deciding if
the breakpoint trigger should be reported back to @var{GDBN}.
+See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason})
+for how to best report a memory breakpoint event to @value{GDBN}.
+
The @var{cond_list} parameter is comprised of a series of expressions,
concatenated without separators. Each expression has the following form:
address @var{addr}.
A hardware breakpoint is implemented using a mechanism that is not
-dependant on being able to modify the target's memory. @var{kind}
+dependant on being able to modify the target's memory. The @var{kind}
and @var{cond_list} have the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
@cindex @samp{z2} packet
@cindex @samp{Z2} packet
Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@cindex @samp{z3} packet
@cindex @samp{Z3} packet
Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@cindex @samp{z4} packet
@cindex @samp{Z4} packet
Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@itemize @bullet
@item
If @var{n} is a hexadecimal number, it is a register number, and the
-corresponding @var{r} gives that register's value. @var{r} is a
+corresponding @var{r} gives that register's value. The data @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
@item
If @var{n} is a recognized @dfn{stop reason}, it describes a more
specific event that stopped the target. The currently defined stop
-reasons are listed below. @var{aa} should be @samp{05}, the trap
+reasons are listed below. The @var{aa} should be @samp{05}, the trap
signal. At most one stop reason should be present.
@item
The packet indicates a watchpoint hit, and @var{r} is the data address, in
hex.
+@item syscall_entry
+@itemx syscall_return
+The packet indicates a syscall entry or return, and @var{r} is the
+syscall number, in hex.
+
@cindex shared library events, remote reply
@item library
The packet indicates that the loaded libraries have changed.
@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
-list of loaded libraries. @var{r} is ignored.
+list of loaded libraries. The @var{r} part is ignored.
@cindex replay log events, remote reply
@item replaylog
beginning when executing backward) of the log. The value of @var{r}
will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
for more information.
+
+@item swbreak
+@anchor{swbreak stop reason}
+The packet indicates a memory breakpoint instruction was executed,
+irrespective of whether it was @value{GDBN} that planted the
+breakpoint or the breakpoint is hardcoded in the program. The @var{r}
+part must be left empty.
+
+On some architectures, such as x86, at the architecture level, when a
+breakpoint instruction executes the program counter points at the
+breakpoint address plus an offset. On such targets, the stub is
+responsible for adjusting the PC to point back at the breakpoint
+address.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+This packet is required for correct non-stop mode operation.
+
+@item hwbreak
+The packet indicates the target stopped for a hardware breakpoint.
+The @var{r} part must be left empty.
+
+The same remarks about @samp{qSupported} and non-stop mode above
+apply.
+
+@cindex fork events, remote reply
+@item fork
+The packet indicates that @code{fork} was called, and @var{r}
+is the thread ID of the new child process. Refer to
+@ref{thread-id syntax} for the format of the @var{thread-id}
+field. This packet is only applicable to targets that support
+fork events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex vfork events, remote reply
+@item vfork
+The packet indicates that @code{vfork} was called, and @var{r}
+is the thread ID of the new child process. Refer to
+@ref{thread-id syntax} for the format of the @var{thread-id}
+field. This packet is only applicable to targets that support
+vfork events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex vforkdone events, remote reply
+@item vforkdone
+The packet indicates that a child process created by a vfork
+has either called @code{exec} or terminated, so that the
+address spaces of the parent and child process are no longer
+shared. The @var{r} part is ignored. This packet is only
+applicable to targets that support vforkdone events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex exec events, remote reply
+@item exec
+The packet indicates that @code{execve} was called, and @var{r}
+is the absolute pathname of the file that was executed, in hex.
+This packet is only applicable to targets that support exec events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex thread create event, remote reply
+@anchor{thread create event}
+@item create
+The packet indicates that the thread was just created. The new thread
+is stopped until @value{GDBN} sets it running with a resumption packet
+(@pxref{vCont packet}). This packet should not be sent by default;
+@value{GDBN} requests it with the @ref{QThreadEvents} packet. See
+also the @samp{w} (@ref{thread exit event}) remote reply below.
+
@end table
@item W @var{AA}
support for multiprocess protocol extensions; see @ref{multiprocess
extensions}. The @var{pid} is formatted as a big-endian hex string.
+@anchor{thread exit event}
+@cindex thread exit event, remote reply
+@item w @var{AA} ; @var{tid}
+
+The thread exited, and @var{AA} is the exit status. This response
+should not be sent by default; @value{GDBN} requests it with the
+@ref{QThreadEvents} packet. See also @ref{thread create event} above.
+
+@item N
+There are no resumed threads left in the target. In other words, even
+though the process is alive, the last resumed thread has exited. For
+example, say the target process has two threads: thread 1 and thread
+2. The client leaves thread 1 stopped, and resumes thread 2, which
+subsequently exits. At this point, even though the process is still
+alive, and thus no @samp{W} stop reply is sent, no thread is actually
+executing either. The @samp{N} stop reply thus informs the client
+that it can stop waiting for stop replies. This packet should not be
+sent by default; older @value{GDBN} versions did not support it.
+@value{GDBN} requests it, by supplying an appropriate
+@samp{qSupported} feature (@pxref{qSupported}). The remote stub must
+also supply the appropriate @samp{qSupported} feature indicating
+support.
+
@item O @var{XX}@dots{}
@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
written as the program's console output. This can happen at any time
@item qCRC:@var{addr},@var{length}
@cindex CRC of memory block, remote request
@cindex @samp{qCRC} packet
+@anchor{qCRC packet}
Compute the CRC checksum of a block of memory using CRC-32 defined in
IEEE 802.3. The CRC is computed byte at a time, taking the most
significant bit of each byte first. The initial pattern code
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QDisableRandomization} is not supported
Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
fields.
+@emph{Note: @value{GDBN} will send the @code{qfThreadInfo} query during the
+initial connection with the remote target, and the very first thread ID
+mentioned in the reply will be stopped by @value{GDBN} in a subsequent
+message. Therefore, the stub should ensure that the first thread ID in
+the @code{qfThreadInfo} reply is suitable for being stopped by @value{GDBN}.}
+
@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
@cindex get thread-local storage address, remote request
@cindex @samp{qGetTLSAddr} packet
local storage requested.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
returned; @var{done} (one hex digit) is zero to indicate more threads
and one indicates no further threads; @var{argthreadid} (eight hex
digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
-is a sequence of thread IDs from the target. @var{threadid} (eight hex
-digits). See @code{remote.c:parse_threadlist_response()}.
+is a sequence of thread IDs, @var{threadid} (eight hex
+digits), from the target. See @code{remote.c:parse_threadlist_response()}.
@end table
@item qOffsets
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QNonStop} is not supported by
Use of this packet is controlled by the @code{set non-stop} command;
@pxref{Non-Stop Mode}.
+@item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{}
+@itemx QCatchSyscalls:0
+@cindex catch syscalls from inferior, remote request
+@cindex @samp{QCatchSyscalls} packet
+@anchor{QCatchSyscalls}
+Enable (@samp{QCatchSyscalls:1}) or disable (@samp{QCatchSyscalls:0})
+catching syscalls from the inferior process.
+
+For @samp{QCatchSyscalls:1}, each listed syscall @var{sysno} (encoded
+in hex) should be reported to @value{GDBN}. If no syscall @var{sysno}
+is listed, every system call should be reported.
+
+Note that if a syscall not in the list is reported, @value{GDBN} will
+still filter the event according to its own list from all corresponding
+@code{catch syscall} commands. However, it is more efficient to only
+report the requested syscalls.
+
+Multiple @samp{QCatchSyscalls:1} packets do not combine; any earlier
+@samp{QCatchSyscalls:1} list is completely replaced by the new list.
+
+If the inferior process execs, the state of @samp{QCatchSyscalls} is
+kept for the new process too. On targets where exec may affect syscall
+numbers, for example with exec between 32 and 64-bit processes, the
+client should send a new packet with the new syscall list.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item @w{}
+An empty reply indicates that @samp{QCatchSyscalls} is not supported by
+the stub.
+@end table
+
+Use of this packet is controlled by the @code{set remote catch-syscalls}
+command (@pxref{Remote Configuration, set remote catch-syscalls}).
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
@cindex pass signals to inferior, remote request
@cindex @samp{QPassSignals} packet
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QPassSignals} is not supported by
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QProgramSignals} is not supported
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@anchor{QThreadEvents}
+@item QThreadEvents:1
+@itemx QThreadEvents:0
+@cindex thread create/exit events, remote request
+@cindex @samp{QThreadEvents} packet
+
+Enable (@samp{QThreadEvents:1}) or disable (@samp{QThreadEvents:0})
+reporting of thread create and exit events. @xref{thread create
+event}, for the reply specifications. For example, this is used in
+non-stop mode when @value{GDBN} stops a set of threads and
+synchronously waits for the their corresponding stop replies. Without
+exit events, if one of the threads exits, @value{GDBN} would hang
+forever not knowing that it should no longer expect a stop for that
+same thread. @value{GDBN} does not enable this feature unless the
+stub reports that it supports it by including @samp{QThreadEvents+} in
+its @samp{qSupported} reply.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. The error number @var{nn} is given as hex digits.
+
+@item @w{}
+An empty reply indicates that @samp{QThreadEvents} is not supported by
+the stub.
+@end table
+
+Use of this packet is controlled by the @code{set remote thread-events}
+command (@pxref{Remote Configuration, set remote thread-events}).
+
@item qRcmd,@var{command}
@cindex execute remote command, remote request
@cindex @samp{qRcmd} packet
@cindex @samp{qSearch memory} packet
@anchor{qSearch memory}
Search @var{length} bytes at @var{address} for @var{search-pattern}.
-@var{address} and @var{length} are encoded in hex.
-@var{search-pattern} is a sequence of bytes, hex encoded.
+Both @var{address} and @var{length} are encoded in hex;
+@var{search-pattern} is a sequence of bytes, also hex encoded.
Reply:
@table @samp
This feature indicates whether @value{GDBN} supports the
@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate
instruction reply packet}).
+
+@item swbreak
+This feature indicates whether @value{GDBN} supports the swbreak stop
+reason in stop replies. @xref{swbreak stop reason}, for details.
+
+@item hwbreak
+This feature indicates whether @value{GDBN} supports the hwbreak stop
+reason in stop replies. @xref{swbreak stop reason}, for details.
+
+@item fork-events
+This feature indicates whether @value{GDBN} supports fork event
+extensions to the remote protocol. @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{fork-events+} in its @samp{qSupported} reply.
+
+@item vfork-events
+This feature indicates whether @value{GDBN} supports vfork event
+extensions to the remote protocol. @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{vfork-events+} in its @samp{qSupported} reply.
+
+@item exec-events
+This feature indicates whether @value{GDBN} supports exec event
+extensions to the remote protocol. @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{exec-events+} in its @samp{qSupported} reply.
+
+@item vContSupported
+This feature indicates whether @value{GDBN} wants to know the
+supported actions in the reply to @samp{vCont?} packet.
@end table
Stubs should ignore any unknown values for
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:btrace-conf:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:exec-file:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:features:read}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab Yes
+@item @samp{Qbtrace:pt}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
+@item @samp{Qbtrace-conf:bts:size}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
+@item @samp{Qbtrace-conf:pt:size}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab Yes
+@item @samp{QCatchSyscalls}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{QPassSignals}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{swbreak}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{hwbreak}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{fork-events}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{vfork-events}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{exec-events}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{QThreadEvents}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{no-resumed}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer:btrace:read}
packet (@pxref{qXfer btrace read}).
+@item qXfer:btrace-conf:read
+The remote stub understands the @samp{qXfer:btrace-conf:read}
+packet (@pxref{qXfer btrace-conf read}).
+
+@item qXfer:exec-file:read
+The remote stub understands the @samp{qXfer:exec-file:read} packet
+(@pxref{qXfer executable filename read}).
+
@item qXfer:features:read
The remote stub understands the @samp{qXfer:features:read} packet
(@pxref{qXfer target description read}).
The remote stub understands the @samp{QNonStop} packet
(@pxref{QNonStop}).
+@item QCatchSyscalls
+The remote stub understands the @samp{QCatchSyscalls} packet
+(@pxref{QCatchSyscalls}).
+
@item QPassSignals
The remote stub understands the @samp{QPassSignals} packet
(@pxref{QPassSignals}).
@item Qbtrace:bts
The remote stub understands the @samp{Qbtrace:bts} packet.
+@item Qbtrace:pt
+The remote stub understands the @samp{Qbtrace:pt} packet.
+
+@item Qbtrace-conf:bts:size
+The remote stub understands the @samp{Qbtrace-conf:bts:size} packet.
+
+@item Qbtrace-conf:pt:size
+The remote stub understands the @samp{Qbtrace-conf:pt:size} packet.
+
+@item swbreak
+The remote stub reports the @samp{swbreak} stop reason for memory
+breakpoints.
+
+@item hwbreak
+The remote stub reports the @samp{hwbreak} stop reason for hardware
+breakpoints.
+
+@item fork-events
+The remote stub reports the @samp{fork} stop reason for fork events.
+
+@item vfork-events
+The remote stub reports the @samp{vfork} stop reason for vfork events
+and vforkdone events.
+
+@item exec-events
+The remote stub reports the @samp{exec} stop reason for exec events.
+
+@item vContSupported
+The remote stub reports the supported actions in the reply to
+@samp{vCont?} packet.
+
+@item QThreadEvents
+The remote stub understands the @samp{QThreadEvents} packet.
+
+@item no-resumed
+The remote stub reports the @samp{N} stop reply.
+
@end table
@item qSymbol::
@item qThreadExtraInfo,@var{thread-id}
@cindex thread attributes info, remote request
@cindex @samp{qThreadExtraInfo} packet
-Obtain a printable string description of a thread's attributes from
-the target OS. @var{thread-id} is a thread ID;
-see @ref{thread-id syntax}. This
+Obtain from the target OS a printable string description of thread
+attributes for the thread @var{thread-id}; see @ref{thread-id syntax},
+for the forms of @var{thread-id}. This
string may contain anything that the target OS thinks is interesting
for @value{GDBN} to tell the user about the thread. The string is
displayed in @value{GDBN}'s @code{info threads} display. Some
encoding of @var{annex} is specific to @var{object}; it can supply
additional details about what data to access.
-Here are the specific requests of this form defined so far. All
+Reply:
+@table @samp
+@item m @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the
+target. There may be more data at a higher address (although
+it is permitted to return @samp{m} even for the last valid
+block of data, as long as at least one byte of data was read).
+It is possible for @var{data} to have fewer bytes than the @var{length} in the
+request.
+
+@item l @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the target.
+There is no more data to be read. It is possible for @var{data} to
+have fewer bytes than the @var{length} in the request.
+
+@item l
+The @var{offset} in the request is at the end of the data.
+There is no more data to be read.
+
+@item E00
+The request was malformed, or @var{annex} was invalid.
+
+@item E @var{nn}
+The offset was invalid, or there was an error encountered reading the data.
+The @var{nn} part is a hex-encoded @code{errno} value.
+
+@item @w{}
+An empty reply indicates the @var{object} string was not recognized by
+the stub, or that the object does not support reading.
+@end table
+
+Here are the specific requests of this form defined so far. All the
@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
-formats, listed below.
+formats, listed above.
@table @samp
@item qXfer:auxv:read::@var{offset},@var{length}
@item new
Returns all available branch trace if the branch trace changed since
the last read request.
+
+@item delta
+Returns the new branch trace since the last read request. Adds a new
+block to the end of the trace that begins at zero and ends at the source
+location of the first branch in the trace buffer. This extra block is
+used to stitch traces together.
+
+If the trace buffer overflowed, returns an error indicating the overflow.
@end table
This packet is not probed by default; the remote stub must request it
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:btrace-conf:read::@var{offset},@var{length}
+@anchor{qXfer btrace-conf read}
+
+Return a description of the current branch trace configuration.
+@xref{Branch Trace Configuration Format}.
+
+This packet is not probed by default; the remote stub must request it
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
+@item qXfer:exec-file:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer executable filename read}
+Return the full absolute name of the file that was executed to create
+a process running on the remote system. The annex specifies the
+numeric process ID of the process to query, encoded as a hexadecimal
+number. If the annex part is empty the remote stub should return the
+filename corresponding to the currently executing process.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:features:read:@var{annex}:@var{offset},@var{length}
@anchor{qXfer target description read}
Access the @dfn{target description}. @xref{Target Descriptions}. The
@item qXfer:osdata:read::@var{offset},@var{length}
@anchor{qXfer osdata read}
-Access the target's @dfn{operating system information}.
+Access the target's @dfn{operating system information}.
@xref{Operating System Information}.
@end table
+@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@cindex write data into object, remote request
+@anchor{qXfer write}
+Write uninterpreted bytes into the target's special data area
+identified by the keyword @var{object}, starting at @var{offset} bytes
+into the data. The binary-encoded data (@pxref{Binary Data}) to be
+written is given by @var{data}@dots{}. The content and encoding of @var{annex}
+is specific to @var{object}; it can supply additional details about what data
+to access.
+
Reply:
@table @samp
-@item m @var{data}
-Data @var{data} (@pxref{Binary Data}) has been read from the
-target. There may be more data at a higher address (although
-it is permitted to return @samp{m} even for the last valid
-block of data, as long as at least one byte of data was read).
-@var{data} may have fewer bytes than the @var{length} in the
-request.
-
-@item l @var{data}
-Data @var{data} (@pxref{Binary Data}) has been read from the target.
-There is no more data to be read. @var{data} may have fewer bytes
-than the @var{length} in the request.
-
-@item l
-The @var{offset} in the request is at the end of the data.
-There is no more data to be read.
+@item @var{nn}
+@var{nn} (hex encoded) is the number of bytes written.
+This may be fewer bytes than supplied in the request.
@item E00
The request was malformed, or @var{annex} was invalid.
@item E @var{nn}
-The offset was invalid, or there was an error encountered reading the data.
-@var{nn} is a hex-encoded @code{errno} value.
+The offset was invalid, or there was an error encountered writing the data.
+The @var{nn} part is a hex-encoded @code{errno} value.
@item @w{}
-An empty reply indicates the @var{object} string was not recognized by
-the stub, or that the object does not support reading.
+An empty reply indicates the @var{object} string was not
+recognized by the stub, or that the object does not support writing.
@end table
-@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
-@cindex write data into object, remote request
-@anchor{qXfer write}
-Write uninterpreted bytes into the target's special data area
-identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. @var{data}@dots{} is the binary-encoded data
-(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
-is specific to @var{object}; it can supply additional details about what data
-to access.
-
-Here are the specific requests of this form defined so far. All
+Here are the specific requests of this form defined so far. All the
@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
-formats, listed below.
+formats, listed above.
@table @samp
@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{}
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
@end table
-Reply:
-@table @samp
-@item @var{nn}
-@var{nn} (hex encoded) is the number of bytes written.
-This may be fewer bytes than supplied in the request.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered writing the data.
-@var{nn} is a hex-encoded @code{errno} value.
-
-@item @w{}
-An empty reply indicates the @var{object} string was not
-recognized by the stub, or that the object does not support writing.
-@end table
-
@item qXfer:@var{object}:@var{operation}:@dots{}
Requests of this form may be added in the future. When a stub does
not recognize the @var{object} keyword, or its support for
@end table
@item Qbtrace:bts
-Enable branch tracing for the current thread using bts tracing.
+Enable branch tracing for the current thread using Branch Trace Store.
+
+Reply:
+@table @samp
+@item OK
+Branch tracing has been enabled.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
+@item Qbtrace:pt
+Enable branch tracing for the current thread using Intel Processor Trace.
Reply:
@table @samp
A badly formed request or an error was encountered.
@end table
+@item Qbtrace-conf:bts:size=@var{value}
+Set the requested ring buffer size for new threads that use the
+btrace recording method in bts format.
+
+Reply:
+@table @samp
+@item OK
+The ring buffer size has been set.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
+@item Qbtrace-conf:pt:size=@var{value}
+Set the requested ring buffer size for new threads that use the
+btrace recording method in pt format.
+
+Reply:
+@table @samp
+@item OK
+The ring buffer size has been set.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
@end table
@node Architecture-Specific Protocol Details
@cindex @samp{QTDP} packet
Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
-the tracepoint is disabled. @var{step} is the tracepoint's step
-count, and @var{pass} is its pass count. If an @samp{F} is present,
+the tracepoint is disabled. The @var{step} gives the tracepoint's step
+count, and @var{pass} gives its pass count. If an @samp{F} is present,
then the tracepoint is to be a fast tracepoint, and the @var{flen} is
the number of bytes that the target should copy elsewhere to make room
for the tracepoint. If an @samp{X} is present, it introduces a
@end table
@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
-Define actions to be taken when a tracepoint is hit. @var{n} and
+Define actions to be taken when a tracepoint is hit. The @var{n} and
@var{addr} must be the same as in the initial @samp{QTDP} packet for
this tracepoint. This packet may only be sent immediately after
another @samp{QTDP} packet that ended with a @samp{-}. If the
@table @samp
@item R @var{mask}
-Collect the registers whose bits are set in @var{mask}. @var{mask} is
+Collect the registers whose bits are set in @var{mask},
a hexadecimal number whose @var{i}'th bit is set if register number
@var{i} should be collected. (The least significant bit is numbered
zero.) Note that @var{mask} may be any number of digits long; it may
@item X @var{len},@var{expr}
Evaluate @var{expr}, whose length is @var{len}, and collect memory as
-it directs. @var{expr} is an agent expression, as described in
+it directs. The agent expression @var{expr} is as described in
@ref{Agent Expressions}. Each byte of the expression is encoded as a
two-digit hex number in the packet; @var{len} is the number of bytes
in the expression (and thus one-half the number of hex digits in the
@cindex @samp{QTDPsrc} packet
Specify a source string of tracepoint @var{n} at address @var{addr}.
This is useful to get accurate reproduction of the tracepoints
-originally downloaded at the beginning of the trace run. @var{type}
+originally downloaded at the beginning of the trace run. The @var{type}
is the name of the tracepoint part, such as @samp{cond} for the
tracepoint's conditional expression (see below for a list of types), while
@var{bytes} is the string, encoded in hexadecimal.
could cause @samp{tdump} not to work, or a particular trace frame not
be found.
-@item QTDV:@var{n}:@var{value}
+@item QTDV:@var{n}:@var{value}:@var{builtin}:@var{name}
@cindex define trace state variable, remote request
@cindex @samp{QTDV} packet
Create a new trace state variable, number @var{n}, with an initial
and @var{value} are encoded as hexadecimal values. @value{GDBN} has
the option of not using this packet for initial values of zero; the
target should simply create the trace state variables as they are
-mentioned in expressions.
+mentioned in expressions. The value @var{builtin} should be 1 (one)
+if the trace state variable is builtin and 0 (zero) if it is not builtin.
+@value{GDBN} only sets @var{builtin} to 1 if a previous @samp{qTfV} or
+@samp{qTsV} packet had it set. The contents of @var{name} is the
+hex-encoded name (without the leading @samp{$}) of the trace state
+variable.
@item QTFrame:@var{n}
@cindex @samp{QTFrame} packet
@item 0
The minimum instruction length is currently unknown.
@item @var{length}
-The minimum instruction length is @var{length}, where @var{length} is greater
-or equal to 1. @var{length} is a hexadecimal number. A reply of 1 means
-that a fast tracepoint may be placed on any instruction regardless of size.
+The minimum instruction length is @var{length}, where @var{length}
+is a hexadecimal number greater or equal to 1. A reply
+of 1 means that a fast tracepoint may be placed on any instruction
+regardless of size.
@item E
An error has occurred.
@item @w{}
@item terror:@var{text}:@var{tpnum}
The trace stopped because tracepoint @var{tpnum} had an error. The
string @var{text} is available to describe the nature of the error
-(for instance, a divide by zero in the condition expression).
-@var{text} is hex encoded.
+(for instance, a divide by zero in the condition expression); it
+is hex encoded.
@item tunknown:0
The trace stopped for some other reason.
@item l
(lower case letter @samp{L}) denotes end of list.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that the request is not supported by the
stub.
@end table
-@var{address} is encoded in hex.
+The @var{address} is encoded in hex;
@var{id} and @var{extra} are strings encoded in hex.
In response to each query, the target will reply with a list of one or
@item QTSave:@var{filename}
@cindex @samp{QTSave} packet
This packet directs the target to save trace data to the file name
-@var{filename} in the target's filesystem. @var{filename} is encoded
+@var{filename} in the target's filesystem. The @var{filename} is encoded
as a hex string; the interpretation of the file name (relative vs
absolute, wild cards, etc) is up to the target.
Replies:
@table @samp
@item qRelocInsn:@var{adjusted_size}
-Informs the stub the relocation is complete. @var{adjusted_size} is
+Informs the stub the relocation is complete. The @var{adjusted_size} is
the length in bytes of resulting relocated instruction sequence.
@item E @var{NN}
A badly formed request was detected, or an error was encountered while
@item F @var{result} [, @var{errno}] [; @var{attachment}]
@var{result} is the integer value returned by this operation, usually
non-negative for success and -1 for errors. If an error has occured,
-@var{errno} will be included in the result. @var{errno} will have a
+@var{errno} will be included in the result specifying a
value defined by the File-I/O protocol (@pxref{Errno Values}). For
operations which return data, @var{attachment} supplies the data as a
binary buffer. Binary buffers in response packets are escaped in the
These are the supported Host I/O operations:
@table @samp
-@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
-Open a file at @var{pathname} and return a file descriptor for it, or
-return -1 if an error occurs. @var{pathname} is a string,
+@item vFile:open: @var{filename}, @var{flags}, @var{mode}
+Open a file at @var{filename} and return a file descriptor for it, or
+return -1 if an error occurs. The @var{filename} is a string,
@var{flags} is an integer indicating a mask of open flags
(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
of mode bits to use if the file is created (@pxref{mode_t Values}).
which may be shorter than the length of @var{data}, or -1 if an
error occurred.
-@item vFile:unlink: @var{pathname}
-Delete the file at @var{pathname} on the target. Return 0,
-or -1 if an error occurs. @var{pathname} is a string.
+@item vFile:fstat: @var{fd}
+Get information about the open file corresponding to @var{fd}.
+On success the information is returned as a binary attachment
+and the return value is the size of this attachment in bytes.
+If an error occurs the return value is -1. The format of the
+returned binary attachment is as described in @ref{struct stat}.
+
+@item vFile:unlink: @var{filename}
+Delete the file at @var{filename} on the target. Return 0,
+or -1 if an error occurs. The @var{filename} is a string.
@item vFile:readlink: @var{filename}
Read value of symbolic link @var{filename} on the target. Return
number of target bytes read; the binary attachment may be longer if
some characters were escaped.
+@item vFile:setfs: @var{pid}
+Select the filesystem on which @code{vFile} operations with
+@var{filename} arguments will operate. This is required for
+@value{GDBN} to be able to access files on remote targets where
+the remote stub does not share a common filesystem with the
+inferior(s).
+
+If @var{pid} is nonzero, select the filesystem as seen by process
+@var{pid}. If @var{pid} is zero, select the filesystem as seen by
+the remote stub. Return 0 on success, or -1 if an error occurs.
+If @code{vFile:setfs:} indicates success, the selected filesystem
+remains selected until the next successful @code{vFile:setfs:}
+operation.
+
@end table
@node Interrupts
@section Interrupts
@cindex interrupts (remote protocol)
+@anchor{interrupting remote targets}
-When a program on the remote target is running, @value{GDBN} may
-attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or
-a @code{BREAK} followed by @code{g},
-control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}.
+In all-stop mode, when a program on the remote target is running,
+@value{GDBN} may attempt to interrupt it by sending a @samp{Ctrl-C},
+@code{BREAK} or a @code{BREAK} followed by @code{g}, control of which
+is specified via @value{GDBN}'s @samp{interrupt-sequence}.
The precise meaning of @code{BREAK} is defined by the transport
mechanism and may, in fact, be undefined. @value{GDBN} does not
When Linux kernel receives this sequence from serial port,
it stops execution and connects to gdb.
+In non-stop mode, because packet resumptions are asynchronous
+(@pxref{vCont packet}), @value{GDBN} is always free to send a remote
+command to the remote stub, even when the target is running. For that
+reason, @value{GDBN} instead sends a regular packet (@pxref{vCtrlC
+packet}) with the usual packet framing instead of the single byte
+@code{0x03}.
+
Stubs are not required to recognize these interrupt mechanisms and the
precise meaning associated with receipt of the interrupt is
implementation defined. If the target supports debugging of multiple
of successfully stopping the program in all-stop mode, and a stop reply
for each stopped thread in non-stop mode.
Interrupts received while the
-program is stopped are discarded.
+program is stopped are queued and the program will be interrupted when
+it is resumed next time.
@node Notification Packets
@section Notification Packets
@item @var{name}:@var{event}
The notification packet is sent by the side that initiates the
exchange (currently, only the stub does that), with @var{event}
-carrying the specific information about the notification.
-@var{name} is the name of the notification.
+carrying the specific information about the notification, and
+@var{name} specifying the name of the notification.
@item @var{ack}
The acknowledge sent by the other side, usually @value{GDBN}, to
acknowledge the exchange and request the event.
or if the target is not attached to any process, it shall respond
@samp{OK}.
+If the stub supports non-stop mode, it should also support the
+@samp{swbreak} stop reason if software breakpoints are supported, and
+the @samp{hwbreak} stop reason if hardware breakpoints are supported
+(@pxref{swbreak stop reason}). This is because given the asynchronous
+nature of non-stop mode, between the time a thread hits a breakpoint
+and the time the event is finally processed by @value{GDBN}, the
+breakpoint may have already been removed from the target. Due to
+this, @value{GDBN} needs to be able to tell whether a trap stop was
+caused by a delayed breakpoint event, which should be ignored, as
+opposed to a random trap signal, which should be reported to the user.
+Note the @samp{swbreak} feature implies that the target is responsible
+for adjusting the PC when a software breakpoint triggers, if
+necessary, such as on the x86 architecture.
+
@node Packet Acknowledgment
@section Packet Acknowledgment
@smallexample
<?xml version="1.0"?>
<threads>
- <thread id="id" core="0">
+ <thread id="id" core="0" name="name">
... description ...
</thread>
</threads>
Each @samp{thread} element must have the @samp{id} attribute that
identifies the thread (@pxref{thread-id syntax}). The
@samp{core} attribute, if present, specifies which processor core
-the thread was last executing on. The content of the of @samp{thread}
-element is interpreted as human-readable auxilliary information.
+the thread was last executing on. The @samp{name} attribute, if
+present, specifies the human-readable name of the thread. The content
+of the of @samp{thread} element is interpreted as human-readable
+auxiliary information.
@node Traceframe Info Format
@section Traceframe Info Format
The formal DTD for the branch trace format is given below:
@smallexample
-<!ELEMENT btrace (block)* >
+<!ELEMENT btrace (block* | pt) >
<!ATTLIST btrace version CDATA #FIXED "1.0">
<!ELEMENT block EMPTY>
<!ATTLIST block begin CDATA #REQUIRED
end CDATA #REQUIRED>
+
+<!ELEMENT pt (pt-config?, raw?)>
+
+<!ELEMENT pt-config (cpu?)>
+
+<!ELEMENT cpu EMPTY>
+<!ATTLIST cpu vendor CDATA #REQUIRED
+ family CDATA #REQUIRED
+ model CDATA #REQUIRED
+ stepping CDATA #REQUIRED>
+
+<!ELEMENT raw (#PCDATA)>
+@end smallexample
+
+@node Branch Trace Configuration Format
+@section Branch Trace Configuration Format
+@cindex branch trace configuration format
+
+For each inferior thread, @value{GDBN} can obtain the branch trace
+configuration using the @samp{qXfer:btrace-conf:read}
+(@pxref{qXfer btrace-conf read}) packet.
+
+The configuration describes the branch trace format and configuration
+settings for that format. The following information is described:
+
+@table @code
+@item bts
+This thread uses the @dfn{Branch Trace Store} (@acronym{BTS}) format.
+@table @code
+@item size
+The size of the @acronym{BTS} ring buffer in bytes.
+@end table
+@item pt
+This thread uses the @dfn{Intel Processor Trace} (@acronym{Intel
+PT}) format.
+@table @code
+@item size
+The size of the @acronym{Intel PT} ring buffer in bytes.
+@end table
+@end table
+
+@value{GDBN} must be linked with the Expat library to support XML
+branch trace configuration discovery. @xref{Expat}.
+
+The formal DTD for the branch trace configuration format is given below:
+
+@smallexample
+<!ELEMENT btrace-conf (bts?, pt?)>
+<!ATTLIST btrace-conf version CDATA #FIXED "1.0">
+
+<!ELEMENT bts EMPTY>
+<!ATTLIST bts size CDATA #IMPLIED>
+
+<!ELEMENT pt EMPTY>
+<!ATTLIST pt size CDATA #IMPLIED>
@end smallexample
@include agentexpr.texi
* Target Description Format:: The contents of a target description.
* Predefined Target Types:: Standard types available for target
descriptions.
+* Enum Target Types:: How to define enum target types.
* Standard Target Features:: Features @value{GDBN} knows about.
@end menu
interpret. The default interpretation is a two's complement integer,
but other types can be requested by name in the register description.
Some predefined types are provided by @value{GDBN} (@pxref{Predefined
-Target Types}), and the description can define additional composite types.
+Target Types}), and the description can define additional composite
+and enum types.
Each type element must have an @samp{id} attribute, which gives
a unique (within the containing @samp{<feature>}) name to the type.
@end smallexample
@cindex <struct>
+@cindex <flags>
If a register's value is composed from several separate values, define
-it with a structure type. There are two forms of the @samp{<struct>}
-element; a @samp{<struct>} element must either contain only bitfields
-or contain no bitfields. If the structure contains only bitfields,
-its total size in bytes must be specified, each bitfield must have an
-explicit start and end, and bitfields are automatically assigned an
-integer type. The field's @var{start} should be less than or
-equal to its @var{end}, and zero represents the least significant bit.
+it with either a structure type or a flags type.
+A flags type may only contain bitfields.
+A structure type may either contain only bitfields or contain no bitfields.
+If the value contains only bitfields, its total size in bytes must be
+specified.
+
+Non-bitfield values have a @var{name} and @var{type}.
@smallexample
-<struct id="@var{id}" size="@var{size}">
- <field name="@var{name}" start="@var{start}" end="@var{end}"/>
+<struct id="@var{id}">
+ <field name="@var{name}" type="@var{type}"/>
@dots{}
</struct>
@end smallexample
-If the structure contains no bitfields, then each field has an
-explicit type, and no implicit padding is added.
+Both @var{name} and @var{type} values are required.
+No implicit padding is added.
+
+Bitfield values have a @var{name}, @var{start}, @var{end} and @var{type}.
@smallexample
-<struct id="@var{id}">
- <field name="@var{name}" type="@var{type}"/>
+<struct id="@var{id}" size="@var{size}">
+ <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/>
@dots{}
</struct>
@end smallexample
-@cindex <flags>
-If a register's value is a series of single-bit flags, define it with
-a flags type. The @samp{<flags>} element has an explicit @var{size}
-and contains one or more @samp{<field>} elements. Each field has a
-@var{name}, a @var{start}, and an @var{end}. Only single-bit flags
-are supported.
-
@smallexample
<flags id="@var{id}" size="@var{size}">
- <field name="@var{name}" start="@var{start}" end="@var{end}"/>
+ <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/>
@dots{}
</flags>
@end smallexample
+The @var{name} value is required.
+Bitfield values may be named with the empty string, @samp{""},
+in which case the field is ``filler'' and its value is not printed.
+Not all bits need to be specified, so ``filler'' fields are optional.
+
+The @var{start} value is required, and @var{end} and @var{type}
+are optional.
+The field's @var{start} must be less than or equal to its @var{end},
+and zero represents the least significant bit.
+The default value of @var{end} is @var{start}, a single bit field.
+
+The default value of @var{type} depends on whether the
+@var{end} was specified. If @var{end} is specified then the default
+value of @var{type} is an unsigned integer. If @var{end} is unspecified
+then the default value of @var{type} is @code{bool}.
+
+Which to choose? Structures or flags?
+
+Registers defined with @samp{flags} have these advantages over
+defining them with @samp{struct}:
+
+@itemize @bullet
+@item
+Arithmetic may be performed on them as if they were integers.
+@item
+They are printed in a more readable fashion.
+@end itemize
+
+Registers defined with @samp{struct} have one advantage over
+defining them with @samp{flags}:
+
+@itemize @bullet
+@item
+One can fetch individual fields like in @samp{C}.
+
+@smallexample
+(gdb) print $my_struct_reg.field3
+$1 = 42
+@end smallexample
+
+@end itemize
+
@subsection Registers
@cindex <reg>
ABI.
@item type
-The type of the register. @var{type} may be a predefined type, a type
+The type of the register. It may be a predefined type, a type
defined in the current feature, or one of the special types @code{int}
and @code{float}. @code{int} is an integer type of the correct size
for @var{bitsize}, and @code{float} is a floating point type (in the
@var{bitsize}. The default is @code{int}.
@item group
-The register group to which this register belongs. @var{group} must
+The register group to which this register belongs. It must
be either @code{general}, @code{float}, or @code{vector}. If no
@var{group} is specified, @value{GDBN} will not display the register
in @code{info registers}.
@table @code
+@item bool
+Boolean type, occupying a single bit.
+
@item int8
@itemx int16
@itemx int32
@end table
+@node Enum Target Types
+@section Enum Target Types
+@cindex target descriptions, enum types
+
+Enum target types are useful in @samp{struct} and @samp{flags}
+register descriptions. @xref{Target Description Format}.
+
+Enum types have a name, size and a list of name/value pairs.
+
+@smallexample
+<enum id="@var{id}" size="@var{size}">
+ <evalue name="@var{name}" value="@var{value}"/>
+ @dots{}
+</enum>
+@end smallexample
+
+Enums must be defined before they are used.
+
+@smallexample
+<enum id="levels_type" size="4">
+ <evalue name="low" value="0"/>
+ <evalue name="high" value="1"/>
+</enum>
+<flags id="flags_type" size="4">
+ <field name="X" start="0"/>
+ <field name="LEVEL" start="1" end="1" type="levels_type"/>
+</flags>
+<reg name="flags" bitsize="32" type="flags_type"/>
+@end smallexample
+
+Given that description, a value of 3 for the @samp{flags} register
+would be printed as:
+
+@smallexample
+(gdb) info register flags
+flags 0x3 [ X LEVEL=high ]
+@end smallexample
+
@node Standard Target Features
@section Standard Target Features
@cindex target descriptions, standard features
* AArch64 Features::
* ARM Features::
* i386 Features::
+* MicroBlaze Features::
* MIPS Features::
* M68K Features::
+* NDS32 Features::
* Nios II Features::
* PowerPC Features::
* S/390 and System z Features::
@samp{ymm0h} through @samp{ymm15h} for amd64
@end itemize
-The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R)
+The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel
Memory Protection Extension (MPX). It should describe the following registers:
@itemize @minus
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.
+The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the
+@samp{org.gnu.gdb.i386.avx} feature. It should
+describe additional @sc{xmm} registers:
+
+@itemize @minus
+@item
+@samp{xmm16h} through @samp{xmm31h}, only valid for amd64.
+@end itemize
+
+It should describe the upper 128 bits of additional @sc{ymm} registers:
+
+@itemize @minus
+@item
+@samp{ymm16h} through @samp{ymm31h}, only valid for amd64.
+@end itemize
+
+It should
+describe the upper 256 bits of @sc{zmm} registers:
+
+@itemize @minus
+@item
+@samp{zmm0h} through @samp{zmm7h} for i386.
+@item
+@samp{zmm0h} through @samp{zmm15h} for amd64.
+@end itemize
+
+It should
+describe the additional @sc{zmm} registers:
+
+@itemize @minus
+@item
+@samp{zmm16h} through @samp{zmm31h}, only valid for amd64.
+@end itemize
+
+@node MicroBlaze Features
+@subsection MicroBlaze Features
+@cindex target descriptions, MicroBlaze features
+
+The @samp{org.gnu.gdb.microblaze.core} feature is required for MicroBlaze
+targets. It should contain registers @samp{r0} through @samp{r31},
+@samp{rpc}, @samp{rmsr}, @samp{rear}, @samp{resr}, @samp{rfsr}, @samp{rbtr},
+@samp{rpvr}, @samp{rpvr1} through @samp{rpvr11}, @samp{redr}, @samp{rpid},
+@samp{rzpr}, @samp{rtlbx}, @samp{rtlbsx}, @samp{rtlblo}, and @samp{rtlbhi}.
+
+The @samp{org.gnu.gdb.microblaze.stack-protect} feature is optional.
+If present, it should contain registers @samp{rshr} and @samp{rslr}
+
@node MIPS Features
@subsection @acronym{MIPS} Features
@cindex target descriptions, @acronym{MIPS} features
@samp{fpiaddr}.
@end table
+@node NDS32 Features
+@subsection NDS32 Features
+@cindex target descriptions, NDS32 features
+
+The @samp{org.gnu.gdb.nds32.core} feature is required for NDS32
+targets. It should contain at least registers @samp{r0} through
+@samp{r10}, @samp{r15}, @samp{fp}, @samp{gp}, @samp{lp}, @samp{sp},
+and @samp{pc}.
+
+The @samp{org.gnu.gdb.nds32.fpu} feature is optional. If present,
+it should contain 64-bit double-precision floating-point registers
+@samp{fd0} through @emph{fdN}, which should be @samp{fd3}, @samp{fd7},
+@samp{fd15}, or @samp{fd31} based on the FPU configuration implemented.
+
+@emph{Note:} The first sixteen 64-bit double-precision floating-point
+registers are overlapped with the thirty-two 32-bit single-precision
+floating-point registers. The 32-bit single-precision registers, if
+not being listed explicitly, will be synthesized from halves of the
+overlapping 64-bit double-precision registers. Listing 32-bit
+single-precision registers explicitly is deprecated, and the
+support to it could be totally removed some day.
+
@node Nios II Features
@subsection Nios II Features
@cindex target descriptions, Nios II features
contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
@samp{atia}, and @samp{tr0} through @samp{tr15}.
+The @samp{org.gnu.gdb.s390.vx} feature is optional. It should contain
+64-bit wide registers @samp{v0l} through @samp{v15l}, which will be
+combined by @value{GDBN} with the floating point registers @samp{f0}
+through @samp{f15} to present the 128-bit wide vector registers
+@samp{v0} through @samp{v15}. In addition, this feature should
+contain the 128-bit wide vector registers @samp{v16} through
+@samp{v31}.
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
ignore any line that it does not recognize. An empty line marks the end
of this section.
-@c FIXME add some specific types of data
+@table @code
+@item R @var{size}
+Specifies the size of a register block in bytes. This is equal to the
+size of a @code{g} packet payload in the remote protocol. @var{size}
+is an ascii decimal number. There should be only one such line in
+a single trace file.
+
+@item status @var{status}
+Trace status. @var{status} has the same format as a @code{qTStatus}
+remote packet reply. There should be only one such line in a single trace
+file.
+
+@item tp @var{payload}
+Tracepoint definition. The @var{payload} has the same format as
+@code{qTfP}/@code{qTsP} remote packet reply payload. A single tracepoint
+may take multiple lines of definition, corresponding to the multiple
+reply packets.
+
+@item tsv @var{payload}
+Trace state variable definition. The @var{payload} has the same format as
+@code{qTfV}/@code{qTsV} remote packet reply payload. A single variable
+may take multiple lines of definition, corresponding to the multiple
+reply packets.
+
+@item tdesc @var{payload}
+Target description in XML format. The @var{payload} is a single line of
+the XML file. All such lines should be concatenated together to get
+the original XML file. This file is in the same format as @code{qXfer}
+@code{features} payload, and corresponds to the main @code{target.xml}
+file. Includes are not allowed.
+
+@end table
The trace frame section consists of a number of consecutive frames.
Each frame begins with a two-byte tracepoint number, followed by a
@item R @var{bytes}
Register block. The number and ordering of bytes matches that of a
@code{g} packet in the remote protocol. Note that these are the
-actual bytes, in target order and @value{GDBN} register order, not a
-hexadecimal encoding.
+actual bytes, in target order, not a hexadecimal encoding.
@item M @var{address} @var{length} @var{bytes}...
Memory block. This is a contiguous block of memory, at the 8-byte
@c pod2man highlights the right hand side of the @item lines.
@table @env
-@item break [@var{file}:]@var{functiop}
+@item break [@var{file}:]@var{function}
Set a breakpoint at @var{function} (in @var{file}).
@item run [@var{arglist}]
This option is intended for @code{gdbserver} development and for bug reports to
the developers.
+@item --debug-format=option1@r{[},option2,...@r{]}
+Instruct @code{gdbserver} to include extra information in each line
+of debugging output.
+@xref{Other Command-Line Arguments for gdbserver}.
+
@item --wrapper
Specify a wrapper to launch programs
for debugging. The option should be followed by the name of the
projects / deliverable / binutils-gdb.git / blobdiff