\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2018 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2019 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2019 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2018 Free Software Foundation, Inc.
+Copyright (C) 1988-2019 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
communicate with @value{GDBN} using it as a back end.
@xref{Interpreters, , Command Interpreters}.
-@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
-@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
-The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
-previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
-selected with @samp{--interpreter=mi1}, is deprecated. Earlier
-@sc{gdb/mi} interfaces are no longer supported.
+@samp{--interpreter=mi} (or @samp{--interpreter=mi3}) causes
+@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} version 3 (@pxref{GDB/MI, ,
+The @sc{gdb/mi} Interface}) included since @value{GDBN} version 9.1. @sc{gdb/mi}
+version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}),
+included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi}
+interfaces are no longer supported.
@item -write
@cindex @code{--write}
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
+@table @code
+@kindex pipe
+@kindex |
+@cindex send the output of a gdb command to a shell command
+@anchor{pipe}
+@item pipe [@var{command}] | @var{shell_command}
+@itemx | [@var{command}] | @var{shell_command}
+@itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command}
+@itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command}
+Executes @var{command} and sends its output to @var{shell_command}.
+Note that no space is needed around @code{|}.
+If no @var{command} is provided, the last command executed is repeated.
+
+In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}}
+can be used to specify an alternate delimiter string @var{delim} that separates
+the @var{command} from the @var{shell_command}.
+
+Example:
+@smallexample
+@group
+(gdb) p var
+$1 = @{
+ black = 144,
+ red = 233,
+ green = 377,
+ blue = 610,
+ white = 987
+@}
+@end group
+@group
+(gdb) pipe p var|wc
+ 7 19 80
+(gdb) |p var|wc -l
+7
+@end group
+@group
+(gdb) p /x var
+$4 = @{
+ black = 0x90,
+ red = 0xe9,
+ green = 0x179,
+ blue = 0x262,
+ white = 0x3db
+@}
+(gdb) ||grep red
+ red => 0xe9,
+@end group
+@group
+(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
+this contains a PIPE char
+(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
+this contains a PIPE char!
+(gdb)
+@end group
+@end smallexample
+@end table
+
+The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal}
+can be used to examine the exit status of the last shell command launched
+by @code{shell}, @code{make}, @code{pipe} and @code{|}.
+@xref{Convenience Vars,, Convenience Variables}.
+
@node Logging Output
@section Logging Output
@cindex logging @value{GDBN} output
@item set logging redirect [on|off]
By default, @value{GDBN} output will go to both the terminal and the logfile.
Set @code{redirect} if you want output to go only to the log file.
+@item set logging debugredirect [on|off]
+By default, @value{GDBN} debug output will go to both the terminal and the logfile.
+Set @code{debugredirect} if you want debug output to go only to the log file.
@kindex show logging
@item show logging
Show the current values of the logging settings.
@end table
+You can also redirect the output of a @value{GDBN} command to a
+shell command. @xref{pipe}.
@node Commands
@chapter @value{GDBN} Commands
short paragraph on how to use that command.
@kindex apropos
-@item apropos @var{args}
+@item apropos [-v] @var{regexp}
The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
-@var{args}. It prints out all matches found. For example:
+@var{args}. It prints out all matches found. The optional flag @samp{-v},
+which stands for @samp{verbose}, indicates to output the full documentation
+of the matching commands and highlight the parts of the documentation
+matching @var{regexp}. For example:
@smallexample
apropos alias
results in:
@smallexample
-@c @group
+@group
alias -- Define a new command that is an alias of an existing command
aliases -- Aliases of other commands
d -- Delete some breakpoints or auto-display expressions
del -- Delete some breakpoints or auto-display expressions
delete -- Delete some breakpoints or auto-display expressions
-@c @end group
+@end group
+@end smallexample
+
+@noindent
+while
+
+@smallexample
+apropos -v cut.*thread apply
+@end smallexample
+
+@noindent
+results in the below output, where @samp{cut for 'thread apply}
+is highlighted if styling is enabled.
+
+@smallexample
+@group
+taas -- Apply a command to all threads (ignoring errors
+and empty output).
+Usage: taas COMMAND
+shortcut for 'thread apply all -s COMMAND'
+
+tfaas -- Apply a command to all frames of all threads
+(ignoring errors and empty output).
+Usage: tfaas COMMAND
+shortcut for 'thread apply all -s frame apply all -s COMMAND'
+@end group
@end smallexample
@kindex complete
the @code{break} command. You can delete them, disable them, or make
them conditional the same way as any other breakpoint.
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the list of all breakpoints it sets according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the breakpoint's function, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
The syntax of the regular expression is the standard one used with tools
like @file{grep}. Note that this is different from the syntax used by
shells, so for instance @code{foo*} matches all functions that include
You cannot install an exception handler interactively.
@end itemize
-@item exception
+@item exception @r{[}@var{name}@r{]}
@kindex catch exception
@cindex Ada exception catching
@cindex catch Ada exceptions
the command to use to catch such exceptions is @kbd{catch exception
Pck.Constraint_Error}.
-@item handlers
+@item exception unhandled
+@kindex catch exception unhandled
+An exception that was raised but is not handled by the program.
+
+@item handlers @r{[}@var{name}@r{]}
@kindex catch handlers
@cindex Ada exception handlers catching
@cindex catch Ada exceptions when handled
command to use to catch such exceptions handling is
@kbd{catch handlers 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.
@cindex break on fork/exec
A call to @code{exec}.
+@anchor{catch syscall}
@item syscall
@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @r{group:}@var{groupname} @r{|} @r{g:}@var{groupname}@r{]} @dots{}
@kindex catch syscall
@kindex catch vfork
A call to @code{vfork}.
-@item load @r{[}regexp@r{]}
-@itemx unload @r{[}regexp@r{]}
+@item load @r{[}@var{regexp}@r{]}
+@itemx unload @r{[}@var{regexp}@r{]}
@kindex catch load
@kindex catch unload
The loading or unloading of a shared library. If @var{regexp} is
Contrast this with the @code{return} command (@pxref{Returning,
,Returning from a Function}).
+@kindex set print finish
+@kindex show print finish
+@item set print finish @r{[}on|off@r{]}
+@itemx show print finish
+By default the @code{finish} command will show the value that is
+returned by the function. This can be disabled using @code{set print
+finish off}. When disabled, the value is still entered into the value
+history (@pxref{Value History}), but not displayed.
+
@kindex until
@kindex u @r{(@code{until})}
@cindex run until specified location
consistant state, but @value{GDBN} accepts whatever it is given.
}.
+On some platforms, @value{GDBN} has built-in support for reverse
+execution, activated with the @code{record} or @code{record btrace}
+commands. @xref{Process Record and Replay}. Some remote targets,
+typically full system emulators, support reverse execution directly
+without requiring any special command.
+
If you are debugging in a target environment that supports
reverse execution, @value{GDBN} provides the following commands.
previous instruction; otherwise, it will work in record mode, if the
platform supports reverse execution, or stop if not.
+Currently, process record and replay is supported on ARM, Aarch64,
+Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running
+GNU/Linux. Process record and replay can be used both when native
+debugging, and when remote debugging via @code{gdbserver}.
+
For architecture environments that support process record and replay,
@value{GDBN} provides the following commands:
execution.
@item btrace @var{format}
-Hardware-supported instruction recording. This method does not record
-data. Further, the data is collected in a ring buffer so old data will
-be overwritten when the buffer is full. It allows limited reverse
-execution. Variables and registers are not available during reverse
-execution. In remote debugging, recording continues on disconnect.
-Recorded data can be inspected after reconnecting. The recording may
-be stopped using @code{record stop}.
+Hardware-supported instruction recording, supported on Intel
+processors. This method does not record data. Further, the data is
+collected in a ring buffer so old data will be overwritten when the
+buffer is full. It allows limited reverse execution. Variables and
+registers are not available during reverse execution. In remote
+debugging, recording continues on disconnect. Recorded data can be
+inspected after reconnecting. The recording may be stopped using
+@code{record stop}.
The recording format can be specified as parameter. Without a parameter
the command chooses the recording format. The following recording
@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
+@item set print raw-frame-arguments on
Print frame arguments in raw, non pretty-printed, form.
-@item set print raw frame-arguments off
+@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
+@item show print raw-frame-arguments
Show whether to print frame arguments in raw form.
@anchor{set print entry-values}
Display the current threshold for printing repeated identical
elements.
+@item set print max-depth @var{depth}
+@item set print max-depth unlimited
+@cindex printing nested structures
+Set the threshold after which nested structures are replaced with
+ellipsis, this can make visualising deeply nested structures easier.
+
+For example, given this C code
+
+@smallexample
+typedef struct s1 @{ int a; @} s1;
+typedef struct s2 @{ s1 b; @} s2;
+typedef struct s3 @{ s2 c; @} s3;
+typedef struct s4 @{ s3 d; @} s4;
+
+s4 var = @{ @{ @{ @{ 3 @} @} @} @};
+@end smallexample
+
+The following table shows how different values of @var{depth} will
+effect how @code{var} is printed by @value{GDBN}:
+
+@multitable @columnfractions .3 .7
+@headitem @var{depth} setting @tab Result of @samp{p var}
+@item unlimited
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@item @code{0}
+@tab @code{$1 = @{...@}}
+@item @code{1}
+@tab @code{$1 = @{d = @{...@}@}}
+@item @code{2}
+@tab @code{$1 = @{d = @{c = @{...@}@}@}}
+@item @code{3}
+@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}}
+@item @code{4}
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@end multitable
+
+To see the contents of structures that have been hidden the user can
+either increase the print max-depth, or they can print the elements of
+the structure that are visible, for example
+
+@smallexample
+(gdb) set print max-depth 2
+(gdb) p var
+$1 = @{d = @{c = @{...@}@}@}
+(gdb) p var.d
+$2 = @{c = @{b = @{...@}@}@}
+(gdb) p var.d.c
+$3 = @{b = @{a = 3@}@}
+@end smallexample
+
+The pattern used to replace nested structures varies based on
+language, for most languages @code{@{...@}} is used, but Fortran uses
+@code{(...)}.
+
+@item show print max-depth
+Display the current threshold after which nested structures are
+replaces with ellipsis.
+
@item set print null-stop
@cindex @sc{null} elements in arrays
Cause @value{GDBN} to stop printing the characters of an array when the first
@cindex symbol decoding style, C@t{++}
@kindex set demangle-style
@item set demangle-style @var{style}
-Choose among several encoding schemes used by different compilers to
-represent C@t{++} names. The choices for @var{style} are currently:
-
-@table @code
-@item auto
-Allow @value{GDBN} to choose a decoding style by inspecting your program.
-This is the default.
-
-@item gnu
-Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
-
-@item hp
-Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
-
-@item lucid
-Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
-
-@item arm
-Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
-@strong{Warning:} this setting alone is not sufficient to allow
-debugging @code{cfront}-generated executables. @value{GDBN} would
-require further enhancement to permit that.
-
-@end table
-If you omit @var{style}, you will see a list of possible formats.
+Choose among several encoding schemes used by different compilers to represent
+C@t{++} names. If you omit @var{style}, you will see a list of possible
+formats. The default value is @var{auto}, which lets @value{GDBN} choose a
+decoding style by inspecting your program.
@item show demangle-style
Display the encoding style currently in use for decoding C@t{++} symbols.
@vindex $_tlb@r{, convenience variable}
The variable @code{$_tlb} is automatically set when debugging
applications running on MS-Windows in native mode or connected to
-gdbserver that supports the @code{qGetTIBAddr} request.
+gdbserver that supports the @code{qGetTIBAddr} request.
@xref{General Query Packets}.
This variable contains the address of the thread information block.
@item $_gthread
The global number of the current thread. @xref{global thread numbers}.
+@item $_gdb_major
+@itemx $_gdb_minor
+@vindex $_gdb_major@r{, convenience variable}
+@vindex $_gdb_minor@r{, convenience variable}
+The major and minor version numbers of the running @value{GDBN}.
+Development snapshots and pretest versions have their minor version
+incremented by one; thus, @value{GDBN} pretest 9.11.90 will produce
+the value 12 for @code{$_gdb_minor}. These variables allow you to
+write scripts that work with different versions of @value{GDBN}
+without errors caused by features unavailable in some of those
+versions.
+
+@item $_shell_exitcode
+@itemx $_shell_exitsignal
+@vindex $_shell_exitcode@r{, convenience variable}
+@vindex $_shell_exitsignal@r{, convenience variable}
+@cindex shell command, exit code
+@cindex shell command, exit signal
+@cindex exit status of shell commands
+@value{GDBN} commands such as @code{shell} and @code{|} are launching
+shell commands. When a launched command terminates, @value{GDBN}
+automatically maintains the variables @code{$_shell_exitcode}
+and @code{$_shell_exitsignal} according to the exit status of the last
+launched command. These variables are set and used similarly to
+the variables @code{$_exitcode} and @code{$_exitsignal}.
+
@end table
@node Convenience Funs
Visiting node of type NODE_INTEGER
@end smallexample
+@item $_cimag(@var{value})
+@itemx $_creal(@var{value})
+@findex $_cimag@r{, convenience function}
+@findex $_creal@r{, convenience function}
+Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of
+the complex number @var{value}.
+
+The type of the imaginary or real part depends on the type of the
+complex number, e.g., using @code{$_cimag} on a @code{float complex}
+will return an imaginary part of type @code{float}.
+
@end table
@value{GDBN} provides the ability to list and get help on
/* XXX 3-bit hole */
/* XXX 4-byte hole */
/* 8 | 8 */ int64_t a5;
-/* 16:27 | 4 */ int a6 : 5;
-/* 16:56 | 8 */ int64_t a7 : 3;
+/* 16: 0 | 4 */ int a6 : 5;
+/* 16: 5 | 8 */ int64_t a7 : 3;
+"/* XXX 7-byte padding */
/* total size (bytes): 24 */
@}
@end smallexample
-Note how the offset information is now extended to also include how
-many bits are left to be used in each bitfield.
+Note how the offset information is now extended to also include the
+first bit of the bitfield.
@end table
@kindex ptype
@samp{i type ^value$} gives information only on types whose complete
name is @code{value}.
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the type description according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the type, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
This command differs from @code{ptype} in two ways: first, like
@code{whatis}, it does not print a detailed description; second, it
lists all source files and line numbers where a type is defined.
files and annotates each function definition with its source line
number.
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the function name and type according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the function, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no functions
have been printed.
The printed variables are grouped by source files and annotated with
their respective source line numbers.
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the variable name and type according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the variable, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no variables
have been printed.
Show the current setting of stack unwinding in the functions called by
@value{GDBN}.
+@item set may-call-functions
+@kindex set may-call-functions
+@cindex disabling calling functions in the program
+@cindex calling functions in the program, disabling
+Set permission to call functions in the program.
+This controls whether @value{GDBN} will attempt to call functions in
+the program, such as with expressions in the @code{print} command. It
+defaults to @code{on}.
+
+To call a function in the program, @value{GDBN} has to temporarily
+modify the state of the inferior. This has potentially undesired side
+effects. Also, having @value{GDBN} call nested functions is likely to
+be erroneous and may even crash the program being debugged. You can
+avoid such hazards by forbidding @value{GDBN} from calling functions
+in the program being debugged. If calling functions in the program
+is forbidden, GDB will throw an error when a command (such as printing
+an expression) starts a function call in the program.
+
+@item show may-call-functions
+@kindex show may-call-functions
+Show permission to call functions in the program.
+
@end table
@subsection Calling functions with no debug info
@item
For the ``debug link'' method, @value{GDBN} looks up the named file in
the directory of the executable file, then in a subdirectory of that
-directory named @file{.debug}, and finally under each one of the global debug
-directories, in a subdirectory whose name is identical to the leading
-directories of the executable's absolute file name.
+directory named @file{.debug}, and finally under each one of the
+global debug directories, in a subdirectory whose name is identical to
+the leading directories of the executable's absolute file name. (On
+MS-Windows/MS-DOS, the drive letter of the executable's leading
+directories is converted to a one-letter subdirectory, i.e.@:
+@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows
+filesystems disallow colons in file names.)
@item
For the ``build ID'' method, @value{GDBN} looks in the
@subsection Automatic symbol index cache
+@cindex automatic symbol index cache
It is possible for @value{GDBN} to automatically save a copy of this index in a
cache on disk and retrieve it from there when loading the same binary in the
future. This feature can be turned on with @kbd{set index-cache on}. The
@table @code
+@kindex set index-cache
@item set index-cache on
@itemx set index-cache off
Enable or disable the use of the symbol index cache.
@item set index-cache directory @var{directory}
+@kindex show index-cache
@itemx show index-cache directory
Set/show the directory where index files will be saved.
status information about the debugging process.
@cindex @option{--remote-debug}, @code{gdbserver} option
The @option{--remote-debug} option tells @code{gdbserver} to display
-remote protocol debug output. These options are intended for
-@code{gdbserver} development and for bug reports to the developers.
+remote protocol debug output.
+@cindex @option{--debug-file}, @code{gdbserver} option
+@cindex @code{gdbserver}, send all debug output to a single file
+The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to
+write any debug output to the given @var{filename}. These options are intended
+for @code{gdbserver} development and for bug reports to the developers.
@cindex @option{--debug-format}, @code{gdbserver} option
The @option{--debug-format=option1[,option2,...]} option tells
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor set debug-file filename
+@itemx monitor set debug-file
+Send any debug output to the given file, or to stderr.
+
@item monitor set debug-format option1@r{[},option2,...@r{]}
Specify additional text to add to debugging messages.
Possible options are:
Record remote serial communications on the named @var{file}. The
default is not to record at all.
-@item show remotelogfile.
+@item show remotelogfile
Show the current setting of the file name on which to record the
serial communications.
* Cygwin Native:: Features specific to the Cygwin port
* Hurd Native:: Features specific to @sc{gnu} Hurd
* Darwin:: Features specific to Darwin
+* FreeBSD:: Features specific to FreeBSD
@end menu
@node BSD libkvm Interface
Show the current state of exceptions trapping.
@end table
+@node FreeBSD
+@subsection FreeBSD
+@cindex FreeBSD
+
+When the ABI of a system call is changed in the FreeBSD kernel, this
+is implemented by leaving a compatibility system call using the old
+ABI at the existing number and allocating a new system call number for
+the version using the new ABI. As a convenience, when a system call
+is caught by name (@pxref{catch syscall}), compatibility system calls
+are also caught.
+
+For example, FreeBSD 12 introduced a new variant of the @code{kevent}
+system call and catching the @code{kevent} system call by name catches
+both variants:
+
+@smallexample
+(@value{GDBP}) catch syscall kevent
+Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560])
+(@value{GDBP})
+@end smallexample
+
@node Embedded OS
@section Embedded Operating Systems
* Editing:: Command editing
* Command History:: Command history
* Screen Size:: Screen size
+* Output Styling:: Output styling
* Numbers:: Numbers
* ABI:: Configuring the current ABI
* Auto-loading:: Automatically loading associated files
Show the current pagination mode.
@end table
+@node Output Styling
+@section Output Styling
+@cindex styling
+@cindex colors
+
+@kindex set style
+@kindex show style
+@value{GDBN} can style its output on a capable terminal. This is
+enabled by default on most systems, but disabled by default when in
+batch mode (@pxref{Mode Options}). Various style settings are available;
+and styles can also be disabled entirely.
+
+@table @code
+@item set style enabled @samp{on|off}
+Enable or disable all styling. The default is host-dependent, with
+most hosts defaulting to @samp{on}.
+
+@item show style enabled
+Show the current state of styling.
+
+@item set style sources @samp{on|off}
+Enable or disable source code styling. This affects whether source
+code, such as the output of the @code{list} command, is styled. Note
+that source styling only works if styling in general is enabled, and
+if @value{GDBN} was linked with the GNU Source Highlight library. The
+default is @samp{on}.
+
+@item show style sources
+Show the current state of source code styling.
+@end table
+
+Subcommands of @code{set style} control specific forms of styling.
+These subcommands all follow the same pattern: each style-able object
+can be styled with a foreground color, a background color, and an
+intensity.
+
+For example, the style of file names can be controlled using the
+@code{set style filename} group of commands:
+
+@table @code
+@item set style filename background @var{color}
+Set the background to @var{color}. Valid colors are @samp{none}
+(meaning the terminal's default color), @samp{black}, @samp{red},
+@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
+and@samp{white}.
+
+@item set style filename foreground @var{color}
+Set the foreground to @var{color}. Valid colors are @samp{none}
+(meaning the terminal's default color), @samp{black}, @samp{red},
+@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
+and@samp{white}.
+
+@item set style filename intensity @var{value}
+Set the intensity to @var{value}. Valid intensities are @samp{normal}
+(the default), @samp{bold}, and @samp{dim}.
+@end table
+
+The @code{show style} command and its subcommands are styling
+a style name in their output using its own style.
+So, use @command{show style} to see the complete list of styles,
+their characteristics and the visual aspect of each style.
+
+The style-able objects are:
+@table @code
+@item filename
+Control the styling of file names. By default, this style's
+foreground color is green.
+
+@item function
+Control the styling of function names. These are managed with the
+@code{set style function} family of commands. By default, this
+style's foreground color is yellow.
+
+@item variable
+Control the styling of variable names. These are managed with the
+@code{set style variable} family of commands. By default, this style's
+foreground color is cyan.
+
+@item address
+Control the styling of addresses. These are managed with the
+@code{set style address} family of commands. By default, this style's
+foreground color is blue.
+
+@item title
+Control the styling of titles. These are managed with the
+@code{set style title} family of commands. By default, this style's
+intensity is bold. Commands are using the title style to improve
+the readibility of large output. For example, the commands
+@command{apropos} and @command{help} are using the title style
+for the command names.
+
+@item highlight
+Control the styling of highlightings. These are managed with the
+@code{set style highlight} family of commands. By default, this style's
+foreground color is red. Commands are using the highlight style to draw
+the user attention to some specific parts of their output. For example,
+the command @command{apropos -v REGEXP} uses the highlight style to
+mark the documentation parts matching @var{regexp}.
+
+@end table
+
@node Numbers
@section Numbers
@cindex number representation
@item mi
@cindex mi interpreter
-The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
+The newest @sc{gdb/mi} interface (currently @code{mi3}). Used primarily
by programs wishing to use @value{GDBN} as a backend for a debugger GUI
or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
Interface}.
+@item mi3
+@cindex mi3 interpreter
+The @sc{gdb/mi} interface introduced in @value{GDBN} 9.1.
+
@item mi2
@cindex mi2 interpreter
-The current @sc{gdb/mi} interface.
+The @sc{gdb/mi} interface introduced in @value{GDBN} 6.0.
@item mi1
@cindex mi1 interpreter
-The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
+The @sc{gdb/mi} interface introduced in @value{GDBN} 5.1.
@end table
The application which takes the MI output and presents the state of the
program being debugged to the user is called a @dfn{front end}.
-Although @sc{gdb/mi} is still incomplete, it is currently being used
-by a variety of front ends to @value{GDBN}. This makes it difficult
-to introduce new functionality without breaking existing usage. This
-section tries to minimize the problems by describing how the protocol
-might change.
+Since @sc{gdb/mi} is used by a variety of front ends to @value{GDBN}, changes
+to the MI interface may break existing usage. This section describes how the
+protocol changes and how to request previous version of the protocol when it
+does.
Some changes in MI need not break a carefully designed front end, and
for these the MI version will remain unchanged. The following is a
@end itemize
If the changes are likely to break front ends, the MI version level
-will be increased by one. This will allow the front end to parse the
-output according to the MI version. Apart from mi0, new versions of
-@value{GDBN} will not support old versions of MI and it will be the
-responsibility of the front end to work with the new one.
+will be increased by one. The new versions of the MI protocol are not compatible
+with the old versions. Old versions of MI remain available, allowing front ends
+to keep using them until they are modified to use the latest MI version.
+
+Since @code{--interpreter=mi} always points to the latest MI version, it is
+recommended that front ends request a specific version of MI when launching
+@value{GDBN} (e.g. @code{--interpreter=mi2}) to make sure they get an
+interpreter with the MI version they expect.
+
+The following table gives a summary of the the released versions of the MI
+interface: the version number, the version of GDB in which it first appeared
+and the breaking changes compared to the previous version.
+
+@multitable @columnfractions .05 .05 .9
+@headitem MI version @tab GDB version @tab Breaking changes
+
+@item
+@center 1
+@tab
+@center 5.1
+@tab
+None
+
+@item
+@center 2
+@tab
+@center 6.0
+@tab
+
+@itemize
+@item
+The @code{-environment-pwd}, @code{-environment-directory} and
+@code{-environment-path} commands now returns values using the MI output
+syntax, rather than CLI output syntax.
+
+@item
+@code{-var-list-children}'s @code{children} result field is now a list, rather
+than a tuple.
+
+@item
+@code{-var-update}'s @code{changelist} result field is now a list, rather than
+a tuple.
+@end itemize
+
+@item
+@center 3
+@tab
+@center 9.1
+@tab
+
+@itemize
+@item
+The output of information about multi-location breakpoints has changed in the
+responses to the @code{-break-insert} and @code{-break-info} commands, as well
+as in the @code{=breakpoint-created} and @code{=breakpoint-modified} events.
+The multiple locations are now placed in a @code{locations} field, whose value
+is a list.
+@end itemize
-@c Starting with mi3, add a new command -mi-version that prints the MI
-@c version?
+@end multitable
+
+If your front end cannot yet migrate to a more recent version of the
+MI protocol, you can nevertheless selectively enable specific features
+available in those recent MI versions, using the following commands:
+
+@table @code
+
+@item -fix-multi-location-breakpoint-output
+Use the output for multi-location breakpoints which was introduced by
+MI 3, even when using MI versions 2 or 1. This command has no
+effect when using MI version 3 or later.
+
+@end table
The best way to avoid unexpected changes in MI that might break your front
end is to make your project known to @value{GDBN} developers and
@table @code
@item number
-The breakpoint number. For a breakpoint that represents one location
-of a multi-location breakpoint, this will be a dotted pair, like
-@samp{1.2}.
+The breakpoint number.
@item type
The type of the breakpoint. For ordinary breakpoints this will be
@item what
Some extra data, the exact contents of which are type-dependent.
+@item locations
+This field is present if the breakpoint has multiple locations. It is also
+exceptionally present if the breakpoint is enabled and has a single, disabled
+location.
+
+The value is a list of locations. The format of a location is decribed below.
+
+@end table
+
+A location in a multi-location breakpoint is represented as a tuple with the
+following fields:
+
+@table @code
+
+@item number
+The location number as a dotted pair, like @samp{1.2}. The first digit is the
+number of the parent breakpoint. The second digit is the number of the
+location within that breakpoint.
+
+@item enabled
+This indicates whether the location is enabled, in which case the
+value is @samp{y}, or disabled, in which case the value is @samp{n}.
+Note that this is not the same as the field @code{enable}.
+
+@item addr
+The address of this location as an hexidecimal number.
+
+@item func
+If known, the function in which the location appears.
+If not known, this field is not present.
+
+@item file
+The name of the source file which contains this location, if known.
+If not known, this field is not present.
+
+@item fullname
+The full file name of the source file which contains this location, if
+known. If not known, this field is not present.
+
+@item line
+The line number at which this location appears, if known.
+If not known, this field is not present.
+
+@item thread-groups
+The thread groups this location is in.
+
@end table
For example, here is what the output of @code{-break-insert}
(gdb)
@end smallexample
+@subheading The @code{-complete} Command
+@findex -complete
+
+@subheading Synopsis
+
+@smallexample
+-complete @var{command}
+@end smallexample
+
+Show a list of completions for partially typed CLI @var{command}.
+
+This command is intended for @sc{gdb/mi} frontends that cannot use two separate
+CLI and MI channels --- for example: because of lack of PTYs like on Windows or
+because @value{GDBN} is used remotely via a SSH connection.
+
+@subheading Result
+
+The result consists of two or three fields:
+
+@table @samp
+@item completion
+This field contains the completed @var{command}. If @var{command}
+has no known completions, this field is omitted.
+
+@item matches
+This field contains a (possibly empty) array of matches. It is always present.
+
+@item max_completions_reached
+This field contains @code{1} if number of known completions is above
+@code{max-completions} limit (@pxref{Completion}), otherwise it contains
+@code{0}. It is always present.
+
+@end table
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{complete}.
+
+@subheading Example
+
+@smallexample
+(gdb)
+-complete br
+^done,completion="break",
+ matches=["break","break-range"],
+ max_completions_reached="0"
+(gdb)
+-complete "b ma"
+^done,completion="b ma",
+ matches=["b madvise","b main"],max_completions_reached="0"
+(gdb)
+-complete "b push_b"
+^done,completion="b push_back(",
+ matches=[
+ "b A::push_back(void*)",
+ "b std::string::push_back(char)",
+ "b std::vector<int, std::allocator<int> >::push_back(int&&)"],
+ max_completions_reached="0"
+(gdb)
+-complete "nonexist"
+^done,matches=[],max_completions_reached="0"
+(gdb)
+
+@end smallexample
+
@node Annotations
@chapter @value{GDBN} Annotations
@value{GDBN} scripting much more powerful than the restricted CLI
scripting language. If your host does not have Python installed, you
can find it on `http://www.python.org/download/'. The oldest version
-of Python supported by GDB is 2.4. The optional argument @var{python}
+of Python supported by GDB is 2.6. The optional argument @var{python}
is used to find the Python headers and libraries. It can be either
the name of a Python executable, or the name of the directory in which
Python is installed.
If a @var{filter} is passed, only the tests with @var{filter} in their
name will by ran.
-@kindex "maint info selftests"
+@kindex maint info selftests
@cindex self tests
@item maint info selftests
List the selftests compiled in to @value{GDBN}.
is also printed. For dynamically linked executables, the name of
executable or shared library containing the symbol is printed as well.
+@kindex maint test-settings
+@item maint test-settings set @var{kind}
+@itemx maint test-settings show @var{kind}
+These are representative commands for each @var{kind} of setting type
+@value{GDBN} supports. They are used by the testsuite for exercising
+the settings infrastructure.
@end table
The following command is useful for non-interactive invocations of
* Nios II Features::
* OpenRISC 1000 Features::
* PowerPC Features::
+* RISC-V Features::
* S/390 and System z Features::
* Sparc Features::
* TIC6x Features::
it should contain registers @samp{z0} through @samp{z31}, @samp{p0}
through @samp{p15}, @samp{ffr} and @samp{vg}.
+The @samp{org.gnu.gdb.aarch64.pauth} feature is optional. If present,
+it should contain registers @samp{pauth_dmask} and @samp{pauth_cmask}.
+
@node ARC Features
@subsection ARC Features
@cindex target descriptions, ARC Features
contain registers @samp{f0} through @samp{f31} and @samp{fpscr}.
The @samp{org.gnu.gdb.power.altivec} feature is optional. It should
-contain registers @samp{vr0} through @samp{vr31}, @samp{vscr},
-and @samp{vrsave}.
+contain registers @samp{vr0} through @samp{vr31}, @samp{vscr}, and
+@samp{vrsave}. @value{GDBN} will define pseudo-registers @samp{v0}
+through @samp{v31} as aliases for the corresponding @samp{vrX}
+registers.
The @samp{org.gnu.gdb.power.vsx} feature is optional. It should
-contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN}
-will combine these registers with the floating point registers
-(@samp{f0} through @samp{f31}) and the altivec registers (@samp{vr0}
-through @samp{vr31}) to present the 128-bit wide registers @samp{vs0}
-through @samp{vs63}, the set of vector registers for POWER7.
+contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN} will
+combine these registers with the floating point registers (@samp{f0}
+through @samp{f31}) and the altivec registers (@samp{vr0} through
+@samp{vr31}) to present the 128-bit wide registers @samp{vs0} through
+@samp{vs63}, the set of vector-scalar registers for POWER7.
+Therefore, this feature requires both @samp{org.gnu.gdb.power.fpu} and
+@samp{org.gnu.gdb.power.altivec}.
The @samp{org.gnu.gdb.power.spe} feature is optional. It should
contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
The @samp{org.gnu.gdb.power.htm.tar} feature is optional. It should
contain the 64-bit checkpointed register @samp{ctar}.
+
+@node RISC-V Features
+@subsection RISC-V Features
+@cindex target descriptions, RISC-V Features
+
+The @samp{org.gnu.gdb.riscv.cpu} feature is required for RISC-V
+targets. It should contain the registers @samp{x0} through
+@samp{x31}, and @samp{pc}. Either the architectural names (@samp{x0},
+@samp{x1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra},
+etc).
+
+The @samp{org.gnu.gdb.riscv.fpu} feature is optional. If present, it
+should contain registers @samp{f0} through @samp{f31}, @samp{fflags},
+@samp{frm}, and @samp{fcsr}. As with the cpu feature, either the
+architectural register names, or the ABI names can be used.
+
+The @samp{org.gnu.gdb.riscv.virtual} feature is optional. If present,
+it should contain registers that are not backed by real registers on
+the target, but are instead virtual, where the register value is
+derived from other target state. In many ways these are like
+@value{GDBN}s pseudo-registers, except implemented by the target.
+Currently the only register expected in this set is the one byte
+@samp{priv} register that contains the target's privilege level in the
+least significant two bits.
+
+The @samp{org.gnu.gdb.riscv.csr} feature is optional. If present, it
+should contain all of the target's standard CSRs. Standard CSRs are
+those defined in the RISC-V specification documents. There is some
+overlap between this feature and the fpu feature; the @samp{fflags},
+@samp{frm}, and @samp{fcsr} registers could be in either feature. The
+expectation is that these registers will be in the fpu feature if the
+target has floating point hardware, but can be moved into the csr
+feature if the target has the floating point control registers, but no
+other floating point hardware.
+
@node S/390 and System z Features
@subsection S/390 and System z Features
@cindex target descriptions, S/390 features
This option is intended for @code{gdbserver} development and for bug reports to
the developers.
+@item --debug-file=@var{filename}
+Instruct @code{gdbserver} to send any debug output to the given @var{filename}.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
@item --debug-format=option1@r{[},option2,...@r{]}
Instruct @code{gdbserver} to include extra information in each line
of debugging output.
projects / deliverable / binutils-gdb.git / blobdiff