\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}
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
@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
a Frame}). The selected frame remains unchanged by this command.
@kindex info args
-@item info args
+@item info args [-q]
Print the arguments of the selected frame, each on a separate line.
-@item info locals
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no argument
+have been printed.
+
+@item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info args}, but only print the arguments selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the arguments whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the arguments whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+@item info locals [-q]
@kindex info locals
Print the local variables of the selected frame, each on a separate
line. These are all variables (declared either static or automatic)
accessible at the point of execution of the selected frame.
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no local variables
+have been printed.
+
+@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info locals}, but only print the local variables selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the local variables whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the local variables whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, a local variable
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+The command @kbd{info locals -q -t @var{type_regexp}} can usefully be
+combined with the commands @kbd{frame apply} and @kbd{thread apply}.
+For example, your program might use Resource Acquisition Is
+Initialization types (RAII) such as @code{lock_something_t}: each
+local variable of type @code{lock_something_t} automatically places a
+lock that is destroyed when the variable goes out of scope. You can
+then list all acquired locks in your program by doing
+@smallexample
+thread apply all -s frame apply all -s info locals -q -t lock_something_t
+@end smallexample
+@noindent
+or the equivalent shorter form
+@smallexample
+tfaas i lo -q -t lock_something_t
+@end smallexample
+
@end table
@node Frame Apply
@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
(@value{GDBP}) info task 2
Ada Task: 0x807c468
Name: task_1
-Thread: 0x807f378
+Thread: 0
+LWP: 0x1fac
Parent: 1 (main_task)
Base Priority: 15
State: Runnable
@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.
have already been read, and files whose symbols will be read when needed.
@kindex info functions
-@item info functions
+@item info functions [-q]
Print the names and data types of all defined functions.
Similarly to @samp{info types}, this command groups its output by source
files and annotates each function definition with its source line
number.
-@item info functions @var{regexp}
-Like @samp{info functions}, but only print the names and data types of
-functions whose names contain a match for regular expression
-@var{regexp}. Thus, @samp{info fun step} finds all functions whose
+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.
+
+@item info functions [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @samp{info functions}, but only print the names and data types
+of the functions selected with the provided regexp(s).
+
+If @var{regexp} is provided, print only the functions whose names
+match the regular expression @var{regexp}.
+Thus, @samp{info fun step} finds all functions whose
names include @code{step}; @samp{info fun ^step} finds those whose names
start with @code{step}. If a function name contains characters that
conflict with the regular expression language (e.g.@:
@samp{operator*()}), they may be quoted with a backslash.
+If @var{type_regexp} is provided, print only the functions whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+Thus, @samp{info fun -t '^int ('} finds the functions that return
+an integer; @samp{info fun -t '(.*int.*'} finds the functions that
+have an argument type containing int; @samp{info fun -t '^int (' ^step}
+finds the functions whose names start with @code{step} and that return
+int.
+
+If both @var{regexp} and @var{type_regexp} are provided, a function
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+
@kindex info variables
-@item info variables
+@item info variables [-q]
Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
The printed variables are grouped by source files and annotated with
their respective source line numbers.
-@item info variables @var{regexp}
-Like @kbd{info variables}, but only print the names and data types of
-non-local variables whose names contain a match for regular expression
-@var{regexp}.
+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.
+
+@item info variables [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info variables}, but only print the variables selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the variables whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the variables whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
@kindex info classes
@cindex Objective-C, classes and selectors
to a serial line. @value{GDBN} will automatically determine which
kind of file you have specified and will make the appropriate kind
of connection.
-The above command is identical to the command:
-
-@smallexample
-target remote unix::/tmp/gdb-socket1
-@end smallexample
-@noindent
-
-See below for the explanation of this syntax.
-
This feature is not available if the host system does not support
Unix domain sockets.
@itemx target remote @code{tcp4:@var{host}:@var{port}}
@itemx target remote @code{tcp6:@var{host}:@var{port}}
@itemx target remote @code{tcp6:@var{[host]}:@var{port}}
-@itemx target remote @code{unix::@var{local-socket}}
@itemx target extended-remote @code{@var{host}:@var{port}}
@itemx target extended-remote @code{@var{[host]}:@var{port}}
@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
@itemx target extended-remote @code{tcp4:@var{host}:@var{port}}
@itemx target extended-remote @code{tcp6:@var{host}:@var{port}}
@itemx target extended-remote @code{tcp6:@var{[host]}:@var{port}}
-@itemx target extended-remote @code{unix::@var{local-socket}}
@cindex @acronym{TCP} port, @code{target remote}
-Debug using a @acronym{TCP} connection to @var{port} on @var{host}
-or using the Unix domain socket @var{local-socket} on the local machine.
+Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
The @var{host} may be either a host name, a numeric @acronym{IPv4}
address, or a numeric @acronym{IPv6} address (with or without the
square brackets to separate the address from the port); @var{port}
@noindent
Note that the colon is still required here.
-Alternatively you can use a Unix domain socket:
-
-@smallexample
-target remote unix::/tmp/gdb-socket1
-@end smallexample
-@noindent
-
-This has the advantage that it'll not fail if the port number is already
-in use.
-
@item target remote @code{udp:@var{host}:@var{port}}
@itemx target remote @code{udp:@var{[host]}:@var{port}}
target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
@end smallexample
-@code{gdbserver} waits passively for the host @value{GDBN} to communicate
-with it.
-
-@var{comm} may take several forms:
-
-@table @code
-@item @var{device}
-A serial line device.
-
-@item -
-@itemx stdio
-To use the stdin/stdout of @code{gdbserver}.
-
+@var{comm} is either a device name (to use a serial line), or a TCP
+hostname and portnumber, or @code{-} or @code{stdio} to use
+stdin/stdout of @code{gdbserver}.
For example, to debug Emacs with the argument
@samp{foo.txt} and communicate with @value{GDBN} over the serial port
@file{/dev/com1}:
target> gdbserver /dev/com1 emacs foo.txt
@end smallexample
-The @code{stdio} connection is useful when starting @code{gdbserver}
-with ssh:
-
-@smallexample
-(gdb) target remote | ssh -T hostname gdbserver - hello
-@end smallexample
-
-The @samp{-T} option to ssh is provided because we don't need a remote pty,
-and we don't want escape-character handling. Ssh does this by default when
-a command is provided, the flag is provided to make it explicit.
-You could elide it if you want to.
-
-Programs started with stdio-connected gdbserver have @file{/dev/null} for
-@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for
-display through a pipe connected to gdbserver.
-Both @code{stdout} and @code{stderr} use the same pipe.
-
-@item @var{host}:@var{port}
-@itemx tcp:@var{host}:@var{port}
-@itemx tcp4:@var{host}:@var{port}
-To use a @acronym{TCP} @acronym{IPv4} socket connection on port number @var{port}.
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
To use a TCP connection instead of a serial line:
and exits.} You must use the same port number with the host @value{GDBN}
@code{target remote} command.
-
-@item tcp6:@var{host}:@var{port}
-To use a @acronym{TCP} @acronym{IPv6} socket connection on port number @var{port}.
-
-@item unix:@var{host}:@var{local-socket}
-To use a Unix domain socket. This will create a socket with the file
-system entry @var{local-socket} and listen on that. For example:
+The @code{stdio} connection is useful when starting @code{gdbserver}
+with ssh:
@smallexample
-target> gdbserver unix:localhost:/tmp/gdb-socket0 emacs foo.txt
+(gdb) target remote | ssh -T hostname gdbserver - hello
@end smallexample
-@var{host} must either be the empty string or the literal string @code{localhost}.
-@end table
+The @samp{-T} option to ssh is provided because we don't need a remote pty,
+and we don't want escape-character handling. Ssh does this by default when
+a command is provided, the flag is provided to make it explicit.
+You could elide it if you want to.
+Programs started with stdio-connected gdbserver have @file{/dev/null} for
+@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for
+display through a pipe connected to gdbserver.
+Both @code{stdout} and @code{stderr} use the same pipe.
@anchor{Attaching to a program}
@subsubsection Attaching to a Running Program
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
-@c Starting with mi3, add a new command -mi-version that prints the MI
-@c version?
+@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
+
+@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.
* 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
these to present registers @samp{ev0} through @samp{ev31} to the
user.
+The @samp{org.gnu.gdb.power.ppr} feature is optional. It should
+contain the 64-bit register @samp{ppr}.
+
+The @samp{org.gnu.gdb.power.dscr} feature is optional. It should
+contain the 64-bit register @samp{dscr}.
+
+The @samp{org.gnu.gdb.power.tar} feature is optional. It should
+contain the 64-bit register @samp{tar}.
+
+The @samp{org.gnu.gdb.power.ebb} feature is optional. It should
+contain registers @samp{bescr}, @samp{ebbhr} and @samp{ebbrr}, all
+64-bit wide.
+
+The @samp{org.gnu.gdb.power.linux.pmu} feature is optional. It should
+contain registers @samp{mmcr0}, @samp{mmcr2}, @samp{siar}, @samp{sdar}
+and @samp{sier}, all 64-bit wide. This is the subset of the isa 2.07
+server PMU registers provided by @sc{gnu}/Linux.
+
+The @samp{org.gnu.gdb.power.htm.spr} feature is optional. It should
+contain registers @samp{tfhar}, @samp{texasr} and @samp{tfiar}, all
+64-bit wide.
+
+The @samp{org.gnu.gdb.power.htm.core} feature is optional. It should
+contain the checkpointed general-purpose registers @samp{cr0} through
+@samp{cr31}, as well as the checkpointed registers @samp{clr} and
+@samp{cctr}. These registers may all be either 32-bit or 64-bit
+depending on the target. It should also contain the checkpointed
+registers @samp{ccr} and @samp{cxer}, which should both be 32-bit
+wide.
+
+The @samp{org.gnu.gdb.power.htm.fpu} feature is optional. It should
+contain the checkpointed 64-bit floating-point registers @samp{cf0}
+through @samp{cf31}, as well as the checkpointed 64-bit register
+@samp{cfpscr}.
+
+The @samp{org.gnu.gdb.power.htm.altivec} feature is optional. It
+should contain the checkpointed altivec registers @samp{cvr0} through
+@samp{cvr31}, all 128-bit wide. It should also contain the
+checkpointed registers @samp{cvscr} and @samp{cvrsave}, both 32-bit
+wide.
+
+The @samp{org.gnu.gdb.power.htm.vsx} feature is optional. It should
+contain registers @samp{cvs0h} through @samp{cvs31h}. @value{GDBN}
+will combine these registers with the checkpointed floating point
+registers (@samp{cf0} through @samp{cf31}) and the checkpointed
+altivec registers (@samp{cvr0} through @samp{cvr31}) to present the
+128-bit wide checkpointed vector-scalar registers @samp{cvs0} through
+@samp{cvs63}. Therefore, this feature requires both
+@samp{org.gnu.gdb.power.htm.altivec} and
+@samp{org.gnu.gdb.power.htm.fpu}.
+
+The @samp{org.gnu.gdb.power.htm.ppr} feature is optional. It should
+contain the 64-bit checkpointed register @samp{cppr}.
+
+The @samp{org.gnu.gdb.power.htm.dscr} feature is optional. It should
+contain the 64-bit checkpointed register @samp{cdscr}.
+
+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
projects / deliverable / binutils-gdb.git / blobdiff