OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [gdb/] [doc/] [gdb.info-3] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
This is ./gdb.info, produced by makeinfo version 4.0 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 Ninth Edition, April 2001, of `Debugging with GDB: the
11
GNU Source-Level Debugger' for GDB Version 20010707.
12
 
13
   Copyright (C)
14
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
15
Free Software Foundation, Inc.
16
 
17
   Permission is granted to copy, distribute and/or modify this document
18
under the terms of the GNU Free Documentation License, Version 1.1 or
19
any later version published by the Free Software Foundation; with the
20
Invariant Sections being "A Sample GDB Session" and "Free Software",
21
with the Front-Cover texts being "A GNU Manual," and with the
22
Back-Cover Texts as in (a) below.
23
 
24
   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
25
modify this GNU Manual, like GNU software.  Copies published by the Free
26
Software Foundation raise funds for GNU development."
27
 
28

29
File: gdb.info,  Node: Conditions,  Next: Break Commands,  Prev: Disabling,  Up: Breakpoints
30
 
31
Break conditions
32
----------------
33
 
34
   The simplest sort of breakpoint breaks every time your program
35
reaches a specified place.  You can also specify a "condition" for a
36
breakpoint.  A condition is just a Boolean expression in your
37
programming language (*note Expressions: Expressions.).  A breakpoint
38
with a condition evaluates the expression each time your program
39
reaches it, and your program stops only if the condition is _true_.
40
 
41
   This is the converse of using assertions for program validation; in
42
that situation, you want to stop when the assertion is violated--that
43
is, when the condition is false.  In C, if you want to test an
44
assertion expressed by the condition ASSERT, you should set the
45
condition `! ASSERT' on the appropriate breakpoint.
46
 
47
   Conditions are also accepted for watchpoints; you may not need them,
48
since a watchpoint is inspecting the value of an expression anyhow--but
49
it might be simpler, say, to just set a watchpoint on a variable name,
50
and specify a condition that tests whether the new value is an
51
interesting one.
52
 
53
   Break conditions can have side effects, and may even call functions
54
in your program.  This can be useful, for example, to activate functions
55
that log program progress, or to use your own print functions to format
56
special data structures. The effects are completely predictable unless
57
there is another enabled breakpoint at the same address.  (In that
58
case, GDB might see the other breakpoint first and stop your program
59
without checking the condition of this one.)  Note that breakpoint
60
commands are usually more convenient and flexible than break conditions
61
for the purpose of performing side effects when a breakpoint is reached
62
(*note Breakpoint command lists: Break Commands.).
63
 
64
   Break conditions can be specified when a breakpoint is set, by using
65
`if' in the arguments to the `break' command.  *Note Setting
66
breakpoints: Set Breaks.  They can also be changed at any time with the
67
`condition' command.
68
 
69
   You can also use the `if' keyword with the `watch' command.  The
70
`catch' command does not recognize the `if' keyword; `condition' is the
71
only way to impose a further condition on a catchpoint.
72
 
73
`condition BNUM EXPRESSION'
74
     Specify EXPRESSION as the break condition for breakpoint,
75
     watchpoint, or catchpoint number BNUM.  After you set a condition,
76
     breakpoint BNUM stops your program only if the value of EXPRESSION
77
     is true (nonzero, in C).  When you use `condition', GDB checks
78
     EXPRESSION immediately for syntactic correctness, and to determine
79
     whether symbols in it have referents in the context of your
80
     breakpoint.  If EXPRESSION uses symbols not referenced in the
81
     context of the breakpoint, GDB prints an error message:
82
 
83
          No symbol "foo" in current context.
84
 
85
     GDB does not actually evaluate EXPRESSION at the time the
86
     `condition' command (or a command that sets a breakpoint with a
87
     condition, like `break if ...') is given, however.  *Note
88
     Expressions: Expressions.
89
 
90
`condition BNUM'
91
     Remove the condition from breakpoint number BNUM.  It becomes an
92
     ordinary unconditional breakpoint.
93
 
94
   A special case of a breakpoint condition is to stop only when the
95
breakpoint has been reached a certain number of times.  This is so
96
useful that there is a special way to do it, using the "ignore count"
97
of the breakpoint.  Every breakpoint has an ignore count, which is an
98
integer.  Most of the time, the ignore count is zero, and therefore has
99
no effect.  But if your program reaches a breakpoint whose ignore count
100
is positive, then instead of stopping, it just decrements the ignore
101
count by one and continues.  As a result, if the ignore count value is
102
N, the breakpoint does not stop the next N times your program reaches
103
it.
104
 
105
`ignore BNUM COUNT'
106
     Set the ignore count of breakpoint number BNUM to COUNT.  The next
107
     COUNT times the breakpoint is reached, your program's execution
108
     does not stop; other than to decrement the ignore count, GDB takes
109
     no action.
110
 
111
     To make the breakpoint stop the next time it is reached, specify a
112
     count of zero.
113
 
114
     When you use `continue' to resume execution of your program from a
115
     breakpoint, you can specify an ignore count directly as an
116
     argument to `continue', rather than using `ignore'.  *Note
117
     Continuing and stepping: Continuing and Stepping.
118
 
119
     If a breakpoint has a positive ignore count and a condition, the
120
     condition is not checked.  Once the ignore count reaches zero, GDB
121
     resumes checking the condition.
122
 
123
     You could achieve the effect of the ignore count with a condition
124
     such as `$foo-- <= 0' using a debugger convenience variable that
125
     is decremented each time.  *Note Convenience variables:
126
     Convenience Vars.
127
 
128
   Ignore counts apply to breakpoints, watchpoints, and catchpoints.
129
 
130

131
File: gdb.info,  Node: Break Commands,  Next: Breakpoint Menus,  Prev: Conditions,  Up: Breakpoints
132
 
133
Breakpoint command lists
134
------------------------
135
 
136
   You can give any breakpoint (or watchpoint or catchpoint) a series of
137
commands to execute when your program stops due to that breakpoint.  For
138
example, you might want to print the values of certain expressions, or
139
enable other breakpoints.
140
 
141
`commands [BNUM]'
142
`... COMMAND-LIST ...'
143
`end'
144
     Specify a list of commands for breakpoint number BNUM.  The
