2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
3 _dnl__ This file is part of the source for the GDB manual.
5 @node Source, Data, Stack, Top
6 @chapter Examining Source Files
8 _GDBN__ can print parts of your program's source, since the debugging
9 information recorded in your program tells _GDBN__ what source files
10 were used to built it. When your program stops, _GDBN__ spontaneously
11 prints the line where it stopped. Likewise, when you select a stack
12 frame (@pxref{Selection}), _GDBN__ prints the line where execution in
13 that frame has stopped. You can print other portions of source files by
16 If you use _GDBN__ through its GNU Emacs interface, you may prefer to
17 use Emacs facilities to view source; @pxref{Emacs}.
20 * List:: Printing Source Lines
21 * Search:: Searching Source Files
22 * Source Path:: Specifying Source Directories
23 * Machine Code:: Source and Machine Code
26 @node List, Search, Source, Source
27 @section Printing Source Lines
31 To print lines from a source file, use the @code{list} command
32 (abbreviated @code{l}). There are several ways to specify what part
33 of the file you want to print.
35 Here are the forms of the @code{list} command most commonly used:
38 @item list @var{linenum}
39 Print ten lines centered around line number @var{linenum} in the
42 @item list @var{function}
43 Print ten lines centered around the beginning of function
47 Print ten more lines. If the last lines printed were printed with a
48 @code{list} command, this prints ten lines following the last lines
49 printed; however, if the last line printed was a solitary line printed
50 as part of displaying a stack frame (@pxref{Stack}), this prints ten
51 lines centered around that line.
54 Print ten lines just before the lines last printed.
57 Repeating a @code{list} command with @key{RET} discards the argument,
58 so it is equivalent to typing just @code{list}. This is more useful
59 than listing the same lines again. An exception is made for an
60 argument of @samp{-}; that argument is preserved in repetition so that
61 each repetition moves up in the source file.
64 In general, the @code{list} command expects you to supply zero, one or two
65 @dfn{linespecs}. Linespecs specify source lines; there are several ways
66 of writing them but the effect is always to specify some source line.
67 Here is a complete description of the possible arguments for @code{list}:
70 @item list @var{linespec}
71 Print ten lines centered around the line specified by @var{linespec}.
73 @item list @var{first},@var{last}
74 Print lines from @var{first} to @var{last}. Both arguments are
77 @item list ,@var{last}
78 Print ten lines ending with @var{last}.
80 @item list @var{first},
81 Print ten lines starting with @var{first}.
84 Print ten lines just after the lines last printed.
87 Print ten lines just before the lines last printed.
90 As described in the preceding table.
93 Here are the ways of specifying a single source line---all the
98 Specifies line @var{number} of the current source file.
99 When a @code{list} command has two linespecs, this refers to
100 the same source file as the first linespec.
103 Specifies the line @var{offset} lines after the last line printed.
104 When used as the second linespec in a @code{list} command that has
105 two, this specifies the line @var{offset} lines down from the
109 Specifies the line @var{offset} lines before the last line printed.
111 @item @var{filename}:@var{number}
112 Specifies line @var{number} in the source file @var{filename}.
115 @c FIXME: "of the open-brace" is C-centric. When we add other langs...
116 Specifies the line of the open-brace that begins the body of the
117 function @var{function}.
119 @item @var{filename}:@var{function}
120 Specifies the line of the open-brace that begins the body of the
121 function @var{function} in the file @var{filename}. You only need the
122 file name with a function name to avoid ambiguity when there are
123 identically named functions in different source files.
126 Specifies the line containing the program address @var{address}.
127 @var{address} may be any expression.
130 @node Search, Source Path, List, Source
131 @section Searching Source Files
133 @kindex reverse-search
135 There are two commands for searching through the current source file for a
139 @item forward-search @var{regexp}
140 @itemx search @var{regexp}
142 @kindex forward-search
143 The command @samp{forward-search @var{regexp}} checks each line, starting
144 with the one following the last line listed, for a match for @var{regexp}.
145 It lists the line that is found. You can abbreviate the command name
146 as @code{fo}. The synonym @samp{search @var{regexp}} is also supported.
148 @item reverse-search @var{regexp}
149 The command @samp{reverse-search @var{regexp}} checks each line, starting
150 with the one before the last line listed and going backward, for a match
151 for @var{regexp}. It lists the line that is found. You can abbreviate
152 this command as @code{rev}.
155 @node Source Path, Machine Code, Search, Source
156 @section Specifying Source Directories
159 @cindex directories for source files
160 Executable programs sometimes do not record the directories of the source
161 files from which they were compiled, just the names. Even when they do,
162 the directories could be moved between the compilation and your debugging
163 session. _GDBN__ has a list of directories to search for source files;
164 this is called the @dfn{source path}. Each time _GDBN__ wants a source file,
165 it tries all the directories in the list, in the order they are present
166 in the list, until it finds a file with the desired name. Note that
167 the executable search path is @emph{not} used for this purpose. Neither is
168 the current working directory, unless it happens to be in the source
171 If _GDBN__ can't find a source file in the source path, and the object
172 program records a directory, _GDBN__ tries that directory too. If the
173 source path is empty, and there is no record of the compilation
174 directory, _GDBN__ will, as a last resort, look in the current
177 Whenever you reset or rearrange the source path, _GDBN__ will clear out
178 any information it has cached about where source files are found, where
179 each line is in the file, etc.
182 When you start _GDBN__, its source path is empty.
183 To add other directories, use the @code{directory} command.
186 @item directory @var{dirname} @dots{}
187 Add directory @var{dirname} to the front of the source path. Several
188 directory names may be given to this command, separated by @samp{:} or
189 whitespace. You may specify a directory that is already in the source
190 path; this moves it forward, so it will be searched sooner. You can use
191 the string @samp{$cdir} to refer to the compilation directory (if one is
192 recorded), and @samp{$cwd} to refer to the current working directory.
193 @footnote{@samp{$cwd} is not the same as @samp{.}---the former tracks
194 the current working directory as it changes during your _GDBN__ session,
195 while the latter is immediately expanded to the current directory at the
196 time you add an entry to the source path.}
199 Reset the source path to empty again. This requires confirmation.
201 @c RET-repeat for @code{directory} is explicitly disabled, but since
202 @c repeating it would be a no-op we don't say that. (thanks to RMS)
204 @item show directories
205 @kindex show directories
206 Print the source path: show which directories it contains.
209 If your source path is cluttered with directories that are no longer of
210 interest, _GDBN__ may sometimes cause confusion by finding the wrong
211 versions of source. You can correct the situation as follows:
215 Use @code{directory} with no argument to reset the source path to empty.
218 Use @code{directory} with suitable arguments to reinstall the
219 directories you want in the source path. You can add all the
220 directories in one command.
223 @node Machine Code, , Source Path, Source
224 @section Source and Machine Code
225 You can use the command @code{info line} to map source lines to program
226 addresses (and viceversa), and the command @code{disassemble} to display
227 a range of addresses as machine instructions.
230 @item info line @var{linespec}
232 Print the starting and ending addresses of the compiled code for
233 source line @var{linespec}. You can specify source lines in any of the
234 ways understood by the @code{list} command (@pxref{List}).
237 For example, we can use @code{info line} to inquire on where the object
238 code for the first line of function @code{m4_changequote} lies:
240 (_GDBP__) info line m4_changecom
241 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
245 We can also inquire (using @code{*@var{addr}} as the form for
246 @var{linespec}) what source line covers a particular address:
248 (_GDBP__) info line *0x63ff
249 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
253 After @code{info line}, the default address for the @code{x}
254 command is changed to the starting address of the line, so that
255 @samp{x/i} is sufficient to begin examining the machine code
256 (@pxref{Memory}). Also, this address is saved as the value of the
257 convenience variable @code{$_} (@pxref{Convenience Vars}).
262 This specialized command is provided to dump a range of memory as
263 machine instructions. The default memory range is the function
264 surrounding the program counter of the selected frame. A single
265 argument to this command is a program counter value; the function
266 surrounding this value will be dumped. Two arguments (separated by one
267 or more spaces) specify a range of addresses (first inclusive, second
268 exclusive) to be dumped.
271 We can use @code{disassemble} to inspect the object code
272 range shown in the last @code{info line} example:
275 (_GDBP__) disas 0x63e4 0x6404
276 Dump of assembler code from 0x63e4 to 0x6404:
277 0x63e4 <builtin_init+5340>: ble 0x63f8 <builtin_init+5360>
278 0x63e8 <builtin_init+5344>: sethi %hi(0x4c00), %o0
279 0x63ec <builtin_init+5348>: ld [%i1+4], %o0
280 0x63f0 <builtin_init+5352>: b 0x63fc <builtin_init+5364>
281 0x63f4 <builtin_init+5356>: ld [%o0+4], %o0
282 0x63f8 <builtin_init+5360>: or %o0, 0x1a4, %o0
283 0x63fc <builtin_init+5364>: call 0x9288 <path_search>
284 0x6400 <builtin_init+5368>: nop
285 End of assembler dump.