@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
that situation.
+It is also possible to insert a breakpoint that will stop the program
+only if a specific thread (@pxref{Thread-Specific Breakpoints})
+or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
+
@item break
When called without any arguments, @code{break} sets a breakpoint at
the next instruction to be executed in the selected stack frame
@group
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
-#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
+#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
at macro.c:71
(More stack frames follow...)
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
+@noindent
+The value of parameter @code{data} in frame 1 has been replaced by
+@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter
+only if it is a scalar (integer, pointer, enumeration, etc). See command
+@kbd{set print frame-arguments} in @ref{Print Settings} for more details
+on how to configure the way function parameter values are printed.
+
@cindex value optimized out, in backtrace
@cindex function call arguments, optimized out
If your program was compiled with optimizations, some compilers will
located at the original location, a substitution rule is the only
method available to point @value{GDBN} at the new location.
+@cindex @samp{--with-relocated-sources}
+@cindex default source path substitution
+You can configure a default source path substitution rule by
+configuring @value{GDBN} with the
+@samp{--with-relocated-sources=@var{dir}} option. The @var{dir}
+should be the name of a directory under @value{GDBN}'s configured
+prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and
+directory names in debug information under @var{dir} will be adjusted
+automatically if the installed @value{GDBN} is moved to a new
+location. This is useful if @value{GDBN}, libraries or executables
+with debug information and corresponding source code are being moved
+together.
+
@table @code
@item directory @var{dirname} @dots{}
@item dir @var{dirname} @dots{}
@kindex show disassemble-next-line
@item set disassemble-next-line
@itemx show disassemble-next-line
-Control whether or not @value{GDBN} will disassemble next source line
-when execution stops. If ON, GDB will display disassembly of the next
-source line when execution of the program being debugged stops.
-If AUTO (which is the default), or there's no line info to determine
-the source line of the next instruction, display disassembly of next
-instruction instead.
+Control whether or not @value{GDBN} will disassemble the next source
+line or instruction when execution stops. If ON, @value{GDBN} will
+display disassembly of the next source line when execution of the
+program being debugged stops. This is @emph{in addition} to
+displaying the source line itself, which @value{GDBN} always does if
+possible. If the next source line cannot be displayed for some reason
+(e.g., if @value{GDBN} cannot find the source file, or there's no line
+info in the debug info), @value{GDBN} will display disassembly of the
+next @emph{instruction} instead of showing the next source line. If
+AUTO, @value{GDBN} will display disassembly of next instruction only
+if the source line cannot be displayed. This setting causes
+@value{GDBN} to display some feedback when you step through a function
+with no line info or whose source file is unavailable. The default is
+OFF, which means never display the disassembly of the next line or
+instruction.
@end table
If the number is 0, then the printing is unlimited.
@item set print frame-arguments @var{value}
+@kindex set print frame-arguments
@cindex printing frame argument values
@cindex print all frame argument values
@cindex print frame argument values for scalars only
@table @code
@item all
-The values of all arguments are printed. This is the default.
+The values of all arguments are printed.
@item scalars
Print the value of an argument only if it is a scalar. The value of more
complex arguments such as arrays, structures, unions, etc, is replaced
-by @code{@dots{}}. Here is an example where only scalar arguments are shown:
+by @code{@dots{}}. This is the default. Here is an example where
+only scalar arguments are shown:
@smallexample
#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
@end smallexample
@end table
-By default, all argument values are always printed. But this command
-can be useful in several cases. For instance, it can be used to reduce
-the amount of information printed in each frame, making the backtrace
-more readable. Also, this command can be used to improve performance
-when displaying Ada frames, because the computation of large arguments
-can sometimes be CPU-intensive, especiallly in large applications.
-Setting @code{print frame-arguments} to @code{scalars} or @code{none}
-avoids this computation, thus speeding up the display of each Ada frame.
+By default, only scalar arguments are printed. This command can be used
+to configure the debugger to print the value of all arguments, regardless
+of their type. However, it is often advantageous to not print the value
+of more complex parameters. For instance, it reduces the amount of
+information printed in each frame, making the backtrace more readable.
+Also, it improves performance when displaying Ada frames, because
+the computation of large arguments can sometimes be CPU-intensive,
+especially in large applications. Setting @code{print frame-arguments}
+to @code{scalars} (the default) or @code{none} avoids this computation,
+thus speeding up the display of each Ada frame.
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
By default, @value{GDBN} uses a host character set appropriate to the
system it is running on; you can override that default using the
-@code{set host-charset} command.
+@code{set host-charset} command. On some systems, @value{GDBN} cannot
+automatically determine the appropriate host character set. In this
+case, @value{GDBN} uses @samp{UTF-8}.
@value{GDBN} can only use certain character sets as its host character
set. If you type @kbd{@w{set target-charset @key{TAB}@key{TAB}}},
@cindex definition, showing a macro's
@item info macro @var{macro}
Show the definition of the macro named @var{macro}, and describe the
-source location where that definition was established.
+source location or compiler command-line where that definition was established.
@kindex macro define
@cindex user-defined macros
(@value{GDBP})
@end smallexample
+In addition to source files, macros can be defined on the compilation command
+line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in
+such a way, @value{GDBN} displays the location of their definition as line zero
+of the source file submitted to the compiler.
+
+@smallexample
+(@value{GDBP}) info macro __STDC__
+Defined at /home/jimb/gdb/macros/play/sample.c:0
+-D__STDC__=1
+(@value{GDBP})
+@end smallexample
+
@node Tracepoints
@chapter Tracepoints
#4 0x804aacc in un () at un.adb:5
@end smallexample
+@item break @var{linespec} task @var{taskno}
+@itemx break @var{linespec} task @var{taskno} if @dots{}
+@cindex breakpoints and tasks, in Ada
+@cindex task breakpoints, in Ada
+@kindex break @dots{} task @var{taskno}@r{ (Ada)}
+These commands are like the @code{break @dots{} thread @dots{}}
+command (@pxref{Thread Stops}).
+@var{linespec} specifies source lines, as described
+in @ref{Specify Location}.
+
+Use the qualifier @samp{task @var{taskno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular Ada task reaches this breakpoint. @var{taskno} is one of the
+numeric task identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info tasks} display.
+
+If you do not specify @samp{task @var{taskno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} tasks of your
+program.
+
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @samp{task @var{taskno}} before the
+breakpoint condition (before the @code{if}).
+
+For example,
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 140022020 0 15 Child Activation Wait main_task
+ 2 140045060 1 15 Accept/Select Wait t2
+ 3 140044840 1 15 Runnable t1
+* 4 140056040 1 15 Runnable t3
+(@value{GDBP}) b 15 task 2
+Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
+(@value{GDBP}) cont
+Continuing.
+task # 1 running
+task # 2 running
+
+Breakpoint 5, test_task_debug () at test_task_debug.adb:15
+15 flush;
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 140022020 0 15 Child Activation Wait main_task
+* 2 140045060 1 15 Runnable t2
+ 3 140044840 1 15 Runnable t1
+ 4 140056040 1 15 Delay Sleep t3
+@end smallexample
@end table
@node Ada Tasks and Core Files
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
* Symbol Errors:: Errors reading symbol files
+* Data Files:: GDB data files
@end menu
@node Files
@end table
+@node Data Files
+@section GDB Data Files
+
+@cindex prefix for data files
+@value{GDBN} will sometimes read an auxiliary data file. These files
+are kept in a directory known as the @dfn{data directory}.
+
+You can set the data directory's name, and view the name @value{GDBN}
+is currently using.
+
+@table @code
+@kindex set data-directory
+@item set data-directory @var{directory}
+Set the directory which @value{GDBN} searches for auxiliary data files
+to @var{directory}.
+
+@kindex show data-directory
+@item show data-directory
+Show the directory @value{GDBN} searches for auxiliary data files.
+@end table
+
+@cindex default data directory
+@cindex @samp{--with-gdb-datadir}
+You can set the default data directory by using the configure-time
+@samp{--with-gdb-datadir} option. If the data directory is inside
+@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
+@samp{--exec-prefix}), then the default data directory will be updated
+automatically if the installed @value{GDBN} is moved to a new
+location.
+
@node Targets
@chapter Specifying a Debugging Target
(gdb)
@end smallexample
+@subheading The @code{-exec-jump} Command
+@findex -exec-jump
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-jump @var{location}
+@end smallexample
+
+Resumes execution of the inferior program at the location specified by
+parameter. @xref{Specify Location}, for a description of the
+different forms of @var{location}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{jump}.
+
+@subsubheading Example
+
+@smallexample
+-exec-jump foo.c:10
+*running,thread-id="all"
+^running
+@end smallexample
+
@subheading The @code{-exec-next} Command
@findex -exec-next
compiled with the @samp{-pg} compiler option.
@kindex maint show-debug-regs
-@cindex x86 hardware debug registers
+@cindex hardware debug registers
@item maint show-debug-regs
-Control whether to show variables that mirror the x86 hardware debug
+Control whether to show variables that mirror the hardware debug
registers. Use @code{ON} to enable, @code{OFF} to disable. If
enabled, the debug registers values are shown when @value{GDBN} inserts or
removes a hardware breakpoint or watchpoint, and when the inferior
projects / deliverable / binutils-gdb.git / blobdiff