288 lines
10 KiB
Text
Executable file
288 lines
10 KiB
Text
Executable file
_dnl__ -*- Texinfo -*-
|
|
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
|
|
_dnl__ This file is part of the source for the GDB manual.
|
|
@c M4 FRAGMENT: $Id$
|
|
@node Source, Data, Stack, Top
|
|
@chapter Examining Source Files
|
|
|
|
_GDBN__ can print parts of your program's source, since the debugging
|
|
information recorded in your program tells _GDBN__ what source files
|
|
were used to built it. When your program stops, _GDBN__ spontaneously
|
|
prints the line where it stopped. Likewise, when you select a stack
|
|
frame (@pxref{Selection}), _GDBN__ prints the line where execution in
|
|
that frame has stopped. You can print other portions of source files by
|
|
explicit command.
|
|
|
|
If you use _GDBN__ through its GNU Emacs interface, you may prefer to
|
|
use Emacs facilities to view source; @pxref{Emacs}.
|
|
|
|
@menu
|
|
* List:: Printing Source Lines
|
|
* Search:: Searching Source Files
|
|
* Source Path:: Specifying Source Directories
|
|
* Machine Code:: Source and Machine Code
|
|
@end menu
|
|
|
|
@node List, Search, Source, Source
|
|
@section Printing Source Lines
|
|
|
|
@kindex list
|
|
@kindex l
|
|
To print lines from a source file, use the @code{list} command
|
|
(abbreviated @code{l}). There are several ways to specify what part
|
|
of the file you want to print.
|
|
|
|
Here are the forms of the @code{list} command most commonly used:
|
|
|
|
@table @code
|
|
@item list @var{linenum}
|
|
Print ten lines centered around line number @var{linenum} in the
|
|
current source file.
|
|
|
|
@item list @var{function}
|
|
Print ten lines centered around the beginning of function
|
|
@var{function}.
|
|
|
|
@item list
|
|
Print ten more lines. If the last lines printed were printed with a
|
|
@code{list} command, this prints ten lines following the last lines
|
|
printed; however, if the last line printed was a solitary line printed
|
|
as part of displaying a stack frame (@pxref{Stack}), this prints ten
|
|
lines centered around that line.
|
|
|
|
@item list -
|
|
Print ten lines just before the lines last printed.
|
|
@end table
|
|
|
|
Repeating a @code{list} command with @key{RET} discards the argument,
|
|
so it is equivalent to typing just @code{list}. This is more useful
|
|
than listing the same lines again. An exception is made for an
|
|
argument of @samp{-}; that argument is preserved in repetition so that
|
|
each repetition moves up in the source file.
|
|
|
|
@cindex linespec
|
|
In general, the @code{list} command expects you to supply zero, one or two
|
|
@dfn{linespecs}. Linespecs specify source lines; there are several ways
|
|
of writing them but the effect is always to specify some source line.
|
|
Here is a complete description of the possible arguments for @code{list}:
|
|
|
|
@table @code
|
|
@item list @var{linespec}
|
|
Print ten lines centered around the line specified by @var{linespec}.
|
|
|
|
@item list @var{first},@var{last}
|
|
Print lines from @var{first} to @var{last}. Both arguments are
|
|
linespecs.
|
|
|
|
@item list ,@var{last}
|
|
Print ten lines ending with @var{last}.
|
|
|
|
@item list @var{first},
|
|
Print ten lines starting with @var{first}.
|
|
|
|
@item list +
|
|
Print ten lines just after the lines last printed.
|
|
|
|
@item list -
|
|
Print ten lines just before the lines last printed.
|
|
|
|
@item list
|
|
As described in the preceding table.
|
|
@end table
|
|
|
|
Here are the ways of specifying a single source line---all the
|
|
kinds of linespec.
|
|
|
|
@table @code
|
|
@item @var{number}
|
|
Specifies line @var{number} of the current source file.
|
|
When a @code{list} command has two linespecs, this refers to
|
|
the same source file as the first linespec.
|
|
|
|
@item +@var{offset}
|
|
Specifies the line @var{offset} lines after the last line printed.
|
|
When used as the second linespec in a @code{list} command that has
|
|
two, this specifies the line @var{offset} lines down from the
|
|
first linespec.
|
|
|
|
@item -@var{offset}
|
|
Specifies the line @var{offset} lines before the last line printed.
|
|
|
|
@item @var{filename}:@var{number}
|
|
Specifies line @var{number} in the source file @var{filename}.
|
|
|
|
@item @var{function}
|
|
@c FIXME: "of the open-brace" is C-centric. When we add other langs...
|
|
Specifies the line of the open-brace that begins the body of the
|
|
function @var{function}.
|
|
|
|
@item @var{filename}:@var{function}
|
|
Specifies the line of the open-brace that begins the body of the
|
|
function @var{function} in the file @var{filename}. You only need the
|
|
file name with a function name to avoid ambiguity when there are
|
|
identically named functions in different source files.
|
|
|
|
@item *@var{address}
|
|
Specifies the line containing the program address @var{address}.
|
|
@var{address} may be any expression.
|
|
@end table
|
|
|
|
@node Search, Source Path, List, Source
|
|
@section Searching Source Files
|
|
@cindex searching
|
|
@kindex reverse-search
|
|
|
|
There are two commands for searching through the current source file for a
|
|
regular expression.
|
|
|
|
@table @code
|
|
@item forward-search @var{regexp}
|
|
@itemx search @var{regexp}
|
|
@kindex search
|
|
@kindex forward-search
|
|
The command @samp{forward-search @var{regexp}} checks each line, starting
|
|
with the one following the last line listed, for a match for @var{regexp}.
|
|
It lists the line that is found. You can abbreviate the command name
|
|
as @code{fo}. The synonym @samp{search @var{regexp}} is also supported.
|
|
|
|
@item reverse-search @var{regexp}
|
|
The command @samp{reverse-search @var{regexp}} checks each line, starting
|
|
with the one before the last line listed and going backward, for a match
|
|
for @var{regexp}. It lists the line that is found. You can abbreviate
|
|
this command as @code{rev}.
|
|
@end table
|
|
|
|
@node Source Path, Machine Code, Search, Source
|
|
@section Specifying Source Directories
|
|
|
|
@cindex source path
|
|
@cindex directories for source files
|
|
Executable programs sometimes do not record the directories of the source
|
|
files from which they were compiled, just the names. Even when they do,
|
|
the directories could be moved between the compilation and your debugging
|
|
session. _GDBN__ has a list of directories to search for source files;
|
|
this is called the @dfn{source path}. Each time _GDBN__ wants a source file,
|
|
it tries all the directories in the list, in the order they are present
|
|
in the list, until it finds a file with the desired name. Note that
|
|
the executable search path is @emph{not} used for this purpose. Neither is
|
|
the current working directory, unless it happens to be in the source
|
|
path.
|
|
|
|
If _GDBN__ can't find a source file in the source path, and the object
|
|
program records a directory, _GDBN__ tries that directory too. If the
|
|
source path is empty, and there is no record of the compilation
|
|
directory, _GDBN__ will, as a last resort, look in the current
|
|
directory.
|
|
|
|
Whenever you reset or rearrange the source path, _GDBN__ will clear out
|
|
any information it has cached about where source files are found, where
|
|
each line is in the file, etc.
|
|
|
|
@kindex directory
|
|
When you start _GDBN__, its source path is empty.
|
|
To add other directories, use the @code{directory} command.
|
|
|
|
@table @code
|
|
@item directory @var{dirname} @dots{}
|
|
Add directory @var{dirname} to the front of the source path. Several
|
|
directory names may be given to this command, separated by @samp{:} or
|
|
whitespace. You may specify a directory that is already in the source
|
|
path; this moves it forward, so it will be searched sooner. You can use
|
|
the string @samp{$cdir} to refer to the compilation directory (if one is
|
|
recorded), and @samp{$cwd} to refer to the current working directory.
|
|
@footnote{@samp{$cwd} is not the same as @samp{.}---the former tracks
|
|
the current working directory as it changes during your _GDBN__ session,
|
|
while the latter is immediately expanded to the current directory at the
|
|
time you add an entry to the source path.}
|
|
|
|
@item directory
|
|
Reset the source path to empty again. This requires confirmation.
|
|
|
|
@c RET-repeat for @code{directory} is explicitly disabled, but since
|
|
@c repeating it would be a no-op we don't say that. (thanks to RMS)
|
|
|
|
@item show directories
|
|
@kindex show directories
|
|
Print the source path: show which directories it contains.
|
|
@end table
|
|
|
|
If your source path is cluttered with directories that are no longer of
|
|
interest, _GDBN__ may sometimes cause confusion by finding the wrong
|
|
versions of source. You can correct the situation as follows:
|
|
|
|
@enumerate
|
|
@item
|
|
Use @code{directory} with no argument to reset the source path to empty.
|
|
|
|
@item
|
|
Use @code{directory} with suitable arguments to reinstall the
|
|
directories you want in the source path. You can add all the
|
|
directories in one command.
|
|
@end enumerate
|
|
|
|
@node Machine Code, , Source Path, Source
|
|
@section Source and Machine Code
|
|
You can use the command @code{info line} to map source lines to program
|
|
addresses (and viceversa), and the command @code{disassemble} to display
|
|
a range of addresses as machine instructions.
|
|
|
|
@table @code
|
|
@item info line @var{linespec}
|
|
@kindex info line
|
|
Print the starting and ending addresses of the compiled code for
|
|
source line @var{linespec}. You can specify source lines in any of the
|
|
ways understood by the @code{list} command (@pxref{List}).
|
|
@end table
|
|
|
|
For example, we can use @code{info line} to inquire on where the object
|
|
code for the first line of function @code{m4_changequote} lies:
|
|
@smallexample
|
|
(_GDBP__) info line m4_changecom
|
|
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
|
|
@end smallexample
|
|
|
|
@noindent
|
|
We can also inquire (using @code{*@var{addr}} as the form for
|
|
@var{linespec}) what source line covers a particular address:
|
|
@smallexample
|
|
(_GDBP__) info line *0x63ff
|
|
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
|
|
@end smallexample
|
|
|
|
@kindex $_
|
|
After @code{info line}, the default address for the @code{x}
|
|
command is changed to the starting address of the line, so that
|
|
@samp{x/i} is sufficient to begin examining the machine code
|
|
(@pxref{Memory}). Also, this address is saved as the value of the
|
|
convenience variable @code{$_} (@pxref{Convenience Vars}).
|
|
|
|
@table @code
|
|
@kindex disassemble
|
|
@item disassemble
|
|
This specialized command is provided to dump a range of memory as
|
|
machine instructions. The default memory range is the function
|
|
surrounding the program counter of the selected frame. A single
|
|
argument to this command is a program counter value; the function
|
|
surrounding this value will be dumped. Two arguments (separated by one
|
|
or more spaces) specify a range of addresses (first inclusive, second
|
|
exclusive) to be dumped.
|
|
@end table
|
|
|
|
We can use @code{disassemble} to inspect the object code
|
|
range shown in the last @code{info line} example:
|
|
|
|
@smallexample
|
|
(_GDBP__) disas 0x63e4 0x6404
|
|
Dump of assembler code from 0x63e4 to 0x6404:
|
|
0x63e4 <builtin_init+5340>: ble 0x63f8 <builtin_init+5360>
|
|
0x63e8 <builtin_init+5344>: sethi %hi(0x4c00), %o0
|
|
0x63ec <builtin_init+5348>: ld [%i1+4], %o0
|
|
0x63f0 <builtin_init+5352>: b 0x63fc <builtin_init+5364>
|
|
0x63f4 <builtin_init+5356>: ld [%o0+4], %o0
|
|
0x63f8 <builtin_init+5360>: or %o0, 0x1a4, %o0
|
|
0x63fc <builtin_init+5364>: call 0x9288 <path_search>
|
|
0x6400 <builtin_init+5368>: nop
|
|
End of assembler dump.
|
|
(_GDBP__)
|
|
|
|
@end smallexample
|