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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [gdb.info-3] - Blame information for rev 107

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
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: 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 stop if
348
     a function that has debugging information is called within the
349
     line.  In other words, `step' _steps inside_ any functions called
350
     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
`finish'
378
     Continue running until just after function in the selected stack
379
     frame returns.  Print the returned value (if any).
380
 
381
     Contrast this with the `return' command (*note Returning from a
382
     function: Returning.).
383
 
384
`until'
385
`u'
386
     Continue running until a source line past the current line, in the
387
     current stack frame, is reached.  This command is used to avoid
388
     single stepping through a loop more than once.  It is like the
389
     `next' command, except that when `until' encounters a jump, it
390
     automatically continues execution until the program counter is
391
     greater than the address of the jump.
392
 
393
     This means that when you reach the end of a loop after single
394
     stepping though it, `until' makes your program continue execution
395
     until it exits the loop.  In contrast, a `next' command at the end
396
     of a loop simply steps back to the beginning of the loop, which
397
     forces you to step through the next iteration.
398
 
399
     `until' always stops your program if it attempts to exit the
400
     current stack frame.
401
 
402
     `until' may produce somewhat counterintuitive results if the order
403
     of machine code does not match the order of the source lines.  For
404
     example, in the following excerpt from a debugging session, the `f'
405
     (`frame') command shows that execution is stopped at line `206';
406
     yet when we use `until', we get to line `195':
407
 
408
          (gdb) f
409
          #0  main (argc=4, argv=0xf7fffae8) at m4.c:206
410
          206                 expand_input();
411
          (gdb) until
