\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2014 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars. However, you can override filename with makeinfo -o.
@setfilename gdb.info
@c
+@c man begin INCLUDE
@include gdb-cfg.texi
+@c man end
@c
@settitle Debugging with @value{GDBN}
@setchapternewpage odd
@dircategory Software development
@direntry
* Gdb: (gdb). The GNU debugger.
+* gdbserver: (gdb) Server. The GNU debugging server.
@end direntry
@copying
-Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
+@c man begin COPYRIGHT
+Copyright @copyright{} 1988-2014 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
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
+@c man end
@end copying
@ifnottex
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2013 Free Software Foundation, Inc.
+Copyright (C) 1988-2014 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
the operating system
* Trace File Format:: GDB trace file format
* Index Section Format:: .gdb_index section format
+* Man Pages:: Manual pages
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
This option causes @value{GDBN} to print its version number and
no-warranty blurb, and exit.
+@item -configuration
+@cindex @code{--configuration}
+This option causes @value{GDBN} to print details about its build-time
+configuration parameters, and then exit. These details can be
+important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}).
+
@end table
@node Startup
@end table
@c @end group
-Here are three miscellaneous @code{show} subcommands, all of which are
+Here are several miscellaneous @code{show} subcommands, all of which are
exceptional in lacking corresponding @code{set} commands:
@table @code
Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
if your version of @value{GDBN} comes with one.
+@kindex show configuration
+@item show configuration
+Display detailed information about the way @value{GDBN} was configured
+when it was built. This displays the optional arguments passed to the
+@file{configure} script and also configuration parameters detected
+automatically by @command{configure}. When reporting a @value{GDBN}
+bug (@pxref{GDB Bugs}), it is important to include this information in
+your report.
+
@end table
@node Running
(such as wildcard expansion or variable substitution) in describing
the arguments.
In Unix systems, you can control which shell is used with the
-@code{SHELL} environment variable.
-@xref{Arguments, ,Your Program's Arguments}.
+@code{SHELL} environment variable. If you do not define @code{SHELL},
+@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable
+use of any shell with the @code{set startup-with-shell} command (see
+below for details).
@item The @emph{environment.}
Your program normally inherits its environment from @value{GDBN}, but you can
This command is available when debugging locally on most targets, excluding
@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
+@kindex set startup-with-shell
+@item set startup-with-shell
+@itemx set startup-with-shell on
+@itemx set startup-with-shell off
+@itemx show set startup-with-shell
+On Unix systems, by default, if a shell is available on your target,
+@value{GDBN}) uses it to start your program. Arguments of the
+@code{run} command are passed to the shell, which does variable
+substitution, expands wildcard characters and performs redirection of
+I/O. In some circumstances, it may be useful to disable such use of a
+shell, for example, when debugging the shell itself or diagnosing
+startup failures such as:
+
+@smallexample
+(@value{GDBP}) run
+Starting program: ./a.out
+During startup program terminated with signal SIGSEGV, Segmentation fault.
+@end smallexample
+
+@noindent
+which indicates the shell or the wrapper specified with
+@samp{exec-wrapper} crashed, not your program. Most often, this is
+caused by something odd in your shell's non-interactive mode
+initialization file---such as @file{.cshrc} for C-shell,
+$@file{.zshenv} for the Z shell, or the file specified in the
+@samp{BASH_ENV} environment variable for BASH.
+
@kindex set disable-randomization
@item set disable-randomization
@itemx set disable-randomization on
@end table
@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
-the shell indicated
-by your @code{SHELL} environment variable if it exists (or
-@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
-that runs an initialization file---such as @file{.cshrc} for C-shell, or
-@file{.bashrc} for BASH---any variables you set in that file affect
-your program. You may wish to move setting of environment variables to
-files that are only run when you sign on, such as @file{.login} or
-@file{.profile}.
+the shell indicated by your @code{SHELL} environment variable if it
+exists (or @code{/bin/sh} if not). If your @code{SHELL} variable
+names a shell that runs an initialization file when started
+non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv}
+for the Z shell, or the file specified in the @samp{BASH_ENV}
+environment variable for BASH---any variables you set in that file
+affect your program. You may wish to move setting of environment
+variables to files that are only run when you sign on, such as
+@file{.login} or @file{.profile}.
@node Working Directory
@section Your Program's Working Directory
@kindex catch
@item catch @var{event}
Stop when @var{event} occurs. @var{event} can be any of the following:
+
@table @code
-@item throw
+@item throw @r{[}@var{regexp}@r{]}
+@itemx rethrow @r{[}@var{regexp}@r{]}
+@itemx catch @r{[}@var{regexp}@r{]}
+@kindex catch throw
+@kindex catch rethrow
+@kindex catch catch
@cindex stop on C@t{++} exceptions
-The throwing of a C@t{++} exception.
+The throwing, re-throwing, or catching of a C@t{++} exception.
+
+If @var{regexp} is given, then only exceptions whose type matches the
+regular expression will be caught.
+
+@vindex $_exception@r{, convenience variable}
+The convenience variable @code{$_exception} is available at an
+exception-related catchpoint, on some systems. This holds the
+exception being thrown.
+
+There are currently some limitations to C@t{++} exception handling in
+@value{GDBN}:
+
+@itemize @bullet
+@item
+The support for these commands is system-dependent. Currently, only
+systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are
+supported.
+
+@item
+The regular expression feature and the @code{$_exception} convenience
+variable rely on the presence of some SDT probes in @code{libstdc++}.
+If these probes are not present, then these features cannot be used.
+These probes were first available in the GCC 4.8 release, but whether
+or not they are available in your GCC also depends on how it was
+built.
+
+@item
+The @code{$_exception} convenience variable is only valid at the
+instruction at which an exception-related catchpoint is set.
+
+@item
+When an exception-related catchpoint is hit, @value{GDBN} stops at a
+location in the system library which implements runtime exception
+support for C@t{++}, usually @code{libstdc++}. You can use @code{up}
+(@pxref{Selection}) to get to your code.
+
+@item
+If you call a function interactively, @value{GDBN} normally returns
+control to you when the function has finished executing. If the call
+raises an exception, however, the call may bypass the mechanism that
+returns control to you and cause your program either to abort or to
+simply continue running until it hits a breakpoint, catches a signal
+that @value{GDBN} is listening for, or exits. This is the case even if
+you set a catchpoint for the exception; catchpoints on exceptions are
+disabled within interactive calls. @xref{Calling}, for information on
+controlling this with @code{set unwind-on-terminating-exception}.
+
+@item
+You cannot raise an exception interactively.
-@item catch
-The catching of a C@t{++} exception.
+@item
+You cannot install an exception handler interactively.
+@end itemize
@item exception
+@kindex catch exception
@cindex Ada exception catching
@cindex catch Ada exceptions
An Ada exception being raised. If an exception name is specified
Pck.Constraint_Error}.
@item exception unhandled
+@kindex catch exception unhandled
An exception that was raised but is not handled by the program.
@item assert
+@kindex catch assert
A failed Ada assertion.
@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.
@item syscall
@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
+@kindex catch syscall
@cindex break on a system call.
A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
syscall is a mechanism for application programs to request a service
Again, in this case @value{GDBN} would not be able to display syscall's names.
@item fork
+@kindex catch fork
A call to @code{fork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item vfork
+@kindex catch vfork
A call to @code{vfork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item load @r{[}regexp@r{]}
@itemx unload @r{[}regexp@r{]}
+@kindex catch load
+@kindex catch unload
The loading or unloading of a shared library. If @var{regexp} is
given, then the catchpoint will stop only if the regular expression
matches one of the affected libraries.
@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
+@kindex catch signal
The delivery of a signal.
With no arguments, this catchpoint will catch any signal that is not
@end table
@item tcatch @var{event}
+@kindex tcatch
Set a catchpoint that is enabled only for one stop. The catchpoint is
automatically deleted after the first time the event is caught.
Use the @code{info break} command to list the current catchpoints.
-There are currently some limitations to C@t{++} exception handling
-(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
-
-@itemize @bullet
-@item
-If you call a function interactively, @value{GDBN} normally returns
-control to you when the function has finished executing. If the call
-raises an exception, however, the call may bypass the mechanism that
-returns control to you and cause your program either to abort or to
-simply continue running until it hits a breakpoint, catches a signal
-that @value{GDBN} is listening for, or exits. This is the case even if
-you set a catchpoint for the exception; catchpoints on exceptions are
-disabled within interactive calls.
-
-@item
-You cannot raise an exception interactively.
-
-@item
-You cannot install an exception handler interactively.
-@end itemize
-
-@cindex raise exceptions
-Sometimes @code{catch} is not the best way to debug exception handling:
-if you need to know exactly where an exception is raised, it is better to
-stop @emph{before} the exception handler is called, since that way you
-can see the stack before any unwinding takes place. If you set a
-breakpoint in an exception handler instead, it may not be easy to find
-out where the exception was raised.
-
-To stop just before an exception handler is called, you need some
-knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
-raised by calling a library function named @code{__raise_exception}
-which has the following ANSI C interface:
-
-@smallexample
- /* @var{addr} is where the exception identifier is stored.
- @var{id} is the exception identifier. */
- void __raise_exception (void **addr, void *id);
-@end smallexample
-
-@noindent
-To make the debugger catch all exceptions before any stack
-unwinding takes place, set a breakpoint on @code{__raise_exception}
-(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
-
-With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
-that depends on the value of @var{id}, you can stop your program when
-a specific exception is raised. You can use multiple conditional
-breakpoints to stop your program when any of a number of exceptions are
-raised.
-
@node Delete Breaks
@subsection Deleting Breakpoints
proceed until the function returns.
An argument is a repeat count, as in @code{next}.
+
+@end table
+
+@anchor{range stepping}
+@cindex range stepping
+@cindex target-assisted range stepping
+By default, and if available, @value{GDBN} makes use of
+target-assisted @dfn{range stepping}. In other words, whenever you
+use a stepping command (e.g., @code{step}, @code{next}), @value{GDBN}
+tells the target to step the corresponding range of instruction
+addresses instead of issuing multiple single-steps. This speeds up
+line stepping, particularly for remote targets. Ideally, there should
+be no reason you would want to turn range stepping off. However, it's
+possible that a bug in the debug info, a bug in the remote stub (for
+remote targets), or even a bug in @value{GDBN} could make line
+stepping behave incorrectly when target-assisted range stepping is
+enabled. You can use the following command to turn off range stepping
+if necessary:
+
+@table @code
+@kindex set range-stepping
+@kindex show range-stepping
+@item set range-stepping
+@itemx show range-stepping
+Control whether range stepping is enabled.
+
+If @code{on}, and the target supports it, @value{GDBN} tells the
+target to step a range of addresses itself, instead of issuing
+multiple single-steps. If @code{off}, @value{GDBN} always issues
+single-steps, even if range stepping is supported by the target. The
+default is @code{on}.
+
@end table
@node Skipping Over Functions and Files
@end table
+Thread-specific breakpoints are automatically deleted when
+@value{GDBN} detects the corresponding thread is no longer in the
+thread list. For example:
+
+@smallexample
+(@value{GDBP}) c
+Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.
+@end smallexample
+
+There are several ways for a thread to disappear, such as a regular
+thread exit, but also when you detach from the process with the
+@code{detach} command (@pxref{Attach, ,Debugging an Already-running
+Process}), or if @value{GDBN} loses the remote connection
+(@pxref{Remote Debugging}), etc. Note that with some targets,
+@value{GDBN} is only able to detect a thread has exited when the user
+explictly asks for the thread list with the @code{info threads}
+command.
+
@node Interrupted System Calls
@subsection Interrupted System Calls
When the inferior process exits, or @value{GDBN} detaches from it,
process record and replay target will automatically stop itself.
+@kindex record goto
+@item record goto
+Go to a specific location in the execution log. There are several
+ways to specify the location to go to:
+
+@table @code
+@item record goto begin
+@itemx record goto start
+Go to the beginning of the execution log.
+
+@item record goto end
+Go to the end of the execution log.
+
+@item record goto @var{n}
+Go to instruction number @var{n} in the execution log.
+@end table
+
@kindex record save
@item record save @var{filename}
Save the execution log to a file @file{@var{filename}}.
@kindex set record full
@item set record full insn-number-max @var{limit}
+@itemx set record full insn-number-max unlimited
Set the limit of instructions to be recorded for the @code{full}
recording method. Default value is 200000.
lets you control what happens when the limit is reached, by means of
the @code{stop-at-limit} option, described below.)
-If @var{limit} is zero, @value{GDBN} will never delete recorded
-instructions from the execution log. The number of recorded
-instructions is unlimited in this case.
+If @var{limit} is @code{unlimited} or zero, @value{GDBN} will never
+delete recorded instructions from the execution log. The number of
+recorded instructions is limited only by the available memory.
@kindex show record full
@item show record full insn-number-max
This command may not be available for all recording methods.
@kindex set record
-@item set record instruction-history-size
+@item set record instruction-history-size @var{size}
+@itemx set record instruction-history-size unlimited
Define how many instructions to disassemble in the @code{record
instruction-history} command. The default value is 10.
+A @var{size} of @code{unlimited} means unlimited instructions.
@kindex show record
@item show record instruction-history-size
This command may not be available for all recording methods.
-@item set record function-call-history-size
+@item set record function-call-history-size @var{size}
+@itemx set record function-call-history-size unlimited
Define how many lines to print in the
@code{record function-call-history} command. The default value is 10.
+A size of @code{unlimited} means unlimited lines.
@item show record function-call-history-size
Show how many lines to print in the
@menu
* Frames:: Stack frames
* Backtrace:: Backtraces
+* Frame Filter Management:: Managing frame filters
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
frame (frame zero), followed by its caller (frame one), and on up the
stack.
+@anchor{backtrace-command}
@table @code
@kindex backtrace
@kindex bt @r{(@code{backtrace})}
@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.
+
+@item backtrace no-filters
+@itemx bt no-filters
+@itemx bt no-filters @var{n}
+@itemx bt no-filters -@var{n}
+@itemx bt no-filters full
+@itemx bt no-filters full @var{n}
+@itemx bt no-filters full -@var{n}
+Do not run Python frame filters on this backtrace. @xref{Frame
+Filter API}, for more information. Additionally use @ref{disable
+frame-filter all} to turn off all frame filters. This is only
+relevant when @value{GDBN} has been configured with @code{Python}
+support.
@end table
@kindex where
@item set backtrace limit @var{n}
@itemx set backtrace limit 0
+@itemx set backtrace limit unlimited
@cindex backtrace limit
-Limit the backtrace to @var{n} levels. A value of zero means
-unlimited.
+Limit the backtrace to @var{n} levels. A value of @code{unlimited}
+or zero means unlimited levels.
@item show backtrace limit
Display the current limit on backtrace levels.
Show the current way to display filenames.
@end table
+@node Frame Filter Management
+@section Management of Frame Filters.
+@cindex managing frame filters
+
+Frame filters are Python based utilities to manage and decorate the
+output of frames. @xref{Frame Filter API}, for further information.
+
+Managing frame filters is performed by several commands available
+within @value{GDBN}, detailed here.
+
+@table @code
+@kindex info frame-filter
+@item info frame-filter
+Print a list of installed frame filters from all dictionaries, showing
+their name, priority and enabled status.
+
+@kindex disable frame-filter
+@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} 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 disabled. @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} 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
+filter and is used when @code{all} is not the option for
+@var{filter-dictionary}.
+
+Example:
+
+@smallexample
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 No PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 Yes BuildProgra Filter
+
+(gdb) disable frame-filter /build/test BuildProgramFilter
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 No PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+
+(gdb) enable frame-filter global PrimaryFunctionFilter
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 Yes PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+@end smallexample
+
+@kindex set frame-filter priority
+@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},
+@code{progspace} or the name of the object file where the frame filter
+dictionary resides. @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},
+@code{progspace} or the name of the object file where the frame filter
+dictionary resides.
+
+Example:
+
+@smallexample
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 Yes PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+
+(gdb) set frame-filter priority global Reverse 50
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 Yes PrimaryFunctionFilter
+ 50 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+@end smallexample
+@end table
+
@node Selection
@section Selecting a Frame
@table @code
@kindex set listsize
@item set listsize @var{count}
+@itemx set listsize unlimited
Make the @code{list} command display @var{count} source lines (unless
the @code{list} argument explicitly specifies some other number).
-Setting @var{count} to 0 means there's no limit.
+Setting @var{count} to @code{unlimited} or 0 means there's no limit.
@kindex show listsize
@item show listsize
* Core File Generation:: Cause a program dump its core
* Character Sets:: Debugging programs that use a different
character set than GDB does
-* Caching Remote Data:: Data caching for remote targets
+* Caching Target Data:: Data caching for targets
* Searching Memory:: Searching memory for a sequence of bytes
@end menu
@end smallexample
@cindex C@t{++} scope resolution
-These uses of @samp{::} are very rarely in conflict with the very similar
-use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
-scope resolution operator in @value{GDBN} expressions.
-@c FIXME: Um, so what happens in one of those rare cases where it's in
-@c conflict?? --mew
+These uses of @samp{::} are very rarely in conflict with the very
+similar use of the same notation in C@t{++}. When they are in
+conflict, the C@t{++} meaning takes precedence; however, this can be
+overridden by quoting the file or function name with single quotes.
+
+For example, suppose the program is stopped in a method of a class
+that has a field named @code{includefile}, and there is also an
+include file named @file{includefile} that defines a variable,
+@code{some_global}.
+
+@smallexample
+(@value{GDBP}) p includefile
+$1 = 23
+(@value{GDBP}) p includefile::some_global
+A syntax error in expression, near `'.
+(@value{GDBP}) p 'includefile'::some_global
+$2 = 27
+@end smallexample
@cindex wrong values
@cindex variable values, wrong
strings. Single-byte members of a vector are displayed as an integer
array.
+@item z
+Like @samp{x} formatting, the value is treated as an integer and
+printed as hexadecimal, but leading zeros are printed to pad the value
+to the size of the integer type.
+
@item r
@cindex raw printing
Print using the @samp{raw} formatting. By default, @value{GDBN} will
@table @code
@item set print max-symbolic-offset @var{max-offset}
+@itemx set print max-symbolic-offset unlimited
@cindex maximum value for offset of closest symbol
Tell @value{GDBN} to only display the symbolic form of an address if the
offset between the closest earlier symbol and the address is less than
-@var{max-offset}. The default is 0, which tells @value{GDBN}
-to always print the symbolic form of an address if any symbol precedes it.
+@var{max-offset}. The default is @code{unlimited}, which tells @value{GDBN}
+to always print the symbolic form of an address if any symbol precedes
+it. Zero is equivalent to @code{unlimited}.
@item show print max-symbolic-offset
Ask how large the maximum offset is that @value{GDBN} prints in a
arrays.
@item set print elements @var{number-of-elements}
+@itemx set print elements unlimited
@cindex number of array elements to print
@cindex limit on number of printed array elements
Set a limit on how many elements of an array @value{GDBN} will print.
printed the number of elements set by the @code{set print elements} command.
This limit also applies to the display of strings.
When @value{GDBN} starts, this limit is set to 200.
-Setting @var{number-of-elements} to zero means that the printing is unlimited.
+Setting @var{number-of-elements} to @code{unlimited} or zero means
+that the number of elements to print is unlimited.
@item show print elements
Display the number of elements of a large array that @value{GDBN} will print.
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
+@item set print raw frame-arguments on
+Print frame arguments in raw, non pretty-printed, form.
+
+@item set print raw frame-arguments off
+Print frame arguments in pretty-printed form, if there is a pretty-printer
+for the value (@pxref{Pretty Printing}),
+otherwise print the value in raw form.
+This is the default.
+
+@item show print raw frame-arguments
+Show whether to print frame arguments in raw form.
+
@anchor{set print entry-values}
@item set print entry-values @var{value}
@kindex set print entry-values
Show the method being used for printing of frame argument values at function
entry.
-@item set print repeats
+@item set print repeats @var{number-of-repeats}
+@itemx set print repeats unlimited
@cindex repeated array elements
Set the threshold for suppressing display of repeated array
elements. When the number of consecutive identical elements of an
array exceeds the threshold, @value{GDBN} prints the string
@code{"<repeats @var{n} times>"}, where @var{n} is the number of
identical repetitions, instead of displaying the identical elements
-themselves. Setting the threshold to zero will cause all elements to
-be individually printed. The default threshold is 10.
+themselves. Setting the threshold to @code{unlimited} or zero will
+cause all elements to be individually printed. The default threshold
+is 10.
@item show print repeats
Display the current threshold for printing repeated identical
@item $_exitcode
@vindex $_exitcode@r{, convenience variable}
-The variable @code{$_exitcode} is automatically set to the exit code when
-the program being debugged terminates.
+When the program being debugged terminates normally, @value{GDBN}
+automatically sets this variable to the exit code of the program, and
+resets @code{$_exitsignal} to @code{void}.
+
+@item $_exitsignal
+@vindex $_exitsignal@r{, convenience variable}
+When the program being debugged dies due to an uncaught signal,
+@value{GDBN} automatically sets this variable to that signal's number,
+and resets @code{$_exitcode} to @code{void}.
+
+To distinguish between whether the program being debugged has exited
+(i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e.,
+@code{$_exitsignal} is not @code{void}), the convenience function
+@code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience
+Functions}). For example, considering the following source code:
+
+@smallexample
+#include <signal.h>
+
+int
+main (int argc, char *argv[])
+@{
+ raise (SIGALRM);
+ return 0;
+@}
+@end smallexample
+
+A valid way of telling whether the program being debugged has exited
+or signalled would be:
+
+@smallexample
+(@value{GDBP}) define has_exited_or_signalled
+Type commands for definition of ``has_exited_or_signalled''.
+End with a line saying just ``end''.
+>if $_isvoid ($_exitsignal)
+ >echo The program has exited\n
+ >else
+ >echo The program has signalled\n
+ >end
+>end
+(@value{GDBP}) run
+Starting program:
+
+Program terminated with signal SIGALRM, Alarm clock.
+The program no longer exists.
+(@value{GDBP}) has_exited_or_signalled
+The program has signalled
+@end smallexample
+
+As can be seen, @value{GDBN} correctly informs that the program being
+debugged has signalled, since it calls @code{raise} and raises a
+@code{SIGALRM} signal. If the program being debugged had not called
+@code{raise}, then @value{GDBN} would report a normal exit:
+
+@smallexample
+(@value{GDBP}) has_exited_or_signalled
+The program has exited
+@end smallexample
+
+@item $_exception
+The variable @code{$_exception} is set to the exception object being
+thrown at an exception-related catchpoint. @xref{Set Catchpoints}.
@item $_probe_argc
@itemx $_probe_arg0@dots{}$_probe_arg11
however, a convenience function is implemented internally to
@value{GDBN}.
+These functions do not require @value{GDBN} to be configured with
+@code{Python} support, which means that they are always available.
+
+@table @code
+
+@item $_isvoid (@var{expr})
+@findex $_isvoid@r{, convenience function}
+Return one if the expression @var{expr} is @code{void}. Otherwise it
+returns zero.
+
+A @code{void} expression is an expression where the type of the result
+is @code{void}. For example, you can examine a convenience variable
+(see @ref{Convenience Vars,, Convenience Variables}) to check whether
+it is @code{void}:
+
+@smallexample
+(@value{GDBP}) print $_exitcode
+$1 = void
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$2 = 1
+(@value{GDBP}) run
+Starting program: ./a.out
+[Inferior 1 (process 29572) exited normally]
+(@value{GDBP}) print $_exitcode
+$3 = 0
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$4 = 0
+@end smallexample
+
+In the example above, we used @code{$_isvoid} to check whether
+@code{$_exitcode} is @code{void} before and after the execution of the
+program being debugged. Before the execution there is no exit code to
+be examined, therefore @code{$_exitcode} is @code{void}. After the
+execution the program being debugged returned zero, therefore
+@code{$_exitcode} is zero, which means that it is not @code{void}
+anymore.
+
+The @code{void} expression can also be a call of a function from the
+program being debugged. For example, given the following function:
+
+@smallexample
+void
+foo (void)
+@{
+@}
+@end smallexample
+
+The result of calling it inside @value{GDBN} is @code{void}:
+
+@smallexample
+(@value{GDBP}) print foo ()
+$1 = void
+(@value{GDBP}) print $_isvoid (foo ())
+$2 = 1
+(@value{GDBP}) set $v = foo ()
+(@value{GDBP}) print $v
+$3 = void
+(@value{GDBP}) print $_isvoid ($v)
+$4 = 1
+@end smallexample
+
+@end table
+
These functions require @value{GDBN} to be configured with
@code{Python} support.
true contents of hardware registers, you must select the innermost
frame (with @samp{frame 0}).
-However, @value{GDBN} must deduce where registers are saved, from the machine
-code generated by your compiler. If some registers are not saved, or if
-@value{GDBN} is unable to locate the saved registers, the selected stack
-frame makes no difference.
+@cindex caller-saved registers
+@cindex call-clobbered registers
+@cindex volatile registers
+@cindex <not saved> values
+Usually ABIs reserve some registers as not needed to be saved by the
+callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile''
+registers). It may therefore not be possible for @value{GDBN} to know
+the value a register had before the call (in other words, in the outer
+frame), if the register value has since been changed by the callee.
+@value{GDBN} tries to deduce where the inner frame saved
+(``callee-saved'') registers, from the debug info, unwind info, or the
+machine code generated by your compiler. If some register is not
+saved, and @value{GDBN} knows the register is ``caller-saved'' (via
+its own knowledge of the ABI, or because the debug/unwind info
+explicitly says the register's value is undefined), @value{GDBN}
+displays @w{@samp{<not saved>}} as the register's value. With targets
+that @value{GDBN} has no knowledge of the register saving convention,
+if a register was not saved by the callee, then its value and location
+in the outer frame are assumed to be the same of the inner frame.
+This is usually harmless, because if the register is call-clobbered,
+the caller either does not care what is in the register after the
+call, or has code to restore the value that it does care about. Note,
+however, that if you change such a register in the outer frame, you
+may also be affecting the inner frame. Also, the more ``outer'' the
+frame is you're looking at, the more likely a call-clobbered
+register's value is to be wrong, in the sense that it doesn't actually
+represent the value the register had just before the call.
@node Floating Point Hardware
@section Floating Point Hardware
The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
character.
-@node Caching Remote Data
-@section Caching Data of Remote Targets
-@cindex caching data of remote targets
-
-@value{GDBN} caches data exchanged between the debugger and a
-remote target (@pxref{Remote Debugging}). Such caching generally improves
-performance, because it reduces the overhead of the remote protocol by
-bundling memory reads and writes into large chunks. Unfortunately, simply
-caching everything would lead to incorrect results, since @value{GDBN}
-does not necessarily know anything about volatile values, memory-mapped I/O
-addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
-memory can be changed @emph{while} a gdb command is executing.
+@node Caching Target Data
+@section Caching Data of Targets
+@cindex caching data of targets
+
+@value{GDBN} caches data exchanged between the debugger and a target.
+Each cache is associated with the address space of the inferior.
+@xref{Inferiors and Programs}, about inferior and address space.
+Such caching generally improves performance in remote debugging
+(@pxref{Remote Debugging}), because it reduces the overhead of the
+remote protocol by bundling memory reads and writes into large chunks.
+Unfortunately, simply caching everything would lead to incorrect results,
+since @value{GDBN} does not necessarily know anything about volatile
+values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode
+(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command
+is executing.
Therefore, by default, @value{GDBN} only caches data
known to be on the stack@footnote{In non-stop mode, it is moderately
rare for a running thread to modify the stack of a stopped thread
in a way that would interfere with a backtrace, and caching of
-stack reads provides a significant speed up of remote backtraces.}.
+stack reads provides a significant speed up of remote backtraces.} or
+in the code segment.
Other regions of memory can be explicitly marked as
-cacheable; see @pxref{Memory Region Attributes}.
+cacheable; @pxref{Memory Region Attributes}.
@table @code
@kindex set remotecache
@kindex set stack-cache
@item set stack-cache on
@itemx set stack-cache off
-Enable or disable caching of stack accesses. When @code{ON}, use
-caching. By default, this option is @code{ON}.
+Enable or disable caching of stack accesses. When @code{on}, use
+caching. By default, this option is @code{on}.
@kindex show stack-cache
@item show stack-cache
Show the current state of data caching for memory accesses.
+@kindex set code-cache
+@item set code-cache on
+@itemx set code-cache off
+Enable or disable caching of code segment accesses. When @code{on},
+use caching. By default, this option is @code{on}. This improves
+performance of disassembly in remote debugging.
+
+@kindex show code-cache
+@item show code-cache
+Show the current state of target memory cache for code segment
+accesses.
+
@kindex info dcache
@item info dcache @r{[}line@r{]}
-Print the information about the data cache performance. The
-information displayed includes the dcache width and depth, and for
-each cache line, its number, address, and how many times it was
-referenced. This command is useful for debugging the data cache
-operation.
+Print the information about the performance of data cache of the
+current inferior's address space. The information displayed
+includes the dcache width and depth, and for each cache line, its
+number, address, and how many times it was referenced. This
+command is useful for debugging the data cache operation.
If a line number is specified, the contents of that line will be
printed in hex.
@item show dcache size
@kindex show dcache size
-Show maximum number of dcache entries. See also @ref{Caching Remote Data, info dcache}.
+Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}.
@item show dcache line-size
@kindex show dcache line-size
-Show default size of dcache lines. See also @ref{Caching Remote Data, info dcache}.
+Show default size of dcache lines.
@end table
@table @code
@item set trace-buffer-size @var{n}
+@itemx set trace-buffer-size unlimited
@kindex set trace-buffer-size
Request that the target use a trace buffer of @var{n} bytes. Not all
targets will honor the request; they may have a compiled-in size for
the trace buffer, or some other limitation. Set to a value of
-@code{-1} to let the target use whatever size it likes. This is also
-the default.
+@code{unlimited} or @code{-1} to let the target use whatever size it
+likes. This is also the default.
@item show trace-buffer-size
@kindex show trace-buffer-size
@kindex target tfile
@kindex tfile
+@kindex target ctf
+@kindex ctf
@item target tfile @var{filename}
-Use the file named @var{filename} as a source of trace data. Commands
-that examine data work as they do with 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} must be
-on a filesystem accessible to the host.
+@itemx target ctf @var{dirname}
+Use the file named @var{filename} or directory named @var{dirname} as
+a source of trace data. Commands that examine data work as they do with
+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
+the host.
+
+@smallexample
+(@value{GDBP}) target ctf ctf.ctf
+(@value{GDBP}) tfind
+Found trace frame 0, tracepoint 2
+39 ++a; /* set tracepoint 1 here */
+(@value{GDBP}) tdump
+Data collected at tracepoint 2, trace frame 0:
+i = 0
+a = 0
+b = 1 '\001'
+c = @{"123", "456", "789", "123", "456", "789"@}
+d = @{@{@{a = 1, b = 2@}, @{a = 3, b = 4@}@}, @{@{a = 5, b = 6@}, @{a = 7, b = 8@}@}@}
+(@value{GDBP}) p b
+$1 = 1
+@end smallexample
@end table
@table @code
@item show language
+@anchor{show language}
@kindex show language
Display the current working language. This is the
language you can use with commands such as @code{print} to
@cindex C@t{++} exception handling
@item catch throw
+@itemx catch rethrow
@itemx catch catch
Debug C@t{++} exception handling using these commands. @xref{Set
Catchpoints, , Setting Catchpoints}.
There are two encodings in use, depending on the architecture: BID (Binary
Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
-PowerPC. @value{GDBN} will use the appropriate encoding for the configured
-target.
+PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the
+configured target.
Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
to manipulate decimal floating point numbers, it is not possible to convert
* Omissions from Ada:: Restrictions on the Ada expression syntax.
* Additions to Ada:: Extensions of the Ada expression syntax.
* Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Exceptions:: Ada Exceptions
* Ada Tasks:: Listing and setting breakpoints in tasks.
* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
* Ravenscar Profile:: Tasking Support when using the Ravenscar
elaboration, simply use the following two commands:
@code{tbreak adainit} and @code{run}.
+@node Ada Exceptions
+@subsubsection Ada Exceptions
+
+A command is provided to list all Ada exceptions:
+
+@table @code
+@kindex info exceptions
+@item info exceptions
+@itemx info exceptions @var{regexp}
+The @code{info exceptions} command allows you to list all Ada exceptions
+defined within the program being debugged, as well as their addresses.
+With a regular expression, @var{regexp}, as argument, only those exceptions
+whose names match @var{regexp} are listed.
+@end table
+
+Below is a small example, showing how the command can be used, first
+without argument, and next with a regular expression passed as an
+argument.
+
+@smallexample
+(@value{GDBP}) info exceptions
+All defined Ada exceptions:
+constraint_error: 0x613da0
+program_error: 0x613d20
+storage_error: 0x613ce0
+tasking_error: 0x613ca0
+const.aint_global_e: 0x613b00
+(@value{GDBP}) info exceptions const.aint
+All Ada exceptions matching regular expression "const.aint":
+constraint_error: 0x613da0
+const.aint_global_e: 0x613b00
+@end smallexample
+
+It is also possible to ask @value{GDBN} to stop your program's execution
+when an exception is raised. For more details, see @ref{Set Catchpoints}.
+
@node Ada Tasks
@subsubsection Extensions for Ada Tasks
@cindex Ada, tasking
@cindex symbol dump
@kindex maint print psymbols
@cindex partial symbol dump
+@kindex maint print msymbols
+@cindex minimal symbol dump
@item maint print symbols @var{filename}
@itemx maint print psymbols @var{filename}
@itemx maint print msymbols @var{filename}
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
@code{add-symbol-file} command any number of times; the new symbol data
-thus read keeps adding to the old. To discard all old symbol data
-instead, use the @code{symbol-file} command without any arguments.
+thus read is kept in addition to the old.
+
+Changes can be reverted using the command @code{remove-symbol-file}.
@cindex relocatable object files, reading symbols from
@cindex object files, relocatable, reading symbols from
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+@kindex remove-symbol-file
+@item remove-symbol-file @var{filename}
+@item remove-symbol-file -a @var{address}
+Remove a symbol file added via the @code{add-symbol-file} command. The
+file to remove can be identified by its @var{filename} or by an @var{address}
+that lies within the boundaries of this symbol file in memory. Example:
+
+@smallexample
+(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
+add symbol table from file "/home/user/gdb/mylib.so" at
+ .text_addr = 0x7ffff7ff9480
+(y or n) y
+Reading symbols from /home/user/gdb/mylib.so...done.
+(gdb) remove-symbol-file -a 0x7ffff7ff9480
+Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
+(gdb)
+@end smallexample
+
+
+@code{remove-symbol-file} does not repeat if you press @key{RET} after using it.
+
@kindex add-symbol-file-from-memory
@cindex @code{syscall DSO}
@cindex load symbols from memory
@smallexample
# Extract the dynamic symbols from the main binary, there is no need
-# to also have these in the normal symbol table
+# to also have these in the normal symbol table.
nm -D @var{binary} --format=posix --defined-only \
| awk '@{ print $1 @}' | sort > dynsyms
-# Extract all the text (i.e. function) symbols from the debuginfo .
+# Extract all the text (i.e. function) symbols from the debuginfo.
+# (Note that we actually also accept "D" symbols, for the benefit
+# of platforms like PowerPC64 that use function descriptors.)
nm @var{binary} --format=posix --defined-only \
- | awk '@{ if ($2 == "T" || $2 == "t") print $1 @}' \
+ | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \
| sort > funcsyms
# Keep all the function symbols not already in the dynamic symbol
# table.
comm -13 dynsyms funcsyms > keep_symbols
+# Separate full debug info into debug binary.
+objcopy --only-keep-debug @var{binary} debug
+
# Copy the full debuginfo, keeping only a minimal set of symbols and
# removing some unnecessary sections.
objcopy -S --remove-section .gdb_index --remove-section .comment \
- --keep-symbols=keep_symbols @var{binary} mini_debuginfo
+ --keep-symbols=keep_symbols debug mini_debuginfo
+
+# Drop the full debug info from the original binary.
+strip --strip-all -R .comment @var{binary}
# Inject the compressed data into the .gnu_debugdata section of the
# original binary.
@end table
-Some configurations may include these targets as well:
-
-@table @code
-
-@item target nrom @var{dev}
-@cindex NetROM ROM emulator target
-NetROM ROM emulator. This target only supports downloading.
-
-@end table
-
Different targets are available on different configurations of @value{GDBN};
your configuration may have more or fewer targets.
@end smallexample
If you're using a serial line, you may want to give @value{GDBN} the
-@w{@samp{--baud}} option, or use the @code{set remotebaud} command
-(@pxref{Remote Configuration, set remotebaud}) before the
+@samp{--baud} option, or use the @code{set serial baud} command
+(@pxref{Remote Configuration, set serial baud}) before the
@code{target} command.
@item target remote @code{@var{host}:@var{port}}
@cindex @option{--once}, @code{gdbserver} option
By default, @code{gdbserver} keeps the listening TCP port open, so that
-additional connections are possible. However, if you start @code{gdbserver}
+subsequent connections are possible. However, if you start @code{gdbserver}
with the @option{--once} option, it will stop listening for any further
connection attempts after connecting to the first @value{GDBN} session. This
means no further connections to @code{gdbserver} will be possible after the
@item show remoteaddresssize
Show the current value of remote address size in bits.
-@item set remotebaud @var{n}
+@item set serial baud @var{n}
@cindex baud rate for remote targets
Set the baud rate for the remote serial I/O to @var{n} baud. The
value is used to set the speed of the serial port used for debugging
remote targets.
-@item show remotebaud
+@item show serial baud
Show the current speed of the remote connection.
@item set remotebreak
Show the current auto-retry setting.
@item set tcp connect-timeout @var{seconds}
+@itemx set tcp connect-timeout unlimited
@cindex connection timeout, for remote TCP target
@cindex timeout, for remote target connection
Set the timeout for establishing a TCP connection to the remote target to
@var{seconds}. The timeout affects both polling to retry failed connections
(enabled by @code{set tcp auto-retry on}) and waiting for connections
that are merely slow to complete, and represents an approximate cumulative
-value.
+value. If @var{seconds} is @code{unlimited}, there is no timeout and
+@value{GDBN} will keep attempting to establish a connection forever,
+unless interrupted with @kbd{Ctrl-c}. The default is 15 seconds.
@item show tcp connect-timeout
Show the current connection timeout setting.
@tab @code{qAttached}
@tab Querying remote process attach state.
+@item @code{trace-buffer-size}
+@tab @code{QTBuffer:size}
+@tab @code{set trace-buffer-size}
+
+@item @code{trace-status}
+@tab @code{qTStatus}
+@tab @code{tstatus}
+
@item @code{traceframe-info}
@tab @code{qXfer:traceframe-info:read}
@tab Traceframe info
* HPPA:: HP PA architecture
* SPU:: Cell Broadband Engine SPU architecture
* PowerPC::
+* Nios II::
@end menu
@node AArch64
from functions.
@end table
+@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).
+@cindex Intel(R) Memory Protection Extensions (MPX).
+
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{The register named with capital letters represent the architecture
+registers.} through @samp{BND3}. Bound registers store a pair of 64-bit values
+which are the lower bound and upper bound. Bounds are effective addresses or
+memory locations. The upper bounds are architecturally represented in 1's
+complement form. A bound having lower bound = 0, and upper bound = 0
+(1's complement of all bits set) will allow access to the entire address space.
+
+@samp{BND0} through @samp{BND3} are represented in @value{GDBN} as @samp{bnd0raw}
+through @samp{bnd3raw}. Pseudo registers @samp{bnd0} through @samp{bnd3}
+display the upper bound performing the complement of one operation on the
+upper bound value, i.e.@ when upper bound in @samp{bnd0raw} is 0 in the
+@value{GDBN} @samp{bnd0} it will be @code{0xfff@dots{}}. In this sense it
+can also be noted that the upper bounds are inclusive.
+
+As an example, assume that the register BND0 holds bounds for a pointer having
+access allowed for the range between 0x32 and 0x71. The values present on
+bnd0raw and bnd registers are presented as follows:
+
+@smallexample
+ bnd0raw = @{0x32, 0xffffffff8e@}
+ bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64
+@end smallexample
+
+This way the raw value can be accessed via bnd0raw@dots{}bnd3raw. Any
+change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its
+counterpart. When the bnd0@dots{}bnd3 registers are displayed via
+Python, the display includes the memory size, in bits, accessible to
+the pointer.
+
@node Alpha
@subsection Alpha
For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit
wide Extended Floating Point Registers (@samp{f32} through @samp{f63}).
+@node Nios II
+@subsection Nios II
+@cindex Nios II architecture
+
+When @value{GDBN} is debugging the Nios II architecture,
+it provides the following special commands:
+
+@table @code
+
+@item set debug nios2
+@kindex set debug nios2
+This command turns on and off debugging messages for the Nios II
+target code in @value{GDBN}.
+
+@item show debug nios2
+@kindex show debug nios2
+Show the current setting of Nios II debugging messages.
+@end table
@node Controlling GDB
@chapter Controlling @value{GDBN}
@kindex set history size
@cindex @env{HISTSIZE}, 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.
+@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.
@end table
History expansion assigns special meaning to the character @kbd{!}.
@kindex show width
@kindex show height
@item set height @var{lpp}
+@itemx set height unlimited
@itemx show height
@itemx set width @var{cpl}
+@itemx set width unlimited
@itemx show width
These @code{set} commands specify a screen height of @var{lpp} lines and
a screen width of @var{cpl} characters. The associated @code{show}
commands display the current settings.
-If you specify a height of zero lines, @value{GDBN} does not pause during
-output no matter how long the output is. This is useful if output is to a
-file or to an editor buffer.
+If you specify a height of either @code{unlimited} or zero lines,
+@value{GDBN} does not pause during output no matter how long the
+output is. This is useful if output is to a file or to an editor
+buffer.
-Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
-from wrapping its output.
+Likewise, you can specify @samp{set width unlimited} or @samp{set
+width 0} to prevent @value{GDBN} from wrapping its output.
@item set pagination on
@itemx set pagination off
@kindex set pagination
Turn the output pagination on or off; the default is on. Turning
-pagination off is the alternative to @code{set height 0}. Note that
+pagination off is the alternative to @code{set height unlimited}. Note that
running @value{GDBN} with the @option{--batch} option (@pxref{Mode
Options, -batch}) also automatically disables pagination.
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 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
to "$debugdir:$datadir/auto-load".
@end smallexample
+@noindent
+To instruct @value{GDBN} to go ahead and use the init files anyway,
+invoke @value{GDBN} like this:
+
+@smallexample
+$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb
+@end smallexample
+
The list of trusted directories is controlled by the following commands:
@table @code
Displays the current setting of asynchronous command completion
notification.
@kindex set debug
+@cindex ARM AArch64
+@item set debug aarch64
+Turns on or off display of debugging messages related to ARM AArch64.
+The default is off.
+@kindex show debug
+@item show debug aarch64
+Displays the current state of displaying debugging messages related to
+ARM AArch64.
@cindex gdbarch debugging info
@cindex architecture debugging info
@item set debug arch
Turns on or off display of gdbarch debugging info. The default is off
-@kindex show debug
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
+@item set debug aix-solib
+@cindex AIX shared library debugging
+Control display of debugging messages from the AIX shared library
+support module. The default is off.
+@item show debug aix-thread
+Show the current state of displaying AIX shared library debugging messages.
@item set debug aix-thread
@cindex AIX threads
Display debugging messages about inner workings of the AIX thread
both ways and display any discrepancies.
@item show debug check-physname
Show the current state of ``physname'' checking.
+@item set debug coff-pe-read
+@cindex COFF/PE exported symbols
+Control display of debugging messages related to reading of COFF/PE
+exported symbols. The default is off.
+@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 dwarf2-read
@cindex DWARF2 Reading
Turns on or off display of debugging messages related to reading
-DWARF debug info. The default is off.
+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 set debug displaced
Turns 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 mach-o
+@cindex Mach-O symbols processing
+Control display of debugging messages related to Mach-O symbols
+processing. The default is off.
+@item show debug mach-o
+Displays the current state of displaying debugging messages related to
+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.
@item show debug solib-frv
Display the current state of FR-V shared-library code debugging
messages.
+@item set debug symfile
+@cindex symbol file functions
+Turns on or off display of debugging messages related to symbol file functions.
+The default is off. @xref{Files}.
+@item show debug symfile
+Show the current state of symbol file debugging messages.
@item set debug symtab-create
@cindex symbol table creation
Turns on or off display of debugging messages related to symbol table creation.
-The default is off.
+The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
@item show debug symtab-create
Show the current state of symbol table creation debugging.
@item set debug target
@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
+* Auto-loading extensions:: Automatically loading extensions
+* 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
@end table
+@node Auto-loading sequences
+@subsection Controlling auto-loading native @value{GDBN} scripts
+@cindex native script 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 the command file @file{@var{objfile}-gdb.gdb}.
+@xref{Auto-loading extensions}.
+
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
+
+@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 Python
-@section Scripting @value{GDBN} using Python
+@section Extending @value{GDBN} using Python
@cindex python scripting
@cindex scripting with python
-You can script @value{GDBN} using the @uref{http://www.python.org/,
+You can extend @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 api
@cindex programming in 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.
+You can get quick online help for @value{GDBN}'s Python API by issuing
+the command @w{@kbd{python help (gdb)}}.
+
+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)}}.
@menu
* Basic Python:: Basic Python Functions.
* 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.
* Progspaces In Python:: Program spaces.
* Objfiles In Python:: Object files.
* Frames In Python:: Accessing inferior stack frames from Python.
-* Blocks In Python:: Accessing frame blocks 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.
@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
bar = some_val['foo']
@end smallexample
-Again, @code{bar} will also be a @code{gdb.Value} object.
+@cindex getting structure elements using gdb.Field objects as subscripts
+Again, @code{bar} will also be a @code{gdb.Value} object. Structure
+elements can also be accessed by using @code{gdb.Field} objects as
+subscripts (@pxref{Types In Python}, for more information on
+@code{gdb.Field} objects). For example, if @code{foo_field} is a
+@code{gdb.Field} object corresponding to element @code{foo} of the above
+structure, then @code{bar} can also be accessed as follows:
+
+@smallexample
+bar = some_val[foo_field]
+@end smallexample
A @code{gdb.Value} that represents a function can be executed via
inferior function call. Any arguments provided to the call must match
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.
+This attribute is not available for @code{enum} or @code{static}
+(as in C@t{++} or Java) fields. The value is the position, counting
+in bits, from the start of the containing type.
+
+@item enumval
+This attribute is only available for @code{enum} fields, and its value
+is the enumeration member's integer representation.
@item name
The name of the field, or @code{None} for anonymous fields.
@item type
The type of the field. This is usually an instance of @code{Type},
but it can be @code{None} in some situations.
+
+@item parent_type
+The type which contains this field. This is an instance of
+@code{gdb.Type}.
@end table
@end defun
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
@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
@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
@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 ()
No particular reason (older frames should be available).
@item gdb.FRAME_UNWIND_NULL_ID
-The previous frame's analyzer returns an invalid result.
+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.
@end defun
@node Blocks In Python
-@subsubsection Accessing frame blocks from Python.
+@subsubsection Accessing blocks from Python.
@cindex blocks in python
@tindex gdb.Block
-Within each frame, @value{GDBN} maintains information on each block
-stored in that frame. These blocks are organized hierarchically, and
-are represented individually in Python as a @code{gdb.Block}.
-Please see @ref{Frames In Python}, for a more in-depth discussion on
-frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
-detailed technical information on @value{GDBN}'s book-keeping of the
-stack.
+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
@findex gdb.block_for_pc
@defun gdb.block_for_pc (pc)
-Return the @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}.
+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:
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
@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
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
-@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal@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{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.
+@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 as a sub-class of @code{gdb.Breakpoint},
+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
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:
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}).
+@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
+@xref{Auto-loading extensions}.
The auto-loading feature is useful for supplying application-specific
debugging commands and scripts.
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.
-
-@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.
-
-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
-@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-
-For object files using @file{.exe} suffix @value{GDBN} tries to load first the
-scripts normally according to its @file{.exe} filename. But if no scripts are
-found @value{GDBN} also tries script filenames matching the object file without
-its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
-is attempted on any platform. This makes the script filenames compatible
-between Unix and MS-Windows hosts.
-
-@table @code
-@anchor{set auto-load scripts-directory}
-@kindex set auto-load scripts-directory
-@item set auto-load scripts-directory @r{[}@var{directories}@r{]}
-Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
-may be delimited by the host platform path separator in use
-(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
-
-Each entry here needs to be covered also by the security setting
-@code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
-
-@anchor{with-auto-load-dir}
-This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
-@code{set auto-load safe-path} value can be also overriden by @value{GDBN}
-configuration option @option{--with-auto-load-dir}.
-
-Any reference to @file{$debugdir} will get replaced by
-@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
-reference to @file{$datadir} will get replaced by @var{data-directory} which is
-determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
-@file{$datadir} must be placed as a directory component --- either alone or
-delimited by @file{/} or @file{\} directory separators, depending on the host
-platform.
-
-The list of directories uses path separator (@samp{:} on GNU and Unix
-systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
-to the @env{PATH} environment variable.
-
-@anchor{show auto-load scripts-directory}
-@kindex show auto-load scripts-directory
-@item show auto-load scripts-directory
-Show @value{GDBN} auto-loaded scripts location.
-@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
-is evaluated more than once.
-
-@node dotdebug_gdb_scripts section
-@subsubsection 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.
-
-@value{GDBN} will look for each specified script 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:
-
-@example
-/* Note: The "MS" section flags are to remove duplicates. */
-#define DEFINE_GDB_SCRIPT(script_name) \
- asm("\
-.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
-.byte 1\n\
-.asciz \"" script_name "\"\n\
-.popsection \n\
-");
-@end example
-
-@noindent
-Then one can reference the macro in a header or source file like this:
-
-@example
-DEFINE_GDB_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.
-
-@node Which flavor to choose?
-@subsubsection Which flavor to choose?
-
-Given the multiple ways of auto-loading Python scripts, it might not always
-be clear which one to choose. This section provides some guidance.
-
-Benefits of the @file{-gdb.py} way:
-
-@itemize @bullet
-@item
-Can be used with file formats that don't support multiple sections.
-
-@item
-Ease of finding scripts for public libraries.
-
-Scripts specified in the @code{.debug_gdb_scripts} section are searched for
-in the source search path.
-For publicly installed libraries, e.g., @file{libstdc++}, there typically
-isn't a source directory in which to find the script.
-
-@item
-Doesn't require source code additions.
-@end itemize
-
-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
-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.
-
-@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.
-
-@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
-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
+registering objfile-specific pretty-printers and frame-filters.
@node Python modules
@subsection Python modules
@end smallexample
@end table
+@node Auto-loading extensions
+@section Auto-loading extensions
+@cindex auto-loading extensions
+
+@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
+* 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
+
+The auto-loading feature is useful for supplying application-specific
+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}.
+
+Note that loading of this script file also requires accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+
+@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}
+
+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:
+
+@table @code
+@item @file{@var{objfile}-gdb.gdb}
+GDB's own command language
+@item @file{@var{objfile}-gdb.py}
+Python
+@end table
+
+@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 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
+scripts normally according to its @file{.exe} filename. But if no scripts are
+found @value{GDBN} also tries script filenames matching the object file without
+its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
+is attempted on any platform. This makes the script filenames compatible
+between Unix and MS-Windows hosts.
+
+@table @code
+@anchor{set auto-load scripts-directory}
+@kindex set auto-load scripts-directory
+@item set auto-load scripts-directory @r{[}@var{directories}@r{]}
+Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
+may be delimited by the host platform path separator in use
+(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
+
+Each entry here needs to be covered also by the security setting
+@code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
+
+@anchor{with-auto-load-dir}
+This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
+@code{set auto-load safe-path} value can be also overriden by @value{GDBN}
+configuration option @option{--with-auto-load-dir}.
+
+Any reference to @file{$debugdir} will get replaced by
+@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
+reference to @file{$datadir} will get replaced by @var{data-directory} which is
+determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
+@file{$datadir} must be placed as a directory component --- either alone or
+delimited by @file{/} or @file{\} directory separators, depending on the host
+platform.
+
+The list of directories uses path separator (@samp{:} on GNU and Unix
+systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
+to the @env{PATH} environment variable.
+
+@anchor{show auto-load scripts-directory}
+@kindex show auto-load scripts-directory
+@item show auto-load scripts-directory
+Show @value{GDBN} auto-loaded scripts location.
+@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.@var{ext}} file should be careful to avoid errors if it
+is evaluated more than once.
+
+@node dotdebug_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 @code{.debug_gdb_scripts}.
+If this section exists, its contents is a list of NUL-terminated names
+of scripts to load. Each entry begins with a non-NULL prefix byte that
+specifies the kind of entry, typically the extension language.
+
+@value{GDBN} will look for each specified script 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 for Python scripts.
+
+@example
+/* Note: The "MS" section flags are to remove duplicates. */
+#define DEFINE_GDB_PY_SCRIPT(script_name) \
+ asm("\
+.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
+.byte 1 /* Python */\n\
+.asciz \"" script_name "\"\n\
+.popsection \n\
+");
+@end example
+
+@noindent
+Then one can reference the macro in a header or source file like this:
+
+@example
+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 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.
+
+@node Which flavor to choose?
+@subsection Which flavor to choose?
+
+Given the multiple ways of auto-loading extensions, it might not always
+be clear which one to choose. This section provides some guidance.
+
+@noindent
+Benefits of the @file{-gdb.@var{ext}} way:
+
+@itemize @bullet
+@item
+Can be used with file formats that don't support multiple sections.
+
+@item
+Ease of finding scripts for public libraries.
+
+Scripts specified in the @code{.debug_gdb_scripts} section are searched for
+in the source search path.
+For publicly installed libraries, e.g., @file{libstdc++}, there typically
+isn't a source directory in which to find the script.
+
+@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.@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.@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.@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.@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 Aliases
@section Creating new spellings of existing commands
@cindex aliases for commands
@end ignore
* GDB/MI Target Manipulation::
* GDB/MI File Transfer Commands::
+* GDB/MI Ada Exceptions Commands::
+* GDB/MI Support Commands::
* GDB/MI Miscellaneous Commands::
@end menu
@node Context management
@subsection Context management
+@subsubsection Threads and Frames
+
In most cases when @value{GDBN} accesses the target, this access is
done in context of a specific thread and frame (@pxref{Frames}).
Often, even when accessing global data, the target requires that a thread
right, so it is suggested to just always pass the @samp{--thread} and
@samp{--frame} options.
+@subsubsection Language
+
+The execution of several commands depends on which language is selected.
+By default, the current language (@pxref{show language}) is used.
+But for commands known to be language-sensitive, it is recommended
+to use the @samp{--language} option. This option takes one argument,
+which is the name of the language to use while executing the command.
+For instance:
+
+@smallexample
+-data-evaluate-expression --language c "sizeof (void*)"
+^done,value="4"
+(gdb)
+@end smallexample
+
+The valid language names are the same names accepted by the
+@samp{set language} command (@pxref{Manually}), excluding @samp{auto},
+@samp{local} or @samp{unknown}.
+
@node Asynchronous and non-stop modes
@subsection Asynchronous command execution and non-stop mode
@findex ^connected
@value{GDBN} has connected to a remote target.
-@item "^error" "," @var{c-string}
+@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
@findex ^error
-The operation failed. The @code{@var{c-string}} contains the corresponding
-error message.
+The operation failed. The @code{msg=@var{c-string}} variable contains
+the corresponding error message.
+
+If present, the @code{code=@var{c-string}} variable provides an error
+code on which consumers can rely on to detect the corresponding
+error condition. At present, only one error code is defined:
+
+@table @samp
+@item "undefined-command"
+Indicates that the command causing the error does not exist.
+@end table
@item "^exit"
@findex ^exit
@c (gdb)
@end smallexample
+@subheading The @code{-dprintf-insert} Command
+@findex -dprintf-insert
+
+@subsubheading Synopsis
+
+@smallexample
+ -dprintf-insert [ -t ] [ -f ] [ -d ]
+ [ -c @var{condition} ] [ -i @var{ignore-count} ]
+ [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
+ [ @var{argument} ]
+@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
+
+The possible optional parameters of this command are:
+
+@table @samp
+@item -t
+Insert a temporary breakpoint.
+@item -f
+If @var{location} cannot be parsed (for example, if it
+refers to unknown files or functions), create a pending
+breakpoint. Without this flag, @value{GDBN} will report
+an error, and won't create a breakpoint, if @var{location}
+cannot be parsed.
+@item -d
+Create a disabled breakpoint.
+@item -c @var{condition}
+Make the breakpoint conditional on @var{condition}.
+@item -i @var{ignore-count}
+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}.
+@end table
+
+@subsubheading Result
+
+@xref{GDB/MI Breakpoint Information}, for details on the format of the
+resulting breakpoint.
+
+@c An out-of-band breakpoint instead of part of the result?
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{dprintf}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+4-dprintf-insert foo "At foo entry\n"
+4^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y",
+addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
+fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
+times="0",script=@{"printf \"At foo entry\\n\"","continue"@},
+original-location="foo"@}
+(gdb)
+5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
+5^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y",
+addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
+fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
+times="0",script=@{"printf \"arg=%d, g=%d\\n\", arg, g","continue"@},
+original-location="mi-dprintf.c:26"@}
+(gdb)
+@end smallexample
+
@subheading The @code{-break-list} Command
@findex -break-list
This section documents @sc{gdb/mi} commands for manipulating
catchpoints.
+@menu
+* Shared Library GDB/MI Catchpoint Commands::
+* Ada Exception GDB/MI Catchpoint Commands::
+@end menu
+
+@node Shared Library GDB/MI Catchpoint Commands
+@subsection Shared Library @sc{gdb/mi} Catchpoints
+
@subheading The @code{-catch-load} Command
@findex -catch-load
(gdb)
@end smallexample
+@node Ada Exception GDB/MI Catchpoint Commands
+@subsection Ada Exception @sc{gdb/mi} Catchpoints
+
+The following @sc{gdb/mi} commands can be used to create catchpoints
+that stop the execution when Ada exceptions are being raised.
+
+@subheading The @code{-catch-assert} Command
+@findex -catch-assert
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-assert [ -c @var{condition}] [ -d ] [ -t ]
+@end smallexample
+
+Add a catchpoint for failed Ada assertions.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -t
+Create a temporary catchpoint.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch assert}.
+
+@subsubheading Example
+
+@smallexample
+-catch-assert
+^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
+thread-groups=["i1"],times="0",
+original-location="__gnat_debug_raise_assert_failure"@}
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-exception} Command
+@findex -catch-exception
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
+ [ -t ] [ -u ]
+@end smallexample
+
+Add a catchpoint stopping when Ada exceptions are raised.
+By default, the command stops the program when any Ada exception
+gets raised. But it is also possible, by using some of the
+optional parameters described below, to create more selective
+catchpoints.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -e @var{exception-name}
+Only stop when @var{exception-name} is raised. This option cannot
+be used combined with @samp{-u}.
+@item -t
+Create a temporary catchpoint.
+@item -u
+Stop only when an unhandled exception gets raised. This option
+cannot be used combined with @samp{-e}.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch exception}
+and @samp{catch exception unhandled}.
+
+@subsubheading Example
+
+@smallexample
+-catch-exception -e Program_Error
+^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404874",
+what="`Program_Error' Ada exception", thread-groups=["i1"],
+times="0",original-location="__gnat_debug_raise_exception"@}
+(gdb)
+@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@subsubheading Synopsis
@smallexample
- -exec-run [--all | --thread-group N]
+ -exec-run [ --all | --thread-group N ] [ --start ]
@end smallexample
Starts execution of the inferior from the beginning. The inferior
exits. In the latter case the output will include an exit code, if
the program has exited exceptionally.
-When no option is specified, the current inferior is started. If the
+When neither the @samp{--all} nor the @samp{--thread-group} option
+is specified, the current inferior is started. If the
@samp{--thread-group} option is specified, it should refer to a thread
group of type @samp{process}, and that thread group will be started.
If the @samp{--all} option is specified, then all inferiors will be started.
+Using the @samp{--start} option instructs the debugger to stop
+the execution at the start of the inferior's main subprogram,
+following the same behavior as the @code{start} command
+(@pxref{Starting}).
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{run}.
@node GDB/MI Stack Manipulation
@section @sc{gdb/mi} Stack Manipulation Commands
+@subheading The @code{-enable-frame-filters} Command
+@findex -enable-frame-filters
+
+@smallexample
+-enable-frame-filters
+@end smallexample
+
+@value{GDBN} allows Python-based frame filters to affect the output of
+the MI commands relating to stack traces. As there is no way to
+implement this in a fully backward-compatible way, a front end must
+request that this functionality be enabled.
+
+Once enabled, this feature cannot be disabled.
+
+Note that if Python support has not been compiled into @value{GDBN},
+this command will still succeed (and do nothing).
@subheading The @code{-stack-info-frame} Command
@findex -stack-info-frame
(gdb)
@end smallexample
+@anchor{-stack-list-arguments}
@subheading The @code{-stack-list-arguments} Command
@findex -stack-list-arguments
@subsubheading Synopsis
@smallexample
- -stack-list-arguments @var{print-values}
+ -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
[ @var{low-frame} @var{high-frame} ]
@end smallexample
the variables; if it is 1 or @code{--all-values}, print also their
values; and if it is 2 or @code{--simple-values}, print the name,
type and value for simple data types, and the name and type for arrays,
-structures and unions.
+structures and unions. If the option @code{--no-frame-filters} is
+supplied, then Python frame filters will not be executed.
+
+If the @code{--skip-unavailable} option is specified, arguments that
+are not available are not listed. Partially available arguments
+are still displayed, however.
Use of this command to obtain arguments in a single frame is
deprecated in favor of the @samp{-stack-list-variables} command.
@c @subheading -stack-list-exception-handlers
+@anchor{-stack-list-frames}
@subheading The @code{-stack-list-frames} Command
@findex -stack-list-frames
@subsubheading Synopsis
@smallexample
- -stack-list-frames [ @var{low-frame} @var{high-frame} ]
+ -stack-list-frames [ --no-frame-filters @var{low-frame} @var{high-frame} ]
@end smallexample
List the frames currently on the stack. For each frame it displays the
are equal, it shows the single frame at the corresponding level. It is
an error if @var{low-frame} is larger than the actual number of
frames. On the other hand, @var{high-frame} may be larger than the
-actual number of frames, in which case only existing frames will be returned.
+actual number of frames, in which case only existing frames will be
+returned. If the option @code{--no-frame-filters} is supplied, then
+Python frame filters will not be executed.
@subsubheading @value{GDBN} Command
@subheading The @code{-stack-list-locals} Command
@findex -stack-list-locals
+@anchor{-stack-list-locals}
@subsubheading Synopsis
@smallexample
- -stack-list-locals @var{print-values}
+ -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
@end smallexample
Display the local variable names for the selected frame. If
structures and unions. In this last case, a frontend can immediately
display the value of simple data types and create variable objects for
other data types when the user wishes to explore their values in
-more detail.
+more detail. If the option @code{--no-frame-filters} is supplied, then
+Python frame filters will not be executed.
+
+If the @code{--skip-unavailable} option is specified, local variables
+that are not available are not listed. Partially available local
+variables are still displayed, however.
This command is deprecated in favor of the
@samp{-stack-list-variables} command.
(gdb)
@end smallexample
+@anchor{-stack-list-variables}
@subheading The @code{-stack-list-variables} Command
@findex -stack-list-variables
@subsubheading Synopsis
@smallexample
- -stack-list-variables @var{print-values}
+ -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
@end smallexample
Display the names of local variables and function arguments for the selected frame. If
the variables; if it is 1 or @code{--all-values}, print also their
values; and if it is 2 or @code{--simple-values}, print the name,
type and value for simple data types, and the name and type for arrays,
-structures and unions.
+structures and unions. If the option @code{--no-frame-filters} is
+supplied, then Python frame filters will not be executed.
+
+If the @code{--skip-unavailable} option is specified, local variables
+and arguments that are not available are not listed. Partially
+available arguments and local variables are still displayed, however.
@subsubheading Example
@item frozen
If the variable object is frozen, this variable will be present with a value of 1.
+
+@item displayhint
+A dynamic varobj can supply a display hint to the front end. The
+value comes directly from the Python pretty-printer object's
+@code{display_hint} method. @xref{Pretty Printing API}.
+
+@item dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
@end table
The result may have its own attributes:
@end smallexample
@noindent
-Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
+Here, the value of @code{lang} is the language name, which can be
+found in @ref{Supported Languages}.
Note that the output of the @code{-var-list-children} command also
includes those expressions, so the @code{-var-info-expression} command
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
@subsubheading Synopsis
@smallexample
- -data-list-register-values @var{fmt} [ ( @var{regno} )*]
+ -data-list-register-values
+ [ @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.
+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:
The corresponding @value{GDBN} command is @samp{tvariable}.
+@subheading The @code{-trace-frame-collected} Command
+@findex -trace-frame-collected
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-frame-collected
+ [--var-print-values @var{var_pval}]
+ [--comp-print-values @var{comp_pval}]
+ [--registers-format @var{regformat}]
+ [--memory-contents]
+@end smallexample
+
+This command returns the set of collected objects, register names,
+trace state variable names, memory ranges and computed expressions
+that have been collected at a particular trace frame. The optional
+parameters to the command affect the output format in different ways.
+See the output description table below for more details.
+
+The reported names can be used in the normal manner to create
+varobjs and inspect the objects themselves. The items returned by
+this command are categorized so that it is clear which is a variable,
+which is a register, which is a trace state variable, which is a
+memory range and which is a computed expression.
+
+For instance, if the actions were
+@smallexample
+collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
+collect *(int*)0xaf02bef0@@40
+@end smallexample
+
+@noindent
+the object collected in its entirety would be @code{myVar}. The
+object @code{myArray} would be partially collected, because only the
+element at index @code{myIndex} would be collected. The remaining
+objects would be computed expressions.
+
+An example output would be:
+
+@smallexample
+(gdb)
+-trace-frame-collected
+^done,
+ explicit-variables=[@{name="myVar",value="1"@}],
+ computed-expressions=[@{name="myArray[myIndex]",value="0"@},
+ @{name="myObj.field",value="0"@},
+ @{name="myPtr->field",value="1"@},
+ @{name="myCount + 2",value="3"@},
+ @{name="$tvar1 + 1",value="43970027"@}],
+ registers=[@{number="0",value="0x7fe2c6e79ec8"@},
+ @{number="1",value="0x0"@},
+ @{number="2",value="0x4"@},
+ ...
+ @{number="125",value="0x0"@}],
+ tvars=[@{name="$tvar1",current="43970026"@}],
+ memory=[@{address="0x0000000000602264",length="4"@},
+ @{address="0x0000000000615bc0",length="4"@}]
+(gdb)
+@end smallexample
+
+Where:
+
+@table @code
+@item explicit-variables
+The set of objects that have been collected in their entirety (as
+opposed to collecting just a few elements of an array or a few struct
+members). For each object, its name and value are printed.
+The @code{--var-print-values} option affects how or whether the value
+field is output. If @var{var_pval} is 0, then print only the names;
+if it is 1, print also their values; and if it is 2, print the name,
+type and value for simple data types, and the name and type for
+arrays, structures and unions.
+
+@item computed-expressions
+The set of computed expressions that have been collected at the
+current trace frame. The @code{--comp-print-values} option affects
+this set like the @code{--var-print-values} option affects the
+@code{explicit-variables} set. See above.
+
+@item registers
+The registers that have been collected at the current trace frame.
+For each register collected, the name and current value are returned.
+The value is formatted according to the @code{--registers-format}
+option. See the @command{-data-list-register-values} command for a
+list of the allowed formats. The default is @samp{x}.
+
+@item tvars
+The trace state variables that have been collected at the current
+trace frame. For each trace state variable collected, the name and
+current value are returned.
+
+@item memory
+The set of memory ranges that have been collected at the current trace
+frame. Its content is a list of tuples. Each tuple represents a
+collected memory range and has the following fields:
+
+@table @code
+@item address
+The start address of the memory range, as hexadecimal literal.
+
+@item length
+The length of the memory range, as decimal literal.
+
+@item contents
+The contents of the memory block, in hex. This field is only present
+if the @code{--memory-contents} option is specified.
+
+@end table
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+There is no corresponding @value{GDBN} command.
+
+@subsubheading Example
+
@subheading -trace-list-variables
@findex -trace-list-variables
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Miscellaneous Commands
-@section Miscellaneous @sc{gdb/mi} Commands
+@node GDB/MI Ada Exceptions Commands
+@section Ada Exceptions @sc{gdb/mi} Commands
-@c @subheading -gdb-complete
-
-@subheading The @code{-gdb-exit} Command
-@findex -gdb-exit
+@subheading The @code{-info-ada-exceptions} Command
+@findex -info-ada-exceptions
@subsubheading Synopsis
@smallexample
- -gdb-exit
+ -info-ada-exceptions [ @var{regexp}]
@end smallexample
-Exit @value{GDBN} immediately.
+List all Ada exceptions defined within the program being debugged.
+With a regular expression @var{regexp}, only those exceptions whose
+names match @var{regexp} are listed.
@subsubheading @value{GDBN} Command
-Approximately corresponds to @samp{quit}.
-
-@subsubheading Example
-
-@smallexample
-(gdb)
--gdb-exit
-^exit
-@end smallexample
-
+The corresponding @value{GDBN} command is @samp{info exceptions}.
-@ignore
-@subheading The @code{-exec-abort} Command
-@findex -exec-abort
-
-@subsubheading Synopsis
+@subsubheading Result
-@smallexample
- -exec-abort
-@end smallexample
+The result is a table of Ada exceptions. The following columns are
+defined for each exception:
-Kill the inferior running program.
+@table @samp
+@item name
+The name of the exception.
-@subsubheading @value{GDBN} Command
+@item address
+The address of the exception.
-The corresponding @value{GDBN} command is @samp{kill}.
+@end table
@subsubheading Example
-N.A.
-@end ignore
-
-
-@subheading The @code{-gdb-set} Command
-@findex -gdb-set
-
-@subsubheading Synopsis
@smallexample
- -gdb-set
+-info-ada-exceptions aint
+^done,ada-exceptions=@{nr_rows="2",nr_cols="2",
+hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@},
+@{width="1",alignment="-1",col_name="address",colhdr="Address"@}],
+body=[@{name="constraint_error",address="0x0000000000613da0"@},
+@{name="const.aint_global_e",address="0x0000000000613b00"@}]@}
@end smallexample
-Set an internal @value{GDBN} variable.
-@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
+@subheading Catching Ada Exceptions
-@subsubheading @value{GDBN} Command
+The commands describing how to ask @value{GDBN} to stop when a program
+raises an exception are described at @ref{Ada Exception GDB/MI
+Catchpoint Commands}.
-The corresponding @value{GDBN} command is @samp{set}.
-@subsubheading Example
-
-@smallexample
-(gdb)
--gdb-set $foo=3
-^done
-(gdb)
-@end smallexample
+@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{-gdb-show} Command
-@findex -gdb-show
+@subheading The @code{-info-gdb-mi-command} Command
+@cindex @code{-info-gdb-mi-command}
+@findex -info-gdb-mi-command
@subsubheading Synopsis
@smallexample
- -gdb-show
+ -info-gdb-mi-command @var{cmd_name}
@end smallexample
-Show the current value of a @value{GDBN} variable.
+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
-The corresponding @value{GDBN} command is @samp{show}.
+There is no corresponding @value{GDBN} command.
-@subsubheading Example
+@subsubheading Result
-@smallexample
-(gdb)
--gdb-show annotate
-^done,value="0"
-(gdb)
-@end smallexample
+The result is a tuple. There is currently only one field:
-@c @subheading -gdb-source
+@table @samp
+@item exists
+This field is equal to @code{"true"} if the @sc{gdb/mi} command exists,
+@code{"false"} otherwise.
+@end table
-@subheading The @code{-gdb-version} Command
-@findex -gdb-version
+@subsubheading Example
-@subsubheading Synopsis
+Here is an example where the @sc{gdb/mi} command does not exist:
@smallexample
- -gdb-version
+-info-gdb-mi-command unsupported-command
+^done,command=@{exists="false"@}
@end smallexample
-Show version information for @value{GDBN}. Used mostly in testing.
-
-@subsubheading @value{GDBN} Command
-
-The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
-default shows this information when you start an interactive session.
-
-@subsubheading Example
+@noindent
+And here is an example where the @sc{gdb/mi} command is known
+to the debugger:
-@c This example modifies the actual output from GDB to avoid overfull
-@c box in TeX.
@smallexample
-(gdb)
--gdb-version
-~GNU gdb 5.2.1
-~Copyright 2000 Free Software Foundation, Inc.
-~GDB is free software, covered by the GNU General Public License, and
-~you are welcome to change it and/or distribute copies of it under
-~ certain conditions.
-~Type "show copying" to see the conditions.
-~There is absolutely no warranty for GDB. Type "show warranty" for
-~ details.
-~This GDB was configured as
- "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
-^done
-(gdb)
+-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.
+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
+have any internal structure. The list of possible feature names
is given below.
Example output:
The current list of features is:
-@table @samp
+@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
CLI will be announced via async records.
@item ada-task-info
Indicates support for the @code{-ada-task-info} command.
-@end table
+@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
Example output:
@smallexample
-(gdb) -list-features
+(gdb) -list-target-features
^done,result=["async"]
@end smallexample
@end table
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Miscellaneous Commands
+@section Miscellaneous @sc{gdb/mi} Commands
+
+@c @subheading -gdb-complete
+
+@subheading The @code{-gdb-exit} Command
+@findex -gdb-exit
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-exit
+@end smallexample
+
+Exit @value{GDBN} immediately.
+
+@subsubheading @value{GDBN} Command
+
+Approximately corresponds to @samp{quit}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-gdb-exit
+^exit
+@end smallexample
+
+
+@ignore
+@subheading The @code{-exec-abort} Command
+@findex -exec-abort
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-abort
+@end smallexample
+
+Kill the inferior running program.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{kill}.
+
+@subsubheading Example
+N.A.
+@end ignore
+
+
+@subheading The @code{-gdb-set} Command
+@findex -gdb-set
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-set
+@end smallexample
+
+Set an internal @value{GDBN} variable.
+@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{set}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-gdb-set $foo=3
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-gdb-show} Command
+@findex -gdb-show
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-show
+@end smallexample
+
+Show the current value of a @value{GDBN} variable.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{show}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-gdb-show annotate
+^done,value="0"
+(gdb)
+@end smallexample
+
+@c @subheading -gdb-source
+
+
+@subheading The @code{-gdb-version} Command
+@findex -gdb-version
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-version
+@end smallexample
+
+Show version information for @value{GDBN}. Used mostly in testing.
+
+@subsubheading @value{GDBN} Command
+
+The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
+default shows this information when you start an interactive session.
+
+@subsubheading Example
+
+@c This example modifies the actual output from GDB to avoid overfull
+@c box in TeX.
+@smallexample
+(gdb)
+-gdb-version
+~GNU gdb 5.2.1
+~Copyright 2000 Free Software Foundation, Inc.
+~GDB is free software, covered by the GNU General Public License, and
+~you are welcome to change it and/or distribute copies of it under
+~ certain conditions.
+~Type "show copying" to see the conditions.
+~There is absolutely no warranty for GDB. Type "show warranty" for
+~ details.
+~This GDB was configured as
+ "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
+^done
+(gdb)
+@end smallexample
+
@subheading The @code{-list-thread-groups} Command
@findex -list-thread-groups
inferior is not associated with any executable. Such association may
be established with the @samp{-file-exec-and-symbols} command
(@pxref{GDB/MI File Commands}). The command response has a single
-field, @samp{thread-group}, whose value is the identifier of the
+field, @samp{inferior}, whose value is the identifier of the
thread group corresponding to the new inferior.
@subheading Example
@smallexample
@value{GDBP}
-add-inferior
-^done,thread-group="i3"
+^done,inferior="i3"
@end smallexample
@subheading The @code{-interpreter-exec} Command
The type of machine you are using, and the operating system name and
version number.
+@item
+The details of the @value{GDBN} build-time configuration.
+@value{GDBN} shows these details if you invoke it with the
+@option{--configuration} command-line option, or if you type
+@code{show configuration} at @value{GDBN}'s prompt.
+
@item
What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
``@value{GCC}--2.8.1''.
started with the @code{set data-directory} command, the file will not be
reread.
+@menu
+* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
+@end menu
+
+@node System-wide Configuration Scripts
+@subsection Installed System-wide Configuration Scripts
+@cindex system-wide configuration scripts
+
+The @file{system-gdbinit} directory, located inside the data-directory
+(as specified by @option{--with-gdb-datadir} at configure time) contains
+a number of scripts which can be used as system-wide init files. To
+automatically source those scripts at startup, @value{GDBN} should be
+configured with @option{--with-system-gdbinit}. Otherwise, any user
+should be able to source them by hand as needed.
+
+The following scripts are currently available:
+@itemize @bullet
+
+@item @file{elinos.py}
+@pindex elinos.py
+@cindex ELinOS system-wide configuration script
+This script is useful when debugging a program on an ELinOS target.
+It takes advantage of the environment variables defined in a standard
+ELinOS environment in order to determine the location of the system
+shared libraries, and then sets the @samp{solib-absolute-prefix}
+and @samp{solib-search-path} variables appropriately.
+
+@item @file{wrs-linux.py}
+@pindex wrs-linux.py
+@cindex Wind River Linux system-wide configuration script
+This script is useful when debugging a program on a target running
+Wind River Linux. It expects the @env{ENV_PREFIX} to be set to
+the host-side sysroot used by the target system.
+
+@end itemize
+
@node Maintenance Commands
@appendix Maintenance Commands
@cindex maintenance commands
architecture supports displaced stepping.
@end table
+@kindex maint check-psymtabs
+@item maint check-psymtabs
+Check the consistency of currently expanded psymtabs versus symtabs.
+Use this to check, for example, whether a symbol is in one but not the other.
+
@kindex maint check-symtabs
@item maint check-symtabs
-Check the consistency of psymtabs and symtabs.
+Check the consistency of currently expanded symtabs.
+
+@kindex maint expand-symtabs
+@item maint expand-symtabs [@var{regexp}]
+Expand symbol tables.
+If @var{regexp} is specified, only expand symbol tables for file
+names matching @var{regexp}.
@kindex maint cplus first_component
@item maint cplus first_component @var{name}
to user; the command @code{maint print register-groups} includes the
groups that each register is a member of; and the command @code{maint
print remote-registers} includes the remote target's register numbers
-and offsets in the `G' packets. @xref{Registers,, Registers, gdbint,
-@value{GDBN} Internals}.
+and offsets in the `G' packets.
These commands take an optional parameter, a file name to which to
write the information.
@kindex maint print objfiles
@cindex info for known object files
-@item maint print objfiles
-Print a dump of all known object files. For each object file, this
-command prints its name, address in memory, and all of its psymtabs
-and symtabs.
+@item maint print objfiles @r{[}@var{regexp}@r{]}
+Print a dump of all known object files.
+If @var{regexp} is specified, only print object files whose names
+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 section-scripts
@cindex info for known .debug_gdb_scripts-loaded scripts
@item maint set show-debug-regs
@itemx maint show show-debug-regs
Control whether to show variables that mirror the hardware debug
-registers. Use @code{ON} to enable, @code{OFF} to disable. If
+registers. Use @code{on} to enable, @code{off} to disable. If
enabled, the debug registers values are shown when @value{GDBN} inserts or
removes a hardware breakpoint or watchpoint, and when the inferior
triggers a hardware-assisted breakpoint or watchpoint.
for each command.
If enabled, @value{GDBN} will display the following information:
-@table @bullet
-@item number of symbol tables
-@itemx number of primary symbol tables
-@itemx number of blocks in the blockvector
-@end table
+@enumerate a
+@item
+number of symbol tables
+@item
+number of primary symbol tables
+@item
+number of blocks in the blockvector
+@end enumerate
@end table
@kindex maint space
Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
@item t
Stop.
+@item r @var{start},@var{end}
+Step once, and then keep stepping as long as the thread stops at
+addresses between @var{start} (inclusive) and @var{end} (exclusive).
+The remote stub reports a stop reply when either the thread goes out
+of the range or is stopped due to an unrelated reason, such as hitting
+a breakpoint. @xref{range stepping}.
+
+If the range is empty (@var{start} == @var{end}), then the action
+becomes equivalent to the @samp{s} action. In other words,
+single-step once, and report the stop (even if the stepped instruction
+jumps to @var{start}).
+
+(A stop reply may be sent at any point even if the PC is still within
+the stepping range; for example, it is valid to implement this packet
+in a degenerate way as a single instruction step operation.)
+
@end table
The optional argument @var{addr} normally associated with the
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:libraries-svr4:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{augmented-libraries-svr4-read}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{qXfer:memory-map:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:libraries-svr4:read} packet
(@pxref{qXfer svr4 library list read}).
+@item augmented-libraries-svr4-read
+The remote stub understands the augmented form of the
+@samp{qXfer:libraries-svr4:read} packet
+(@pxref{qXfer svr4 library list read}).
+
@item qXfer:memory-map:read
The remote stub understands the @samp{qXfer:memory-map:read} packet
(@pxref{qXfer memory map read}).
@anchor{qXfer svr4 library list read}
Access the target's list of loaded libraries when the target is an SVR4
platform. @xref{Library List Format for SVR4 Targets}. The annex part
-of the generic @samp{qXfer} packet must be empty (@pxref{qXfer read}).
+of the generic @samp{qXfer} packet must be empty unless the remote
+stub indicated it supports the augmented form of this packet
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qXfer read}, @ref{qSupported}).
This packet is optional for better performance on SVR4 targets.
@value{GDBN} uses memory read packets to read the SVR4 library list otherwise.
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+If the remote stub indicates it supports the augmented form of this
+packet then the annex part of the generic @samp{qXfer} packet may
+contain a semicolon-separated list of @samp{@var{name}=@var{value}}
+arguments. The currently supported arguments are:
+
+@table @code
+@item start=@var{address}
+A hexadecimal number specifying the address of the @samp{struct
+link_map} to start reading the library list from. If unset or zero
+then the first @samp{struct link_map} in the library list will be
+chosen as the starting point.
+
+@item prev=@var{address}
+A hexadecimal number specifying the address of the @samp{struct
+link_map} immediately preceding the @samp{struct link_map}
+specified by the @samp{start} argument. If unset or zero then
+the remote stub will expect that no @samp{struct link_map}
+exists prior to the starting point.
+
+@end table
+
+Arguments that are not understood by the remote stub will be silently
+ignored.
+
@item qXfer:memory-map:read::@var{offset},@var{length}
@anchor{qXfer memory map read}
Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
<memory start="@var{addr}" length="@var{length}"/>
@end smallexample
+@item
+A block indicating trace state variable numbered @var{number} has been
+collected:
+
+@smallexample
+<tvar id="@var{number}"/>
+@end smallexample
+
@end itemize
The formal DTD for the traceframe info format is given below:
@smallexample
-<!ELEMENT traceframe-info (memory)* >
+<!ELEMENT traceframe-info (memory | tvar)* >
<!ATTLIST traceframe-info version CDATA #FIXED "1.0">
<!ELEMENT memory EMPTY>
<!ATTLIST memory start CDATA #REQUIRED
length CDATA #REQUIRED>
+<!ELEMENT tvar>
+<!ATTLIST tvar id CDATA #REQUIRED>
@end smallexample
@node Branch Trace Format
* i386 Features::
* MIPS Features::
* M68K Features::
+* Nios II Features::
* PowerPC Features::
+* S/390 and System z Features::
* TIC6x Features::
@end menu
@samp{ymm0h} through @samp{ymm15h} for amd64
@end itemize
+The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R)
+Memory Protection Extension (MPX). It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64.
+@item
+@samp{bndcfgu} and @samp{bndstatus} for i386 and amd64.
+@end itemize
+
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.
@samp{fpiaddr}.
@end table
+@node Nios II Features
+@subsection Nios II Features
+@cindex target descriptions, Nios II features
+
+The @samp{org.gnu.gdb.nios2.cpu} feature is required for Nios II
+targets. It should contain the 32 core registers (@samp{zero},
+@samp{at}, @samp{r2} through @samp{r23}, @samp{et} through @samp{ra}),
+@samp{pc}, and the 16 control registers (@samp{status} through
+@samp{mpuacc}).
+
@node PowerPC Features
@subsection PowerPC Features
@cindex target descriptions, PowerPC features
these to present registers @samp{ev0} through @samp{ev31} to the
user.
+@node S/390 and System z Features
+@subsection S/390 and System z Features
+@cindex target descriptions, S/390 features
+@cindex target descriptions, System z features
+
+The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and
+System z targets. It should contain the PSW and the 16 general
+registers. In particular, System z targets should provide the 64-bit
+registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}.
+S/390 targets should provide the 32-bit versions of these registers.
+A System z target that runs in 31-bit addressing mode should provide
+32-bit versions of @samp{pswm} and @samp{pswa}, as well as the general
+register's upper halves @samp{r0h} through @samp{r15h}, and their
+lower halves @samp{r0l} through @samp{r15l}.
+
+The @samp{org.gnu.gdb.s390.fpr} feature is required. It should
+contain the 64-bit registers @samp{f0} through @samp{f15}, and
+@samp{fpc}.
+
+The @samp{org.gnu.gdb.s390.acr} feature is required. It should
+contain the 32-bit registers @samp{acr0} through @samp{acr15}.
+
+The @samp{org.gnu.gdb.s390.linux} feature is optional. It should
+contain the register @samp{orig_r2}, which is 64-bit wide on System z
+targets and 32-bit otherwise. In addition, the feature may contain
+the @samp{last_break} register, whose width depends on the addressing
+mode, as well as the @samp{system_call} register, which is always
+32-bit wide.
+
+The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should
+contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
+@samp{atia}, and @samp{tr0} through @samp{tr15}.
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
@}
@end smallexample
+@node Man Pages
+@appendix Manual pages
+@cindex Man pages
+
+@menu
+* gdb man:: The GNU Debugger man page
+* gdbserver man:: Remote Server for the GNU Debugger man page
+* gcore man:: Generate a core file of a running program
+* gdbinit man:: gdbinit scripts
+@end menu
+
+@node gdb man
+@heading gdb man
+
+@c man title gdb The GNU Debugger
+
+@c man begin SYNOPSIS gdb
+gdb [@option{-help}] [@option{-nh}] [@option{-nx}] [@option{-q}]
+[@option{-batch}] [@option{-cd=}@var{dir}] [@option{-f}]
+[@option{-b}@w{ }@var{bps}]
+ [@option{-tty=}@var{dev}] [@option{-s} @var{symfile}]
+[@option{-e}@w{ }@var{prog}] [@option{-se}@w{ }@var{prog}]
+[@option{-c}@w{ }@var{core}] [@option{-p}@w{ }@var{procID}]
+ [@option{-x}@w{ }@var{cmds}] [@option{-d}@w{ }@var{dir}]
+[@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}]
+@c man end
+
+@c man begin DESCRIPTION gdb
+The purpose of a debugger such as @value{GDBN} is to allow you to see what is
+going on ``inside'' another program while it executes -- or what another
+program was doing at the moment it crashed.
+
+@value{GDBN} can do four main kinds of things (plus other things in support of
+these) to help you catch bugs in the act:
+
+@itemize @bullet
+@item
+Start your program, specifying anything that might affect its behavior.
+
+@item
+Make your program stop on specified conditions.
+
+@item
+Examine what has happened, when your program has stopped.
+
+@item
+Change things in your program, so you can experiment with correcting the
+effects of one bug and go on to learn about another.
+@end itemize
+
+You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and
+Modula-2.
+
+@value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads
+commands from the terminal until you tell it to exit with the @value{GDBN}
+command @code{quit}. You can get online help from @value{GDBN} itself
+by using the command @code{help}.
+
+You can run @code{gdb} with no arguments or options; but the most
+usual way to start @value{GDBN} is with one argument or two, specifying an
+executable program as the argument:
+
+@smallexample
+gdb program
+@end smallexample
+
+You can also start with both an executable program and a core file specified:
+
+@smallexample
+gdb program core
+@end smallexample
+
+You can, instead, specify a process ID as a second argument, if you want
+to debug a running process:
+
+@smallexample
+gdb program 1234
+gdb -p 1234
+@end smallexample
+
+@noindent
+would attach @value{GDBN} to process @code{1234} (unless you also have a file
+named @file{1234}; @value{GDBN} does check for a core file first).
+With option @option{-p} you can omit the @var{program} filename.
+
+Here are some of the most frequently needed @value{GDBN} commands:
+
+@c pod2man highlights the right hand side of the @item lines.
+@table @env
+@item break [@var{file}:]@var{functiop}
+Set a breakpoint at @var{function} (in @var{file}).
+
+@item run [@var{arglist}]
+Start your program (with @var{arglist}, if specified).
+
+@item bt
+Backtrace: display the program stack.
+
+@item print @var{expr}
+Display the value of an expression.
+
+@item c
+Continue running your program (after stopping, e.g. at a breakpoint).
+
+@item next
+Execute next program line (after stopping); step @emph{over} any
+function calls in the line.
+
+@item edit [@var{file}:]@var{function}
+look at the program line where it is presently stopped.
+
+@item list [@var{file}:]@var{function}
+type the text of the program in the vicinity of where it is presently stopped.
+
+@item step
+Execute next program line (after stopping); step @emph{into} any
+function calls in the line.
+
+@item help [@var{name}]
+Show information about @value{GDBN} command @var{name}, or general information
+about using @value{GDBN}.
+
+@item quit
+Exit from @value{GDBN}.
+@end table
+
+@ifset man
+For full details on @value{GDBN},
+see @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+by Richard M. Stallman and Roland H. Pesch. The same text is available online
+as the @code{gdb} entry in the @code{info} program.
+@end ifset
+@c man end
+
+@c man begin OPTIONS gdb
+Any arguments other than options specify an executable
+file and core file (or process ID); that is, the first argument
+encountered with no
+associated option flag is equivalent to a @option{-se} option, and the second,
+if any, is equivalent to a @option{-c} option if it's the name of a file.
+Many options have
+both long and short forms; both are shown here. The long forms are also
+recognized if you truncate them, so long as enough of the option is
+present to be unambiguous. (If you prefer, you can flag option
+arguments with @option{+} rather than @option{-}, though we illustrate the
+more usual convention.)
+
+All the options and command line arguments you give are processed
+in sequential order. The order makes a difference when the @option{-x}
+option is used.
+
+@table @env
+@item -help
+@itemx -h
+List all options, with brief explanations.
+
+@item -symbols=@var{file}
+@itemx -s @var{file}
+Read symbol table from file @var{file}.
+
+@item -write
+Enable writing into executable and core files.
+
+@item -exec=@var{file}
+@itemx -e @var{file}
+Use file @var{file} as the executable file to execute when
+appropriate, and for examining pure data in conjunction with a core
+dump.
+
+@item -se=@var{file}
+Read symbol table from file @var{file} and use it as the executable
+file.
+
+@item -core=@var{file}
+@itemx -c @var{file}
+Use file @var{file} as a core dump to examine.
+
+@item -command=@var{file}
+@itemx -x @var{file}
+Execute @value{GDBN} commands from file @var{file}.
+
+@item -ex @var{command}
+Execute given @value{GDBN} @var{command}.
+
+@item -directory=@var{directory}
+@itemx -d @var{directory}
+Add @var{directory} to the path to search for source files.
+
+@item -nh
+Do not execute commands from @file{~/.gdbinit}.
+
+@item -nx
+@itemx -n
+Do not execute commands from any @file{.gdbinit} initialization files.
+
+@item -quiet
+@itemx -q
+``Quiet''. Do not print the introductory and copyright messages. These
+messages are also suppressed in batch mode.
+
+@item -batch
+Run in batch mode. Exit with status @code{0} after processing all the command
+files specified with @option{-x} (and @file{.gdbinit}, if not inhibited).
+Exit with nonzero status if an error occurs in executing the @value{GDBN}
+commands in the command files.
+
+Batch mode may be useful for running @value{GDBN} as a filter, for example to
+download and run a program on another computer; in order to make this
+more useful, the message
+
+@smallexample
+Program exited normally.
+@end smallexample
+
+@noindent
+(which is ordinarily issued whenever a program running under @value{GDBN} control
+terminates) is not issued when running in batch mode.
+
+@item -cd=@var{directory}
+Run @value{GDBN} using @var{directory} as its working directory,
+instead of the current directory.
+
+@item -fullname
+@itemx -f
+Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells
+@value{GDBN} to output the full file name and line number in a standard,
+recognizable fashion each time a stack frame is displayed (which
+includes each time the program stops). This recognizable format looks
+like two @samp{\032} characters, followed by the file name, line number
+and character position separated by colons, and a newline. The
+Emacs-to-@value{GDBN} interface program uses the two @samp{\032}
+characters as a signal to display the source code for the frame.
+
+@item -b @var{bps}
+Set the line speed (baud rate or bits per second) of any serial
+interface used by @value{GDBN} for remote debugging.
+
+@item -tty=@var{device}
+Run using @var{device} for your program's standard input and output.
+@end table
+@c man end
+
+@c man begin SEEALSO gdb
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+@noindent
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gdbserver man
+@heading gdbserver man
+
+@c man title gdbserver Remote Server for the GNU Debugger
+@format
+@c man begin SYNOPSIS gdbserver
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
+
+gdbserver --attach @var{comm} @var{pid}
+
+gdbserver --multi @var{comm}
+@c man end
+@end format
+
+@c man begin DESCRIPTION gdbserver
+@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine
+than the one which is running the program being debugged.
+
+@ifclear man
+@subheading Usage (server (target) side)
+@end ifclear
+@ifset man
+Usage (server (target) side):
+@end ifset
+
+First, you need to have a copy of the program you want to debug put onto
+the target system. The program can be stripped to save space if needed, as
+@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by
+the @value{GDBN} running on the host system.
+
+To use the server, you log on to the target system, and run the @command{gdbserver}
+program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of
+your program, and (c) its arguments. The general syntax is:
+
+@smallexample
+target> gdbserver @var{comm} @var{program} [@var{args} ...]
+@end smallexample
+
+For example, using a serial port, you might say:
+
+@smallexample
+@ifset man
+@c @file would wrap it as F</dev/com1>.
+target> gdbserver /dev/com1 emacs foo.txt
+@end ifset
+@ifclear man
+target> gdbserver @file{/dev/com1} emacs foo.txt
+@end ifclear
+@end smallexample
+
+This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and
+to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now
+waits patiently for the host @value{GDBN} to communicate with it.
+
+To use a TCP connection, you could say:
+
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
+
+This says pretty much the same thing as the last example, except that we are
+going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means
+that we are expecting to see a TCP connection from @code{host} to local TCP port
+2345. (Currently, the @code{host} part is ignored.) You can choose any number you
+want for the port number as long as it does not conflict with any existing TCP
+ports on the target system. This same port number must be used in the host
+@value{GDBN}s @code{target remote} command, which will be described shortly. Note that if
+you chose a port number that conflicts with another service, @command{gdbserver} will
+print an error message and exit.
+
+@command{gdbserver} can also attach to running programs.
+This is accomplished via the @option{--attach} argument. The syntax is:
+
+@smallexample
+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 @command{gdbserver} at a binary for the running process.
+
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use the @option{--multi} command line option.
+In such case you should connect using @kbd{target extended-remote} to start
+the program you want to debug.
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
+@ifclear man
+@subheading Usage (host side)
+@end ifclear
+@ifset man
+Usage (host side):
+@end ifset
+
+You need an unstripped copy of the target program on your host system, since
+@value{GDBN} needs to examine it's symbol tables and such. Start up @value{GDBN} as you normally
+would, with the target program as the first argument. (You may need to use the
+@option{--baud} option if the serial line is running at anything except 9600 baud.)
+That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only
+new command you need to know about is @code{target remote}
+(or @code{target extended-remote}). Its argument is either
+a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
+descriptor. For example:
+
+@smallexample
+@ifset man
+@c @file would wrap it as F</dev/ttyb>.
+(gdb) target remote /dev/ttyb
+@end ifset
+@ifclear man
+(gdb) target remote @file{/dev/ttyb}
+@end ifclear
+@end smallexample
+
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and:
+
+@smallexample
+(gdb) target remote the-target:2345
+@end smallexample
+
+@noindent
+communicates via a TCP connection to port 2345 on host `the-target', where
+you previously started up @command{gdbserver} with the same port number. Note that for
+TCP connections, you must start up @command{gdbserver} prior to using the `target remote'
+command, otherwise you may get an error that looks something like
+`Connection refused'.
+
+@command{gdbserver} can also debug multiple inferiors at once,
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Inferiors and Programs}
+-- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
+@end ifset
+@ifclear man
+@ref{Inferiors and Programs}.
+@end ifclear
+In such case use the @code{extended-remote} @value{GDBN} command variant:
+
+@smallexample
+(gdb) target extended-remote the-target:2345
+@end smallexample
+
+The @command{gdbserver} option @option{--multi} may or may not be used in such
+case.
+@c man end
+
+@c man begin OPTIONS gdbserver
+There are three different modes for invoking @command{gdbserver}:
+
+@itemize @bullet
+
+@item
+Debug a specific program specified by its program name:
+
+@smallexample
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
+@end smallexample
+
+The @var{comm} parameter specifies how should the server communicate
+with @value{GDBN}; it is either a device name (to use a serial line),
+a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use
+stdin/stdout of @code{gdbserver}. Specify the name of the program to
+debug in @var{prog}. Any remaining arguments will be passed to the
+program verbatim. When the program exits, @value{GDBN} will close the
+connection, and @code{gdbserver} will exit.
+
+@item
+Debug a specific program by specifying the process ID of a running
+program:
+
+@smallexample
+gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+The @var{comm} parameter is as described above. Supply the process ID
+of a running program in @var{pid}; @value{GDBN} will do everything
+else. Like with the previous mode, when the process @var{pid} exits,
+@value{GDBN} will close the connection, and @code{gdbserver} will exit.
+
+@item
+Multi-process mode -- debug more than one program/process:
+
+@smallexample
+gdbserver --multi @var{comm}
+@end smallexample
+
+In this mode, @value{GDBN} can instruct @command{gdbserver} which
+command(s) to run. Unlike the other 2 modes, @value{GDBN} will not
+close the connection when a process being debugged exits, so you can
+debug several processes in the same session.
+@end itemize
+
+In each of the modes you may specify these options:
+
+@table @env
+
+@item --help
+List all options, with brief explanations.
+
+@item --version
+This option causes @command{gdbserver} to print its version number and exit.
+
+@item --attach
+@command{gdbserver} will attach to a running program. The syntax is:
+
+@smallexample
+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 @command{gdbserver} at a binary for the running process.
+
+@item --multi
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use this command line option.
+Then you can connect using @kbd{target extended-remote} and start
+the program you want to debug. The syntax is:
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
+@item --debug
+Instruct @code{gdbserver} to display extra status information about the debugging
+process.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --remote-debug
+Instruct @code{gdbserver} to display remote protocol debug output.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --wrapper
+Specify a wrapper to launch programs
+for debugging. The option should be followed by the name of the
+wrapper, then any command-line arguments to pass to the wrapper, then
+@kbd{--} indicating the end of the wrapper arguments.
+
+@item --once
+By default, @command{gdbserver} keeps the listening TCP port open, so that
+additional connections are possible. However, if you start @code{gdbserver}
+with the @option{--once} option, it will stop listening for any further
+connection attempts after connecting to the first @value{GDBN} session.
+
+@c --disable-packet is not documented for users.
+
+@c --disable-randomization and --no-disable-randomization are superseded by
+@c QDisableRandomization.
+
+@end table
+@c man end
+
+@c man begin SEEALSO gdbserver
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gcore man
+@heading gcore
+
+@c man title gcore Generate a core file of a running program
+
+@format
+@c man begin SYNOPSIS gcore
+gcore [-o @var{filename}] @var{pid}
+@c man end
+@end format
+
+@c man begin DESCRIPTION gcore
+Generate a core dump of a running program with process ID @var{pid}.
+Produced file is equivalent to a kernel produced core file as if the process
+crashed (and if @kbd{ulimit -c} were used to set up an appropriate core dump
+limit). Unlike after a crash, after @command{gcore} the program remains
+running without any change.
+@c man end
+
+@c man begin OPTIONS gcore
+@table @env
+@item -o @var{filename}
+The optional argument
+@var{filename} specifies the file name where to put the core dump.
+If not specified, the file name defaults to @file{core.@var{pid}},
+where @var{pid} is the running program process ID.
+@end table
+@c man end
+
+@c man begin SEEALSO gcore
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+@noindent
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gdbinit man
+@heading gdbinit
+
+@c man title gdbinit GDB initialization scripts
+
+@format
+@c man begin SYNOPSIS gdbinit
+@ifset SYSTEM_GDBINIT
+@value{SYSTEM_GDBINIT}
+@end ifset
+
+~/.gdbinit
+
+./.gdbinit
+@c man end
+@end format
+
+@c man begin DESCRIPTION gdbinit
+These files contain @value{GDBN} commands to automatically execute during
+@value{GDBN} startup. The lines of contents are canned sequences of commands,
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Sequences}
+-- shell command @code{info -f gdb -n Sequences}.
+@end ifset
+@ifclear man
+@ref{Sequences}.
+@end ifclear
+
+Please read more in
+@ifset man
+the @value{GDBN} manual in node @code{Startup}
+-- shell command @code{info -f gdb -n Startup}.
+@end ifset
+@ifclear man
+@ref{Startup}.
+@end ifclear
+
+@table @env
+@ifset SYSTEM_GDBINIT
+@item @value{SYSTEM_GDBINIT}
+@end ifset
+@ifclear SYSTEM_GDBINIT
+@item (not enabled with @code{--with-system-gdbinit} during compilation)
+@end ifclear
+System-wide initialization file. It is executed unless user specified
+@value{GDBN} option @code{-nx} or @code{-n}.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{System-wide configuration}
+-- shell command @code{info -f gdb -n 'System-wide configuration'}.
+@end ifset
+@ifclear man
+@ref{System-wide configuration}.
+@end ifclear
+
+@item ~/.gdbinit
+User initialization file. It is executed unless user specified
+@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}.
+
+@item ./.gdbinit
+Initialization file for current directory. It may need to be enabled with
+@value{GDBN} security command @code{set auto-load local-gdbinit}.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{Init File in the Current Directory}
+-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}.
+@end ifset
+@ifclear man
+@ref{Init File in the Current Directory}.
+@end ifclear
+@end table
+@c man end
+
+@c man begin SEEALSO gdbinit
+@ifset man
+gdb(1), @code{info -f gdb -n Startup}
+
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
@include gpl.texi
@node GNU Free Documentation License
projects / thirdparty / binutils-gdb.git / blobdiff