145
     commands themselves appear on the following lines.  Type a line
146
     containing just `end' to terminate the commands.
147
 
148
     To remove all commands from a breakpoint, type `commands' and
149
     follow it immediately with `end'; that is, give no commands.
150
 
151
     With no BNUM argument, `commands' refers to the last breakpoint,
152
     watchpoint, or catchpoint set (not to the breakpoint most recently
153
     encountered).
154
 
155
   Pressing  as a means of repeating the last GDB command is
156
disabled within a COMMAND-LIST.
157
 
158
   You can use breakpoint commands to start your program up again.
159
Simply use the `continue' command, or `step', or any other command that
160
resumes execution.
161
 
162
   Any other commands in the command list, after a command that resumes
163
execution, are ignored.  This is because any time you resume execution
164
(even with a simple `next' or `step'), you may encounter another
165
breakpoint--which could have its own command list, leading to
166
ambiguities about which list to execute.
167
 
168
   If the first command you specify in a command list is `silent', the
169
usual message about stopping at a breakpoint is not printed.  This may
170
be desirable for breakpoints that are to print a specific message and
171
then continue.  If none of the remaining commands print anything, you
172
see no sign that the breakpoint was reached.  `silent' is meaningful
173
only at the beginning of a breakpoint command list.
174
 
175
   The commands `echo', `output', and `printf' allow you to print
176
precisely controlled output, and are often useful in silent
177
breakpoints.  *Note Commands for controlled output: Output.
178
 
179
   For example, here is how you could use breakpoint commands to print
180
the value of `x' at entry to `foo' whenever `x' is positive.
181
 
182
     break foo if x>0
183
     commands
184
     silent
185
     printf "x is %d\n",x
186
     cont
187
     end
188
 
189
   One application for breakpoint commands is to compensate for one bug
190
so you can test for another.  Put a breakpoint just after the erroneous
191
line of code, give it a condition to detect the case in which something
192
erroneous has been done, and give it commands to assign correct values
193
to any variables that need them.  End with the `continue' command so
194
that your program does not stop, and start with the `silent' command so
195
that no output is produced.  Here is an example:
196
 
197
     break 403
198
     commands
199
     silent
200
     set x = y + 4
201
     cont
202
     end
203
 
204

205
File: gdb.info,  Node: Breakpoint Menus,  Next: Error in Breakpoints,  Prev: Break Commands,  Up: Breakpoints
206
 
207
Breakpoint menus
208
----------------
209
 
210
   Some programming languages (notably C++) permit a single function
211
name to be defined several times, for application in different contexts.
212
This is called "overloading".  When a function name is overloaded,
213
`break FUNCTION' is not enough to tell GDB where you want a breakpoint.
214
If you realize this is a problem, you can use something like `break
215
FUNCTION(TYPES)' to specify which particular version of the function
216
you want.  Otherwise, GDB offers you a menu of numbered choices for
217
different possible breakpoints, and waits for your selection with the
218
prompt `>'.  The first two options are always `[0] cancel' and `[1]
219
all'.  Typing `1' sets a breakpoint at each definition of FUNCTION, and
220
typing `0' aborts the `break' command without setting any new
221
breakpoints.
222
 
223
   For example, the following session excerpt shows an attempt to set a
224
breakpoint at the overloaded symbol `String::after'.  We choose three
225
particular definitions of that function name:
226
 
227
     (gdb) b String::after
228
     [0] cancel
229
     [1] all
230
     [2] file:String.cc; line number:867
231
     [3] file:String.cc; line number:860
232
     [4] file:String.cc; line number:875
233
     [5] file:String.cc; line number:853
234
     [6] file:String.cc; line number:846
235
     [7] file:String.cc; line number:735
236
     > 2 4 6
237
     Breakpoint 1 at 0xb26c: file String.cc, line 867.
238
     Breakpoint 2 at 0xb344: file String.cc, line 875.
239
     Breakpoint 3 at 0xafcc: file String.cc, line 846.
240
     Multiple breakpoints were set.
241
     Use the "delete" command to delete unwanted
242
      breakpoints.
243
     (gdb)
244
 
245

246
File: gdb.info,  Node: Error in Breakpoints,  Prev: Breakpoint Menus,  Up: Breakpoints
247
 
248
"Cannot insert breakpoints"
249
---------------------------
250
 
251
   Under some operating systems, breakpoints cannot be used in a
252
program if any other process is running that program.  In this
253
situation, attempting to run or continue a program with a breakpoint
254
causes GDB to print an error message:
255
 
256
     Cannot insert breakpoints.
257
     The same program may be running in another process.
258
 
259
   When this happens, you have three ways to proceed:
260
 
261
  1. Remove or disable the breakpoints, then continue.
262
 
263
  2. Suspend GDB, and copy the file containing your program to a new
264
     name.  Resume GDB and use the `exec-file' command to specify that
265
     GDB should run your program under that name.  Then start your
266
     program again.
267
 
268
  3. Relink your program so that the text segment is nonsharable, using
269
     the linker option `-N'.  The operating system limitation may not
270
     apply to nonsharable executables.
271
 
272
   A similar message can be printed if you request too many active
273
hardware-assisted breakpoints and watchpoints:
274
 
275
     Stopped; cannot insert breakpoints.
276
     You may have requested too many hardware breakpoints and watchpoints.
277
 
278
This message is printed when you attempt to resume the program, since
279
only then GDB knows exactly how many hardware breakpoints and
280
watchpoints it needs to insert.
281
 
282
   When this message is printed, you need to disable or remove some of
283
the hardware-assisted breakpoints and watchpoints, and then continue.
284
 
285

286
File: gdb.info,  Node: Continuing and Stepping,  Next: Signals,  Prev: Breakpoints,  Up: Stopping
287
 
288
Continuing and stepping
289
=======================
290
 
291
   "Continuing" means resuming program execution until your program
292
completes normally.  In contrast, "stepping" means executing just one
293
more "step" of your program, where "step" may mean either one line of
294
source code, or one machine instruction (depending on what particular
295
command you use).  Either when continuing or when stepping, your
296
program may stop even sooner, due to a breakpoint or a signal.  (If it
297
stops due to a signal, you may want to use `handle', or use `signal 0'
298
to resume execution.  *Note Signals: Signals.)
299
 
