\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
@item run
@itemx r
Use the @code{run} command to start your program under @value{GDBN}.
-You must first specify the program name (except on VxWorks) with an
-argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
-@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
-(@pxref{Files, ,Commands to Specify Files}).
+You must first specify the program name with an argument to
+@value{GDBN} (@pxref{Invocation, ,Getting In and Out of
+@value{GDBN}}), or by using the @code{file} or @code{exec-file}
+command (@pxref{Files, ,Commands to Specify Files}).
@end table
@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
@item set breakpoint always-inserted off
All breakpoints, including newly added by the user, are inserted in
the target only when the target is resumed. All breakpoints are
-removed from the target when it stops.
+removed from the target when it stops. This is the default mode.
@item set breakpoint always-inserted on
Causes all breakpoints to be inserted in the target at all times. If
the user adds a new breakpoint, or changes an existing breakpoint, the
breakpoints in the target are updated immediately. A breakpoint is
-removed from the target only when breakpoint itself is removed.
-
-@cindex non-stop mode, and @code{breakpoint always-inserted}
-@item set breakpoint always-inserted auto
-This is the default mode. If @value{GDBN} is controlling the inferior
-in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
-@code{breakpoint always-inserted} mode is on. If @value{GDBN} is
-controlling the inferior in all-stop mode, @value{GDBN} behaves as if
-@code{breakpoint always-inserted} mode is off.
+removed from the target only when breakpoint itself is deleted.
@end table
@value{GDBN} handles conditional breakpoints by evaluating these conditions
@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:
-Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
-@acronym{SDT} probes are supported on ELF-compatible systems. See
+@itemize @bullet
+
+@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.
particular command you use). Either when continuing or when stepping,
your program may stop even sooner, due to a breakpoint or a signal. (If
it stops due to a signal, you may want to use @code{handle}, or use
-@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
+@samp{signal 0} to resume execution (@pxref{Signals, ,Signals}),
+or you may step into the signal's handler (@pxref{stepping and signal
+handlers}).)
@table @code
@kindex continue
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
Program a Signal}.
+@cindex stepping and signal handlers
+@anchor{stepping and signal handlers}
+
+@value{GDBN} optimizes for stepping the mainline code. If a signal
+that has @code{handle nostop} and @code{handle pass} set arrives while
+a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is
+in progress, @value{GDBN} lets the signal handler run and then resumes
+stepping the mainline code once the signal handler returns. In other
+words, @value{GDBN} steps over the signal handler. This prevents
+signals that you've specified as not interesting (with @code{handle
+nostop}) from changing the focus of debugging unexpectedly. Note that
+the signal handler itself may still hit a breakpoint, stop for another
+signal that has @code{handle stop} in effect, or for any other event
+that normally results in stopping the stepping command sooner. Also
+note that @value{GDBN} still informs you that the program received a
+signal if @code{handle print} is set.
+
+@anchor{stepping into signal handlers}
+
+If you set @code{handle pass} for a signal, and your program sets up a
+handler for it, then issuing a stepping command, such as @code{step}
+or @code{stepi}, when your program is stopped due to the signal will
+step @emph{into} the signal handler (if the target supports that).
+
+Likewise, if you use the @code{queue-signal} command to queue a signal
+to be delivered to the current thread when execution of the thread
+resumes (@pxref{Signaling, ,Giving your Program a Signal}), then a
+stepping command will step into the signal handler.
+
+Here's an example, using @code{stepi} to step to the first instruction
+of @code{SIGUSR1}'s handler:
+
+@smallexample
+(@value{GDBP}) handle SIGUSR1
+Signal Stop Print Pass to program Description
+SIGUSR1 Yes Yes Yes User defined signal 1
+(@value{GDBP}) c
+Continuing.
+
+Program received signal SIGUSR1, User defined signal 1.
+main () sigusr1.c:28
+28 p = 0;
+(@value{GDBP}) si
+sigusr1_handler () at sigusr1.c:9
+9 @{
+@end smallexample
+
+The same, but using @code{queue-signal} instead of waiting for the
+program to receive the signal first:
+
+@smallexample
+(@value{GDBP}) n
+28 p = 0;
+(@value{GDBP}) queue-signal SIGUSR1
+(@value{GDBP}) si
+sigusr1_handler () at sigusr1.c:9
+9 @{
+(@value{GDBP})
+@end smallexample
+
@cindex extra signal information
@anchor{extra signal information}
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
@findex $_strlen@r{, convenience function}
Returns the length of string @var{str}.
+@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
+@findex $_caller_is@r{, convenience function}
+Returns one if the calling function's name is equal to @var{name}.
+Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+Example:
+
+@smallexample
+(gdb) backtrace
+#0 bottom_func ()
+ at testsuite/gdb.python/py-caller-is.c:21
+#1 0x00000000004005a0 in middle_func ()
+ at testsuite/gdb.python/py-caller-is.c:27
+#2 0x00000000004005ab in top_func ()
+ at testsuite/gdb.python/py-caller-is.c:33
+#3 0x00000000004005b6 in main ()
+ at testsuite/gdb.python/py-caller-is.c:39
+(gdb) print $_caller_is ("middle_func")
+$1 = 1
+(gdb) print $_caller_is ("top_func", 2)
+$1 = 1
+@end smallexample
+
+@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
+@findex $_caller_matches@r{, convenience function}
+Returns one if the calling function's name matches the regular expression
+@var{regexp}. Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
+@findex $_any_caller_is@r{, convenience function}
+Returns one if any calling function's name is equal to @var{name}.
+Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+This function differs from @code{$_caller_is} in that this function
+checks all stack frames from the immediate caller to the frame specified
+by @var{number_of_frames}, whereas @code{$_caller_is} only checks the
+frame specified by @var{number_of_frames}.
+
+@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
+@findex $_any_caller_matches@r{, convenience function}
+Returns one if any calling function's name matches the regular expression
+@var{regexp}. Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+This function differs from @code{$_caller_matches} in that this function
+checks all stack frames from the immediate caller to the frame specified
+by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the
+frame specified by @var{number_of_frames}.
+
@end table
@value{GDBN} provides the ability to list and get help on
the machine you are using, with or without the initial @samp{$}.
@end table
+@anchor{standard registers}
@cindex stack pointer register
@cindex program counter register
@cindex process status register
@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
tasking support may be limited or even unavailable, depending on
the platform being used.
For instance, on x86-linux, the list of tasks is available, but task
-switching is not supported. On Tru64, however, task switching will work
-as usual.
+switching is not supported.
-On certain platforms, including Tru64, the debugger needs to perform some
+On certain platforms, the debugger needs to perform some
memory writes in order to provide Ada tasking support. When inspecting
a core file, this means that the core file must be opened with read-write
privileges, using the command @samp{"set write on"} (@pxref{Patching}).
__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
* Returning:: Returning from a function
* Calling:: Calling your program's functions
* Patching:: Patching your program
+* Compiling and Injecting Code:: Compiling and injecting code in @value{GDBN}
@end menu
@node Assignment
@table @code
@kindex signal
@item signal @var{signal}
-Resume execution where your program stopped, but immediately give it the
+Resume execution where your program is stopped, but immediately give it the
signal @var{signal}. The @var{signal} can be the name or the number of a
signal. For example, on many systems @code{signal 2} and @code{signal
SIGINT} are both ways of sending an interrupt signal.
@code{continue} command; @samp{signal 0} causes it to resume without a
signal.
-@code{signal} does not repeat when you press @key{RET} a second time
-after executing the command.
-@end table
-@c @end group
+@emph{Note:} When resuming a multi-threaded program, @var{signal} is
+delivered to the currently selected thread, not the thread that last
+reported a stop. This includes the situation where a thread was
+stopped due to a signal. So if you want to continue execution
+suppressing the signal that stopped a thread, you should select that
+same thread before issuing the @samp{signal 0} command. If you issue
+the @samp{signal 0} command with another thread as the selected one,
+@value{GDBN} detects that and asks for confirmation.
Invoking the @code{signal} command is not the same as invoking the
@code{kill} utility from the shell. Sending a signal with @code{kill}
the signal handling tables (@pxref{Signals}). The @code{signal} command
passes the signal directly to your program.
+@code{signal} does not repeat when you press @key{RET} a second time
+after executing the command.
+
+@kindex queue-signal
+@item queue-signal @var{signal}
+Queue @var{signal} to be delivered immediately to the current thread
+when execution of the thread resumes. The @var{signal} can be the name or
+the number of a signal. For example, on many systems @code{signal 2} and
+@code{signal SIGINT} are both ways of sending an interrupt signal.
+The handling of the signal must be set to pass the signal to the program,
+otherwise @value{GDBN} will report an error.
+You can control the handling of signals from @value{GDBN} with the
+@code{handle} command (@pxref{Signals}).
+
+Alternatively, if @var{signal} is zero, any currently queued signal
+for the current thread is discarded and when execution resumes no signal
+will be delivered. This is useful when your program stopped on account
+of a signal and would ordinarily see the signal when resumed with the
+@code{continue} command.
+
+This command differs from the @code{signal} command in that the signal
+is just queued, execution is not resumed. And @code{queue-signal} cannot
+be used to pass a signal whose handling state has been set to @code{nopass}
+(@pxref{Signals}).
+@end table
+@c @end group
+
+@xref{stepping into signal handlers}, for information on how stepping
+commands behave when the thread has a signal queued.
@node Returning
@section Returning from a Function
as well as reading.
@end table
+@node Compiling and Injecting Code
+@section Compiling and injecting code in @value{GDBN}
+@cindex injecting code
+@cindex writing into executables
+@cindex compiling code
+
+@value{GDBN} supports on-demand compilation and code injection into
+programs running under @value{GDBN}. GCC 5.0 or higher built with
+@file{libcc1.so} must be installed for this functionality to be enabled.
+This functionality is implemented with the following commands.
+
+@table @code
+@kindex compile code
+@item compile code @var{source-code}
+@itemx compile code -raw @var{--} @var{source-code}
+Compile @var{source-code} with the compiler language found as the current
+language in @value{GDBN} (@pxref{Languages}). If compilation and
+injection is not supported with the current language specified in
+@value{GDBN}, or the compiler does not support this feature, an error
+message will be printed. If @var{source-code} compiles and links
+successfully, @value{GDBN} will load the object-code emitted,
+and execute it within the context of the currently selected inferior.
+It is important to note that the compiled code is executed immediately.
+After execution, the compiled code is removed from @value{GDBN} and any
+new types or variables you have defined will be deleted.
+
+The command allows you to specify @var{source-code} in two ways.
+The simplest method is to provide a single line of code to the command.
+E.g.:
+
+@smallexample
+compile code printf ("hello world\n");
+@end smallexample
+
+If you specify options on the command line as well as source code, they
+may conflict. The @samp{--} delimiter can be used to separate options
+from actual source code. E.g.:
+
+@smallexample
+compile code -r -- printf ("hello world\n");
+@end smallexample
+
+Alternatively you can enter source code as multiple lines of text. To
+enter this mode, invoke the @samp{compile code} command without any text
+following the command. This will start the multiple-line editor and
+allow you to type as many lines of source code as required. When you
+have completed typing, enter @samp{end} on its own line to exit the
+editor.
+
+@smallexample
+compile code
+>printf ("hello\n");
+>printf ("world\n");
+>end
+@end smallexample
+
+Specifying @samp{-raw}, prohibits @value{GDBN} from wrapping the
+provided @var{source-code} in a callable scope. In this case, you must
+specify the entry point of the code by defining a function named
+@code{_gdb_expr_}. The @samp{-raw} code cannot access variables of the
+inferior. Using @samp{-raw} option may be needed for example when
+@var{source-code} requires @samp{#include} lines which may conflict with
+inferior symbols otherwise.
+
+@kindex compile file
+@item compile file @var{filename}
+@itemx compile file -raw @var{filename}
+Like @code{compile code}, but take the source code from @var{filename}.
+
+@smallexample
+compile file /home/user/example.c
+@end smallexample
+@end table
+
+@subsection Caveats when using the @code{compile} command
+
+There are a few caveats to keep in mind when using the @code{compile}
+command. As the caveats are different per language, the table below
+highlights specific issues on a per language basis.
+
+@table @asis
+@item C code examples and caveats
+When the language in @value{GDBN} is set to @samp{C}, the compiler will
+attempt to compile the source code with a @samp{C} compiler. The source
+code provided to the @code{compile} command will have much the same
+access to variables and types as it normally would if it were part of
+the program currently being debugged in @value{GDBN}.
+
+Below is a sample program that forms the basis of the examples that
+follow. This program has been compiled and loaded into @value{GDBN},
+much like any other normal debugging session.
+
+@smallexample
+void function1 (void)
+@{
+ int i = 42;
+ printf ("function 1\n");
+@}
+
+void function2 (void)
+@{
+ int j = 12;
+ function1 ();
+@}
+
+int main(void)
+@{
+ int k = 6;
+ int *p;
+ function2 ();
+ return 0;
+@}
+@end smallexample
+
+For the purposes of the examples in this section, the program above has
+been compiled, loaded into @value{GDBN}, stopped at the function
+@code{main}, and @value{GDBN} is awaiting input from the user.
+
+To access variables and types for any program in @value{GDBN}, the
+program must be compiled and packaged with debug information. The
+@code{compile} command is not an exception to this rule. Without debug
+information, you can still use the @code{compile} command, but you will
+be very limited in what variables and types you can access.
+
+So with that in mind, the example above has been compiled with debug
+information enabled. The @code{compile} command will have access to
+all variables and types (except those that may have been optimized
+out). Currently, as @value{GDBN} has stopped the program in the
+@code{main} function, the @code{compile} command would have access to
+the variable @code{k}. You could invoke the @code{compile} command
+and type some source code to set the value of @code{k}. You can also
+read it, or do anything with that variable you would normally do in
+@code{C}. Be aware that changes to inferior variables in the
+@code{compile} command are persistent. In the following example:
+
+@smallexample
+compile code k = 3;
+@end smallexample
+
+@noindent
+the variable @code{k} is now 3. It will retain that value until
+something else in the example program changes it, or another
+@code{compile} command changes it.
+
+Normal scope and access rules apply to source code compiled and
+injected by the @code{compile} command. In the example, the variables
+@code{j} and @code{k} are not accessible yet, because the program is
+currently stopped in the @code{main} function, where these variables
+are not in scope. Therefore, the following command
+
+@smallexample
+compile code j = 3;
+@end smallexample
+
+@noindent
+will result in a compilation error message.
+
+Once the program is continued, execution will bring these variables in
+scope, and they will become accessible; then the code you specify via
+the @code{compile} command will be able to access them.
+
+You can create variables and types with the @code{compile} command as
+part of your source code. Variables and types that are created as part
+of the @code{compile} command are not visible to the rest of the program for
+the duration of its run. This example is valid:
+
+@smallexample
+compile code int ff = 5; printf ("ff is %d\n", ff);
+@end smallexample
+
+However, if you were to type the following into @value{GDBN} after that
+command has completed:
+
+@smallexample
+compile code printf ("ff is %d\n'', ff);
+@end smallexample
+
+@noindent
+a compiler error would be raised as the variable @code{ff} no longer
+exists. Object code generated and injected by the @code{compile}
+command is removed when its execution ends. Caution is advised
+when assigning to program variables values of variables created by the
+code submitted to the @code{compile} command. This example is valid:
+
+@smallexample
+compile code int ff = 5; k = ff;
+@end smallexample
+
+The value of the variable @code{ff} is assigned to @code{k}. The variable
+@code{k} does not require the existence of @code{ff} to maintain the value
+it has been assigned. However, pointers require particular care in
+assignment. If the source code compiled with the @code{compile} command
+changed the address of a pointer in the example program, perhaps to a
+variable created in the @code{compile} command, that pointer would point
+to an invalid location when the command exits. The following example
+would likely cause issues with your debugged program:
+
+@smallexample
+compile code int ff = 5; p = &ff;
+@end smallexample
+
+In this example, @code{p} would point to @code{ff} when the
+@code{compile} command is executing the source code provided to it.
+However, as variables in the (example) program persist with their
+assigned values, the variable @code{p} would point to an invalid
+location when the command exists. A general rule should be followed
+in that you should either assign @code{NULL} to any assigned pointers,
+or restore a valid location to the pointer before the command exits.
+
+Similar caution must be exercised with any structs, unions, and typedefs
+defined in @code{compile} command. Types defined in the @code{compile}
+command will no longer be available in the next @code{compile} command.
+Therefore, if you cast a variable to a type defined in the
+@code{compile} command, care must be taken to ensure that any future
+need to resolve the type can be achieved.
+
+@smallexample
+(gdb) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v;
+(gdb) compile code printf ("%d\n", ((struct a *) argv)->a);
+gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’
+Compilation failed.
+(gdb) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a);
+42
+@end smallexample
+
+Variables that have been optimized away by the compiler are not
+accessible to the code submitted to the @code{compile} command.
+Access to those variables will generate a compiler error which @value{GDBN}
+will print to the console.
+@end table
+
@node GDB Files
@chapter @value{GDBN} Files
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
facility, the command @code{info proc} is available to report
information about the process running your program, or about any
process running on your system. This includes, as of this writing,
-@sc{gnu}/Linux, OSF/1 (Digital Unix), Solaris, and Irix, but
-not HP-UX, for example.
+@sc{gnu}/Linux and Solaris, but not HP-UX, for example.
This command may also work on core files that were created on a system
that has the @samp{/proc} facility.
@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
embedded operating systems that are available for several different
architectures.
-@menu
-* VxWorks:: Using @value{GDBN} with VxWorks
-@end menu
-
@value{GDBN} includes the ability to debug programs running on
various real-time operating systems.
-@node VxWorks
-@subsection Using @value{GDBN} with VxWorks
-
-@cindex VxWorks
-
-@table @code
-
-@kindex target vxworks
-@item target vxworks @var{machinename}
-A VxWorks system, attached via TCP/IP. The argument @var{machinename}
-is the target system's machine name or IP address.
-
-@end table
-
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
-
-@value{GDBN} enables developers to spawn and debug tasks running on networked
-VxWorks targets from a Unix host. Already-running tasks spawned from
-the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
-both the Unix host and on the VxWorks target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
-installed with the name @code{vxgdb}, to distinguish it from a
-@value{GDBN} for debugging programs on the host itself.)
-
-@table @code
-@item VxWorks-timeout @var{args}
-@kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses to rpc's. You might use this if
-your VxWorks target is a slow software simulator or is on the far side
-of a thin network line.
-@end table
-
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
-
-@findex INCLUDE_RDB
-To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
-to include the remote debugging interface routines in the VxWorks
-library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
-VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
-kernel. The resulting kernel contains @file{rdb.a}, and spawns the
-source debugging task @code{tRdbTask} when VxWorks is booted. For more
-information on configuring and remaking VxWorks, see the manufacturer's
-manual.
-@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
-
-Once you have included @file{rdb.a} in your VxWorks system image and set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
-@code{vxgdb}, depending on your installation).
-
-@value{GDBN} comes up showing the prompt:
-
-@smallexample
-(vxgdb)
-@end smallexample
-
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
-
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
-
-The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
-network. To connect to a target whose host name is ``@code{tt}'', type:
-
-@smallexample
-(vxgdb) target vxworks tt
-@end smallexample
-
-@need 750
-@value{GDBN} displays messages like these:
-
-@smallexample
-Attaching remote machine across net...
-Connected to tt.
-@end smallexample
-
-@need 1000
-@value{GDBN} then attempts to read the symbol tables of any object modules
-loaded into the VxWorks target since it was last booted. @value{GDBN} locates
-these files by searching the directories listed in the command search
-path (@pxref{Environment, ,Your Program's Environment}); if it fails
-to find an object file, it displays a message such as:
-
-@smallexample
-prog.o: No such file or directory.
-@end smallexample
-
-When this happens, add the appropriate directory to the search path with
-the @value{GDBN} command @code{path}, and execute the @code{target}
-command again.
-
-@node VxWorks Download
-@subsubsection VxWorks Download
-
-@cindex download to VxWorks
-If you have connected to the VxWorks target and you want to debug an
-object that has not yet been loaded, you can use the @value{GDBN}
-@code{load} command to download a file from Unix to VxWorks
-incrementally. The object file given as an argument to the @code{load}
-command is actually opened twice: first by the VxWorks target in order
-to download the code, then by @value{GDBN} in order to read the symbol
-table. This can lead to problems if the current working directories on
-the two systems differ. If both systems have NFS mounted the same
-filesystems, you can avoid these problems by using absolute paths.
-Otherwise, it is simplest to set the working directory on both systems
-to the directory in which the object file resides, and then to reference
-the file by its name, without any path. For instance, a program
-@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
-and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
-program, type this on VxWorks:
-
-@smallexample
--> cd "@var{vxpath}/vw/demo/rdb"
-@end smallexample
-
-@noindent
-Then, in @value{GDBN}, type:
-
-@smallexample
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
-@end smallexample
-
-@value{GDBN} displays a response similar to this:
-
-@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
-@end smallexample
-
-You can also use the @code{load} command to reload an object module
-after editing and recompiling the corresponding source file. Note that
-this makes @value{GDBN} delete all currently-defined breakpoints,
-auto-displays, and convenience variables, and to clear the value
-history. (This is necessary in order to preserve the integrity of
-debugger's data structures that reference the target system's symbol
-table.)
-
-@node VxWorks Attach
-@subsubsection Running Tasks
-
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
-
-@smallexample
-(vxgdb) attach @var{task}
-@end smallexample
-
-@noindent
-where @var{task} is the VxWorks hexadecimal task ID. The task can be running
-or suspended when you attach to it. Running tasks are suspended at
-the time of attachment.
-
@node Embedded Processors
@section Embedded Processors
@tab Control for @value{GDBN} auto-loaded scripts location.
@item @xref{show auto-load scripts-directory}.
@tab Show @value{GDBN} auto-loaded scripts location.
+@item @xref{add-auto-load-scripts-directory}.
+@tab Add directory for auto-loaded scripts location list.
@item @xref{set auto-load local-gdbinit}.
@tab Control for init file in the current directory.
@item @xref{show auto-load local-gdbinit}.
@anchor{add-auto-load-safe-path}
@kindex add-auto-load-safe-path
@item add-auto-load-safe-path
-Add an entry (or list of entries) the list of directories trusted for automatic
-loading and execution of scripts. Multiple entries may be delimited by the
-host platform path separator in use.
+Add an entry (or list of entries) to the list of directories trusted for
+automatic loading and execution of scripts. Multiple entries may be delimited
+by the host platform path separator in use.
@end table
This variable defaults to what @code{--with-auto-load-dir} has been configured
@item show debug solib-frv
Display the current state of FR-V shared-library code debugging
messages.
+@item set debug symbol-lookup
+@cindex symbol lookup
+Turns on or off display of debugging messages related to symbol lookup.
+The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
+@item show debug symbol-lookup
+Show the current state of symbol lookup debugging messages.
@item set debug symfile
@cindex symbol file functions
Turns on or off display of debugging messages related to symbol file functions.
Turns on or off display of @value{GDBN} target debugging info. This info
includes what is going on at the target level of GDB, as it happens. The
default is 0. Set it to 1 to track events, and to 2 to also track the
-value of large memory transfers. Changes to this flag do not take effect
-until the next time you connect to a target or use the @code{run} command.
+value of large memory transfers.
@item show debug target
Displays the current state of displaying @value{GDBN} target debugging
info.
@kindex show auto-load scripts-directory
@item show auto-load scripts-directory
Show @value{GDBN} auto-loaded scripts location.
+
+@anchor{add-auto-load-scripts-directory}
+@kindex add-auto-load-scripts-directory
+@item add-auto-load-scripts-directory @r{[}@var{directories}@dots{}@r{]}
+Add an entry (or list of entries) to the list of auto-loaded scripts locations.
+Multiple entries may be delimited by the host platform path separator in use.
@end table
@value{GDBN} does not track which files it has already auto-loaded this way.
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}
The target-specific process identifier. This field is only present
for thread groups of type @samp{process} and only if the process exists.
+@item exit-code
+The exit code of this group's last exited thread, formatted in octal.
+This field is only present for thread groups of type @samp{process} and
+only if the process is not running.
+
@item num_children
The number of children this thread group has. This field may be
absent for an available thread group.
@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
match @var{regexp}. For each object file, this command prints its name,
address in memory, and all of its psymtabs and symtabs.
+@kindex maint print user-registers
+@cindex user registers
+@item maint print user-registers
+List all currently available @dfn{user registers}. User registers
+typically provide alternate names for actual hardware registers. They
+include the four ``standard'' registers @code{$fp}, @code{$pc},
+@code{$sp}, and @code{$ps}. @xref{standard registers}. User
+registers can be used in expressions in the same way as the canonical
+register names, but only the latter are listed by the @code{info
+registers} and @code{maint print registers} commands.
+
@kindex maint print section-scripts
@cindex info for known .debug_gdb_scripts-loaded scripts
@item maint print section-scripts [@var{regexp}]
* 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
* AArch64 Features::
* ARM Features::
* i386 Features::
+* MicroBlaze Features::
* MIPS Features::
* M68K Features::
* Nios II Features::
@samp{zmm16h} through @samp{zmm31h}, only valid for amd64.
@end itemize
+@node MicroBlaze Features
+@subsection MicroBlaze Features
+@cindex target descriptions, MicroBlaze features
+
+The @samp{org.gnu.gdb.microblaze.core} feature is required for MicroBlaze
+targets. It should contain registers @samp{r0} through @samp{r31},
+@samp{rpc}, @samp{rmsr}, @samp{rear}, @samp{resr}, @samp{rfsr}, @samp{rbtr},
+@samp{rpvr}, @samp{rpvr1} through @samp{rpvr11}, @samp{redr}, @samp{rpid},
+@samp{rzpr}, @samp{rtlbx}, @samp{rtlbsx}, @samp{rtlblo}, and @samp{rtlbhi}.
+
+The @samp{org.gnu.gdb.microblaze.stack-protect} feature is optional.
+If present, it should contain registers @samp{rshr} and @samp{rslr}
+
@node MIPS Features
@subsection @acronym{MIPS} Features
@cindex target descriptions, @acronym{MIPS} features
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