\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2014 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@dircategory Software development
@direntry
* Gdb: (gdb). The GNU debugger.
+* gdbserver: (gdb) Server. The GNU debugging server.
@end direntry
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2014 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2013 Free Software Foundation, Inc.
+Copyright (C) 1988-2014 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
@item throw @r{[}@var{regexp}@r{]}
@itemx rethrow @r{[}@var{regexp}@r{]}
@itemx catch @r{[}@var{regexp}@r{]}
+@kindex catch throw
+@kindex catch rethrow
+@kindex catch catch
@cindex stop on C@t{++} exceptions
The throwing, re-throwing, or catching of a C@t{++} exception.
@end itemize
@item exception
+@kindex catch exception
@cindex Ada exception catching
@cindex catch Ada exceptions
An Ada exception being raised. If an exception name is specified
Pck.Constraint_Error}.
@item exception unhandled
+@kindex catch exception unhandled
An exception that was raised but is not handled by the program.
@item assert
+@kindex catch assert
A failed Ada assertion.
@item exec
+@kindex catch exec
@cindex break on fork/exec
A call to @code{exec}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item syscall
@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
+@kindex catch syscall
@cindex break on a system call.
A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
syscall is a mechanism for application programs to request a service
Again, in this case @value{GDBN} would not be able to display syscall's names.
@item fork
+@kindex catch fork
A call to @code{fork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item vfork
+@kindex catch vfork
A call to @code{vfork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item load @r{[}regexp@r{]}
@itemx unload @r{[}regexp@r{]}
+@kindex catch load
+@kindex catch unload
The loading or unloading of a shared library. If @var{regexp} is
given, then the catchpoint will stop only if the regular expression
matches one of the affected libraries.
@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
+@kindex catch signal
The delivery of a signal.
With no arguments, this catchpoint will catch any signal that is not
@end table
@item tcatch @var{event}
+@kindex tcatch
Set a catchpoint that is enabled only for one stop. The catchpoint is
automatically deleted after the first time the event is caught.
* Core File Generation:: Cause a program dump its core
* Character Sets:: Debugging programs that use a different
character set than GDB does
-* Caching Remote Data:: Data caching for remote targets
+* Caching Target Data:: Data caching for targets
* Searching Memory:: Searching memory for a sequence of bytes
@end menu
@end smallexample
@cindex C@t{++} scope resolution
-These uses of @samp{::} are very rarely in conflict with the very similar
-use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
-scope resolution operator in @value{GDBN} expressions.
-@c FIXME: Um, so what happens in one of those rare cases where it's in
-@c conflict?? --mew
+These uses of @samp{::} are very rarely in conflict with the very
+similar use of the same notation in C@t{++}. When they are in
+conflict, the C@t{++} meaning takes precedence; however, this can be
+overridden by quoting the file or function name with single quotes.
+
+For example, suppose the program is stopped in a method of a class
+that has a field named @code{includefile}, and there is also an
+include file named @file{includefile} that defines a variable,
+@code{some_global}.
+
+@smallexample
+(@value{GDBP}) p includefile
+$1 = 23
+(@value{GDBP}) p includefile::some_global
+A syntax error in expression, near `'.
+(@value{GDBP}) p 'includefile'::some_global
+$2 = 27
+@end smallexample
@cindex wrong values
@cindex variable values, wrong
The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
character.
-@node Caching Remote Data
-@section Caching Data of Remote Targets
-@cindex caching data of remote targets
-
-@value{GDBN} caches data exchanged between the debugger and a
-remote target (@pxref{Remote Debugging}). Such caching generally improves
-performance, because it reduces the overhead of the remote protocol by
-bundling memory reads and writes into large chunks. Unfortunately, simply
-caching everything would lead to incorrect results, since @value{GDBN}
-does not necessarily know anything about volatile values, memory-mapped I/O
-addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
-memory can be changed @emph{while} a gdb command is executing.
+@node Caching Target Data
+@section Caching Data of Targets
+@cindex caching data of targets
+
+@value{GDBN} caches data exchanged between the debugger and a target.
+Each cache is associated with the address space of the inferior.
+@xref{Inferiors and Programs}, about inferior and address space.
+Such caching generally improves performance in remote debugging
+(@pxref{Remote Debugging}), because it reduces the overhead of the
+remote protocol by bundling memory reads and writes into large chunks.
+Unfortunately, simply caching everything would lead to incorrect results,
+since @value{GDBN} does not necessarily know anything about volatile
+values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode
+(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command
+is executing.
Therefore, by default, @value{GDBN} only caches data
known to be on the stack@footnote{In non-stop mode, it is moderately
rare for a running thread to modify the stack of a stopped thread
in a way that would interfere with a backtrace, and caching of
-stack reads provides a significant speed up of remote backtraces.}.
+stack reads provides a significant speed up of remote backtraces.} or
+in the code segment.
Other regions of memory can be explicitly marked as
-cacheable; see @pxref{Memory Region Attributes}.
+cacheable; @pxref{Memory Region Attributes}.
@table @code
@kindex set remotecache
@kindex set stack-cache
@item set stack-cache on
@itemx set stack-cache off
-Enable or disable caching of stack accesses. When @code{ON}, use
-caching. By default, this option is @code{ON}.
+Enable or disable caching of stack accesses. When @code{on}, use
+caching. By default, this option is @code{on}.
@kindex show stack-cache
@item show stack-cache
Show the current state of data caching for memory accesses.
+@kindex set code-cache
+@item set code-cache on
+@itemx set code-cache off
+Enable or disable caching of code segment accesses. When @code{on},
+use caching. By default, this option is @code{on}. This improves
+performance of disassembly in remote debugging.
+
+@kindex show code-cache
+@item show code-cache
+Show the current state of target memory cache for code segment
+accesses.
+
@kindex info dcache
@item info dcache @r{[}line@r{]}
-Print the information about the data cache performance. The
-information displayed includes the dcache width and depth, and for
-each cache line, its number, address, and how many times it was
-referenced. This command is useful for debugging the data cache
-operation.
+Print the information about the performance of data cache of the
+current inferior's address space. The information displayed
+includes the dcache width and depth, and for each cache line, its
+number, address, and how many times it was referenced. This
+command is useful for debugging the data cache operation.
If a line number is specified, the contents of that line will be
printed in hex.
@item show dcache size
@kindex show dcache size
-Show maximum number of dcache entries. See also @ref{Caching Remote Data, info dcache}.
+Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}.
@item show dcache line-size
@kindex show dcache line-size
-Show default size of dcache lines. See also @ref{Caching Remote Data, info dcache}.
+Show default size of dcache lines.
@end table
from functions.
@end table
+@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).
+@cindex Intel(R) Memory Protection Extensions (MPX).
+
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{The register named with capital letters represent the architecture
+registers.} through @samp{BND3}. Bound registers store a pair of 64-bit values
+which are the lower bound and upper bound. Bounds are effective addresses or
+memory locations. The upper bounds are architecturally represented in 1's
+complement form. A bound having lower bound = 0, and upper bound = 0
+(1's complement of all bits set) will allow access to the entire address space.
+
+@samp{BND0} through @samp{BND3} are represented in @value{GDBN} as @samp{bnd0raw}
+through @samp{bnd3raw}. Pseudo registers @samp{bnd0} through @samp{bnd3}
+display the upper bound performing the complement of one operation on the
+upper bound value, i.e.@ when upper bound in @samp{bnd0raw} is 0 in the
+@value{GDBN} @samp{bnd0} it will be @code{0xfff@dots{}}. In this sense it
+can also be noted that the upper bounds are inclusive.
+
+As an example, assume that the register BND0 holds bounds for a pointer having
+access allowed for the range between 0x32 and 0x71. The values present on
+bnd0raw and bnd registers are presented as follows:
+
+@smallexample
+ bnd0raw = @{0x32, 0xffffffff8e@}
+ bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64
+@end smallexample
+
+This way the raw value can be accessed via bnd0raw@dots{}bnd3raw. Any
+change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its
+counterpart. When the bnd0@dots{}bnd3 registers are displayed via
+Python, the display includes the memory size, in bits, accessible to
+the pointer.
+
@node Alpha
@subsection Alpha
results or introduce security risks (e.g., if the file comes from untrusted
sources).
+@menu
+* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
+* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
+
+* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
+* Auto-loading verbose mode:: @samp{set/show debug auto-load}
+@end menu
+
+There are various kinds of files @value{GDBN} can automatically load.
+In addition to these files, @value{GDBN} supports auto-loading code written
+in various extension languages. @xref{Auto-loading extensions}.
+
Note that loading of these associated files (including the local @file{.gdbinit}
file) requires accordingly configured @code{auto-load safe-path}
(@pxref{Auto-loading safe path}).
@end smallexample
@end table
-These are various kinds of files @value{GDBN} can automatically load:
-
-@itemize @bullet
-@item
-@xref{objfile-gdb.py file}, controlled by @ref{set auto-load python-scripts}.
-@item
-@xref{objfile-gdb.gdb file}, controlled by @ref{set auto-load gdb-scripts}.
-@item
-@xref{dotdebug_gdb_scripts section},
-controlled by @ref{set auto-load python-scripts}.
-@item
-@xref{Init File in the Current Directory},
-controlled by @ref{set auto-load local-gdbinit}.
-@item
-@xref{libthread_db.so.1 file}, controlled by @ref{set auto-load libthread-db}.
-@end itemize
-
These are @value{GDBN} control commands for the auto-loading:
@multitable @columnfractions .5 .5
@tab Add directory trusted for automatic loading.
@end multitable
-@menu
-* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
-* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
-* objfile-gdb.gdb file:: @samp{set/show/info auto-load gdb-script}
-* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
-* Auto-loading verbose mode:: @samp{set/show debug auto-load}
-@xref{Python Auto-loading}.
-@end menu
-
@node Init File in the Current Directory
@subsection Automatically loading init file in the current directory
@cindex auto-loading init file in the current directory
for each such library print list of inferior @var{pid}s using it.
@end table
-@node objfile-gdb.gdb file
-@subsection The @file{@var{objfile}-gdb.gdb} file
-@cindex auto-loading @file{@var{objfile}-gdb.gdb}
-
-@value{GDBN} tries to load an @file{@var{objfile}-gdb.gdb} file containing
-canned sequences of commands (@pxref{Sequences}), as long as @samp{set
-auto-load gdb-scripts} is set to @samp{on}.
-
-Note that loading of this script file also requires accordingly configured
-@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-
-For more background refer to the similar Python scripts auto-loading
-description (@pxref{objfile-gdb.py file}).
-
-@table @code
-@anchor{set auto-load gdb-scripts}
-@kindex set auto-load gdb-scripts
-@item set auto-load gdb-scripts [on|off]
-Enable or disable the auto-loading of canned sequences of commands scripts.
-
-@anchor{show auto-load gdb-scripts}
-@kindex show auto-load gdb-scripts
-@item show auto-load gdb-scripts
-Show whether auto-loading of canned sequences of commands scripts is enabled or
-disabled.
-
-@anchor{info auto-load gdb-scripts}
-@kindex info auto-load gdb-scripts
-@cindex print list of auto-loaded canned sequences of commands scripts
-@item info auto-load gdb-scripts [@var{regexp}]
-Print the list of all canned sequences of commands scripts that @value{GDBN}
-auto-loaded.
-@end table
-
-If @var{regexp} is supplied only canned sequences of commands scripts with
-matching names are printed.
-
@node Auto-loading safe path
@subsection Security restriction for auto-loading
@cindex auto-loading safe-path
@chapter Extending @value{GDBN}
@cindex extending GDB
-@value{GDBN} provides three mechanisms for extension. The first is based
-on composition of @value{GDBN} commands, the second is based on the
-Python scripting language, and the third is for defining new aliases of
-existing commands.
+@value{GDBN} provides several mechanisms for extension.
+@value{GDBN} also provides the ability to automatically load
+extensions when it reads a file for debugging. This allows the
+user to automatically customize @value{GDBN} for the program
+being debugged.
-To facilitate the use of the first two extensions, @value{GDBN} is capable
+@menu
+* Sequences:: Canned Sequences of @value{GDBN} Commands
+* Python:: Extending @value{GDBN} using Python
+* Auto-loading extensions:: Automatically loading extensions
+* Aliases:: Creating new spellings of existing commands
+@end menu
+
+To facilitate the use of extension languages, @value{GDBN} is capable
of evaluating the contents of a file. When doing so, @value{GDBN}
-can recognize which scripting language is being used by looking at
+can recognize which extension language is being used by looking at
the filename extension. Files with an unrecognized filename extension
are always treated as a @value{GDBN} Command Files.
@xref{Command Files,, Command files}.
@end table
-@menu
-* Sequences:: Canned Sequences of Commands
-* Python:: Scripting @value{GDBN} using Python
-* Aliases:: Creating new spellings of existing commands
-@end menu
-
@node Sequences
@section Canned Sequences of Commands
* Hooks:: Hooks for user-defined commands
* Command Files:: How to write scripts of commands to be stored in a file
* Output:: Commands for controlled output
+* Auto-loading sequences:: Controlling auto-loaded command files
@end menu
@node Define
@end table
+@node Auto-loading sequences
+@subsection Controlling auto-loading native @value{GDBN} scripts
+@cindex native script auto-loading
+
+When a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library),
+@value{GDBN} will look for the command file @file{@var{objfile}-gdb.gdb}.
+@xref{Auto-loading extensions}.
+
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
+
+@table @code
+@anchor{set auto-load gdb-scripts}
+@kindex set auto-load gdb-scripts
+@item set auto-load gdb-scripts [on|off]
+Enable or disable the auto-loading of canned sequences of commands scripts.
+
+@anchor{show auto-load gdb-scripts}
+@kindex show auto-load gdb-scripts
+@item show auto-load gdb-scripts
+Show whether auto-loading of canned sequences of commands scripts is enabled or
+disabled.
+
+@anchor{info auto-load gdb-scripts}
+@kindex info auto-load gdb-scripts
+@cindex print list of auto-loaded canned sequences of commands scripts
+@item info auto-load gdb-scripts [@var{regexp}]
+Print the list of all canned sequences of commands scripts that @value{GDBN}
+auto-loaded.
+@end table
+
+If @var{regexp} is supplied only canned sequences of commands scripts with
+matching names are printed.
+
@node Python
-@section Scripting @value{GDBN} using Python
+@section Extending @value{GDBN} using Python
@cindex python scripting
@cindex scripting with python
-You can script @value{GDBN} using the @uref{http://www.python.org/,
+You can extend @value{GDBN} using the @uref{http://www.python.org/,
Python programming language}. This feature is available only if
@value{GDBN} was configured using @option{--with-python}.
bar = some_val['foo']
@end smallexample
-Again, @code{bar} will also be a @code{gdb.Value} object.
+@cindex getting structure elements using gdb.Field objects as subscripts
+Again, @code{bar} will also be a @code{gdb.Value} object. Structure
+elements can also be accessed by using @code{gdb.Field} objects as
+subscripts (@pxref{Types In Python}, for more information on
+@code{gdb.Field} objects). For example, if @code{foo_field} is a
+@code{gdb.Field} object corresponding to element @code{foo} of the above
+structure, then @code{bar} can also be accessed as follows:
+
+@smallexample
+bar = some_val[foo_field]
+@end smallexample
A @code{gdb.Value} that represents a function can be executed via
inferior function call. Any arguments provided to the call must match
Each field is a @code{gdb.Field} object, with some pre-defined attributes:
@table @code
@item bitpos
-This attribute is not available for @code{static} fields (as in
-C@t{++} or Java). For non-@code{static} fields, the value is the bit
-position of the field. For @code{enum} fields, the value is the
-enumeration member's integer representation.
+This attribute is not available for @code{enum} or @code{static}
+(as in C@t{++} or Java) fields. The value is the position, counting
+in bits, from the start of the containing type.
+
+@item enumval
+This attribute is only available for @code{enum} fields, and its value
+is the enumeration member's integer representation.
@item name
The name of the field, or @code{None} for anonymous fields.
@item type
The type of the field. This is usually an instance of @code{Type},
but it can be @code{None} in some situations.
+
+@item parent_type
+The type which contains this field. This is an instance of
+@code{gdb.Type}.
@end table
@end defun
No particular reason (older frames should be available).
@item gdb.FRAME_UNWIND_NULL_ID
-The previous frame's analyzer returns an invalid result.
+The previous frame's analyzer returns an invalid result. This is no
+longer used by @value{GDBN}, and is kept only for backward
+compatibility.
@item gdb.FRAME_UNWIND_OUTERMOST
This frame is the outermost.
@defun Breakpoint.stop (self)
The @code{gdb.Breakpoint} class can be sub-classed and, in
particular, you may choose to implement the @code{stop} method.
-If this method is defined as a sub-class of @code{gdb.Breakpoint},
+If this method is defined in a sub-class of @code{gdb.Breakpoint},
it will be called when the inferior reaches any location of a
breakpoint which instantiates that sub-class. If the method returns
@code{True}, the inferior will be stopped at the location of the
When a new object file is read (for example, due to the @code{file}
command, or because the inferior has loaded a shared library),
@value{GDBN} will look for Python support scripts in several ways:
-@file{@var{objfile}-gdb.py} (@pxref{objfile-gdb.py file})
-and @code{.debug_gdb_scripts} section
-(@pxref{dotdebug_gdb_scripts section}).
+@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
+@xref{Auto-loading extensions}.
The auto-loading feature is useful for supplying application-specific
debugging commands and scripts.
function (@pxref{Objfiles In Python}). This can be useful for
registering objfile-specific pretty-printers and frame-filters.
-@menu
-* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
-* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
-* Which flavor to choose?::
-@end menu
-
-@node objfile-gdb.py file
-@subsubsection The @file{@var{objfile}-gdb.py} file
-@cindex @file{@var{objfile}-gdb.py}
-
-When a new object file is read, @value{GDBN} looks for
-a file named @file{@var{objfile}-gdb.py} (we call it @var{script-name} below),
-where @var{objfile} is the object file's real name, formed by ensuring
-that the file name is absolute, following all symlinks, and resolving
-@code{.} and @code{..} components. If this file exists and is
-readable, @value{GDBN} will evaluate it as a Python script.
-
-If this file does not exist, then @value{GDBN} will look for
-@var{script-name} file in all of the directories as specified below.
-
-Note that loading of this script file also requires accordingly configured
-@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-
-For object files using @file{.exe} suffix @value{GDBN} tries to load first the
-scripts normally according to its @file{.exe} filename. But if no scripts are
-found @value{GDBN} also tries script filenames matching the object file without
-its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
-is attempted on any platform. This makes the script filenames compatible
-between Unix and MS-Windows hosts.
-
-@table @code
-@anchor{set auto-load scripts-directory}
-@kindex set auto-load scripts-directory
-@item set auto-load scripts-directory @r{[}@var{directories}@r{]}
-Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
-may be delimited by the host platform path separator in use
-(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
-
-Each entry here needs to be covered also by the security setting
-@code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
-
-@anchor{with-auto-load-dir}
-This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
-@code{set auto-load safe-path} value can be also overriden by @value{GDBN}
-configuration option @option{--with-auto-load-dir}.
-
-Any reference to @file{$debugdir} will get replaced by
-@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
-reference to @file{$datadir} will get replaced by @var{data-directory} which is
-determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
-@file{$datadir} must be placed as a directory component --- either alone or
-delimited by @file{/} or @file{\} directory separators, depending on the host
-platform.
-
-The list of directories uses path separator (@samp{:} on GNU and Unix
-systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
-to the @env{PATH} environment variable.
-
-@anchor{show auto-load scripts-directory}
-@kindex show auto-load scripts-directory
-@item show auto-load scripts-directory
-Show @value{GDBN} auto-loaded scripts location.
-@end table
-
-@value{GDBN} does not track which files it has already auto-loaded this way.
-@value{GDBN} will load the associated script every time the corresponding
-@var{objfile} is opened.
-So your @file{-gdb.py} file should be careful to avoid errors if it
-is evaluated more than once.
-
-@node dotdebug_gdb_scripts section
-@subsubsection The @code{.debug_gdb_scripts} section
-@cindex @code{.debug_gdb_scripts} section
-
-For systems using file formats like ELF and COFF,
-when @value{GDBN} loads a new object file
-it will look for a special section named @samp{.debug_gdb_scripts}.
-If this section exists, its contents is a list of names of scripts to load.
-
-@value{GDBN} will look for each specified script file first in the
-current directory and then along the source search path
-(@pxref{Source Path, ,Specifying Source Directories}),
-except that @file{$cdir} is not searched, since the compilation
-directory is not relevant to scripts.
-
-Entries can be placed in section @code{.debug_gdb_scripts} with,
-for example, this GCC macro:
-
-@example
-/* Note: The "MS" section flags are to remove duplicates. */
-#define DEFINE_GDB_SCRIPT(script_name) \
- asm("\
-.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
-.byte 1\n\
-.asciz \"" script_name "\"\n\
-.popsection \n\
-");
-@end example
-
-@noindent
-Then one can reference the macro in a header or source file like this:
-
-@example
-DEFINE_GDB_SCRIPT ("my-app-scripts.py")
-@end example
-
-The script name may include directories if desired.
-
-Note that loading of this script file also requires accordingly configured
-@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-
-If the macro is put in a header, any application or library
-using this header will get a reference to the specified script.
-
-@node Which flavor to choose?
-@subsubsection Which flavor to choose?
-
-Given the multiple ways of auto-loading Python scripts, it might not always
-be clear which one to choose. This section provides some guidance.
-
-Benefits of the @file{-gdb.py} way:
-
-@itemize @bullet
-@item
-Can be used with file formats that don't support multiple sections.
-
-@item
-Ease of finding scripts for public libraries.
-
-Scripts specified in the @code{.debug_gdb_scripts} section are searched for
-in the source search path.
-For publicly installed libraries, e.g., @file{libstdc++}, there typically
-isn't a source directory in which to find the script.
-
-@item
-Doesn't require source code additions.
-@end itemize
-
-Benefits of the @code{.debug_gdb_scripts} way:
-
-@itemize @bullet
-@item
-Works with static linking.
-
-Scripts for libraries done the @file{-gdb.py} way require an objfile to
-trigger their loading. When an application is statically linked the only
-objfile available is the executable, and it is cumbersome to attach all the
-scripts from all the input libraries to the executable's @file{-gdb.py} script.
-
-@item
-Works with classes that are entirely inlined.
-
-Some classes can be entirely inlined, and thus there may not be an associated
-shared library to attach a @file{-gdb.py} script to.
-
-@item
-Scripts needn't be copied out of the source tree.
-
-In some circumstances, apps can be built out of large collections of internal
-libraries, and the build infrastructure necessary to install the
-@file{-gdb.py} scripts in a place where @value{GDBN} can find them is
-cumbersome. It may be easier to specify the scripts in the
-@code{.debug_gdb_scripts} section as relative paths, and add a path to the
-top of the source tree to the source search path.
-@end itemize
-
@node Python modules
@subsection Python modules
@cindex python modules
@end smallexample
@end table
+@node Auto-loading extensions
+@section Auto-loading extensions
+@cindex auto-loading extensions
+
+@value{GDBN} provides two mechanisms for automatically loading extensions
+when a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library):
+@file{@var{objfile}-gdb.@var{ext}} and the @code{.debug_gdb_scripts}
+section of modern file formats like ELF.
+
+@menu
+* objfile-gdb.ext file: objfile-gdbdotext file. The @file{@var{objfile}-gdb.@var{ext}} file
+* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The @code{.debug_gdb_scripts} section
+* Which flavor to choose?::
+@end menu
+
+The auto-loading feature is useful for supplying application-specific
+debugging commands and features.
+
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
+See the @samp{auto-loading} section of each extension language
+for more information.
+For @value{GDBN} command files see @ref{Auto-loading sequences}.
+For Python files see @ref{Python Auto-loading}.
+
+Note that loading of this script file also requires accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+
+@node objfile-gdbdotext file
+@subsection The @file{@var{objfile}-gdb.@var{ext}} file
+@cindex @file{@var{objfile}-gdb.gdb}
+@cindex @file{@var{objfile}-gdb.py}
+@cindex @file{@var{objfile}-gdb.scm}
+
+When a new object file is read, @value{GDBN} looks for a file named
+@file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below),
+where @var{objfile} is the object file's name and
+where @var{ext} is the file extension for the extension language:
+
+@table @code
+@item @file{@var{objfile}-gdb.gdb}
+GDB's own command language
+@item @file{@var{objfile}-gdb.py}
+Python
+@end table
+
+@var{script-name} is formed by ensuring that the file name of @var{objfile}
+is absolute, following all symlinks, and resolving @code{.} and @code{..}
+components, and appending the @file{-gdb.@var{ext}} suffix.
+If this file exists and is readable, @value{GDBN} will evaluate it as a
+script in the specified extension language.
+
+If this file does not exist, then @value{GDBN} will look for
+@var{script-name} file in all of the directories as specified below.
+
+Note that loading of these files requires an accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+
+For object files using @file{.exe} suffix @value{GDBN} tries to load first the
+scripts normally according to its @file{.exe} filename. But if no scripts are
+found @value{GDBN} also tries script filenames matching the object file without
+its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
+is attempted on any platform. This makes the script filenames compatible
+between Unix and MS-Windows hosts.
+
+@table @code
+@anchor{set auto-load scripts-directory}
+@kindex set auto-load scripts-directory
+@item set auto-load scripts-directory @r{[}@var{directories}@r{]}
+Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
+may be delimited by the host platform path separator in use
+(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
+
+Each entry here needs to be covered also by the security setting
+@code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
+
+@anchor{with-auto-load-dir}
+This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
+@code{set auto-load safe-path} value can be also overriden by @value{GDBN}
+configuration option @option{--with-auto-load-dir}.
+
+Any reference to @file{$debugdir} will get replaced by
+@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
+reference to @file{$datadir} will get replaced by @var{data-directory} which is
+determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
+@file{$datadir} must be placed as a directory component --- either alone or
+delimited by @file{/} or @file{\} directory separators, depending on the host
+platform.
+
+The list of directories uses path separator (@samp{:} on GNU and Unix
+systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
+to the @env{PATH} environment variable.
+
+@anchor{show auto-load scripts-directory}
+@kindex show auto-load scripts-directory
+@item show auto-load scripts-directory
+Show @value{GDBN} auto-loaded scripts location.
+@end table
+
+@value{GDBN} does not track which files it has already auto-loaded this way.
+@value{GDBN} will load the associated script every time the corresponding
+@var{objfile} is opened.
+So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it
+is evaluated more than once.
+
+@node dotdebug_gdb_scripts section
+@subsection The @code{.debug_gdb_scripts} section
+@cindex @code{.debug_gdb_scripts} section
+
+For systems using file formats like ELF and COFF,
+when @value{GDBN} loads a new object file
+it will look for a special section named @code{.debug_gdb_scripts}.
+If this section exists, its contents is a list of NUL-terminated names
+of scripts to load. Each entry begins with a non-NULL prefix byte that
+specifies the kind of entry, typically the extension language.
+
+@value{GDBN} will look for each specified script file first in the
+current directory and then along the source search path
+(@pxref{Source Path, ,Specifying Source Directories}),
+except that @file{$cdir} is not searched, since the compilation
+directory is not relevant to scripts.
+
+Entries can be placed in section @code{.debug_gdb_scripts} with,
+for example, this GCC macro for Python scripts.
+
+@example
+/* Note: The "MS" section flags are to remove duplicates. */
+#define DEFINE_GDB_PY_SCRIPT(script_name) \
+ asm("\
+.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
+.byte 1 /* Python */\n\
+.asciz \"" script_name "\"\n\
+.popsection \n\
+");
+@end example
+
+@noindent
+Then one can reference the macro in a header or source file like this:
+
+@example
+DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py")
+@end example
+
+The script name may include directories if desired.
+
+Note that loading of this script file also requires accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+
+If the macro invocation is put in a header, any application or library
+using this header will get a reference to the specified script,
+and with the use of @code{"MS"} attributes on the section, the linker
+will remove duplicates.
+
+@node Which flavor to choose?
+@subsection Which flavor to choose?
+
+Given the multiple ways of auto-loading extensions, it might not always
+be clear which one to choose. This section provides some guidance.
+
+@noindent
+Benefits of the @file{-gdb.@var{ext}} way:
+
+@itemize @bullet
+@item
+Can be used with file formats that don't support multiple sections.
+
+@item
+Ease of finding scripts for public libraries.
+
+Scripts specified in the @code{.debug_gdb_scripts} section are searched for
+in the source search path.
+For publicly installed libraries, e.g., @file{libstdc++}, there typically
+isn't a source directory in which to find the script.
+
+@item
+Doesn't require source code additions.
+@end itemize
+
+@noindent
+Benefits of the @code{.debug_gdb_scripts} way:
+
+@itemize @bullet
+@item
+Works with static linking.
+
+Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to
+trigger their loading. When an application is statically linked the only
+objfile available is the executable, and it is cumbersome to attach all the
+scripts from all the input libraries to the executable's
+@file{-gdb.@var{ext}} script.
+
+@item
+Works with classes that are entirely inlined.
+
+Some classes can be entirely inlined, and thus there may not be an associated
+shared library to attach a @file{-gdb.@var{ext}} script to.
+
+@item
+Scripts needn't be copied out of the source tree.
+
+In some circumstances, apps can be built out of large collections of internal
+libraries, and the build infrastructure necessary to install the
+@file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is
+cumbersome. It may be easier to specify the scripts in the
+@code{.debug_gdb_scripts} section as relative paths, and add a path to the
+top of the source tree to the source search path.
+@end itemize
+
@node Aliases
@section Creating new spellings of existing commands
@cindex aliases for commands
* GDB/MI Target Manipulation::
* GDB/MI File Transfer Commands::
* GDB/MI Ada Exceptions Commands::
+* GDB/MI Support Commands::
* GDB/MI Miscellaneous Commands::
@end menu
@findex ^connected
@value{GDBN} has connected to a remote target.
-@item "^error" "," @var{c-string}
+@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
@findex ^error
-The operation failed. The @code{@var{c-string}} contains the corresponding
-error message.
+The operation failed. The @code{msg=@var{c-string}} variable contains
+the corresponding error message.
+
+If present, the @code{code=@var{c-string}} variable provides an error
+code on which consumers can rely on to detect the corresponding
+error condition. At present, only one error code is defined:
+
+@table @samp
+@item "undefined-command"
+Indicates that the command causing the error does not exist.
+@end table
@item "^exit"
@findex ^exit
@item frozen
If the variable object is frozen, this variable will be present with a value of 1.
+
+@item displayhint
+A dynamic varobj can supply a display hint to the front end. The
+value comes directly from the Python pretty-printer object's
+@code{display_hint} method. @xref{Pretty Printing API}.
+
+@item dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
@end table
The result may have its own attributes:
a varobj is created, and so ordinarily is not needed.
This feature is only available if Python support is enabled. The MI
-command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands})
+command @code{-list-features} (@pxref{GDB/MI Support Commands})
can be used to check this.
@subsubheading Example
Catchpoint Commands}.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Support Commands
+@section @sc{gdb/mi} Support Commands
+
+Since new commands and features get regularly added to @sc{gdb/mi},
+some commands are available to help front-ends query the debugger
+about support for these capabilities. Similarly, it is also possible
+to query @value{GDBN} about target support of certain features.
+
+@subheading The @code{-info-gdb-mi-command} Command
+@cindex @code{-info-gdb-mi-command}
+@findex -info-gdb-mi-command
+
+@subsubheading Synopsis
+
+@smallexample
+ -info-gdb-mi-command @var{cmd_name}
+@end smallexample
+
+Query support for the @sc{gdb/mi} command named @var{cmd_name}.
+
+Note that the dash (@code{-}) starting all @sc{gdb/mi} commands
+is technically not part of the command name (@pxref{GDB/MI Input
+Syntax}), and thus should be omitted in @var{cmd_name}. However,
+for ease of use, this command also accepts the form with the leading
+dash.
+
+@subsubheading @value{GDBN} Command
+
+There is no corresponding @value{GDBN} command.
+
+@subsubheading Result
+
+The result is a tuple. There is currently only one field:
+
+@table @samp
+@item exists
+This field is equal to @code{"true"} if the @sc{gdb/mi} command exists,
+@code{"false"} otherwise.
+
+@end table
+
+@subsubheading Example
+
+Here is an example where the @sc{gdb/mi} command does not exist:
+
+@smallexample
+-info-gdb-mi-command unsupported-command
+^done,command=@{exists="false"@}
+@end smallexample
+
+@noindent
+And here is an example where the @sc{gdb/mi} command is known
+to the debugger:
+
+@smallexample
+-info-gdb-mi-command symbol-list-lines
+^done,command=@{exists="true"@}
+@end smallexample
+
+@subheading The @code{-list-features} Command
+@findex -list-features
+@cindex supported @sc{gdb/mi} features, list
+
+Returns a list of particular features of the MI protocol that
+this version of gdb implements. A feature can be a command,
+or a new field in an output of some command, or even an
+important bugfix. While a frontend can sometimes detect presence
+of a feature at runtime, it is easier to perform detection at debugger
+startup.
+
+The command returns a list of strings, with each string naming an
+available feature. Each returned string is just a name, it does not
+have any internal structure. The list of possible feature names
+is given below.
+
+Example output:
+
+@smallexample
+(gdb) -list-features
+^done,result=["feature1","feature2"]
+@end smallexample
+
+The current list of features is:
+
+@ftable @samp
+@item frozen-varobjs
+Indicates support for the @code{-var-set-frozen} command, as well
+as possible presense of the @code{frozen} field in the output
+of @code{-varobj-create}.
+@item pending-breakpoints
+Indicates support for the @option{-f} option to the @code{-break-insert}
+command.
+@item python
+Indicates Python scripting support, Python-based
+pretty-printing commands, and possible presence of the
+@samp{display_hint} field in the output of @code{-var-list-children}
+@item thread-info
+Indicates support for the @code{-thread-info} command.
+@item data-read-memory-bytes
+Indicates support for the @code{-data-read-memory-bytes} and the
+@code{-data-write-memory-bytes} commands.
+@item breakpoint-notifications
+Indicates that changes to breakpoints and breakpoints created via the
+CLI will be announced via async records.
+@item ada-task-info
+Indicates support for the @code{-ada-task-info} command.
+@item language-option
+Indicates that all @sc{gdb/mi} commands accept the @option{--language}
+option (@pxref{Context management}).
+@item info-gdb-mi-command
+Indicates support for the @code{-info-gdb-mi-command} command.
+@item undefined-command-error-code
+Indicates support for the "undefined-command" error code in error result
+records, produced when trying to execute an undefined @sc{gdb/mi} command
+(@pxref{GDB/MI Result Records}).
+@item exec-run-start-option
+Indicates that the @code{-exec-run} command supports the @option{--start}
+option (@pxref{GDB/MI Program Execution}).
+@end ftable
+
+@subheading The @code{-list-target-features} Command
+@findex -list-target-features
+
+Returns a list of particular features that are supported by the
+target. Those features affect the permitted MI commands, but
+unlike the features reported by the @code{-list-features} command, the
+features depend on which target GDB is using at the moment. Whenever
+a target can change, due to commands such as @code{-target-select},
+@code{-target-attach} or @code{-exec-run}, the list of target features
+may change, and the frontend should obtain it again.
+Example output:
+
+@smallexample
+(gdb) -list-target-features
+^done,result=["async"]
+@end smallexample
+
+The current list of features is:
+
+@table @samp
+@item async
+Indicates that the target is capable of asynchronous command
+execution, which means that @value{GDBN} will accept further commands
+while the target is running.
+
+@item reverse
+Indicates that the target is capable of reverse execution.
+@xref{Reverse Execution}, for more information.
+
+@end table
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
(gdb)
@end smallexample
-@subheading The @code{-list-features} Command
-@findex -list-features
-
-Returns a list of particular features of the MI protocol that
-this version of gdb implements. A feature can be a command,
-or a new field in an output of some command, or even an
-important bugfix. While a frontend can sometimes detect presence
-of a feature at runtime, it is easier to perform detection at debugger
-startup.
-
-The command returns a list of strings, with each string naming an
-available feature. Each returned string is just a name, it does not
-have any internal structure. The list of possible feature names
-is given below.
-
-Example output:
-
-@smallexample
-(gdb) -list-features
-^done,result=["feature1","feature2"]
-@end smallexample
-
-The current list of features is:
-
-@table @samp
-@item frozen-varobjs
-Indicates support for the @code{-var-set-frozen} command, as well
-as possible presense of the @code{frozen} field in the output
-of @code{-varobj-create}.
-@item pending-breakpoints
-Indicates support for the @option{-f} option to the @code{-break-insert}
-command.
-@item python
-Indicates Python scripting support, Python-based
-pretty-printing commands, and possible presence of the
-@samp{display_hint} field in the output of @code{-var-list-children}
-@item thread-info
-Indicates support for the @code{-thread-info} command.
-@item data-read-memory-bytes
-Indicates support for the @code{-data-read-memory-bytes} and the
-@code{-data-write-memory-bytes} commands.
-@item breakpoint-notifications
-Indicates that changes to breakpoints and breakpoints created via the
-CLI will be announced via async records.
-@item ada-task-info
-Indicates support for the @code{-ada-task-info} command.
-@item ada-exceptions
-Indicates support for the following commands, all of them related to Ada
-exceptions: @code{-info-ada-exceptions}, @code{-catch-assert} and
-@code{-catch-exception}.
-@end table
-
-@subheading The @code{-list-target-features} Command
-@findex -list-target-features
-
-Returns a list of particular features that are supported by the
-target. Those features affect the permitted MI commands, but
-unlike the features reported by the @code{-list-features} command, the
-features depend on which target GDB is using at the moment. Whenever
-a target can change, due to commands such as @code{-target-select},
-@code{-target-attach} or @code{-exec-run}, the list of target features
-may change, and the frontend should obtain it again.
-Example output:
-
-@smallexample
-(gdb) -list-target-features
-^done,result=["async"]
-@end smallexample
-
-The current list of features is:
-
-@table @samp
-@item async
-Indicates that the target is capable of asynchronous command
-execution, which means that @value{GDBN} will accept further commands
-while the target is running.
-
-@item reverse
-Indicates that the target is capable of reverse execution.
-@xref{Reverse Execution}, for more information.
-
-@end table
-
@subheading The @code{-list-thread-groups} Command
@findex -list-thread-groups
@item maint set show-debug-regs
@itemx maint show show-debug-regs
Control whether to show variables that mirror the hardware debug
-registers. Use @code{ON} to enable, @code{OFF} to disable. If
+registers. Use @code{on} to enable, @code{off} to disable. If
enabled, the debug registers values are shown when @value{GDBN} inserts or
removes a hardware breakpoint or watchpoint, and when the inferior
triggers a hardware-assisted breakpoint or watchpoint.
@samp{ymm0h} through @samp{ymm15h} for amd64
@end itemize
+The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R)
+Memory Protection Extension (MPX). It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64.
+@item
+@samp{bndcfgu} and @samp{bndstatus} for i386 and amd64.
+@end itemize
+
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.
projects / thirdparty / binutils-gdb.git / blobdiff