\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2014 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2015 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-2014 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2015 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-2014 Free Software Foundation, Inc.
+Copyright (C) 1988-2015 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
key designated as the @key{META} shift on your keyboard (if there is
one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
+If the number of possible completions is large, @value{GDBN} will
+print as much of the list as it has collected, as well as a message
+indicating that the list may be truncated.
+
+@smallexample
+(@value{GDBP}) b m@key{TAB}@key{TAB}
+main
+<... the rest of the possible completions ...>
+*** List may be truncated, max-completions reached. ***
+(@value{GDBP}) b m
+@end smallexample
+
+@noindent
+This behavior can be controlled with the following commands:
+
+@table @code
+@kindex set max-completions
+@item set max-completions @var{limit}
+@itemx set max-completions unlimited
+Set the maximum number of completion candidates. @value{GDBN} will
+stop looking for more completions once it collects this many candidates.
+This is useful when completing on things like function names as collecting
+all the possible candidates can be time consuming.
+The default value is 200. A value of zero disables tab-completion.
+Note that setting either no limit or a very large limit can make
+completion slow.
+@kindex show max-completions
+@item show max-completions
+Show the maximum number of candidates that @value{GDBN} will collect and show
+during completion.
+@end table
+
@cindex quotes in commands
@cindex completion of quoted strings
Sometimes the string you need, while logically a ``word'', may contain
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{threadno} | all] @var{command}
+@item thread apply [@var{threadno} | all [-ascending]] @var{command}
The @code{thread apply} command allows you to apply the named
@var{command} to one or more threads. Specify the numbers of the
threads that you want affected with the command argument
@var{threadno}. It can be a single thread number, one of the numbers
shown in the first field of the @samp{info threads} display; or it
-could be a range of thread numbers, as in @code{2-4}. To apply a
-command to all threads, type @kbd{thread apply all @var{command}}.
+could be a range of thread numbers, as in @code{2-4}. To apply
+a command to all threads in descending order, type @kbd{thread apply all
+@var{command}}. To apply a command to all threads in ascending order,
+type @kbd{thread apply all -ascending @var{command}}.
+
@kindex thread name
@cindex name a thread
@subsection Static Probe Points
@cindex static probe point, SystemTap
+@cindex static probe point, DTrace
@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands
for Statically Defined Tracing, and the probes are designed to have a tiny
-runtime code and data footprint, and no dynamic relocations. They are
-usable from assembly, C and C@t{++} languages. See
-@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
-for a good reference on how the @acronym{SDT} probes are implemented.
+runtime code and data footprint, and no dynamic relocations.
+
+Currently, the following types of probes are supported on
+ELF-compatible systems:
+
+@itemize @bullet
-Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
-@acronym{SDT} probes are supported on ELF-compatible systems. See
+@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
+@acronym{SDT} probes@footnote{See
@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
-for more information on how to add @code{SystemTap} @acronym{SDT} probes
-in your applications.
+for more information on how to add @code{SystemTap} @acronym{SDT}
+probes in your applications.}. @code{SystemTap} probes are usable
+from assembly, C and C@t{++} languages@footnote{See
+@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
+for a good reference on how the @acronym{SDT} probes are implemented.}.
+
+@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace})
+@acronym{USDT} probes. @code{DTrace} probes are usable from C and
+C@t{++} languages.
+@end itemize
@cindex semaphores on static probe points
-Some probes have an associated semaphore variable; for instance, this
-happens automatically if you defined your probe using a DTrace-style
-@file{.d} file. If your probe has a semaphore, @value{GDBN} will
-automatically enable it when you specify a breakpoint using the
-@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's
-location by some other method (e.g., @code{break file:line}), then
-@value{GDBN} will not automatically set the semaphore.
+Some @code{SystemTap} probes have an associated semaphore variable;
+for instance, this happens automatically if you defined your probe
+using a DTrace-style @file{.d} file. If your probe has a semaphore,
+@value{GDBN} will automatically enable it when you specify a
+breakpoint using the @samp{-probe-stap} notation. But, if you put a
+breakpoint at a probe's location by some other method (e.g.,
+@code{break file:line}), then @value{GDBN} will not automatically set
+the semaphore. @code{DTrace} probes do not support semaphores.
You can examine the available static static probes using @code{info
probes}, with optional arguments:
@table @code
@kindex info probes
-@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+@item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{type} is either @code{stap} for listing
+@code{SystemTap} probes or @code{dtrace} for listing @code{DTrace}
+probes. If omitted all probes are listed regardless of their types.
+
If given, @var{provider} is a regular expression used to match against provider
names when selecting which probes to list. If omitted, probes by all
probes from all providers are listed.
List the available static probes, from all types.
@end table
+@cindex enabling and disabling probes
+Some probe points can be enabled and/or disabled. The effect of
+enabling or disabling a probe depends on the type of probe being
+handled. Some @code{DTrace} probes can be enabled or
+disabled, but @code{SystemTap} probes cannot be disabled.
+
+You can enable (or disable) one or more probes using the following
+commands, with optional arguments:
+
+@table @code
+@kindex enable probes
+@item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{provider} is a regular expression used to match against
+provider names when selecting which probes to enable. If omitted,
+all probes from all providers are enabled.
+
+If given, @var{name} is a regular expression to match against probe
+names when selecting which probes to enable. If omitted, probe names
+are not considered when deciding whether to enable them.
+
+If given, @var{objfile} is a regular expression used to select which
+object files (executable or shared libraries) to examine. If not
+given, all object files are considered.
+
+@kindex disable probes
+@item disable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+See the @code{enable probes} command above for a description of the
+optional arguments accepted by this command.
+@end table
+
@vindex $_probe_arg@r{, convenience variable}
A probe may specify up to twelve arguments. These are available at the
point at which the probe is defined---that is, when the current PC is
at the probe's location. The arguments are available using the
convenience variables (@pxref{Convenience Vars})
-@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is
-an integer of the appropriate size; types are not preserved. The
+@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap}
+probes each probe argument is an integer of the appropriate size;
+types are not preserved. In @code{DTrace} probes types are preserved
+provided that they are recognized as such by @value{GDBN}; otherwise
+the value of the probe argument will be a long integer. The
convenience variable @code{$_probe_argc} holds the number of arguments
at the current probe point.
mode optimizes for single-stepping; it prevents other threads
from preempting the current thread while you are stepping, so that
the focus of debugging does not change unexpectedly.
-Other threads only rarely (or never) get a chance to run
-when you step. They are more likely to run when you @samp{next} over a
-function call, and they are completely free to run when you use commands
+Other threads never get a chance to run when you step, and they are
+completely free to run when you use commands
like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
thread hits a breakpoint during its timeslice, @value{GDBN} does not change
the current thread away from the thread that you are debugging.
@kindex record
@kindex record full
@kindex record btrace
+@kindex record btrace bts
+@kindex record bts
@kindex rec
@kindex rec full
@kindex rec btrace
+@kindex rec btrace bts
+@kindex rec bts
@item record @var{method}
This command starts the process record and replay target. The
recording method can be specified as parameter. Without a parameter
replay implementation. This method allows replaying and reverse
execution.
-@item btrace
+@item btrace @var{format}
Hardware-supported instruction recording. This method does not record
data. Further, the data is collected in a ring buffer so old data will
be overwritten when the buffer is full. It allows limited replay and
reverse execution.
-This recording method may not be available on all processors.
+The recording format can be specified as parameter. Without a parameter
+the command chooses the recording format. The following recording
+formats are available:
+
+@table @code
+@item bts
+@cindex branch trace store
+Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In
+this format, the processor stores a from/to record for each executed
+branch in the btrace ring buffer.
+@end table
+
+Not all recording formats may be available on all processors.
@end table
The process record and replay target can only debug a process that is
@item show record btrace replay-memory-access
Show the current setting of @code{replay-memory-access}.
+@kindex set record btrace bts
+@item set record btrace bts buffer-size @var{size}
+@itemx set record btrace bts buffer-size unlimited
+Set the requested ring buffer size for branch tracing in @acronym{BTS}
+format. Default is 64KB.
+
+If @var{size} is a positive number, then @value{GDBN} will try to
+allocate a buffer of at least @var{size} bytes for each new thread
+that uses the btrace recording method and the @acronym{BTS} format.
+The actually obtained buffer size may differ from the requested
+@var{size}. Use the @code{info record} command to see the actual
+buffer size for each thread that uses the btrace recording method and
+the @acronym{BTS} format.
+
+If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to
+allocate a buffer of 4MB.
+
+Bigger buffers mean longer traces. On the other hand, @value{GDBN} will
+also need longer to process the branch trace data before it can be used.
+
+@item show record btrace bts buffer-size @var{size}
+Show the current setting of the requested ring buffer size for branch
+tracing in @acronym{BTS} format.
+
@kindex info record
@item info record
Show various statistics about the recording depending on the recording
@end itemize
@item btrace
-For the @code{btrace} recording method, it shows the number of
-instructions that have been recorded and the number of blocks of
-sequential control-flow that is formed by the recorded instructions.
+For the @code{btrace} recording method, it shows:
+
+@itemize @bullet
+@item
+Recording format.
+@item
+Number of instructions that have been recorded.
+@item
+Number of blocks of sequential control-flow formed by the recorded
+instructions.
+@item
+Whether in record mode or replay mode.
+@end itemize
+
+For the @code{bts} recording format, it also shows:
+@itemize @bullet
+@item
+Size of the perf ring buffer.
+@end itemize
@end table
@kindex record delete
This form specifies the address of the function's first instruction,
before the stack frame and arguments have been set up.
-@item '@var{filename}'::@var{funcaddr}
+@item '@var{filename}':@var{funcaddr}
Like @var{funcaddr} above, but also specifies the name of the source
file explicitly. This is useful if the name of the function does not
specify the function unambiguously, e.g., if there are several
@anchor{linux info os infotypes}
@table @code
+@kindex info os cpus
+@item cpus
+Display the list of all CPUs/cores. For each CPU/core, @value{GDBN} prints
+the available fields from /proc/cpuinfo. For each supported architecture
+different fields are available. Two common entries are processor which gives
+CPU number and bogomips; a system constant that is calculated during
+kernel initialization.
+
+@kindex info os files
+@item files
+Display the list of open file descriptors on the target. For each
+file descriptor, @value{GDBN} prints the identifier of the process
+owning the descriptor, the command of the owning process, the value
+of the descriptor, and the target of the descriptor.
+
+@kindex info os modules
+@item modules
+Display the list of all loaded kernel modules on the target. For each
+module, @value{GDBN} prints the module name, the size of the module in
+bytes, the number of times the module is used, the dependencies of the
+module, the status of the module, and the address of the loaded module
+in memory.
+
+@kindex info os msg
+@item msg
+Display the list of all System V message queues on the target. For each
+message queue, @value{GDBN} prints the message queue key, the message
+queue identifier, the access permissions, the current number of bytes
+on the queue, the current number of messages on the queue, the processes
+that last sent and received a message on the queue, the user and group
+of the owner and creator of the message queue, the times at which a
+message was last sent and received on the queue, and the time at which
+the message queue was last changed.
+
@kindex info os processes
@item processes
Display the list of processes on the target. For each process,
so that processes belonging to the same process group are grouped together
and the process group leader is listed first.
-@kindex info os threads
-@item threads
-Display the list of threads running on the target. For each thread,
-@value{GDBN} prints the identifier of the process that the thread
-belongs to, the command of the process, the thread identifier, and the
-processor core that it is currently running on. The main thread of a
-process is not listed.
-
-@kindex info os files
-@item files
-Display the list of open file descriptors on the target. For each
-file descriptor, @value{GDBN} prints the identifier of the process
-owning the descriptor, the command of the owning process, the value
-of the descriptor, and the target of the descriptor.
-
-@kindex info os sockets
-@item sockets
-Display the list of Internet-domain sockets on the target. For each
-socket, @value{GDBN} prints the address and port of the local and
-remote endpoints, the current state of the connection, the creator of
-the socket, the IP address family of the socket, and the type of the
-connection.
+@kindex info os semaphores
+@item semaphores
+Display the list of all System V semaphore sets on the target. For each
+semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
+set identifier, the access permissions, the number of semaphores in the
+set, the user and group of the owner and creator of the semaphore set,
+and the times at which the semaphore set was operated upon and changed.
@kindex info os shm
@item shm
attaches to the region, and the times at which the region was last
attached to, detach from, and changed.
-@kindex info os semaphores
-@item semaphores
-Display the list of all System V semaphore sets on the target. For each
-semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
-set identifier, the access permissions, the number of semaphores in the
-set, the user and group of the owner and creator of the semaphore set,
-and the times at which the semaphore set was operated upon and changed.
-
-@kindex info os msg
-@item msg
-Display the list of all System V message queues on the target. For each
-message queue, @value{GDBN} prints the message queue key, the message
-queue identifier, the access permissions, the current number of bytes
-on the queue, the current number of messages on the queue, the processes
-that last sent and received a message on the queue, the user and group
-of the owner and creator of the message queue, the times at which a
-message was last sent and received on the queue, and the time at which
-the message queue was last changed.
+@kindex info os sockets
+@item sockets
+Display the list of Internet-domain sockets on the target. For each
+socket, @value{GDBN} prints the address and port of the local and
+remote endpoints, the current state of the connection, the creator of
+the socket, the IP address family of the socket, and the type of the
+connection.
-@kindex info os modules
-@item modules
-Display the list of all loaded kernel modules on the target. For each
-module, @value{GDBN} prints the module name, the size of the module in
-bytes, the number of times the module is used, the dependencies of the
-module, the status of the module, and the address of the loaded module
-in memory.
+@kindex info os threads
+@item threads
+Display the list of threads running on the target. For each thread,
+@value{GDBN} prints the identifier of the process that the thread
+belongs to, the command of the process, the thread identifier, and the
+processor core that it is currently running on. The main thread of a
+process is not listed.
@end table
@item info os
Note that this command is implemented only for some systems (as of
this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390).
+
+On @sc{gnu}/Linux, this command can take into account the value of the
+file @file{/proc/@var{pid}/coredump_filter} when generating the core
+dump (@pxref{set use-coredump-filter}).
+
+@kindex set use-coredump-filter
+@anchor{set use-coredump-filter}
+@item set use-coredump-filter on
+@itemx set use-coredump-filter off
+Enable or disable the use of the file
+@file{/proc/@var{pid}/coredump_filter} when generating core dump
+files. This file is used by the Linux kernel to decide what types of
+memory mappings will be dumped or ignored when generating a core dump
+file. @var{pid} is the process ID of a currently running process.
+
+To make use of this feature, you have to write in the
+@file{/proc/@var{pid}/coredump_filter} file a value, in hexadecimal,
+which is a bit mask representing the memory mapping types. If a bit
+is set in the bit mask, then the memory mappings of the corresponding
+types will be dumped; otherwise, they will be ignored. This
+configuration is inherited by child processes. For more information
+about the bits that can be set in the
+@file{/proc/@var{pid}/coredump_filter} file, please refer to the
+manpage of @code{core(5)}.
+
+By default, this option is @code{on}. If this option is turned
+@code{off}, @value{GDBN} does not read the @file{coredump_filter} file
+and instead uses the same default value as the Linux kernel in order
+to decide which pages will be dumped in the core dump file. This
+value is currently @code{0x33}, which means that bits @code{0}
+(anonymous private mappings), @code{1} (anonymous shared mappings),
+@code{4} (ELF headers) and @code{5} (private huge pages) are active.
+This will cause these memory mappings to be dumped automatically.
@end table
@node Character Sets
one entry per virtual table; there may be multiple virtual tables when
multiple inheritance is in use.
+@cindex C@t{++} demangling
+@item demangle @var{name}
+Demangle @var{name}.
+@xref{Symbols}, for a more complete description of the @code{demangle} command.
+
@cindex C@t{++} symbol display
@item set print demangle
@itemx show print demangle
__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
@end smallexample
+@kindex demangle
+@cindex demangle
+@item demangle @r{[}-l @var{language}@r{]} @r{[}@var{--}@r{]} @var{name}
+Demangle @var{name}.
+If @var{language} is provided it is the name of the language to demangle
+@var{name} in. Otherwise @var{name} is demangled in the current language.
+
+The @samp{--} option specifies the end of options,
+and is useful when @var{name} begins with a dash.
+
+The parameter @code{demangle-style} specifies how to interpret the kind
+of mangling used. @xref{Print Settings}.
+
@kindex whatis
@item whatis[/@var{flags}] [@var{arg}]
Print the data type of @var{arg}, which can be either an expression
@item
which programming language it is written in,
@item
+if the debug information provides it, the program that compiled the file
+(which may include, e.g., the compiler version and command line arguments),
+@item
whether the executable includes debugging information for that file, and
if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
@item
@}
(@value{GDBP})
@end smallexample
-@end table
+@kindex maint set symbol-cache-size
+@cindex symbol cache size
+@item maint set symbol-cache-size @var{size}
+Set the size of the symbol cache to @var{size}.
+The default size is intended to be good enough for debugging
+most applications. This option exists to allow for experimenting
+with different sizes.
+
+@kindex maint show symbol-cache-size
+@item maint show symbol-cache-size
+Show the size of the symbol cache.
+
+@kindex maint print symbol-cache
+@cindex symbol cache, printing its contents
+@item maint print symbol-cache
+Print the contents of the symbol cache.
+This is useful when debugging symbol cache issues.
+
+@kindex maint print symbol-cache-statistics
+@cindex symbol cache, printing usage statistics
+@item maint print symbol-cache-statistics
+Print symbol cache usage statistics.
+This helps determine how well the cache is being utilized.
+
+@kindex maint flush-symbol-cache
+@cindex symbol cache, flushing
+@item maint flush-symbol-cache
+Flush the contents of the symbol cache, all entries are removed.
+This command is useful when debugging the symbol cache.
+It is also useful when collecting performance data.
+
+@end table
@node Altering
@chapter Altering Execution
For this command to work, you must have used @code{symbol-file} or
@code{exec-file} commands in advance.
-@kindex add-shared-symbol-files
-@kindex assf
-@item add-shared-symbol-files @var{library-file}
-@itemx assf @var{library-file}
-This command is deprecated and will be removed in future versions
-of @value{GDBN}. Use the @code{sharedlibrary} command instead.
-
-The @code{add-shared-symbol-files} command can currently be used only
-in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
-alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
-@value{GDBN} automatically looks for shared libraries, however if
-@value{GDBN} does not find yours, you can invoke
-@code{add-shared-symbol-files}. It takes one argument: the shared
-library's file name. @code{assf} is a shorthand alias for
-@code{add-shared-symbol-files}.
-
@kindex section
@item section @var{section} @var{addr}
The @code{section} command changes the base address of the named
@item show serial baud
Show the current speed of the remote connection.
+@item set serial parity @var{parity}
+Set the parity for the remote serial I/O. Supported values of @var{parity} are:
+@code{even}, @code{none}, and @code{odd}. The default is @code{none}.
+
+@item show serial parity
+Show the current parity of the serial port.
+
@item set remotebreak
@cindex interrupt remote programs
@cindex BREAK signal instead of Ctrl-C
@tab @code{vFile:readlink}
@tab Host I/O
+@item @code{hostio-fstat-packet}
+@tab @code{vFile:fstat}
+@tab Host I/O
+
@item @code{noack-packet}
@tab @code{QStartNoAckMode}
@tab Packet acknowledgment
@item @code{conditional-breakpoints-packet}
@tab @code{Z0 and Z1}
@tab @code{Support for target-side breakpoint condition evaluation}
+
+@item @code{swbreak-feature}
+@tab @code{swbreak stop reason}
+@tab @code{break}
+
+@item @code{hwbreak-feature}
+@tab @code{hwbreak stop reason}
+@tab @code{hbreak}
+
@end multitable
@node Remote Stub
@item info dll
This is a Cygwin-specific alias of @code{info shared}.
-@kindex dll-symbols
-@item dll-symbols
-This command is deprecated and will be removed in future versions
-of @value{GDBN}. Use the @code{sharedlibrary} command instead.
-
-This command loads symbols from a dll similarly to
-add-sym command but without the need to specify a base address.
-
@kindex set cygwin-exceptions
@cindex debugging the Cygwin DLL
@cindex Cygwin DLL, debugging
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.
+If this section exists, its contents is a list of null-terminated entries
+specifying scripts to load. Each entry begins with a non-null prefix byte that
+specifies the kind of entry, typically the extension language and whether the
+script is in a file or inlined in @code{.debug_gdb_scripts}.
-@value{GDBN} will look for each specified script file first in the
-current directory and then along the source search path
+The following entries are supported:
+
+@table @code
+@item SECTION_SCRIPT_ID_PYTHON_FILE = 1
+@item SECTION_SCRIPT_ID_SCHEME_FILE = 3
+@item SECTION_SCRIPT_ID_PYTHON_TEXT = 4
+@item SECTION_SCRIPT_ID_SCHEME_TEXT = 6
+@end table
+
+@subsubsection Script File Entries
+
+If the entry specifies a file, @value{GDBN} will look for the 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,
+File entries can be placed in section @code{.debug_gdb_scripts} with,
for example, this GCC macro for Python scripts.
@example
and with the use of @code{"MS"} attributes on the section, the linker
will remove duplicates.
+@subsubsection Script Text Entries
+
+Script text entries allow to put the executable script in the entry
+itself instead of loading it from a file.
+The first line of the entry, everything after the prefix byte and up to
+the first newline (@code{0xa}) character, is the script name, and must not
+contain any kind of space character, e.g., spaces or tabs.
+The rest of the entry, up to the trailing null byte, is the script to
+execute in the specified language. The name needs to be unique among
+all script names, as @value{GDBN} executes each script only once based
+on its name.
+
+Here is an example from file @file{py-section-script.c} in the @value{GDBN}
+testsuite.
+
+@example
+#include "symcat.h"
+#include "gdb/section-scripts.h"
+asm(
+".pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n"
+".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n"
+".ascii \"gdb.inlined-script\\n\"\n"
+".ascii \"class test_cmd (gdb.Command):\\n\"\n"
+".ascii \" def __init__ (self):\\n\"\n"
+".ascii \" super (test_cmd, self).__init__ ("
+ "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n"
+".ascii \" def invoke (self, arg, from_tty):\\n\"\n"
+".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n"
+".ascii \"test_cmd ()\\n\"\n"
+".byte 0\n"
+".popsection\n"
+);
+@end example
+
+Loading of inlined scripts requires a properly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+The path to specify in @code{auto-load safe-path} is the path of the file
+containing the @code{.debug_gdb_scripts} section.
+
@node Which flavor to choose?
@subsection Which flavor to choose?
@kindex winheight
Change the height of the window @var{name} by @var{count}
lines. Positive counts increase the height, while negative counts
-decrease it.
+decrease it. The @var{name} parameter can be one of @code{src} (the
+source window), @code{cmd} (the command window), @code{asm} (the
+disassembly window), or @code{regs} (the register display window).
@item tabset @var{nchars}
@kindex tabset
-Set the width of tab stops to be @var{nchars} characters.
+Set the width of tab stops to be @var{nchars} characters. This
+setting affects the display of TAB characters in the source and
+assembly windows.
@end table
@node TUI Configuration
@item syscall-entry
The inferior entered a system call. This is reported when @code{catch
syscall} (@pxref{Set Catchpoints}) has been used.
-@item syscall-entry
+@item syscall-return
The inferior returned from a system call. This is reported when
@code{catch syscall} (@pxref{Set Catchpoints}) has been used.
@item exec
@table @samp
@item @var{address}
An expression specifying the address of the first memory word to be
-read. Complex expressions containing embedded white space should be
+written. Complex expressions containing embedded white space should be
quoted using the C convention.
@item @var{contents}
@smallexample
@value{GDBP}
-info-os
-^done,OSDataTable=@{nr_rows="9",nr_cols="3",
+^done,OSDataTable=@{nr_rows="10",nr_cols="3",
hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@},
@{width="10",alignment="-1",col_name="col1",colhdr="Description"@},
@{width="10",alignment="-1",col_name="col2",colhdr="Title"@}],
-body=[item=@{col0="processes",col1="Listing of all processes",
+body=[item=@{col0="cpus",col1="Listing of all cpus/cores on the system",
+ col2="CPUs"@},
+ item=@{col0="files",col1="Listing of all file descriptors",
+ col2="File descriptors"@},
+ item=@{col0="modules",col1="Listing of all loaded kernel modules",
+ col2="Kernel modules"@},
+ item=@{col0="msg",col1="Listing of all message queues",
+ col2="Message queues"@},
+ item=@{col0="processes",col1="Listing of all processes",
col2="Processes"@},
item=@{col0="procgroups",col1="Listing of all process groups",
col2="Process groups"@},
- item=@{col0="threads",col1="Listing of all threads",
- col2="Threads"@},
- item=@{col0="files",col1="Listing of all file descriptors",
- col2="File descriptors"@},
- item=@{col0="sockets",col1="Listing of all internet-domain sockets",
- col2="Sockets"@},
- item=@{col0="shm",col1="Listing of all shared-memory regions",
- col2="Shared-memory regions"@},
item=@{col0="semaphores",col1="Listing of all semaphores",
col2="Semaphores"@},
- item=@{col0="msg",col1="Listing of all message queues",
- col2="Message queues"@},
- item=@{col0="modules",col1="Listing of all loaded kernel modules",
- col2="Kernel modules"@}]@}
+ item=@{col0="shm",col1="Listing of all shared-memory regions",
+ col2="Shared-memory regions"@},
+ item=@{col0="sockets",col1="Listing of all internet-domain sockets",
+ col2="Sockets"@},
+ item=@{col0="threads",col1="Listing of all threads",
+ col2="Threads"@}]
@value{GDBP}
-info-os processes
^done,OSDataTable=@{nr_rows="190",nr_cols="4",
@item
Traceframe info (@pxref{Traceframe Info Format})
@item
-Branch trace (@pxref{Branch Trace Format})
+Branch trace (@pxref{Branch Trace Format},
+@pxref{Branch Trace Configuration Format})
@end itemize
@item zlib
@item maint cplus namespace
Print the list of possible C@t{++} namespaces.
-@kindex maint demangle
-@item maint demangle @var{name}
-Demangle a C@t{++} or Objective-C mangled @var{name}.
-
@kindex maint deprecate
@kindex maint undeprecate
@cindex deprecated commands
Cause @value{GDBN} to call the internal function @code{internal_error},
@code{internal_warning} or @code{demangler_warning} and hence behave
-as though an internal problam has been detected. In addition to
+as though an internal problem has been detected. In addition to
reporting the internal problem, these functions give the user the
opportunity to either quit @value{GDBN} or (for @code{internal_error}
and @code{internal_warning}) create a core file of the current
* Thread List Format::
* Traceframe Info Format::
* Branch Trace Format::
+* Branch Trace Configuration Format::
@end menu
@node Overview
conditions that should be taken into consideration when deciding if
the breakpoint trigger should be reported back to @var{GDBN}.
+See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason})
+for how to best report a memory breakpoint event to @value{GDBN}.
+
The @var{cond_list} parameter is comprised of a series of expressions,
concatenated without separators. Each expression has the following form:
beginning when executing backward) of the log. The value of @var{r}
will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
for more information.
+
+@item swbreak
+@anchor{swbreak stop reason}
+The packet indicates a memory breakpoint instruction was executed,
+irrespective of whether it was @value{GDBN} that planted the
+breakpoint or the breakpoint is hardcoded in the program. The @var{r}
+part must be left empty.
+
+On some architectures, such as x86, at the architecture level, when a
+breakpoint instruction executes the program counter points at the
+breakpoint address plus an offset. On such targets, the stub is
+responsible for adjusting the PC to point back at the breakpoint
+address.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+This packet is required for correct non-stop mode operation.
+
+@item hwbreak
+The packet indicates the target stopped for a hardware breakpoint.
+The @var{r} part must be left empty.
+
+The same remarks about @samp{qSupported} and non-stop mode above
+apply.
@end table
@item W @var{AA}
This feature indicates whether @value{GDBN} supports the
@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate
instruction reply packet}).
+
+@item swbreak
+This feature indicates whether @value{GDBN} supports the swbreak stop
+reason in stop replies. @xref{swbreak stop reason}, for details.
+
+@item hwbreak
+This feature indicates whether @value{GDBN} supports the hwbreak stop
+reason in stop replies. @xref{swbreak stop reason}, for details.
@end table
Stubs should ignore any unknown values for
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:btrace-conf:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:features:read}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab Yes
+@item @samp{Qbtrace-conf:bts:size}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{swbreak}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{hwbreak}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer:btrace:read}
packet (@pxref{qXfer btrace read}).
+@item qXfer:btrace-conf:read
+The remote stub understands the @samp{qXfer:btrace-conf:read}
+packet (@pxref{qXfer btrace-conf read}).
+
@item qXfer:features:read
The remote stub understands the @samp{qXfer:features:read} packet
(@pxref{qXfer target description read}).
@item Qbtrace:bts
The remote stub understands the @samp{Qbtrace:bts} packet.
+@item Qbtrace-conf:bts:size
+The remote stub understands the @samp{Qbtrace-conf:bts:size} packet.
+
+@item swbreak
+The remote stub reports the @samp{swbreak} stop reason for memory
+breakpoints.
+
+@item hwbreak
+The remote stub reports the @samp{hwbreak} stop reason for hardware
+breakpoints.
+
@end table
@item qSymbol::
This packet is not probed by default; the remote stub must request it
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:btrace-conf:read::@var{offset},@var{length}
+@anchor{qXfer btrace-conf read}
+
+Return a description of the current branch trace configuration.
+@xref{Branch Trace Configuration Format}.
+
+This packet is not probed by default; the remote stub must request it
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:features:read:@var{annex}:@var{offset},@var{length}
@anchor{qXfer target description read}
Access the @dfn{target description}. @xref{Target Descriptions}. The
A badly formed request or an error was encountered.
@end table
+@item Qbtrace-conf:bts:size=@var{value}
+Set the requested ring buffer size for new threads that use the
+btrace recording method in bts format.
+
+Reply:
+@table @samp
+@item OK
+The ring buffer size has been set.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
@end table
@node Architecture-Specific Protocol Details
could cause @samp{tdump} not to work, or a particular trace frame not
be found.
-@item QTDV:@var{n}:@var{value}
+@item QTDV:@var{n}:@var{value}:@var{builtin}:@var{name}
@cindex define trace state variable, remote request
@cindex @samp{QTDV} packet
Create a new trace state variable, number @var{n}, with an initial
and @var{value} are encoded as hexadecimal values. @value{GDBN} has
the option of not using this packet for initial values of zero; the
target should simply create the trace state variables as they are
-mentioned in expressions.
+mentioned in expressions. The value @var{builtin} should be 1 (one)
+if the trace state variable is builtin and 0 (zero) if it is not builtin.
+@value{GDBN} only sets @var{builtin} to 1 if a previous @samp{qTfV} or
+@samp{qTsV} packet had it set. The contents of @var{name} is the
+hex-encoded name (without the leading @samp{$}) of the trace state
+variable.
@item QTFrame:@var{n}
@cindex @samp{QTFrame} packet
which may be shorter than the length of @var{data}, or -1 if an
error occurred.
+@item vFile:fstat: @var{fd}
+Get information about the open file corresponding to @var{fd}.
+On success the information is returned as a binary attachment
+and the return value is the size of this attachment in bytes.
+If an error occurs the return value is -1. The format of the
+returned binary attachment is as described in @ref{struct stat}.
+
@item vFile:unlink: @var{filename}
Delete the file at @var{filename} on the target. Return 0,
or -1 if an error occurs. The @var{filename} is a string.
or if the target is not attached to any process, it shall respond
@samp{OK}.
+If the stub supports non-stop mode, it should also support the
+@samp{swbreak} stop reason if software breakpoints are supported, and
+the @samp{hwbreak} stop reason if hardware breakpoints are supported
+(@pxref{swbreak stop reason}). This is because given the asynchronous
+nature of non-stop mode, between the time a thread hits a breakpoint
+and the time the event is finally processed by @value{GDBN}, the
+breakpoint may have already been removed from the target. Due to
+this, @value{GDBN} needs to be able to tell whether a trap stop was
+caused by a delayed breakpoint event, which should be ignored, as
+opposed to a random trap signal, which should be reported to the user.
+Note the @samp{swbreak} feature implies that the target is responsible
+for adjusting the PC when a software breakpoint triggers, if
+necessary, such as on the x86 architecture.
+
@node Packet Acknowledgment
@section Packet Acknowledgment
end CDATA #REQUIRED>
@end smallexample
+@node Branch Trace Configuration Format
+@section Branch Trace Configuration Format
+@cindex branch trace configuration format
+
+For each inferior thread, @value{GDBN} can obtain the branch trace
+configuration using the @samp{qXfer:btrace-conf:read}
+(@pxref{qXfer btrace-conf read}) packet.
+
+The configuration describes the branch trace format and configuration
+settings for that format. The following information is described:
+
+@table @code
+@item bts
+This thread uses the @dfn{Branch Trace Store} (@acronym{BTS}) format.
+@table @code
+@item size
+The size of the @acronym{BTS} ring buffer in bytes.
+@end table
+@end table
+
+@value{GDBN} must be linked with the Expat library to support XML
+branch trace configuration discovery. @xref{Expat}.
+
+The formal DTD for the branch trace configuration format is given below:
+
+@smallexample
+<!ELEMENT btrace-conf (bts?)>
+<!ATTLIST btrace-conf version CDATA #FIXED "1.0">
+
+<!ELEMENT bts EMPTY>
+<!ATTLIST bts size CDATA #IMPLIED>
+@end smallexample
+
@include agentexpr.texi
@node Target Descriptions
contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
@samp{atia}, and @samp{tr0} through @samp{tr15}.
+The @samp{org.gnu.gdb.s390.vx} feature is optional. It should contain
+64-bit wide registers @samp{v0l} through @samp{v15l}, which will be
+combined by @value{GDBN} with the floating point registers @samp{f0}
+through @samp{f15} to present the 128-bit wide vector registers
+@samp{v0} through @samp{v15}. In addition, this feature should
+contain the 128-bit wide vector registers @samp{v16} through
+@samp{v31}.
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
projects / deliverable / binutils-gdb.git / blobdiff