300
`continue [IGNORE-COUNT]'
301
`c [IGNORE-COUNT]'
302
`fg [IGNORE-COUNT]'
303
     Resume program execution, at the address where your program last
304
     stopped; any breakpoints set at that address are bypassed.  The
305
     optional argument IGNORE-COUNT allows you to specify a further
306
     number of times to ignore a breakpoint at this location; its
307
     effect is like that of `ignore' (*note Break conditions:
308
     Conditions.).
309
 
310
     The argument IGNORE-COUNT is meaningful only when your program
311
     stopped due to a breakpoint.  At other times, the argument to
312
     `continue' is ignored.
313
 
314
     The synonyms `c' and `fg' (for "foreground", as the debugged
315
     program is deemed to be the foreground program) are provided
316
     purely for convenience, and have exactly the same behavior as
317
     `continue'.
318
 
319
   To resume execution at a different place, you can use `return'
320
(*note Returning from a function: Returning.) to go back to the calling
321
function; or `jump' (*note Continuing at a different address: Jumping.)
322
to go to an arbitrary location in your program.
323
 
324
   A typical technique for using stepping is to set a breakpoint (*note
325
Breakpoints; watchpoints; and catchpoints: Breakpoints.) at the
326
beginning of the function or the section of your program where a problem
327
is believed to lie, run your program until it stops at that breakpoint,
328
and then step through the suspect area, examining the variables that are
329
interesting, until you see the problem happen.
330
 
331
`step'
332
     Continue running your program until control reaches a different
333
     source line, then stop it and return control to GDB.  This command
334
     is abbreviated `s'.
335
 
336
          _Warning:_ If you use the `step' command while control is
337
          within a function that was compiled without debugging
338
          information, execution proceeds until control reaches a
339
          function that does have debugging information.  Likewise, it
340
          will not step into a function which is compiled without
341
          debugging information.  To step through functions without
342
          debugging information, use the `stepi' command, described
343
          below.
344
 
345
     The `step' command only stops at the first instruction of a source
346
     line.  This prevents the multiple stops that could otherwise occur
347
     in `switch' statements, `for' loops, etc.  `step' continues to
348
     stop if a function that has debugging information is called within
349
     the line.  In other words, `step' _steps inside_ any functions
350
     called within the line.
351
 
352
     Also, the `step' command only enters a function if there is line
353
     number information for the function.  Otherwise it acts like the
354
     `next' command.  This avoids problems when using `cc -gl' on MIPS
355
     machines.  Previously, `step' entered subroutines if there was any
356
     debugging information about the routine.
357
 
358
`step COUNT'
359
     Continue running as in `step', but do so COUNT times.  If a
360
     breakpoint is reached, or a signal not related to stepping occurs
361
     before COUNT steps, stepping stops right away.
362
 
363
`next [COUNT]'
364
     Continue to the next source line in the current (innermost) stack
365
     frame.  This is similar to `step', but function calls that appear
366
     within the line of code are executed without stopping.  Execution
367
     stops when control reaches a different line of code at the
368
     original stack level that was executing when you gave the `next'
369
     command.  This command is abbreviated `n'.
370
 
371
     An argument COUNT is a repeat count, as for `step'.
372
 
373
     The `next' command only stops at the first instruction of a source
374
     line.  This prevents multiple stops that could otherwise occur in
375
     `switch' statements, `for' loops, etc.
376
 
377
`set step-mode'
378
`set step-mode on'
379
     The `set step-mode on' command causes the `step' command to stop
380
     at the first instruction of a function which contains no debug line
381
     information rather than stepping over it.
382
 
383
     This is useful in cases where you may be interested in inspecting
384
     the machine instructions of a function which has no symbolic info
385
     and do not want GDB to automatically skip over this function.
386
 
387
`set step-mode off'
388
     Causes the `step' command to step over any functions which
389
     contains no debug information.  This is the default.
390
 
391
`finish'
392
     Continue running until just after function in the selected stack
393
     frame returns.  Print the returned value (if any).
394
 
395
     Contrast this with the `return' command (*note Returning from a
396
     function: Returning.).
397
 
398
`until'
399
`u'
400
     Continue running until a source line past the current line, in the
401
     current stack frame, is reached.  This command is used to avoid
402
     single stepping through a loop more than once.  It is like the
403
     `next' command, except that when `until' encounters a jump, it
404
     automatically continues execution until the program counter is
405
     greater than the address of the jump.
406
 
407
     This means that when you reach the end of a loop after single
408
     stepping though it, `until' makes your program continue execution
409
     until it exits the loop.  In contrast, a `next' command at the end
410
     of a loop simply steps back to the beginning of the loop, which
411
     forces you to step through the next iteration.
412
 
413
     `until' always stops your program if it attempts to exit the
414
     current stack frame.
415
 
416
     `until' may produce somewhat counterintuitive results if the order
417
     of machine code does not match the order of the source lines.  For
418
     example, in the following excerpt from a debugging session, the `f'
419
     (`frame') command shows that execution is stopped at line `206';
420
     yet when we use `until', we get to line `195':
421
 
422
          (gdb) f
423
          #0  main (argc=4, argv=0xf7fffae8) at m4.c:206
424
          206                 expand_input();
425
          (gdb) until
