command is a program counter value; @value{GDBN} dumps the function
surrounding this value. When two arguments are given, they should
be separated by a comma, possibly surrounded by whitespace. The
-arguments specify a range of addresses (first inclusive, second exclusive)
-to dump. In that case, the name of the function is also printed (since
-there could be several functions in the given range).
+arguments specify a range of addresses to dump, in one of two forms:
+
+@table @code
+@item @var{start},@var{end}
+the addresses from @var{start} (inclusive) to @var{end} (exclusive)
+@item @var{start},+@var{length}
+the addresses from @var{start} (inclusive) to
+@code{@var{start}+@var{length}} (exclusive).
+@end table
+
+@noindent
+When 2 arguments are specified, the name of the function is also
+printed (since there could be several functions in the given range).
The argument(s) can be any expression yielding a numeric value, such as
@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}.
End of assembler dump.
@end smallexample
+Here is another example showing raw instructions in hex for AMD x86-64,
+
+@smallexample
+(gdb) disas /r 0x400281,+10
+Dump of assembler code from 0x400281 to 0x40028b:
+ 0x0000000000400281: 38 36 cmp %dh,(%rsi)
+ 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
+ 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
+ 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
+End of assembler dump.
+@end smallexample
+
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
@menu
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
+* Index Files:: Index files speed up GDB
* Symbol Errors:: Errors reading symbol files
* Data Files:: GDB data files
@end menu
This computation does not apply to the ``build ID'' method.
+@node Index Files
+@section Index Files Speed Up @value{GDBN}
+@cindex index files
+@cindex @samp{.gdb_index} section
+
+When @value{GDBN} finds a symbol file, it scans the symbols in the
+file in order to construct an internal symbol table. This lets most
+@value{GDBN} operations work quickly---at the cost of a delay early
+on. For large programs, this delay can be quite lengthy, so
+@value{GDBN} provides a way to build an index, which speeds up
+startup.
+
+The index is stored as a section in the symbol file. @value{GDBN} can
+write the index to a file, then you can put it into the symbol file
+using @command{objcopy}.
+
+To create an index file, use the @code{save gdb-index} command:
+
+@table @code
+@item save gdb-index @var{directory}
+@kindex save gdb-index
+Create an index file for each symbol file currently known by
+@value{GDBN}. Each file is named after its corresponding symbol file,
+with @samp{.gdb-index} appended, and is written into the given
+@var{directory}.
+@end table
+
+Once you have created an index file you can merge it into your symbol
+file, here named @file{symfile}, using @command{objcopy}:
+
+@smallexample
+$ objcopy --add-section .gdb_index=symfile.gdb-index \
+ --set-section-flags .gdb_index=readonly symfile symfile
+@end smallexample
+
+There are currently some limitation on indices. They only work when
+for DWARF debugging information, not stabs. And, they do not
+currently work for programs using Ada.
+
+
@node Symbol Errors
@section Errors Reading Symbol Files
@cindex active targets
@cindex multiple targets
-There are three classes of targets: processes, core files, and
-executable files. @value{GDBN} can work concurrently on up to three
-active targets, one in each class. This allows you to (for example)
-start a process and inspect its activity without abandoning your work on
-a core file.
-
-For example, if you execute @samp{gdb a.out}, then the executable file
-@code{a.out} is the only active target. If you designate a core file as
-well---presumably from a prior run that crashed and coredumped---then
-@value{GDBN} has two active targets and uses them in tandem, looking
-first in the corefile target, then in the executable file, to satisfy
-requests for memory addresses. (Typically, these two classes of target
-are complementary, since core files contain only a program's
-read-write memory---variables and so on---plus machine status, while
-executable files contain only the program text and initialized data.)
-
-When you type @code{run}, your executable file becomes an active process
-target as well. When a process target is active, all @value{GDBN}
-commands requesting memory addresses refer to that target; addresses in
-an active core file or executable file target are obscured while the
-process target is active.
-
-Use the @code{core-file} and @code{exec-file} commands to select a new
-core file or executable target (@pxref{Files, ,Commands to Specify
-Files}). To specify as a target a process that is already running, use
-the @code{attach} command (@pxref{Attach, ,Debugging an Already-running
-Process}).
+There are multiple classes of targets such as: processes, executable files or
+recording sessions. Core files belong to the process class, making core file
+and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently
+on multiple active targets, one in each class. This allows you to (for
+example) start a process and inspect its activity, while still having access to
+the executable file after the process finishes. Or if you start process
+recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are
+presented a virtual layer of the recording target, while the process target
+remains stopped at the chronologically last point of the process execution.
+
+Use the @code{core-file} and @code{exec-file} commands to select a new core
+file or executable target (@pxref{Files, ,Commands to Specify Files}). To
+specify as a target a process that is already running, use the @code{attach}
+command (@pxref{Attach, ,Debugging an Already-running Process}).
@node Target Commands
@section Commands for Managing Targets
Again, @code{bar} will also be a @code{gdb.Value} object.
+A @code{gdb.Value} that represents a function can be executed via
+inferior function call. Any arguments provided to the call must match
+the function's prototype, and must be provided in the order specified
+by that prototype.
+
+For example, @code{some_val} is a @code{gdb.Value} instance
+representing a function that takes two integers as arguments. To
+execute this function, call it like so:
+
+@smallexample
+result = some_val (10,20)
+@end smallexample
+
+Any values returned from a function call will be stored as a
+@code{gdb.Value}.
+
The following attributes are provided:
@table @code
projects / deliverable / binutils-gdb.git / blobdiff