Commit | Line | Data |
---|---|---|
9bcc06ef RP |
1 | _dnl__ -*- Texinfo -*- |
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. | |
16e58d91 | 4 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
5 | @node Source, Data, Stack, Top |
6 | @chapter Examining Source Files | |
7 | ||
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 | |
14 | explicit command. | |
15 | ||
16 | If you use _GDBN__ through its GNU Emacs interface, you may prefer to | |
17 | use Emacs facilities to view source; @pxref{Emacs}. | |
18 | ||
19 | @menu | |
20 | * List:: Printing Source Lines | |
21 | * Search:: Searching Source Files | |
22 | * Source Path:: Specifying Source Directories | |
23 | * Machine Code:: Source and Machine Code | |
24 | @end menu | |
25 | ||
26 | @node List, Search, Source, Source | |
27 | @section Printing Source Lines | |
28 | ||
29 | @kindex list | |
30 | @kindex l | |
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. | |
34 | ||
35 | Here are the forms of the @code{list} command most commonly used: | |
36 | ||
37 | @table @code | |
38 | @item list @var{linenum} | |
39 | Print ten lines centered around line number @var{linenum} in the | |
40 | current source file. | |
41 | ||
42 | @item list @var{function} | |
43 | Print ten lines centered around the beginning of function | |
44 | @var{function}. | |
45 | ||
46 | @item list | |
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. | |
52 | ||
53 | @item list - | |
54 | Print ten lines just before the lines last printed. | |
55 | @end table | |
56 | ||
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. | |
62 | ||
63 | @cindex linespec | |
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}: | |
68 | ||
69 | @table @code | |
70 | @item list @var{linespec} | |
71 | Print ten lines centered around the line specified by @var{linespec}. | |
72 | ||
73 | @item list @var{first},@var{last} | |
74 | Print lines from @var{first} to @var{last}. Both arguments are | |
75 | linespecs. | |
76 | ||
77 | @item list ,@var{last} | |
78 | Print ten lines ending with @var{last}. | |
79 | ||
80 | @item list @var{first}, | |
81 | Print ten lines starting with @var{first}. | |
82 | ||
83 | @item list + | |
84 | Print ten lines just after the lines last printed. | |
85 | ||
86 | @item list - | |
87 | Print ten lines just before the lines last printed. | |
88 | ||
89 | @item list | |
90 | As described in the preceding table. | |
91 | @end table | |
92 | ||
93 | Here are the ways of specifying a single source line---all the | |
94 | kinds of linespec. | |
95 | ||
96 | @table @code | |
97 | @item @var{number} | |
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. | |
101 | ||
102 | @item +@var{offset} | |
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 | |
106 | first linespec. | |
107 | ||
108 | @item -@var{offset} | |
109 | Specifies the line @var{offset} lines before the last line printed. | |
110 | ||
111 | @item @var{filename}:@var{number} | |
112 | Specifies line @var{number} in the source file @var{filename}. | |
113 | ||
114 | @item @var{function} | |
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}. | |
118 | ||
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. | |
124 | ||
125 | @item *@var{address} | |
126 | Specifies the line containing the program address @var{address}. | |
127 | @var{address} may be any expression. | |
128 | @end table | |
129 | ||
130 | @node Search, Source Path, List, Source | |
131 | @section Searching Source Files | |
132 | @cindex searching | |
133 | @kindex reverse-search | |
134 | ||
135 | There are two commands for searching through the current source file for a | |
136 | regular expression. | |
137 | ||
138 | @table @code | |
139 | @item forward-search @var{regexp} | |
140 | @itemx search @var{regexp} | |
141 | @kindex search | |
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. | |
147 | ||
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}. | |
153 | @end table | |
154 | ||
155 | @node Source Path, Machine Code, Search, Source | |
156 | @section Specifying Source Directories | |
157 | ||
158 | @cindex source path | |
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 | |
169 | path. | |
170 | ||
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 | |
175 | directory. | |
176 | ||
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. | |
180 | ||
181 | @kindex directory | |
182 | When you start _GDBN__, its source path is empty. | |
183 | To add other directories, use the @code{directory} command. | |
184 | ||
185 | @table @code | |
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.} | |
197 | ||
198 | @item directory | |
199 | Reset the source path to empty again. This requires confirmation. | |
200 | ||
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) | |
203 | ||
204 | @item show directories | |
205 | @kindex show directories | |
206 | Print the source path: show which directories it contains. | |
207 | @end table | |
208 | ||
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: | |
212 | ||
213 | @enumerate | |
214 | @item | |
215 | Use @code{directory} with no argument to reset the source path to empty. | |
216 | ||
217 | @item | |
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. | |
221 | @end enumerate | |
222 | ||
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. | |
228 | ||
229 | @table @code | |
230 | @item info line @var{linespec} | |
231 | @kindex info line | |
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}). | |
235 | @end table | |
236 | ||
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: | |
239 | @smallexample | |
240 | (_GDBP__) info line m4_changecom | |
241 | Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. | |
242 | @end smallexample | |
243 | ||
244 | @noindent | |
245 | We can also inquire (using @code{*@var{addr}} as the form for | |
246 | @var{linespec}) what source line covers a particular address: | |
247 | @smallexample | |
248 | (_GDBP__) info line *0x63ff | |
249 | Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. | |
250 | @end smallexample | |
251 | ||
252 | @kindex $_ | |
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}). | |
258 | ||
259 | @table @code | |
260 | @kindex disassemble | |
261 | @item disassemble | |
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. | |
269 | @end table | |
270 | ||
271 | We can use @code{disassemble} to inspect the object code | |
272 | range shown in the last @code{info line} example: | |
273 | ||
274 | @smallexample | |
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. | |
286 | (_GDBP__) | |
287 | ||
288 | @end smallexample |