\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}
@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
@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.
@end table
@node Convenience Funs
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 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.
+@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
+
+@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
-@c Starting with mi3, add a new command -mi-version that prints the MI
-@c version?
+@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}
@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.
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
projects / deliverable / binutils-gdb.git / blobdiff