1 |
106 |
markom |
This is ./gdb.info, produced by Makeinfo version 3.12f from gdb.texinfo.
|
2 |
|
|
|
3 |
|
|
INFO-DIR-SECTION Programming & development tools.
|
4 |
|
|
START-INFO-DIR-ENTRY
|
5 |
|
|
* Gdb: (gdb). The GNU debugger.
|
6 |
|
|
END-INFO-DIR-ENTRY
|
7 |
|
|
|
8 |
|
|
This file documents the GNU debugger GDB.
|
9 |
|
|
|
10 |
|
|
This is the Eighth Edition, March 2000, of `Debugging with GDB: the
|
11 |
|
|
GNU Source-Level Debugger' for GDB Version 5.0.
|
12 |
|
|
|
13 |
|
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
14 |
|
|
|
15 |
|
|
Permission is granted to make and distribute verbatim copies of this
|
16 |
|
|
manual provided the copyright notice and this permission notice are
|
17 |
|
|
preserved on all copies.
|
18 |
|
|
|
19 |
|
|
Permission is granted to copy and distribute modified versions of
|
20 |
|
|
this manual under the conditions for verbatim copying, provided also
|
21 |
|
|
that the entire resulting derived work is distributed under the terms
|
22 |
|
|
of a permission notice identical to this one.
|
23 |
|
|
|
24 |
|
|
Permission is granted to copy and distribute translations of this
|
25 |
|
|
manual into another language, under the above conditions for modified
|
26 |
|
|
versions.
|
27 |
|
|
|
28 |
|
|
|
29 |
|
|
File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top
|
30 |
|
|
|
31 |
|
|
Examining the Symbol Table
|
32 |
|
|
**************************
|
33 |
|
|
|
34 |
|
|
The commands described in this chapter allow you to inquire about the
|
35 |
|
|
symbols (names of variables, functions and types) defined in your
|
36 |
|
|
program. This information is inherent in the text of your program and
|
37 |
|
|
does not change as your program executes. GDB finds it in your
|
38 |
|
|
program's symbol table, in the file indicated when you started GDB
|
39 |
|
|
(*note Choosing files: File Options.), or by one of the file-management
|
40 |
|
|
commands (*note Commands to specify files: Files.).
|
41 |
|
|
|
42 |
|
|
Occasionally, you may need to refer to symbols that contain unusual
|
43 |
|
|
characters, which GDB ordinarily treats as word delimiters. The most
|
44 |
|
|
frequent case is in referring to static variables in other source files
|
45 |
|
|
(*note Program variables: Variables.). File names are recorded in
|
46 |
|
|
object files as debugging symbols, but GDB would ordinarily parse a
|
47 |
|
|
typical file name, like `foo.c', as the three words `foo' `.' `c'. To
|
48 |
|
|
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
|
49 |
|
|
quotes; for example,
|
50 |
|
|
|
51 |
|
|
p 'foo.c'::x
|
52 |
|
|
|
53 |
|
|
looks up the value of `x' in the scope of the file `foo.c'.
|
54 |
|
|
|
55 |
|
|
`info address SYMBOL'
|
56 |
|
|
Describe where the data for SYMBOL is stored. For a register
|
57 |
|
|
variable, this says which register it is kept in. For a
|
58 |
|
|
non-register local variable, this prints the stack-frame offset at
|
59 |
|
|
which the variable is always stored.
|
60 |
|
|
|
61 |
|
|
Note the contrast with `print &SYMBOL', which does not work at all
|
62 |
|
|
for a register variable, and for a stack local variable prints the
|
63 |
|
|
exact address of the current instantiation of the variable.
|
64 |
|
|
|
65 |
|
|
`whatis EXPR'
|
66 |
|
|
Print the data type of expression EXPR. EXPR is not actually
|
67 |
|
|
evaluated, and any side-effecting operations (such as assignments
|
68 |
|
|
or function calls) inside it do not take place. *Note
|
69 |
|
|
Expressions: Expressions.
|
70 |
|
|
|
71 |
|
|
`whatis'
|
72 |
|
|
Print the data type of `$', the last value in the value history.
|
73 |
|
|
|
74 |
|
|
`ptype TYPENAME'
|
75 |
|
|
Print a description of data type TYPENAME. TYPENAME may be the
|
76 |
|
|
name of a type, or for C code it may have the form `class
|
77 |
|
|
CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum
|
78 |
|
|
ENUM-TAG'.
|
79 |
|
|
|
80 |
|
|
`ptype EXPR'
|
81 |
|
|
`ptype'
|
82 |
|
|
Print a description of the type of expression EXPR. `ptype'
|
83 |
|
|
differs from `whatis' by printing a detailed description, instead
|
84 |
|
|
of just the name of the type.
|
85 |
|
|
|
86 |
|
|
For example, for this variable declaration:
|
87 |
|
|
|
88 |
|
|
struct complex {double real; double imag;} v;
|
89 |
|
|
|
90 |
|
|
the two commands give this output:
|
91 |
|
|
|
92 |
|
|
(gdb) whatis v
|
93 |
|
|
type = struct complex
|
94 |
|
|
(gdb) ptype v
|
95 |
|
|
type = struct complex {
|
96 |
|
|
double real;
|
97 |
|
|
double imag;
|
98 |
|
|
}
|
99 |
|
|
|
100 |
|
|
As with `whatis', using `ptype' without an argument refers to the
|
101 |
|
|
type of `$', the last value in the value history.
|
102 |
|
|
|
103 |
|
|
`info types REGEXP'
|
104 |
|
|
`info types'
|
105 |
|
|
Print a brief description of all types whose names match REGEXP
|
106 |
|
|
(or all types in your program, if you supply no argument). Each
|
107 |
|
|
complete typename is matched as though it were a complete line;
|
108 |
|
|
thus, `i type value' gives information on all types in your
|
109 |
|
|
program whose names include the string `value', but `i type
|
110 |
|
|
^value$' gives information only on types whose complete name is
|
111 |
|
|
`value'.
|
112 |
|
|
|
113 |
|
|
This command differs from `ptype' in two ways: first, like
|
114 |
|
|
`whatis', it does not print a detailed description; second, it
|
115 |
|
|
lists all source files where a type is defined.
|
116 |
|
|
|
117 |
|
|
`info source'
|
118 |
|
|
Show the name of the current source file--that is, the source file
|
119 |
|
|
for the function containing the current point of execution--and
|
120 |
|
|
the language it was written in.
|
121 |
|
|
|
122 |
|
|
`info sources'
|
123 |
|
|
Print the names of all source files in your program for which
|
124 |
|
|
there is debugging information, organized into two lists: files
|
125 |
|
|
whose symbols have already been read, and files whose symbols will
|
126 |
|
|
be read when needed.
|
127 |
|
|
|
128 |
|
|
`info functions'
|
129 |
|
|
Print the names and data types of all defined functions.
|
130 |
|
|
|
131 |
|
|
`info functions REGEXP'
|
132 |
|
|
Print the names and data types of all defined functions whose
|
133 |
|
|
names contain a match for regular expression REGEXP. Thus, `info
|
134 |
|
|
fun step' finds all functions whose names include `step'; `info
|
135 |
|
|
fun ^step' finds those whose names start with `step'.
|
136 |
|
|
|
137 |
|
|
`info variables'
|
138 |
|
|
Print the names and data types of all variables that are declared
|
139 |
|
|
outside of functions (i.e., excluding local variables).
|
140 |
|
|
|
141 |
|
|
`info variables REGEXP'
|
142 |
|
|
Print the names and data types of all variables (except for local
|
143 |
|
|
variables) whose names contain a match for regular expression
|
144 |
|
|
REGEXP.
|
145 |
|
|
|
146 |
|
|
Some systems allow individual object files that make up your
|
147 |
|
|
program to be replaced without stopping and restarting your
|
148 |
|
|
program. For example, in VxWorks you can simply recompile a
|
149 |
|
|
defective object file and keep on running. If you are running on
|
150 |
|
|
one of these systems, you can allow GDB to reload the symbols for
|
151 |
|
|
automatically relinked modules:
|
152 |
|
|
|
153 |
|
|
`set symbol-reloading on'
|
154 |
|
|
Replace symbol definitions for the corresponding source file
|
155 |
|
|
when an object file with a particular name is seen again.
|
156 |
|
|
|
157 |
|
|
`set symbol-reloading off'
|
158 |
|
|
Do not replace symbol definitions when encountering object
|
159 |
|
|
files of the same name more than once. This is the default
|
160 |
|
|
state; if you are not running on a system that permits
|
161 |
|
|
automatic relinking of modules, you should leave
|
162 |
|
|
`symbol-reloading' off, since otherwise GDB may discard
|
163 |
|
|
symbols when linking large programs, that may contain several
|
164 |
|
|
modules (from different directories or libraries) with the
|
165 |
|
|
same name.
|
166 |
|
|
|
167 |
|
|
`show symbol-reloading'
|
168 |
|
|
Show the current `on' or `off' setting.
|
169 |
|
|
|
170 |
|
|
`set opaque-type-resolution on'
|
171 |
|
|
Tell GDB to resolve opaque types. An opaque type is a type
|
172 |
|
|
declared as a pointer to a `struct', `class', or `union'--for
|
173 |
|
|
example, `struct MyType *'--that is used in one source file
|
174 |
|
|
although the full declaration of `struct MyType' is in another
|
175 |
|
|
source file. The default is on.
|
176 |
|
|
|
177 |
|
|
A change in the setting of this subcommand will not take effect
|
178 |
|
|
until the next time symbols for a file are loaded.
|
179 |
|
|
|
180 |
|
|
`set opaque-type-resolution off'
|
181 |
|
|
Tell GDB not to resolve opaque types. In this case, the type is
|
182 |
|
|
printed as follows:
|
183 |
|
|
{}
|
184 |
|
|
|
185 |
|
|
`show opaque-type-resolution'
|
186 |
|
|
Show whether opaque types are resolved or not.
|
187 |
|
|
|
188 |
|
|
`maint print symbols FILENAME'
|
189 |
|
|
`maint print psymbols FILENAME'
|
190 |
|
|
`maint print msymbols FILENAME'
|
191 |
|
|
Write a dump of debugging symbol data into the file FILENAME.
|
192 |
|
|
These commands are used to debug the GDB symbol-reading code. Only
|
193 |
|
|
symbols with debugging data are included. If you use `maint print
|
194 |
|
|
symbols', GDB includes all the symbols for which it has already
|
195 |
|
|
collected full details: that is, FILENAME reflects symbols for
|
196 |
|
|
only those files whose symbols GDB has read. You can use the
|
197 |
|
|
command `info sources' to find out which files these are. If you
|
198 |
|
|
use `maint print psymbols' instead, the dump shows information
|
199 |
|
|
about symbols that GDB only knows partially--that is, symbols
|
200 |
|
|
defined in files that GDB has skimmed, but not yet read
|
201 |
|
|
completely. Finally, `maint print msymbols' dumps just the
|
202 |
|
|
minimal symbol information required for each object file from
|
203 |
|
|
which GDB has read some symbols. *Note Commands to specify files:
|
204 |
|
|
Files, for a discussion of how GDB reads symbols (in the
|
205 |
|
|
description of `symbol-file').
|
206 |
|
|
|
207 |
|
|
|
208 |
|
|
File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top
|
209 |
|
|
|
210 |
|
|
Altering Execution
|
211 |
|
|
******************
|
212 |
|
|
|
213 |
|
|
Once you think you have found an error in your program, you might
|
214 |
|
|
want to find out for certain whether correcting the apparent error
|
215 |
|
|
would lead to correct results in the rest of the run. You can find the
|
216 |
|
|
answer by experiment, using the GDB features for altering execution of
|
217 |
|
|
the program.
|
218 |
|
|
|
219 |
|
|
For example, you can store new values into variables or memory
|
220 |
|
|
locations, give your program a signal, restart it at a different
|
221 |
|
|
address, or even return prematurely from a function.
|
222 |
|
|
|
223 |
|
|
* Menu:
|
224 |
|
|
|
225 |
|
|
* Assignment:: Assignment to variables
|
226 |
|
|
* Jumping:: Continuing at a different address
|
227 |
|
|
* Signaling:: Giving your program a signal
|
228 |
|
|
* Returning:: Returning from a function
|
229 |
|
|
* Calling:: Calling your program's functions
|
230 |
|
|
* Patching:: Patching your program
|
231 |
|
|
|
232 |
|
|
|
233 |
|
|
File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering
|
234 |
|
|
|
235 |
|
|
Assignment to variables
|
236 |
|
|
=======================
|
237 |
|
|
|
238 |
|
|
To alter the value of a variable, evaluate an assignment expression.
|
239 |
|
|
*Note Expressions: Expressions. For example,
|
240 |
|
|
|
241 |
|
|
print x=4
|
242 |
|
|
|
243 |
|
|
stores the value 4 into the variable `x', and then prints the value of
|
244 |
|
|
the assignment expression (which is 4). *Note Using GDB with Different
|
245 |
|
|
Languages: Languages, for more information on operators in supported
|
246 |
|
|
languages.
|
247 |
|
|
|
248 |
|
|
If you are not interested in seeing the value of the assignment, use
|
249 |
|
|
the `set' command instead of the `print' command. `set' is really the
|
250 |
|
|
same as `print' except that the expression's value is not printed and
|
251 |
|
|
is not put in the value history (*note Value history: Value History.).
|
252 |
|
|
The expression is evaluated only for its effects.
|
253 |
|
|
|
254 |
|
|
If the beginning of the argument string of the `set' command appears
|
255 |
|
|
identical to a `set' subcommand, use the `set variable' command instead
|
256 |
|
|
of just `set'. This command is identical to `set' except for its lack
|
257 |
|
|
of subcommands. For example, if your program has a variable `width',
|
258 |
|
|
you get an error if you try to set a new value with just `set
|
259 |
|
|
width=13', because GDB has the command `set width':
|
260 |
|
|
|
261 |
|
|
(gdb) whatis width
|
262 |
|
|
type = double
|
263 |
|
|
(gdb) p width
|
264 |
|
|
$4 = 13
|
265 |
|
|
(gdb) set width=47
|
266 |
|
|
Invalid syntax in expression.
|
267 |
|
|
|
268 |
|
|
The invalid expression, of course, is `=47'. In order to actually set
|
269 |
|
|
the program's variable `width', use
|
270 |
|
|
|
271 |
|
|
(gdb) set var width=47
|
272 |
|
|
|
273 |
|
|
Because the `set' command has many subcommands that can conflict
|
274 |
|
|
with the names of program variables, it is a good idea to use the `set
|
275 |
|
|
variable' command instead of just `set'. For example, if your program
|
276 |
|
|
has a variable `g', you run into problems if you try to set a new value
|
277 |
|
|
with just `set g=4', because GDB has the command `set gnutarget',
|
278 |
|
|
abbreviated `set g':
|
279 |
|
|
|
280 |
|
|
(gdb) whatis g
|
281 |
|
|
type = double
|
282 |
|
|
(gdb) p g
|
283 |
|
|
$1 = 1
|
284 |
|
|
(gdb) set g=4
|
285 |
|
|
(gdb) p g
|
286 |
|
|
$2 = 1
|
287 |
|
|
(gdb) r
|
288 |
|
|
The program being debugged has been started already.
|
289 |
|
|
Start it from the beginning? (y or n) y
|
290 |
|
|
Starting program: /home/smith/cc_progs/a.out
|
291 |
|
|
"/home/smith/cc_progs/a.out": can't open to read symbols:
|
292 |
|
|
Invalid bfd target.
|
293 |
|
|
(gdb) show g
|
294 |
|
|
The current BFD target is "=4".
|
295 |
|
|
|
296 |
|
|
The program variable `g' did not change, and you silently set the
|
297 |
|
|
`gnutarget' to an invalid value. In order to set the variable `g', use
|
298 |
|
|
|
299 |
|
|
(gdb) set var g=4
|
300 |
|
|
|
301 |
|
|
GDB allows more implicit conversions in assignments than C; you can
|
302 |
|
|
freely store an integer value into a pointer variable or vice versa,
|
303 |
|
|
and you can convert any structure to any other structure that is the
|
304 |
|
|
same length or shorter.
|
305 |
|
|
|
306 |
|
|
To store values into arbitrary places in memory, use the `{...}'
|
307 |
|
|
construct to generate a value of specified type at a specified address
|
308 |
|
|
(*note Expressions: Expressions.). For example, `{int}0x83040' refers
|
309 |
|
|
to memory location `0x83040' as an integer (which implies a certain size
|
310 |
|
|
and representation in memory), and
|
311 |
|
|
|
312 |
|
|
set {int}0x83040 = 4
|
313 |
|
|
|
314 |
|
|
stores the value 4 into that memory location.
|
315 |
|
|
|
316 |
|
|
|
317 |
|
|
File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering
|
318 |
|
|
|
319 |
|
|
Continuing at a different address
|
320 |
|
|
=================================
|
321 |
|
|
|
322 |
|
|
Ordinarily, when you continue your program, you do so at the place
|
323 |
|
|
where it stopped, with the `continue' command. You can instead
|
324 |
|
|
continue at an address of your own choosing, with the following
|
325 |
|
|
commands:
|
326 |
|
|
|
327 |
|
|
`jump LINESPEC'
|
328 |
|
|
Resume execution at line LINESPEC. Execution stops again
|
329 |
|
|
immediately if there is a breakpoint there. *Note Printing source
|
330 |
|
|
lines: List, for a description of the different forms of LINESPEC.
|
331 |
|
|
It is common practice to use the `tbreak' command in conjunction
|
332 |
|
|
with `jump'. *Note Setting breakpoints: Set Breaks.
|
333 |
|
|
|
334 |
|
|
The `jump' command does not change the current stack frame, or the
|
335 |
|
|
stack pointer, or the contents of any memory location or any
|
336 |
|
|
register other than the program counter. If line LINESPEC is in a
|
337 |
|
|
different function from the one currently executing, the results
|
338 |
|
|
may be bizarre if the two functions expect different patterns of
|
339 |
|
|
arguments or of local variables. For this reason, the `jump'
|
340 |
|
|
command requests confirmation if the specified line is not in the
|
341 |
|
|
function currently executing. However, even bizarre results are
|
342 |
|
|
predictable if you are well acquainted with the machine-language
|
343 |
|
|
code of your program.
|
344 |
|
|
|
345 |
|
|
`jump *ADDRESS'
|
346 |
|
|
Resume execution at the instruction at address ADDRESS.
|
347 |
|
|
|
348 |
|
|
On many systems, you can get much the same effect as the `jump'
|
349 |
|
|
command by storing a new value into the register `$pc'. The difference
|
350 |
|
|
is that this does not start your program running; it only changes the
|
351 |
|
|
address of where it _will_ run when you continue. For example,
|
352 |
|
|
|
353 |
|
|
set $pc = 0x485
|
354 |
|
|
|
355 |
|
|
makes the next `continue' command or stepping command execute at
|
356 |
|
|
address `0x485', rather than at the address where your program stopped.
|
357 |
|
|
*Note Continuing and stepping: Continuing and Stepping.
|
358 |
|
|
|
359 |
|
|
The most common occasion to use the `jump' command is to back
|
360 |
|
|
up--perhaps with more breakpoints set--over a portion of a program that
|
361 |
|
|
has already executed, in order to examine its execution in more detail.
|
362 |
|
|
|
363 |
|
|
|
364 |
|
|
File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering
|
365 |
|
|
|
366 |
|
|
Giving your program a signal
|
367 |
|
|
============================
|
368 |
|
|
|
369 |
|
|
`signal SIGNAL'
|
370 |
|
|
Resume execution where your program stopped, but immediately give
|
371 |
|
|
it the signal SIGNAL. SIGNAL can be the name or the number of a
|
372 |
|
|
signal. For example, on many systems `signal 2' and `signal
|
373 |
|
|
SIGINT' are both ways of sending an interrupt signal.
|
374 |
|
|
|
375 |
|
|
Alternatively, if SIGNAL is zero, continue execution without
|
376 |
|
|
giving a signal. This is useful when your program stopped on
|
377 |
|
|
account of a signal and would ordinary see the signal when resumed
|
378 |
|
|
with the `continue' command; `signal 0' causes it to resume
|
379 |
|
|
without a signal.
|
380 |
|
|
|
381 |
|
|
`signal' does not repeat when you press a second time after
|
382 |
|
|
executing the command.
|
383 |
|
|
|
384 |
|
|
Invoking the `signal' command is not the same as invoking the `kill'
|
385 |
|
|
utility from the shell. Sending a signal with `kill' causes GDB to
|
386 |
|
|
decide what to do with the signal depending on the signal handling
|
387 |
|
|
tables (*note Signals::.). The `signal' command passes the signal
|
388 |
|
|
directly to your program.
|
389 |
|
|
|
390 |
|
|
|
391 |
|
|
File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering
|
392 |
|
|
|
393 |
|
|
Returning from a function
|
394 |
|
|
=========================
|
395 |
|
|
|
396 |
|
|
`return'
|
397 |
|
|
`return EXPRESSION'
|
398 |
|
|
You can cancel execution of a function call with the `return'
|
399 |
|
|
command. If you give an EXPRESSION argument, its value is used as
|
400 |
|
|
the function's return value.
|
401 |
|
|
|
402 |
|
|
When you use `return', GDB discards the selected stack frame (and
|
403 |
|
|
all frames within it). You can think of this as making the discarded
|
404 |
|
|
frame return prematurely. If you wish to specify a value to be
|
405 |
|
|
returned, give that value as the argument to `return'.
|
406 |
|
|
|
407 |
|
|
This pops the selected stack frame (*note Selecting a frame:
|
408 |
|
|
Selection.), and any other frames inside of it, leaving its caller as
|
409 |
|
|
the innermost remaining frame. That frame becomes selected. The
|
410 |
|
|
specified value is stored in the registers used for returning values of
|
411 |
|
|
functions.
|
412 |
|
|
|
413 |
|
|
The `return' command does not resume execution; it leaves the
|
414 |
|
|
program stopped in the state that would exist if the function had just
|
415 |
|
|
returned. In contrast, the `finish' command (*note Continuing and
|
416 |
|
|
stepping: Continuing and Stepping.) resumes execution until the
|
417 |
|
|
selected stack frame returns naturally.
|
418 |
|
|
|
419 |
|
|
|
420 |
|
|
File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering
|
421 |
|
|
|
422 |
|
|
Calling program functions
|
423 |
|
|
=========================
|
424 |
|
|
|
425 |
|
|
`call EXPR'
|
426 |
|
|
Evaluate the expression EXPR without displaying `void' returned
|
427 |
|
|
values.
|
428 |
|
|
|
429 |
|
|
You can use this variant of the `print' command if you want to
|
430 |
|
|
execute a function from your program, but without cluttering the output
|
431 |
|
|
with `void' returned values. If the result is not void, it is printed
|
432 |
|
|
and saved in the value history.
|
433 |
|
|
|
434 |
|
|
For the A29K, a user-controlled variable `call_scratch_address',
|
435 |
|
|
specifies the location of a scratch area to be used when GDB calls a
|
436 |
|
|
function in the target. This is necessary because the usual method of
|
437 |
|
|
putting the scratch area on the stack does not work in systems that
|
438 |
|
|
have separate instruction and data spaces.
|
439 |
|
|
|
440 |
|
|
|
441 |
|
|
File: gdb.info, Node: Patching, Prev: Calling, Up: Altering
|
442 |
|
|
|
443 |
|
|
Patching programs
|
444 |
|
|
=================
|
445 |
|
|
|
446 |
|
|
By default, GDB opens the file containing your program's executable
|
447 |
|
|
code (or the corefile) read-only. This prevents accidental alterations
|
448 |
|
|
to machine code; but it also prevents you from intentionally patching
|
449 |
|
|
your program's binary.
|
450 |
|
|
|
451 |
|
|
If you'd like to be able to patch the binary, you can specify that
|
452 |
|
|
explicitly with the `set write' command. For example, you might want
|
453 |
|
|
to turn on internal debugging flags, or even to make emergency repairs.
|
454 |
|
|
|
455 |
|
|
`set write on'
|
456 |
|
|
`set write off'
|
457 |
|
|
If you specify `set write on', GDB opens executable and core files
|
458 |
|
|
for both reading and writing; if you specify `set write off' (the
|
459 |
|
|
default), GDB opens them read-only.
|
460 |
|
|
|
461 |
|
|
If you have already loaded a file, you must load it again (using
|
462 |
|
|
the `exec-file' or `core-file' command) after changing `set
|
463 |
|
|
write', for your new setting to take effect.
|
464 |
|
|
|
465 |
|
|
`show write'
|
466 |
|
|
Display whether executable files and core files are opened for
|
467 |
|
|
writing as well as reading.
|
468 |
|
|
|
469 |
|
|
|
470 |
|
|
File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top
|
471 |
|
|
|
472 |
|
|
GDB Files
|
473 |
|
|
*********
|
474 |
|
|
|
475 |
|
|
GDB needs to know the file name of the program to be debugged, both
|
476 |
|
|
in order to read its symbol table and in order to start your program.
|
477 |
|
|
To debug a core dump of a previous run, you must also tell GDB the name
|
478 |
|
|
of the core dump file.
|
479 |
|
|
|
480 |
|
|
* Menu:
|
481 |
|
|
|
482 |
|
|
* Files:: Commands to specify files
|
483 |
|
|
* Symbol Errors:: Errors reading symbol files
|
484 |
|
|
|
485 |
|
|
|
486 |
|
|
File: gdb.info, Node: Files, Next: Symbol Errors, Up: GDB Files
|
487 |
|
|
|
488 |
|
|
Commands to specify files
|
489 |
|
|
=========================
|
490 |
|
|
|
491 |
|
|
You may want to specify executable and core dump file names. The
|
492 |
|
|
usual way to do this is at start-up time, using the arguments to GDB's
|
493 |
|
|
start-up commands (*note Getting In and Out of GDB: Invocation.).
|
494 |
|
|
|
495 |
|
|
Occasionally it is necessary to change to a different file during a
|
496 |
|
|
GDB session. Or you may run GDB and forget to specify a file you want
|
497 |
|
|
to use. In these situations the GDB commands to specify new files are
|
498 |
|
|
useful.
|
499 |
|
|
|
500 |
|
|
`file FILENAME'
|
501 |
|
|
Use FILENAME as the program to be debugged. It is read for its
|
502 |
|
|
symbols and for the contents of pure memory. It is also the
|
503 |
|
|
program executed when you use the `run' command. If you do not
|
504 |
|
|
specify a directory and the file is not found in the GDB working
|
505 |
|
|
directory, GDB uses the environment variable `PATH' as a list of
|
506 |
|
|
directories to search, just as the shell does when looking for a
|
507 |
|
|
program to run. You can change the value of this variable, for
|
508 |
|
|
both GDB and your program, using the `path' command.
|
509 |
|
|
|
510 |
|
|
On systems with memory-mapped files, an auxiliary file named
|
511 |
|
|
`FILENAME.syms' may hold symbol table information for FILENAME.
|
512 |
|
|
If so, GDB maps in the symbol table from `FILENAME.syms', starting
|
513 |
|
|
up more quickly. See the descriptions of the file options
|
514 |
|
|
`-mapped' and `-readnow' (available on the command line, and with
|
515 |
|
|
the commands `file', `symbol-file', or `add-symbol-file',
|
516 |
|
|
described below), for more information.
|
517 |
|
|
|
518 |
|
|
`file'
|
519 |
|
|
`file' with no argument makes GDB discard any information it has
|
520 |
|
|
on both executable file and the symbol table.
|
521 |
|
|
|
522 |
|
|
`exec-file [ FILENAME ]'
|
523 |
|
|
Specify that the program to be run (but not the symbol table) is
|
524 |
|
|
found in FILENAME. GDB searches the environment variable `PATH'
|
525 |
|
|
if necessary to locate your program. Omitting FILENAME means to
|
526 |
|
|
discard information on the executable file.
|
527 |
|
|
|
528 |
|
|
`symbol-file [ FILENAME ]'
|
529 |
|
|
Read symbol table information from file FILENAME. `PATH' is
|
530 |
|
|
searched when necessary. Use the `file' command to get both symbol
|
531 |
|
|
table and program to run from the same file.
|
532 |
|
|
|
533 |
|
|
`symbol-file' with no argument clears out GDB information on your
|
534 |
|
|
program's symbol table.
|
535 |
|
|
|
536 |
|
|
The `symbol-file' command causes GDB to forget the contents of its
|
537 |
|
|
convenience variables, the value history, and all breakpoints and
|
538 |
|
|
auto-display expressions. This is because they may contain
|
539 |
|
|
pointers to the internal data recording symbols and data types,
|
540 |
|
|
which are part of the old symbol table data being discarded inside
|
541 |
|
|
GDB.
|
542 |
|
|
|
543 |
|
|
`symbol-file' does not repeat if you press again after
|
544 |
|
|
executing it once.
|
545 |
|
|
|
546 |
|
|
When GDB is configured for a particular environment, it
|
547 |
|
|
understands debugging information in whatever format is the
|
548 |
|
|
standard generated for that environment; you may use either a GNU
|
549 |
|
|
compiler, or other compilers that adhere to the local conventions.
|
550 |
|
|
Best results are usually obtained from GNU compilers; for example,
|
551 |
|
|
using `gcc' you can generate debugging information for optimized
|
552 |
|
|
code.
|
553 |
|
|
|
554 |
|
|
For most kinds of object files, with the exception of old SVR3
|
555 |
|
|
systems using COFF, the `symbol-file' command does not normally
|
556 |
|
|
read the symbol table in full right away. Instead, it scans the
|
557 |
|
|
symbol table quickly to find which source files and which symbols
|
558 |
|
|
are present. The details are read later, one source file at a
|
559 |
|
|
time, as they are needed.
|
560 |
|
|
|
561 |
|
|
The purpose of this two-stage reading strategy is to make GDB
|
562 |
|
|
start up faster. For the most part, it is invisible except for
|
563 |
|
|
occasional pauses while the symbol table details for a particular
|
564 |
|
|
source file are being read. (The `set verbose' command can turn
|
565 |
|
|
these pauses into messages if desired. *Note Optional warnings
|
566 |
|
|
and messages: Messages/Warnings.)
|
567 |
|
|
|
568 |
|
|
We have not implemented the two-stage strategy for COFF yet. When
|
569 |
|
|
the symbol table is stored in COFF format, `symbol-file' reads the
|
570 |
|
|
symbol table data in full right away. Note that "stabs-in-COFF"
|
571 |
|
|
still does the two-stage strategy, since the debug info is actually
|
572 |
|
|
in stabs format.
|
573 |
|
|
|
574 |
|
|
`symbol-file FILENAME [ -readnow ] [ -mapped ]'
|
575 |
|
|
`file FILENAME [ -readnow ] [ -mapped ]'
|
576 |
|
|
You can override the GDB two-stage strategy for reading symbol
|
577 |
|
|
tables by using the `-readnow' option with any of the commands that
|
578 |
|
|
load symbol table information, if you want to be sure GDB has the
|
579 |
|
|
entire symbol table available.
|
580 |
|
|
|
581 |
|
|
If memory-mapped files are available on your system through the
|
582 |
|
|
`mmap' system call, you can use another option, `-mapped', to
|
583 |
|
|
cause GDB to write the symbols for your program into a reusable
|
584 |
|
|
file. Future GDB debugging sessions map in symbol information
|
585 |
|
|
from this auxiliary symbol file (if the program has not changed),
|
586 |
|
|
rather than spending time reading the symbol table from the
|
587 |
|
|
executable program. Using the `-mapped' option has the same
|
588 |
|
|
effect as starting GDB with the `-mapped' command-line option.
|
589 |
|
|
|
590 |
|
|
You can use both options together, to make sure the auxiliary
|
591 |
|
|
symbol file has all the symbol information for your program.
|
592 |
|
|
|
593 |
|
|
The auxiliary symbol file for a program called MYPROG is called
|
594 |
|
|
`MYPROG.syms'. Once this file exists (so long as it is newer than
|
595 |
|
|
the corresponding executable), GDB always attempts to use it when
|
596 |
|
|
you debug MYPROG; no special options or commands are needed.
|
597 |
|
|
|
598 |
|
|
The `.syms' file is specific to the host machine where you run
|
599 |
|
|
GDB. It holds an exact image of the internal GDB symbol table.
|
600 |
|
|
It cannot be shared across multiple host platforms.
|
601 |
|
|
|
602 |
|
|
`core-file [ FILENAME ]'
|
603 |
|
|
Specify the whereabouts of a core dump file to be used as the
|
604 |
|
|
"contents of memory". Traditionally, core files contain only some
|
605 |
|
|
parts of the address space of the process that generated them; GDB
|
606 |
|
|
can access the executable file itself for other parts.
|
607 |
|
|
|
608 |
|
|
`core-file' with no argument specifies that no core file is to be
|
609 |
|
|
used.
|
610 |
|
|
|
611 |
|
|
Note that the core file is ignored when your program is actually
|
612 |
|
|
running under GDB. So, if you have been running your program and
|
613 |
|
|
you wish to debug a core file instead, you must kill the
|
614 |
|
|
subprocess in which the program is running. To do this, use the
|
615 |
|
|
`kill' command (*note Killing the child process: Kill Process.).
|
616 |
|
|
|
617 |
|
|
`add-symbol-file FILENAME ADDRESS'
|
618 |
|
|
`add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]'
|
619 |
|
|
`add-symbol-file FILENAME ADDRESS DATA_ADDRESS BSS_ADDRESS'
|
620 |
|
|
`add-symbol-file FILENAME -TSECTION ADDRESS'
|
621 |
|
|
The `add-symbol-file' command reads additional symbol table
|
622 |
|
|
information from the file FILENAME. You would use this command
|
623 |
|
|
when FILENAME has been dynamically loaded (by some other means)
|
624 |
|
|
into the program that is running. ADDRESS should be the memory
|
625 |
|
|
address at which the file has been loaded; GDB cannot figure this
|
626 |
|
|
out for itself. You can specify up to three addresses, in which
|
627 |
|
|
case they are taken to be the addresses of the text, data, and bss
|
628 |
|
|
segments respectively. For complicated cases, you can specify an
|
629 |
|
|
arbitrary number of `-TSECTION ADDRESS' pairs, to give an explicit
|
630 |
|
|
section name and base address for that section. You can specify
|
631 |
|
|
any ADDRESS as an expression.
|
632 |
|
|
|
633 |
|
|
The symbol table of the file FILENAME is added to the symbol table
|
634 |
|
|
originally read with the `symbol-file' command. You can use the
|
635 |
|
|
`add-symbol-file' command any number of times; the new symbol data
|
636 |
|
|
thus read keeps adding to the old. To discard all old symbol data
|
637 |
|
|
instead, use the `symbol-file' command without any arguments.
|
638 |
|
|
|
639 |
|
|
`add-symbol-file' does not repeat if you press after using
|
640 |
|
|
it.
|
641 |
|
|
|
642 |
|
|
You can use the `-mapped' and `-readnow' options just as with the
|
643 |
|
|
`symbol-file' command, to change how GDB manages the symbol table
|
644 |
|
|
information for FILENAME.
|
645 |
|
|
|
646 |
|
|
`add-shared-symbol-file'
|
647 |
|
|
The `add-shared-symbol-file' command can be used only under
|
648 |
|
|
Harris' CXUX operating system for the Motorola 88k. GDB
|
649 |
|
|
automatically looks for shared libraries, however if GDB does not
|
650 |
|
|
find yours, you can run `add-shared-symbol-file'. It takes no
|
651 |
|
|
arguments.
|
652 |
|
|
|
653 |
|
|
`section'
|
654 |
|
|
The `section' command changes the base address of section SECTION
|
655 |
|
|
of the exec file to ADDR. This can be used if the exec file does
|
656 |
|
|
not contain section addresses, (such as in the a.out format), or
|
657 |
|
|
when the addresses specified in the file itself are wrong. Each
|
658 |
|
|
section must be changed separately. The `info files' command,
|
659 |
|
|
described below, lists all the sections and their addresses.
|
660 |
|
|
|
661 |
|
|
`info files'
|
662 |
|
|
`info target'
|
663 |
|
|
`info files' and `info target' are synonymous; both print the
|
664 |
|
|
current target (*note Specifying a Debugging Target: Targets.),
|
665 |
|
|
including the names of the executable and core dump files
|
666 |
|
|
currently in use by GDB, and the files from which symbols were
|
667 |
|
|
loaded. The command `help target' lists all possible targets
|
668 |
|
|
rather than current ones.
|
669 |
|
|
|
670 |
|
|
All file-specifying commands allow both absolute and relative file
|
671 |
|
|
names as arguments. GDB always converts the file name to an absolute
|
672 |
|
|
file name and remembers it that way.
|
673 |
|
|
|
674 |
|
|
GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
|
675 |
|
|
libraries.
|
676 |
|
|
|
677 |
|
|
GDB automatically loads symbol definitions from shared libraries
|
678 |
|
|
when you use the `run' command, or when you examine a core file.
|
679 |
|
|
(Before you issue the `run' command, GDB does not understand references
|
680 |
|
|
to a function in a shared library, however--unless you are debugging a
|
681 |
|
|
core file).
|
682 |
|
|
|
683 |
|
|
On HP-UX, if the program loads a library explicitly, GDB
|
684 |
|
|
automatically loads the symbols at the time of the `shl_load' call.
|
685 |
|
|
|
686 |
|
|
`info share'
|
687 |
|
|
`info sharedlibrary'
|
688 |
|
|
Print the names of the shared libraries which are currently loaded.
|
689 |
|
|
|
690 |
|
|
`sharedlibrary REGEX'
|
691 |
|
|
`share REGEX'
|
692 |
|
|
Load shared object library symbols for files matching a Unix
|
693 |
|
|
regular expression. As with files loaded automatically, it only
|
694 |
|
|
loads shared libraries required by your program for a core file or
|
695 |
|
|
after typing `run'. If REGEX is omitted all shared libraries
|
696 |
|
|
required by your program are loaded.
|
697 |
|
|
|
698 |
|
|
On HP-UX systems, GDB detects the loading of a shared library and
|
699 |
|
|
automatically reads in symbols from the newly loaded library, up to a
|
700 |
|
|
threshold that is initially set but that you can modify if you wish.
|
701 |
|
|
|
702 |
|
|
Beyond that threshold, symbols from shared libraries must be
|
703 |
|
|
explicitly loaded. To load these symbols, use the command
|
704 |
|
|
`sharedlibrary FILENAME'. The base address of the shared library is
|
705 |
|
|
determined automatically by GDB and need not be specified.
|
706 |
|
|
|
707 |
|
|
To display or set the threshold, use the commands:
|
708 |
|
|
|
709 |
|
|
`set auto-solib-add THRESHOLD'
|
710 |
|
|
Set the autoloading size threshold, in megabytes. If THRESHOLD is
|
711 |
|
|
nonzero, symbols from all shared object libraries will be loaded
|
712 |
|
|
automatically when the inferior begins execution or when the
|
713 |
|
|
dynamic linker informs GDB that a new library has been loaded,
|
714 |
|
|
until the symbol table of the program and libraries exceeds this
|
715 |
|
|
threshold. Otherwise, symbols must be loaded manually, using the
|
716 |
|
|
`sharedlibrary' command. The default threshold is 100 megabytes.
|
717 |
|
|
|
718 |
|
|
`show auto-solib-add'
|
719 |
|
|
Display the current autoloading size threshold, in megabytes.
|
720 |
|
|
|
721 |
|
|
|
722 |
|
|
File: gdb.info, Node: Symbol Errors, Prev: Files, Up: GDB Files
|
723 |
|
|
|
724 |
|
|
Errors reading symbol files
|
725 |
|
|
===========================
|
726 |
|
|
|
727 |
|
|
While reading a symbol file, GDB occasionally encounters problems,
|
728 |
|
|
such as symbol types it does not recognize, or known bugs in compiler
|
729 |
|
|
output. By default, GDB does not notify you of such problems, since
|
730 |
|
|
they are relatively common and primarily of interest to people
|
731 |
|
|
debugging compilers. If you are interested in seeing information about
|
732 |
|
|
ill-constructed symbol tables, you can either ask GDB to print only one
|
733 |
|
|
message about each such type of problem, no matter how many times the
|
734 |
|
|
problem occurs; or you can ask GDB to print more messages, to see how
|
735 |
|
|
many times the problems occur, with the `set complaints' command (*note
|
736 |
|
|
Optional warnings and messages: Messages/Warnings.).
|
737 |
|
|
|
738 |
|
|
The messages currently printed, and their meanings, include:
|
739 |
|
|
|
740 |
|
|
`inner block not inside outer block in SYMBOL'
|
741 |
|
|
The symbol information shows where symbol scopes begin and end
|
742 |
|
|
(such as at the start of a function or a block of statements).
|
743 |
|
|
This error indicates that an inner scope block is not fully
|
744 |
|
|
contained in its outer scope blocks.
|
745 |
|
|
|
746 |
|
|
GDB circumvents the problem by treating the inner block as if it
|
747 |
|
|
had the same scope as the outer block. In the error message,
|
748 |
|
|
SYMBOL may be shown as "`(don't know)'" if the outer block is not a
|
749 |
|
|
function.
|
750 |
|
|
|
751 |
|
|
`block at ADDRESS out of order'
|
752 |
|
|
The symbol information for symbol scope blocks should occur in
|
753 |
|
|
order of increasing addresses. This error indicates that it does
|
754 |
|
|
not do so.
|
755 |
|
|
|
756 |
|
|
GDB does not circumvent this problem, and has trouble locating
|
757 |
|
|
symbols in the source file whose symbols it is reading. (You can
|
758 |
|
|
often determine what source file is affected by specifying `set
|
759 |
|
|
verbose on'. *Note Optional warnings and messages:
|
760 |
|
|
Messages/Warnings.)
|
761 |
|
|
|
762 |
|
|
`bad block start address patched'
|
763 |
|
|
The symbol information for a symbol scope block has a start address
|
764 |
|
|
smaller than the address of the preceding source line. This is
|
765 |
|
|
known to occur in the SunOS 4.1.1 (and earlier) C compiler.
|
766 |
|
|
|
767 |
|
|
GDB circumvents the problem by treating the symbol scope block as
|
768 |
|
|
starting on the previous source line.
|
769 |
|
|
|
770 |
|
|
`bad string table offset in symbol N'
|
771 |
|
|
Symbol number N contains a pointer into the string table which is
|
772 |
|
|
larger than the size of the string table.
|
773 |
|
|
|
774 |
|
|
GDB circumvents the problem by considering the symbol to have the
|
775 |
|
|
name `foo', which may cause other problems if many symbols end up
|
776 |
|
|
with this name.
|
777 |
|
|
|
778 |
|
|
`unknown symbol type `0xNN''
|
779 |
|
|
The symbol information contains new data types that GDB does not
|
780 |
|
|
yet know how to read. `0xNN' is the symbol type of the
|
781 |
|
|
uncomprehended information, in hexadecimal.
|
782 |
|
|
|
783 |
|
|
GDB circumvents the error by ignoring this symbol information.
|
784 |
|
|
This usually allows you to debug your program, though certain
|
785 |
|
|
symbols are not accessible. If you encounter such a problem and
|
786 |
|
|
feel like debugging it, you can debug `gdb' with itself, breakpoint
|
787 |
|
|
on `complain', then go up to the function `read_dbx_symtab' and
|
788 |
|
|
examine `*bufp' to see the symbol.
|
789 |
|
|
|
790 |
|
|
`stub type has NULL name'
|
791 |
|
|
GDB could not find the full definition for a struct or class.
|
792 |
|
|
|
793 |
|
|
`const/volatile indicator missing (ok if using g++ v1.x), got...'
|
794 |
|
|
The symbol information for a C++ member function is missing some
|
795 |
|
|
information that recent versions of the compiler should have
|
796 |
|
|
output for it.
|
797 |
|
|
|
798 |
|
|
`info mismatch between compiler and debugger'
|
799 |
|
|
GDB could not parse a type specification output by the compiler.
|
800 |
|
|
|
801 |
|
|
|
802 |
|
|
File: gdb.info, Node: Targets, Next: Configurations, Prev: GDB Files, Up: Top
|
803 |
|
|
|
804 |
|
|
Specifying a Debugging Target
|
805 |
|
|
*****************************
|
806 |
|
|
|
807 |
|
|
A "target" is the execution environment occupied by your program.
|
808 |
|
|
|
809 |
|
|
Often, GDB runs in the same host environment as your program; in
|
810 |
|
|
that case, the debugging target is specified as a side effect when you
|
811 |
|
|
use the `file' or `core' commands. When you need more flexibility--for
|
812 |
|
|
example, running GDB on a physically separate host, or controlling a
|
813 |
|
|
standalone system over a serial port or a realtime system over a TCP/IP
|
814 |
|
|
connection--you can use the `target' command to specify one of the
|
815 |
|
|
target types configured for GDB (*note Commands for managing targets:
|
816 |
|
|
Target Commands.).
|
817 |
|
|
|
818 |
|
|
* Menu:
|
819 |
|
|
|
820 |
|
|
* Active Targets:: Active targets
|
821 |
|
|
* Target Commands:: Commands for managing targets
|
822 |
|
|
* Byte Order:: Choosing target byte order
|
823 |
|
|
* Remote:: Remote debugging
|
824 |
|
|
* KOD:: Kernel Object Display
|
825 |
|
|
|
826 |
|
|
|
827 |
|
|
File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets
|
828 |
|
|
|
829 |
|
|
Active targets
|
830 |
|
|
==============
|
831 |
|
|
|
832 |
|
|
There are three classes of targets: processes, core files, and
|
833 |
|
|
executable files. GDB can work concurrently on up to three active
|
834 |
|
|
targets, one in each class. This allows you to (for example) start a
|
835 |
|
|
process and inspect its activity without abandoning your work on a core
|
836 |
|
|
file.
|
837 |
|
|
|
838 |
|
|
For example, if you execute `gdb a.out', then the executable file
|
839 |
|
|
`a.out' is the only active target. If you designate a core file as
|
840 |
|
|
well--presumably from a prior run that crashed and coredumped--then GDB
|
841 |
|
|
has two active targets and uses them in tandem, looking first in the
|
842 |
|
|
corefile target, then in the executable file, to satisfy requests for
|
843 |
|
|
memory addresses. (Typically, these two classes of target are
|
844 |
|
|
complementary, since core files contain only a program's read-write
|
845 |
|
|
memory--variables and so on--plus machine status, while executable
|
846 |
|
|
files contain only the program text and initialized data.)
|
847 |
|
|
|
848 |
|
|
When you type `run', your executable file becomes an active process
|
849 |
|
|
target as well. When a process target is active, all GDB commands
|
850 |
|
|
requesting memory addresses refer to that target; addresses in an
|
851 |
|
|
active core file or executable file target are obscured while the
|
852 |
|
|
process target is active.
|
853 |
|
|
|
854 |
|
|
Use the `core-file' and `exec-file' commands to select a new core
|
855 |
|
|
file or executable target (*note Commands to specify files: Files.).
|
856 |
|
|
To specify as a target a process that is already running, use the
|
857 |
|
|
`attach' command (*note Debugging an already-running process: Attach.).
|
858 |
|
|
|
859 |
|
|
|
860 |
|
|
File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets
|
861 |
|
|
|
862 |
|
|
Commands for managing targets
|
863 |
|
|
=============================
|
864 |
|
|
|
865 |
|
|
`target TYPE PARAMETERS'
|
866 |
|
|
Connects the GDB host environment to a target machine or process.
|
867 |
|
|
A target is typically a protocol for talking to debugging
|
868 |
|
|
facilities. You use the argument TYPE to specify the type or
|
869 |
|
|
protocol of the target machine.
|
870 |
|
|
|
871 |
|
|
Further PARAMETERS are interpreted by the target protocol, but
|
872 |
|
|
typically include things like device names or host names to connect
|
873 |
|
|
with, process numbers, and baud rates.
|
874 |
|
|
|
875 |
|
|
The `target' command does not repeat if you press again
|
876 |
|
|
after executing the command.
|
877 |
|
|
|
878 |
|
|
`help target'
|
879 |
|
|
Displays the names of all targets available. To display targets
|
880 |
|
|
currently selected, use either `info target' or `info files'
|
881 |
|
|
(*note Commands to specify files: Files.).
|
882 |
|
|
|
883 |
|
|
`help target NAME'
|
884 |
|
|
Describe a particular target, including any parameters necessary to
|
885 |
|
|
select it.
|
886 |
|
|
|
887 |
|
|
`set gnutarget ARGS'
|
888 |
|
|
GDB uses its own library BFD to read your files. GDB knows
|
889 |
|
|
whether it is reading an "executable", a "core", or a ".o" file;
|
890 |
|
|
however, you can specify the file format with the `set gnutarget'
|
891 |
|
|
command. Unlike most `target' commands, with `gnutarget' the
|
892 |
|
|
`target' refers to a program, not a machine.
|
893 |
|
|
|
894 |
|
|
_Warning:_ To specify a file format with `set gnutarget', you
|
895 |
|
|
must know the actual BFD name.
|
896 |
|
|
|
897 |
|
|
*Note Commands to specify files: Files.
|
898 |
|
|
|
899 |
|
|
`show gnutarget'
|
900 |
|
|
Use the `show gnutarget' command to display what file format
|
901 |
|
|
`gnutarget' is set to read. If you have not set `gnutarget', GDB
|
902 |
|
|
will determine the file format for each file automatically, and
|
903 |
|
|
`show gnutarget' displays `The current BDF target is "auto"'.
|
904 |
|
|
|
905 |
|
|
Here are some common targets (available, or not, depending on the GDB
|
906 |
|
|
configuration):
|
907 |
|
|
|
908 |
|
|
`target exec PROGRAM'
|
909 |
|
|
An executable file. `target exec PROGRAM' is the same as
|
910 |
|
|
`exec-file PROGRAM'.
|
911 |
|
|
|
912 |
|
|
`target core FILENAME'
|
913 |
|
|
A core dump file. `target core FILENAME' is the same as
|
914 |
|
|
`core-file FILENAME'.
|
915 |
|
|
|
916 |
|
|
`target remote DEV'
|
917 |
|
|
Remote serial target in GDB-specific protocol. The argument DEV
|
918 |
|
|
specifies what serial device to use for the connection (e.g.
|
919 |
|
|
`/dev/ttya'). *Note Remote debugging: Remote. `target remote'
|
920 |
|
|
supports the `load' command. This is only useful if you have some
|
921 |
|
|
other way of getting the stub to the target system, and you can put
|
922 |
|
|
it somewhere in memory where it won't get clobbered by the
|
923 |
|
|
download.
|
924 |
|
|
|
925 |
|
|
`target sim'
|
926 |
|
|
Builtin CPU simulator. GDB includes simulators for most
|
927 |
|
|
architectures. In general,
|
928 |
|
|
target sim
|
929 |
|
|
load
|
930 |
|
|
run
|
931 |
|
|
|
932 |
|
|
works; however, you cannot assume that a specific memory map,
|
933 |
|
|
device drivers, or even basic I/O is available, although some
|
934 |
|
|
simulators do provide these. For info about any
|
935 |
|
|
processor-specific simulator details, see the appropriate section
|
936 |
|
|
in *Note Embedded Processors: Embedded Processors.
|
937 |
|
|
|
938 |
|
|
Some configurations may include these targets as well:
|
939 |
|
|
|
940 |
|
|
`target nrom DEV'
|
941 |
|
|
NetROM ROM emulator. This target only supports downloading.
|
942 |
|
|
|
943 |
|
|
Different targets are available on different configurations of GDB;
|
944 |
|
|
your configuration may have more or fewer targets.
|
945 |
|
|
|
946 |
|
|
Many remote targets require you to download the executable's code
|
947 |
|
|
once you've successfully established a connection.
|
948 |
|
|
|
949 |
|
|
`load FILENAME'
|
950 |
|
|
Depending on what remote debugging facilities are configured into
|
951 |
|
|
GDB, the `load' command may be available. Where it exists, it is
|
952 |
|
|
meant to make FILENAME (an executable) available for debugging on
|
953 |
|
|
the remote system--by downloading, or dynamic linking, for example.
|
954 |
|
|
`load' also records the FILENAME symbol table in GDB, like the
|
955 |
|
|
`add-symbol-file' command.
|
956 |
|
|
|
957 |
|
|
If your GDB does not have a `load' command, attempting to execute
|
958 |
|
|
it gets the error message "`You can't do that when your target is
|
959 |
|
|
...'"
|
960 |
|
|
|
961 |
|
|
The file is loaded at whatever address is specified in the
|
962 |
|
|
executable. For some object file formats, you can specify the
|
963 |
|
|
load address when you link the program; for other formats, like
|
964 |
|
|
a.out, the object file format specifies a fixed address.
|
965 |
|
|
|
966 |
|
|
`load' does not repeat if you press again after using it.
|
967 |
|
|
|
968 |
|
|
|
969 |
|
|
File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets
|
970 |
|
|
|
971 |
|
|
Choosing target byte order
|
972 |
|
|
==========================
|
973 |
|
|
|
974 |
|
|
Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
|
975 |
|
|
offer the ability to run either big-endian or little-endian byte
|
976 |
|
|
orders. Usually the executable or symbol will include a bit to
|
977 |
|
|
designate the endian-ness, and you will not need to worry about which
|
978 |
|
|
to use. However, you may still find it useful to adjust GDB's idea of
|
979 |
|
|
processor endian-ness manually.
|
980 |
|
|
|
981 |
|
|
`set endian big'
|
982 |
|
|
Instruct GDB to assume the target is big-endian.
|
983 |
|
|
|
984 |
|
|
`set endian little'
|
985 |
|
|
Instruct GDB to assume the target is little-endian.
|
986 |
|
|
|
987 |
|
|
`set endian auto'
|
988 |
|
|
Instruct GDB to use the byte order associated with the executable.
|
989 |
|
|
|
990 |
|
|
`show endian'
|
991 |
|
|
Display GDB's current idea of the target byte order.
|
992 |
|
|
|
993 |
|
|
Note that these commands merely adjust interpretation of symbolic
|
994 |
|
|
data on the host, and that they have absolutely no effect on the target
|
995 |
|
|
system.
|
996 |
|
|
|
997 |
|
|
|
998 |
|
|
File: gdb.info, Node: Remote, Next: KOD, Prev: Byte Order, Up: Targets
|
999 |
|
|
|
1000 |
|
|
Remote debugging
|
1001 |
|
|
================
|
1002 |
|
|
|
1003 |
|
|
If you are trying to debug a program running on a machine that
|
1004 |
|
|
cannot run GDB in the usual way, it is often useful to use remote
|
1005 |
|
|
debugging. For example, you might use remote debugging on an operating
|
1006 |
|
|
system kernel, or on a small system which does not have a general
|
1007 |
|
|
purpose operating system powerful enough to run a full-featured
|
1008 |
|
|
debugger.
|
1009 |
|
|
|
1010 |
|
|
Some configurations of GDB have special serial or TCP/IP interfaces
|
1011 |
|
|
to make this work with particular debugging targets. In addition, GDB
|
1012 |
|
|
comes with a generic serial protocol (specific to GDB, but not specific
|
1013 |
|
|
to any particular target system) which you can use if you write the
|
1014 |
|
|
remote stubs--the code that runs on the remote system to communicate
|
1015 |
|
|
with GDB.
|
1016 |
|
|
|
1017 |
|
|
Other remote targets may be available in your configuration of GDB;
|
1018 |
|
|
use `help target' to list them.
|
1019 |
|
|
|
1020 |
|
|
* Menu:
|
1021 |
|
|
|
1022 |
|
|
* Remote Serial:: GDB remote serial protocol
|
1023 |
|
|
|
1024 |
|
|
|
1025 |
|
|
File: gdb.info, Node: Remote Serial, Up: Remote
|
1026 |
|
|
|
1027 |
|
|
The GDB remote serial protocol
|
1028 |
|
|
------------------------------
|
1029 |
|
|
|
1030 |
|
|
To debug a program running on another machine (the debugging
|
1031 |
|
|
"target" machine), you must first arrange for all the usual
|
1032 |
|
|
prerequisites for the program to run by itself. For example, for a C
|
1033 |
|
|
program, you need:
|
1034 |
|
|
|
1035 |
|
|
1. A startup routine to set up the C runtime environment; these
|
1036 |
|
|
usually have a name like `crt0'. The startup routine may be
|
1037 |
|
|
supplied by your hardware supplier, or you may have to write your
|
1038 |
|
|
own.
|
1039 |
|
|
|
1040 |
|
|
2. A C subroutine library to support your program's subroutine calls,
|
1041 |
|
|
notably managing input and output.
|
1042 |
|
|
|
1043 |
|
|
3. A way of getting your program to the other machine--for example, a
|
1044 |
|
|
download program. These are often supplied by the hardware
|
1045 |
|
|
manufacturer, but you may have to write your own from hardware
|
1046 |
|
|
documentation.
|
1047 |
|
|
|
1048 |
|
|
The next step is to arrange for your program to use a serial port to
|
1049 |
|
|
communicate with the machine where GDB is running (the "host" machine).
|
1050 |
|
|
In general terms, the scheme looks like this:
|
1051 |
|
|
|
1052 |
|
|
_On the host,_
|
1053 |
|
|
GDB already understands how to use this protocol; when everything
|
1054 |
|
|
else is set up, you can simply use the `target remote' command
|
1055 |
|
|
(*note Specifying a Debugging Target: Targets.).
|
1056 |
|
|
|
1057 |
|
|
_On the target,_
|
1058 |
|
|
you must link with your program a few special-purpose subroutines
|
1059 |
|
|
that implement the GDB remote serial protocol. The file
|
1060 |
|
|
containing these subroutines is called a "debugging stub".
|
1061 |
|
|
|
1062 |
|
|
On certain remote targets, you can use an auxiliary program
|
1063 |
|
|
`gdbserver' instead of linking a stub into your program. *Note
|
1064 |
|
|
Using the `gdbserver' program: Server, for details.
|
1065 |
|
|
|
1066 |
|
|
The debugging stub is specific to the architecture of the remote
|
1067 |
|
|
machine; for example, use `sparc-stub.c' to debug programs on SPARC
|
1068 |
|
|
boards.
|
1069 |
|
|
|
1070 |
|
|
These working remote stubs are distributed with GDB:
|
1071 |
|
|
|
1072 |
|
|
`i386-stub.c'
|
1073 |
|
|
For Intel 386 and compatible architectures.
|
1074 |
|
|
|
1075 |
|
|
`m68k-stub.c'
|
1076 |
|
|
For Motorola 680x0 architectures.
|
1077 |
|
|
|
1078 |
|
|
`sh-stub.c'
|
1079 |
|
|
For Hitachi SH architectures.
|
1080 |
|
|
|
1081 |
|
|
`sparc-stub.c'
|
1082 |
|
|
For SPARC architectures.
|
1083 |
|
|
|
1084 |
|
|
`sparcl-stub.c'
|
1085 |
|
|
For Fujitsu SPARCLITE architectures.
|
1086 |
|
|
|
1087 |
|
|
The `README' file in the GDB distribution may list other recently
|
1088 |
|
|
added stubs.
|
1089 |
|
|
|
1090 |
|
|
* Menu:
|
1091 |
|
|
|
1092 |
|
|
* Stub Contents:: What the stub can do for you
|
1093 |
|
|
* Bootstrapping:: What you must do for the stub
|
1094 |
|
|
* Debug Session:: Putting it all together
|
1095 |
|
|
* Protocol:: Definition of the communication protocol
|
1096 |
|
|
* Server:: Using the `gdbserver' program
|
1097 |
|
|
* NetWare:: Using the `gdbserve.nlm' program
|
1098 |
|
|
|
1099 |
|
|
|
1100 |
|
|
File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Serial
|
1101 |
|
|
|
1102 |
|
|
What the stub can do for you
|
1103 |
|
|
............................
|
1104 |
|
|
|
1105 |
|
|
The debugging stub for your architecture supplies these three
|
1106 |
|
|
subroutines:
|
1107 |
|
|
|
1108 |
|
|
`set_debug_traps'
|
1109 |
|
|
This routine arranges for `handle_exception' to run when your
|
1110 |
|
|
program stops. You must call this subroutine explicitly near the
|
1111 |
|
|
beginning of your program.
|
1112 |
|
|
|
1113 |
|
|
`handle_exception'
|
1114 |
|
|
This is the central workhorse, but your program never calls it
|
1115 |
|
|
explicitly--the setup code arranges for `handle_exception' to run
|
1116 |
|
|
when a trap is triggered.
|
1117 |
|
|
|
1118 |
|
|
`handle_exception' takes control when your program stops during
|
1119 |
|
|
execution (for example, on a breakpoint), and mediates
|
1120 |
|
|
communications with GDB on the host machine. This is where the
|
1121 |
|
|
communications protocol is implemented; `handle_exception' acts as
|
1122 |
|
|
the GDB representative on the target machine. It begins by
|
1123 |
|
|
sending summary information on the state of your program, then
|
1124 |
|
|
continues to execute, retrieving and transmitting any information
|
1125 |
|
|
GDB needs, until you execute a GDB command that makes your program
|
1126 |
|
|
resume; at that point, `handle_exception' returns control to your
|
1127 |
|
|
own code on the target machine.
|
1128 |
|
|
|
1129 |
|
|
`breakpoint'
|
1130 |
|
|
Use this auxiliary subroutine to make your program contain a
|
1131 |
|
|
breakpoint. Depending on the particular situation, this may be
|
1132 |
|
|
the only way for GDB to get control. For instance, if your target
|
1133 |
|
|
machine has some sort of interrupt button, you won't need to call
|
1134 |
|
|
this; pressing the interrupt button transfers control to
|
1135 |
|
|
`handle_exception'--in effect, to GDB. On some machines, simply
|
1136 |
|
|
receiving characters on the serial port may also trigger a trap;
|
1137 |
|
|
again, in that situation, you don't need to call `breakpoint' from
|
1138 |
|
|
your own program--simply running `target remote' from the host GDB
|
1139 |
|
|
session gets control.
|
1140 |
|
|
|
1141 |
|
|
Call `breakpoint' if none of these is true, or if you simply want
|
1142 |
|
|
to make certain your program stops at a predetermined point for the
|
1143 |
|
|
start of your debugging session.
|
1144 |
|
|
|