426
          195             for ( ; argc > 0; NEXTARG) {
427
 
428
     This happened because, for execution efficiency, the compiler had
429
     generated code for the loop closure test at the end, rather than
430
     the start, of the loop--even though the test in a C `for'-loop is
431
     written before the body of the loop.  The `until' command appeared
432
     to step back to the beginning of the loop when it advanced to this
433
     expression; however, it has not really gone to an earlier
434
     statement--not in terms of the actual machine code.
435
 
436
     `until' with no argument works by means of single instruction
437
     stepping, and hence is slower than `until' with an argument.
438
 
439
`until LOCATION'
440
`u LOCATION'
441
     Continue running your program until either the specified location
442
     is reached, or the current stack frame returns.  LOCATION is any of
443
     the forms of argument acceptable to `break' (*note Setting
444
     breakpoints: Set Breaks.).  This form of the command uses
445
     breakpoints, and hence is quicker than `until' without an argument.
446
 
447
`stepi'
448
`stepi ARG'
449
`si'
450
     Execute one machine instruction, then stop and return to the
451
     debugger.
452
 
453
     It is often useful to do `display/i $pc' when stepping by machine
454
     instructions.  This makes GDB automatically display the next
455
     instruction to be executed, each time your program stops.  *Note
456
     Automatic display: Auto Display.
457
 
458
     An argument is a repeat count, as in `step'.
459
 
460
`nexti'
461
`nexti ARG'
462
`ni'
463
     Execute one machine instruction, but if it is a function call,
464
     proceed until the function returns.
465
 
466
     An argument is a repeat count, as in `next'.
467
 
468

469
File: gdb.info,  Node: Signals,  Next: Thread Stops,  Prev: Continuing and Stepping,  Up: Stopping
470
 
471
Signals
472
=======
473
 
474
   A signal is an asynchronous event that can happen in a program.  The
475
operating system defines the possible kinds of signals, and gives each
476
kind a name and a number.  For example, in Unix `SIGINT' is the signal
477
a program gets when you type an interrupt character (often `C-c');
478
`SIGSEGV' is the signal a program gets from referencing a place in
479
memory far away from all the areas in use; `SIGALRM' occurs when the
480
alarm clock timer goes off (which happens only if your program has
481
requested an alarm).
482
 
483
   Some signals, including `SIGALRM', are a normal part of the
484
functioning of your program.  Others, such as `SIGSEGV', indicate
485
errors; these signals are "fatal" (they kill your program immediately)
486
if the program has not specified in advance some other way to handle
487
the signal.  `SIGINT' does not indicate an error in your program, but
488
it is normally fatal so it can carry out the purpose of the interrupt:
489
to kill the program.
490
 
491
   GDB has the ability to detect any occurrence of a signal in your
492
program.  You can tell GDB in advance what to do for each kind of
493
signal.
494
 
495
   Normally, GDB is set up to let the non-erroneous signals like
496
`SIGALRM' be silently passed to your program (so as not to interfere
497
with their role in the program's functioning) but to stop your program
498
immediately whenever an error signal happens.  You can change these
499
settings with the `handle' command.
500
 
501
`info signals'
502
`info handle'
503
     Print a table of all the kinds of signals and how GDB has been
504
     told to handle each one.  You can use this to see the signal
505
     numbers of all the defined types of signals.
506
 
507
     `info handle' is an alias for `info signals'.
508
 
509
`handle SIGNAL KEYWORDS...'
510
     Change the way GDB handles signal SIGNAL.  SIGNAL can be the
511
     number of a signal or its name (with or without the `SIG' at the
512
     beginning); a list of signal numbers of the form `LOW-HIGH'; or
513
     the word `all', meaning all the known signals.  The KEYWORDS say
514
     what change to make.
515
 
516
   The keywords allowed by the `handle' command can be abbreviated.
517
Their full names are:
518
 
519
`nostop'
520
     GDB should not stop your program when this signal happens.  It may
521
     still print a message telling you that the signal has come in.
522
 
523
`stop'
524
     GDB should stop your program when this signal happens.  This
525
     implies the `print' keyword as well.
526
 
527
`print'
528
     GDB should print a message when this signal happens.
529
 
530
`noprint'
531
     GDB should not mention the occurrence of the signal at all.  This
532
     implies the `nostop' keyword as well.
533
 
534
`pass'
535
`noignore'
536
     GDB should allow your program to see this signal; your program can
537
     handle the signal, or else it may terminate if the signal is fatal
538
     and not handled.  `pass' and `noignore' are synonyms.
539
 
540
`nopass'
541
`ignore'
542
     GDB should not allow your program to see this signal.  `nopass'
543
     and `ignore' are synonyms.
544
 
545
   When a signal stops your program, the signal is not visible to the
546
program until you continue.  Your program sees the signal then, if
547
`pass' is in effect for the signal in question _at that time_.  In
548
other words, after GDB reports a signal, you can use the `handle'
549
command with `pass' or `nopass' to control whether your program sees
550
that signal when you continue.
551
 
552
   The default is set to `nostop', `noprint', `pass' for non-erroneous
553
signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop',
554
`print', `pass' for the erroneous signals.
555
 
556
   You can also use the `signal' command to prevent your program from
557
seeing a signal, or cause it to see a signal it normally would not see,
558
or to give it any signal at any time.  For example, if your program
559
stopped due to some sort of memory reference error, you might store
560
correct values into the erroneous variables and continue, hoping to see
561
more execution; but your program would probably terminate immediately as
562
a result of the fatal signal once it saw the signal.  To prevent this,
563
you can continue with `signal 0'.  *Note Giving your program a signal:
564
Signaling.
565
 
566

567
File: gdb.info,  Node: Thread Stops,  Prev: Signals,  Up: Stopping
568
 
569
Stopping and starting multi-thread programs
570
===========================================
571
 
572
   When your program has multiple threads (*note Debugging programs
573
with multiple threads: Threads.), you can choose whether to set
574
breakpoints on all threads, or on a particular thread.
575
 
576
`break LINESPEC thread THREADNO'
577
`break LINESPEC thread THREADNO if ...'
578
     LINESPEC specifies source lines; there are several ways of writing
579
     them, but the effect is always to specify some source line.
580
 
581
     Use the qualifier `thread THREADNO' with a breakpoint command to
582
     specify that you only want GDB to stop the program when a
583
     particular thread reaches this breakpoint.  THREADNO is one of the
584
     numeric thread identifiers assigned by GDB, shown in the first
585
     column of the `info threads' display.
586
 
587
     If you do not specify `thread THREADNO' when you set a breakpoint,
588
     the breakpoint applies to _all_ threads of your program.
589
 
590
     You can use the `thread' qualifier on conditional breakpoints as
591
     well; in this case, place `thread THREADNO' before the breakpoint
592
     condition, like this:
593
 
594
          (gdb) break frik.c:13 thread 28 if bartab > lim
595
 
596
   Whenever your program stops under GDB for any reason, _all_ threads
597
of execution stop, not just the current thread.  This allows you to
598
examine the overall state of the program, including switching between
599
threads, without worrying that things may change underfoot.
600
 
601
   Conversely, whenever you restart the program, _all_ threads start
602
executing.  _This is true even when single-stepping_ with commands like
603
`step' or `next'.
604
 
605
   In particular, GDB cannot single-step all threads in lockstep.
606
Since thread scheduling is up to your debugging target's operating
607
system (not controlled by GDB), other threads may execute more than one
608
statement while the current thread completes a single step.  Moreover,
609
in general other threads stop in the middle of a statement, rather than
610
at a clean statement boundary, when the program stops.
611
 
612
   You might even find your program stopped in another thread after
613
continuing or even single-stepping.  This happens whenever some other
614
thread runs into a breakpoint, a signal, or an exception before the
615
first thread completes whatever you requested.
616
 
617
   On some OSes, you can lock the OS scheduler and thus allow only a
618
single thread to run.
619
 
620
`set scheduler-locking MODE'
621
     Set the scheduler locking mode.  If it is `off', then there is no
622
     locking and any thread may run at any time.  If `on', then only the
623
     current thread may run when the inferior is resumed.  The `step'
624
     mode optimizes for single-stepping.  It stops other threads from
625
     "seizing the prompt" by preempting the current thread while you are
626
     stepping.  Other threads will only rarely (or never) get a chance
627
     to run when you step.  They are more likely to run when you `next'
628
     over a function call, and they are completely free to run when you
629
     use commands like `continue', `until', or `finish'.  However,
630
     unless another thread hits a breakpoint during its timeslice, they
631
     will never steal the GDB prompt away from the thread that you are
632
     debugging.
633
 
634
`show scheduler-locking'
635
     Display the current scheduler locking mode.
636
 
637

638
File: gdb.info,  Node: Stack,  Next: Source,  Prev: Stopping,  Up: Top
639
 
640
Examining the Stack
641
*******************
642
 
643
   When your program has stopped, the first thing you need to know is
644
where it stopped and how it got there.
645
 
646
   Each time your program performs a function call, information about
647
the call is generated.  That information includes the location of the
648
call in your program, the arguments of the call, and the local
649
variables of the function being called.  The information is saved in a
650
block of data called a "stack frame".  The stack frames are allocated
651
in a region of memory called the "call stack".
652
 
653
   When your program stops, the GDB commands for examining the stack
654
allow you to see all of this information.
655
 
656
   One of the stack frames is "selected" by GDB and many GDB commands
657
refer implicitly to the selected frame.  In particular, whenever you
658
ask GDB for the value of a variable in your program, the value is found
659
in the selected frame.  There are special GDB commands to select
660
whichever frame you are interested in. *Note Selecting a frame:
661
Selection.
662
 
663
   When your program stops, GDB automatically selects the currently
664
executing frame and describes it briefly, similar to the `frame'
665
command (*note Information about a frame: Frame Info.).
666
 
667
* Menu:
668
 
669
* Frames::                      Stack frames
670
* Backtrace::                   Backtraces
671
* Selection::                   Selecting a frame
672
* Frame Info::                  Information on a frame
673
 
674

675
File: gdb.info,  Node: Frames,  Next: Backtrace,  Up: Stack
676
 
677
Stack frames
678
============
679
 
680
   The call stack is divided up into contiguous pieces called "stack
681
frames", or "frames" for short; each frame is the data associated with
682
one call to one function.  The frame contains the arguments given to
683
the function, the function's local variables, and the address at which
684
the function is executing.
685
 
686
   When your program is started, the stack has only one frame, that of
687
the function `main'.  This is called the "initial" frame or the
688
"outermost" frame.  Each time a function is called, a new frame is
689
made.  Each time a function returns, the frame for that function
690
invocation is eliminated.  If a function is recursive, there can be
691
many frames for the same function.  The frame for the function in which
692
execution is actually occurring is called the "innermost" frame.  This
693
is the most recently created of all the stack frames that still exist.
694
 
695
   Inside your program, stack frames are identified by their addresses.
696
A stack frame consists of many bytes, each of which has its own
697
address; each kind of computer has a convention for choosing one byte
698
whose address serves as the address of the frame.  Usually this address
699
is kept in a register called the "frame pointer register" while
700
execution is going on in that frame.
701
 
702
   GDB assigns numbers to all existing stack frames, starting with zero
703
for the innermost frame, one for the frame that called it, and so on
704
upward.  These numbers do not really exist in your program; they are
705
assigned by GDB to give you a way of designating stack frames in GDB
706
commands.
707
 
708
   Some compilers provide a way to compile functions so that they
709
operate without stack frames.  (For example, the gcc option
710
     `-fomit-frame-pointer'
711
   generates functions without a frame.)  This is occasionally done
712
with heavily used library functions to save the frame setup time.  GDB
713
has limited facilities for dealing with these function invocations.  If
714
the innermost function invocation has no stack frame, GDB nevertheless
715
regards it as though it had a separate frame, which is numbered zero as
716
usual, allowing correct tracing of the function call chain.  However,
717
GDB has no provision for frameless functions elsewhere in the stack.
718
 
719
`frame ARGS'
720
     The `frame' command allows you to move from one stack frame to
721
     another, and to print the stack frame you select.  ARGS may be
722
     either the address of the frame or the stack frame number.
723
     Without an argument, `frame' prints the current stack frame.
724
 
725
`select-frame'
726
     The `select-frame' command allows you to move from one stack frame
727
     to another without printing the frame.  This is the silent version
728
     of `frame'.
729
 
730

731
File: gdb.info,  Node: Backtrace,  Next: Selection,  Prev: Frames,  Up: Stack
732
 
733
Backtraces
734
==========
735
 
736
   A backtrace is a summary of how your program got where it is.  It
737
shows one line per frame, for many frames, starting with the currently
738
executing frame (frame zero), followed by its caller (frame one), and
739
on up the stack.
740
 
741
`backtrace'
742
`bt'
743
     Print a backtrace of the entire stack: one line per frame for all
744
     frames in the stack.
745
 
746
     You can stop the backtrace at any time by typing the system
747
     interrupt character, normally `C-c'.
748
 
749
`backtrace N'
750
`bt N'
751
     Similar, but print only the innermost N frames.
752
 
753
`backtrace -N'
754
`bt -N'
755
     Similar, but print only the outermost N frames.
756
 
757
   The names `where' and `info stack' (abbreviated `info s') are
758
additional aliases for `backtrace'.
759
 
760
   Each line in the backtrace shows the frame number and the function
761
name.  The program counter value is also shown--unless you use `set
762
print address off'.  The backtrace also shows the source file name and
763
line number, as well as the arguments to the function.  The program
764
counter value is omitted if it is at the beginning of the code for that
765
line number.
766
 
767
   Here is an example of a backtrace.  It was made with the command `bt
768
3', so it shows the innermost three frames.
769
 
770
     #0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
771
         at builtin.c:993
772
     #1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
773
     #2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
774
         at macro.c:71
775
     (More stack frames follow...)
776
 
777
The display for frame zero does not begin with a program counter value,
778
indicating that your program has stopped at the beginning of the code
779
for line `993' of `builtin.c'.
780
 
781

782
File: gdb.info,  Node: Selection,  Next: Frame Info,  Prev: Backtrace,  Up: Stack
783
 
784
Selecting a frame
785
=================
786
 
787
   Most commands for examining the stack and other data in your program
788
work on whichever stack frame is selected at the moment.  Here are the
789
commands for selecting a stack frame; all of them finish by printing a
790
brief description of the stack frame just selected.
791
 
792
`frame N'
793
`f N'
794
     Select frame number N.  Recall that frame zero is the innermost
795
     (currently executing) frame, frame one is the frame that called the
796
     innermost one, and so on.  The highest-numbered frame is the one
797
     for `main'.
798
 
799
`frame ADDR'
800
`f ADDR'
801
     Select the frame at address ADDR.  This is useful mainly if the
802
     chaining of stack frames has been damaged by a bug, making it
803
     impossible for GDB to assign numbers properly to all frames.  In
804
     addition, this can be useful when your program has multiple stacks
805
     and switches between them.
806
 
807
     On the SPARC architecture, `frame' needs two addresses to select
808
     an arbitrary frame: a frame pointer and a stack pointer.
809
 
810
     On the MIPS and Alpha architecture, it needs two addresses: a stack
811
     pointer and a program counter.
812
 
813
     On the 29k architecture, it needs three addresses: a register stack
814
     pointer, a program counter, and a memory stack pointer.
815
 
816
`up N'
817
     Move N frames up the stack.  For positive numbers N, this advances
818
     toward the outermost frame, to higher frame numbers, to frames
819
     that have existed longer.  N defaults to one.
820
 
821
`down N'
822
     Move N frames down the stack.  For positive numbers N, this
823
     advances toward the innermost frame, to lower frame numbers, to
824
     frames that were created more recently.  N defaults to one.  You
825
     may abbreviate `down' as `do'.
826
 
827
   All of these commands end by printing two lines of output describing
828
the frame.  The first line shows the frame number, the function name,
829
the arguments, and the source file and line number of execution in that
830
frame.  The second line shows the text of that source line.
831
 
832
   For example:
833
 
834
     (gdb) up
835
     #1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
836
         at env.c:10
837
     10              read_input_file (argv[i]);
838
 
839
   After such a printout, the `list' command with no arguments prints
840
ten lines centered on the point of execution in the frame.  *Note
841
Printing source lines: List.
842
 
843
`up-silently N'
844
`down-silently N'
845
     These two commands are variants of `up' and `down', respectively;
846
     they differ in that they do their work silently, without causing
847
     display of the new frame.  They are intended primarily for use in
848
     GDB command scripts, where the output might be unnecessary and
849
     distracting.
850
 
851

852
File: gdb.info,  Node: Frame Info,  Prev: Selection,  Up: Stack
853
 
854
Information about a frame
855
=========================
856
 
857
   There are several other commands to print information about the
858
selected stack frame.
859
 
860
`frame'
861
`f'
862
     When used without any argument, this command does not change which
863
     frame is selected, but prints a brief description of the currently
864
     selected stack frame.  It can be abbreviated `f'.  With an
865
     argument, this command is used to select a stack frame.  *Note
866
     Selecting a frame: Selection.
867
 
868
`info frame'
869
`info f'
870
     This command prints a verbose description of the selected stack
871
     frame, including:
872
 
873
        * the address of the frame
874
 
875
        * the address of the next frame down (called by this frame)
876
 
877
        * the address of the next frame up (caller of this frame)
878
 
879
        * the language in which the source code corresponding to this
880
          frame is written
881
 
882
        * the address of the frame's arguments
883
 
884
        * the address of the frame's local variables
885
 
886
        * the program counter saved in it (the address of execution in
887
          the caller frame)
888
 
889
        * which registers were saved in the frame
890
 
891
     The verbose description is useful when something has gone wrong
892
     that has made the stack format fail to fit the usual conventions.
893
 
894
`info frame ADDR'
895
`info f ADDR'
896
     Print a verbose description of the frame at address ADDR, without
897
     selecting that frame.  The selected frame remains unchanged by this
898
     command.  This requires the same kind of address (more than one
899
     for some architectures) that you specify in the `frame' command.
900
     *Note Selecting a frame: Selection.
901
 
902
`info args'
903
     Print the arguments of the selected frame, each on a separate line.
904
 
905
`info locals'
906
     Print the local variables of the selected frame, each on a separate
907
     line.  These are all variables (declared either static or
908
     automatic) accessible at the point of execution of the selected
909
     frame.
910
 
911
`info catch'
912
     Print a list of all the exception handlers that are active in the
913
     current stack frame at the current point of execution.  To see
914
     other exception handlers, visit the associated frame (using the
915
     `up', `down', or `frame' commands); then type `info catch'.  *Note
916
     Setting catchpoints: Set Catchpoints.
917
 
918

919
File: gdb.info,  Node: Source,  Next: Data,  Prev: Stack,  Up: Top
920
 
921
Examining Source Files
922
**********************
923
 
924
   GDB can print parts of your program's source, since the debugging
925
information recorded in the program tells GDB what source files were
926
used to build it.  When your program stops, GDB spontaneously prints
927
the line where it stopped.  Likewise, when you select a stack frame
928
(*note Selecting a frame: Selection.), GDB prints the line where
929
execution in that frame has stopped.  You can print other portions of
930
source files by explicit command.
931
 
932
   If you use GDB through its GNU Emacs interface, you may prefer to
933
use Emacs facilities to view source; see *Note Using GDB under GNU
934
Emacs: Emacs.
935
 
936
* Menu:
937
 
938
* List::                        Printing source lines
939
* Search::                      Searching source files
940
* Source Path::                 Specifying source directories
941
* Machine Code::                Source and machine code
942
 
943

944
File: gdb.info,  Node: List,  Next: Search,  Up: Source
945
 
946
Printing source lines
947
=====================
948
 
949
   To print lines from a source file, use the `list' command
950
(abbreviated `l').  By default, ten lines are printed.  There are
951
several ways to specify what part of the file you want to print.
952
 
953
   Here are the forms of the `list' command most commonly used:
954
 
955
`list LINENUM'
956
     Print lines centered around line number LINENUM in the current
957
     source file.
958
 
959
`list FUNCTION'
960
     Print lines centered around the beginning of function FUNCTION.
961
 
962
`list'
963
     Print more lines.  If the last lines printed were printed with a
964
     `list' command, this prints lines following the last lines
965
     printed; however, if the last line printed was a solitary line
966
     printed as part of displaying a stack frame (*note Examining the
967
     Stack: Stack.), this prints lines centered around that line.
968
 
969
`list -'
970
     Print lines just before the lines last printed.
971
 
972
   By default, GDB prints ten source lines with any of these forms of
973
the `list' command.  You can change this using `set listsize':
974
 
975
`set listsize COUNT'
976
     Make the `list' command display COUNT source lines (unless the
977
     `list' argument explicitly specifies some other number).
978
 
979
`show listsize'
980
     Display the number of lines that `list' prints.
981
 
982
   Repeating a `list' command with  discards the argument, so it
983
is equivalent to typing just `list'.  This is more useful than listing
984
the same lines again.  An exception is made for an argument of `-';
985
that argument is preserved in repetition so that each repetition moves
986
up in the source file.
987
 
988
   In general, the `list' command expects you to supply zero, one or two
989
"linespecs".  Linespecs specify source lines; there are several ways of
990
writing them, but the effect is always to specify some source line.
991
Here is a complete description of the possible arguments for `list':
992
 
993
`list LINESPEC'
994
     Print lines centered around the line specified by LINESPEC.
995
 
996
`list FIRST,LAST'
997
     Print lines from FIRST to LAST.  Both arguments are linespecs.
998
 
999
`list ,LAST'
1000
     Print lines ending with LAST.
1001
 
1002
`list FIRST,'
1003
     Print lines starting with FIRST.
1004
 
1005
`list +'
1006
     Print lines just after the lines last printed.
1007
 
1008
`list -'
1009
     Print lines just before the lines last printed.
1010
 
1011
`list'
1012
     As described in the preceding table.
1013
 
1014
   Here are the ways of specifying a single source line--all the kinds
1015
of linespec.
1016
 
1017
`NUMBER'
1018
     Specifies line NUMBER of the current source file.  When a `list'
1019
     command has two linespecs, this refers to the same source file as
1020
     the first linespec.
1021
 
1022
`+OFFSET'
1023
     Specifies the line OFFSET lines after the last line printed.  When
1024
     used as the second linespec in a `list' command that has two, this
1025
     specifies the line OFFSET lines down from the first linespec.
1026
 
1027
`-OFFSET'
1028
     Specifies the line OFFSET lines before the last line printed.
1029
 
1030
`FILENAME:NUMBER'
1031
     Specifies line NUMBER in the source file FILENAME.
1032
 
1033
`FUNCTION'
1034
     Specifies the line that begins the body of the function FUNCTION.
1035
     For example: in C, this is the line with the open brace.
1036
 
1037
`FILENAME:FUNCTION'
1038
     Specifies the line of the open-brace that begins the body of the
1039
     function FUNCTION in the file FILENAME.  You only need the file
1040
     name with a function name to avoid ambiguity when there are
1041
     identically named functions in different source files.
1042
 
1043
`*ADDRESS'
1044
     Specifies the line containing the program address ADDRESS.
1045
     ADDRESS may be any expression.
1046
 
1047

1048
File: gdb.info,  Node: Search,  Next: Source Path,  Prev: List,  Up: Source
1049
 
1050
Searching source files
1051
======================
1052
 
1053
   There are two commands for searching through the current source file
1054
for a regular expression.
1055
 
1056
`forward-search REGEXP'
1057
`search REGEXP'
1058
     The command `forward-search REGEXP' checks each line, starting
1059
     with the one following the last line listed, for a match for
1060
     REGEXP.  It lists the line that is found.  You can use the synonym
1061
     `search REGEXP' or abbreviate the command name as `fo'.
1062
 
1063
`reverse-search REGEXP'
1064
     The command `reverse-search REGEXP' checks each line, starting
1065
     with the one before the last line listed and going backward, for a
1066
     match for REGEXP.  It lists the line that is found.  You can
1067
     abbreviate this command as `rev'.
1068
 
1069

1070
File: gdb.info,  Node: Source Path,  Next: Machine Code,  Prev: Search,  Up: Source
1071
 
1072
Specifying source directories
1073
=============================
1074
 
1075
   Executable programs sometimes do not record the directories of the
1076
source files from which they were compiled, just the names.  Even when
1077
they do, the directories could be moved between the compilation and
1078
your debugging session.  GDB has a list of directories to search for
1079
source files; this is called the "source path".  Each time GDB wants a
1080
source file, it tries all the directories in the list, in the order
1081
they are present in the list, until it finds a file with the desired
1082
name.  Note that the executable search path is _not_ used for this
1083
purpose.  Neither is the current working directory, unless it happens
1084
to be in the source path.
1085
 
1086
   If GDB cannot find a source file in the source path, and the object
1087
program records a directory, GDB tries that directory too.  If the
1088
source path is empty, and there is no record of the compilation
1089
directory, GDB looks in the current directory as a last resort.
1090
 
1091
   Whenever you reset or rearrange the source path, GDB clears out any
1092
information it has cached about where source files are found and where
1093
each line is in the file.
1094
 
1095
   When you start GDB, its source path includes only `cdir' and `cwd',
1096
in that order.  To add other directories, use the `directory' command.
1097
 
1098
`directory DIRNAME ...'
1099
 
1100
`dir DIRNAME ...'
1101
     Add directory DIRNAME to the front of the source path.  Several
1102
     directory names may be given to this command, separated by `:'
1103
     (`;' on MS-DOS and MS-Windows, where `:' usually appears as part
1104
     of absolute file names) or whitespace.  You may specify a
1105
     directory that is already in the source path; this moves it
1106
     forward, so GDB searches it sooner.
1107
 
1108
     You can use the string `$cdir' to refer to the compilation
1109
     directory (if one is recorded), and `$cwd' to refer to the current
1110
     working directory.  `$cwd' is not the same as `.'--the former
1111
     tracks the current working directory as it changes during your GDB
1112
     session, while the latter is immediately expanded to the current
1113
     directory at the time you add an entry to the source path.
1114
 
1115
`directory'
1116
     Reset the source path to empty again.  This requires confirmation.
1117
 
1118
`show directories'
1119
     Print the source path: show which directories it contains.
1120
 
1121
   If your source path is cluttered with directories that are no longer
1122
of interest, GDB may sometimes cause confusion by finding the wrong
1123
versions of source.  You can correct the situation as follows:
1124
 
1125
  1. Use `directory' with no argument to reset the source path to empty.
1126
 
1127
  2. Use `directory' with suitable arguments to reinstall the
1128
     directories you want in the source path.  You can add all the
1129
     directories in one command.
1130
 
1131

1132
File: gdb.info,  Node: Machine Code,  Prev: Source Path,  Up: Source
1133
 
1134
Source and machine code
1135
=======================
1136
 
1137
   You can use the command `info line' to map source lines to program
1138
addresses (and vice versa), and the command `disassemble' to display a
1139
range of addresses as machine instructions.  When run under GNU Emacs
1140
mode, the `info line' command causes the arrow to point to the line
1141
specified.  Also, `info line' prints addresses in symbolic form as well
1142
as hex.
1143
 
1144
`info line LINESPEC'
1145
     Print the starting and ending addresses of the compiled code for
1146
     source line LINESPEC.  You can specify source lines in any of the
1147
     ways understood by the `list' command (*note Printing source
1148
     lines: List.).
