*** empty log message ***

gdb/doc/gdb.src-m4

@@ -0,0 +1,288 @@
+_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.
+_dnl__ $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