Run TeX *three* times to get better index, xrefs.

[binutils.git] / gdb / doc / gdb.src-m4

_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