1149
 
1150
   For example, we can use `info line' to discover the location of the
1151
object code for the first line of function `m4_changequote':
1152
 
1153
     (gdb) info line m4_changequote
1154
     Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
1155
 
1156
We can also inquire (using `*ADDR' as the form for LINESPEC) what
1157
source line covers a particular address:
1158
     (gdb) info line *0x63ff
1159
     Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
1160
 
1161
   After `info line', the default address for the `x' command is
1162
changed to the starting address of the line, so that `x/i' is
1163
sufficient to begin examining the machine code (*note Examining memory:
1164
Memory.).  Also, this address is saved as the value of the convenience
1165
variable `$_' (*note Convenience variables: Convenience Vars.).
1166
 
1167
`disassemble'
1168
     This specialized command dumps a range of memory as machine
1169
     instructions.  The default memory range is the function
1170
     surrounding the program counter of the selected frame.  A single
1171
     argument to this command is a program counter value; GDB dumps the
1172
     function surrounding this value.  Two arguments specify a range of
1173
     addresses (first inclusive, second exclusive) to dump.
1174
 
1175
   The following example shows the disassembly of a range of addresses
1176
of HP PA-RISC 2.0 code:
1177
 
1178
     (gdb) disas 0x32c4 0x32e4
1179
     Dump of assembler code from 0x32c4 to 0x32e4:
1180
     0x32c4 :      addil 0,dp
1181
     0x32c8 :      ldw 0x22c(sr0,r1),r26
1182
     0x32cc :      ldil 0x3000,r31
1183
     0x32d0 :      ble 0x3f8(sr4,r31)
1184
     0x32d4 :      ldo 0(r31),rp
1185
     0x32d8 :      addil -0x800,dp
1186
     0x32dc :      ldo 0x588(r1),r26
1187
     0x32e0 :      ldil 0x3000,r31
1188
     End of assembler dump.
1189
 
1190
   Some architectures have more than one commonly-used set of
1191
instruction mnemonics or other syntax.
1192
 
1193
`set disassembly-flavor INSTRUCTION-SET'
1194
     Select the instruction set to use when disassembling the program
1195
     via the `disassemble' or `x/i' commands.
1196
 
1197
     Currently this command is only defined for the Intel x86 family.
1198
     You can set INSTRUCTION-SET to either `intel' or `att'.  The
1199
     default is `att', the AT&T flavor used by default by Unix
1200
     assemblers for x86-based targets.
1201
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.