412
          195             for ( ; argc > 0; NEXTARG) {
413
 
414
     This happened because, for execution efficiency, the compiler had
415
     generated code for the loop closure test at the end, rather than
416
     the start, of the loop--even though the test in a C `for'-loop is
417
     written before the body of the loop.  The `until' command appeared
418
     to step back to the beginning of the loop when it advanced to this
419
     expression; however, it has not really gone to an earlier
420
     statement--not in terms of the actual machine code.
421
 
422
     `until' with no argument works by means of single instruction
423
     stepping, and hence is slower than `until' with an argument.
424
 
425
`until LOCATION'
426
`u LOCATION'
427
     Continue running your program until either the specified location
428
     is reached, or the current stack frame returns.  LOCATION is any of
429
     the forms of argument acceptable to `break' (*note Setting
430
     breakpoints: Set Breaks.).  This form of the command uses
431
     breakpoints, and hence is quicker than `until' without an argument.
432
 
433
`stepi'
434
`stepi ARG'
435
`si'
436
     Execute one machine instruction, then stop and return to the
437
     debugger.
438
 
439
     It is often useful to do `display/i $pc' when stepping by machine
440
     instructions.  This makes GDB automatically display the next
441
     instruction to be executed, each time your program stops.  *Note
442
     Automatic display: Auto Display.
443
 
444
     An argument is a repeat count, as in `step'.
445
 
446
`nexti'
447
`nexti ARG'
448
`ni'
449
     Execute one machine instruction, but if it is a function call,
450
     proceed until the function returns.
451
 
452
     An argument is a repeat count, as in `next'.
453
 
454

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

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

615
File: gdb.info,  Node: Stack,  Next: Source,  Prev: Stopping,  Up: Top
616
 
617
Examining the Stack
618
*******************
619
 
620
   When your program has stopped, the first thing you need to know is
621
where it stopped and how it got there.
622
 
623
   Each time your program performs a function call, information about
624
the call is generated.  That information includes the location of the
625
call in your program, the arguments of the call, and the local
626
variables of the function being called.  The information is saved in a
627
block of data called a "stack frame".  The stack frames are allocated
628
in a region of memory called the "call stack".
629
 
630
   When your program stops, the GDB commands for examining the stack
631
allow you to see all of this information.
632
 
633
   One of the stack frames is "selected" by GDB and many GDB commands
634
refer implicitly to the selected frame.  In particular, whenever you
635
ask GDB for the value of a variable in your program, the value is found
636
in the selected frame.  There are special GDB commands to select
637
whichever frame you are interested in. *Note Selecting a frame:
638
Selection.
639
 
640
   When your program stops, GDB automatically selects the currently
641
executing frame and describes it briefly, similar to the `frame'
642
command (*note Information about a frame: Frame Info.).
643
 
644
* Menu:
645
 
646
* Frames::                      Stack frames
647
* Backtrace::                   Backtraces
648
* Selection::                   Selecting a frame
649
* Frame Info::                  Information on a frame
650
 
651

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

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

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

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

896
File: gdb.info,  Node: Source,  Next: Data,  Prev: Stack,  Up: Top
897
 
898
Examining Source Files
899
**********************
900
 
901
   GDB can print parts of your program's source, since the debugging
902
information recorded in the program tells GDB what source files were
903
used to build it.  When your program stops, GDB spontaneously prints
904
the line where it stopped.  Likewise, when you select a stack frame
905
(*note Selecting a frame: Selection.), GDB prints the line where
906
execution in that frame has stopped.  You can print other portions of
907
source files by explicit command.
908
 
909
   If you use GDB through its GNU Emacs interface, you may prefer to
910
use Emacs facilities to view source; see *Note Using GDB under GNU
911
Emacs: Emacs.
912
 
913
* Menu:
914
 
915
* List::                        Printing source lines
916
* Search::                      Searching source files
917
* Source Path::                 Specifying source directories
918
* Machine Code::                Source and machine code
919
 
920

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

1025
File: gdb.info,  Node: Search,  Next: Source Path,  Prev: List,  Up: Source
1026
 
1027
Searching source files
1028
======================
1029
 
1030
   There are two commands for searching through the current source file
1031
for a regular expression.
1032
 
1033
`forward-search REGEXP'
1034
`search REGEXP'
1035
     The command `forward-search REGEXP' checks each line, starting
1036
     with the one following the last line listed, for a match for
1037
     REGEXP.  It lists the line that is found.  You can use the synonym
1038
     `search REGEXP' or abbreviate the command name as `fo'.
1039
 
1040
`reverse-search REGEXP'
1041
     The command `reverse-search REGEXP' checks each line, starting
1042
     with the one before the last line listed and going backward, for a
1043
     match for REGEXP.  It lists the line that is found.  You can
1044
     abbreviate this command as `rev'.
1045
 
1046

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

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

1180
File: gdb.info,  Node: Data,  Next: Languages,  Prev: Source,  Up: Top
1181
 
1182
Examining Data
1183
**************
1184
 
1185
   The usual way to examine data in your program is with the `print'
1186
command (abbreviated `p'), or its synonym `inspect'.  It evaluates and
1187
prints the value of an expression of the language your program is
1188
written in (*note Using GDB with Different Languages: Languages.).
1189
 
1190
`print EXPR'
1191
`print /F EXPR'
1192
     EXPR is an expression (in the source language).  By default the
1193
     value of EXPR is printed in a format appropriate to its data type;
1194
     you can choose a different format by specifying `/F', where F is a
1195
     letter specifying the format; see *Note Output formats: Output
1196
     Formats.
1197
 
1198
`print'
1199
`print /F'
1200
     If you omit EXPR, GDB displays the last value again (from the
1201
     "value history"; *note Value history: Value History.).  This
1202
     allows you to conveniently inspect the same value in an
1203
     alternative format.
1204
 
1205
   A more low-level way of examining data is with the `x' command.  It
1206
examines data in memory at a specified address and prints it in a
1207
specified format.  *Note Examining memory: Memory.
1208
 
1209
   If you are interested in information about types, or about how the
1210
fields of a struct or a class are declared, use the `ptype EXP' command
1211
rather than `print'.  *Note Examining the Symbol Table: Symbols.
1212
 
1213
* Menu:
1214
 
1215
* Expressions::                 Expressions
1216
* Variables::                   Program variables
1217
* Arrays::                      Artificial arrays
1218
* Output Formats::              Output formats
1219
* Memory::                      Examining memory
1220
* Auto Display::                Automatic display
1221
* Print Settings::              Print settings
1222
* Value History::               Value history
1223
* Convenience Vars::            Convenience variables
1224
* Registers::                   Registers
1225
* Floating Point Hardware::     Floating point hardware
1226
 

powered by: WebSVN 2.1.0

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