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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [gdb.info-2] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 362 markom
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
2 106 markom
 
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: Environment,  Next: Working Directory,  Prev: Arguments,  Up: Running
30
 
31
Your program's environment
32
==========================
33
 
34
   The "environment" consists of a set of environment variables and
35
their values.  Environment variables conventionally record such things
36
as your user name, your home directory, your terminal type, and your
37
search path for programs to run.  Usually you set up environment
38
variables with the shell and they are inherited by all the other
39
programs you run.  When debugging, it can be useful to try running your
40
program with a modified environment without having to start GDB over
41
again.
42
 
43
`path DIRECTORY'
44
     Add DIRECTORY to the front of the `PATH' environment variable (the
45
     search path for executables), for both GDB and your program.  You
46
     may specify several directory names, separated by whitespace or by
47
     a system-dependent separator character (`:' on Unix, `;' on MS-DOS
48
     and MS-Windows).  If DIRECTORY is already in the path, it is moved
49
     to the front, so it is searched sooner.
50
 
51
     You can use the string `$cwd' to refer to whatever is the current
52
     working directory at the time GDB searches the path.  If you use
53
     `.' instead, it refers to the directory where you executed the
54
     `path' command.  GDB replaces `.' in the DIRECTORY argument (with
55
     the current path) before adding DIRECTORY to the search path.
56
 
57
`show paths'
58
     Display the list of search paths for executables (the `PATH'
59
     environment variable).
60
 
61
`show environment [VARNAME]'
62
     Print the value of environment variable VARNAME to be given to
63
     your program when it starts.  If you do not supply VARNAME, print
64
     the names and values of all environment variables to be given to
65
     your program.  You can abbreviate `environment' as `env'.
66
 
67
`set environment VARNAME [=VALUE]'
68
     Set environment variable VARNAME to VALUE.  The value changes for
69
     your program only, not for GDB itself.  VALUE may be any string;
70
     the values of environment variables are just strings, and any
71
     interpretation is supplied by your program itself.  The VALUE
72
     parameter is optional; if it is eliminated, the variable is set to
73
     a null value.
74
 
75
     For example, this command:
76
 
77
          set env USER = foo
78
 
79
     tells the debugged program, when subsequently run, that its user
80
     is named `foo'.  (The spaces around `=' are used for clarity here;
81
     they are not actually required.)
82
 
83
`unset environment VARNAME'
84
     Remove variable VARNAME from the environment to be passed to your
85
     program.  This is different from `set env VARNAME ='; `unset
86
     environment' removes the variable from the environment, rather
87
     than assigning it an empty value.
88
 
89
   _Warning:_ On Unix systems, GDB runs your program using the shell
90
indicated by your `SHELL' environment variable if it exists (or
91
`/bin/sh' if not).  If your `SHELL' variable names a shell that runs an
92
initialization file--such as `.cshrc' for C-shell, or `.bashrc' for
93
BASH--any variables you set in that file affect your program.  You may
94
wish to move setting of environment variables to files that are only
95
run when you sign on, such as `.login' or `.profile'.
96
 
97

98
File: gdb.info,  Node: Working Directory,  Next: Input/Output,  Prev: Environment,  Up: Running
99
 
100
Your program's working directory
101
================================
102
 
103
   Each time you start your program with `run', it inherits its working
104
directory from the current working directory of GDB.  The GDB working
105
directory is initially whatever it inherited from its parent process
106
(typically the shell), but you can specify a new working directory in
107
GDB with the `cd' command.
108
 
109
   The GDB working directory also serves as a default for the commands
110
that specify files for GDB to operate on.  *Note Commands to specify
111
files: Files.
112
 
113
`cd DIRECTORY'
114
     Set the GDB working directory to DIRECTORY.
115
 
116
`pwd'
117
     Print the GDB working directory.
118
 
119

120
File: gdb.info,  Node: Input/Output,  Next: Attach,  Prev: Working Directory,  Up: Running
121
 
122
Your program's input and output
123
===============================
124
 
125
   By default, the program you run under GDB does input and output to
126
the same terminal that GDB uses.  GDB switches the terminal to its own
127
terminal modes to interact with you, but it records the terminal modes
128
your program was using and switches back to them when you continue
129
running your program.
130
 
131
`info terminal'
132
     Displays information recorded by GDB about the terminal modes your
133
     program is using.
134
 
135
   You can redirect your program's input and/or output using shell
136
redirection with the `run' command.  For example,
137
 
138
     run > outfile
139
 
140
starts your program, diverting its output to the file `outfile'.
141
 
142
   Another way to specify where your program should do input and output
143
is with the `tty' command.  This command accepts a file name as
144
argument, and causes this file to be the default for future `run'
145
commands.  It also resets the controlling terminal for the child
146
process, for future `run' commands.  For example,
147
 
148
     tty /dev/ttyb
149
 
150
directs that processes started with subsequent `run' commands default
151
to do input and output on the terminal `/dev/ttyb' and have that as
152
their controlling terminal.
153
 
154
   An explicit redirection in `run' overrides the `tty' command's
155
effect on the input/output device, but not its effect on the controlling
156
terminal.
157
 
158
   When you use the `tty' command or redirect input in the `run'
159
command, only the input _for your program_ is affected.  The input for
160
GDB still comes from your terminal.
161
 
162

163
File: gdb.info,  Node: Attach,  Next: Kill Process,  Prev: Input/Output,  Up: Running
164
 
165
Debugging an already-running process
166
====================================
167
 
168
`attach PROCESS-ID'
169
     This command attaches to a running process--one that was started
170
     outside GDB.  (`info files' shows your active targets.)  The
171
     command takes as argument a process ID.  The usual way to find out
172
     the process-id of a Unix process is with the `ps' utility, or with
173
     the `jobs -l' shell command.
174
 
175
     `attach' does not repeat if you press  a second time after
176
     executing the command.
177
 
178
   To use `attach', your program must be running in an environment
179
which supports processes; for example, `attach' does not work for
180
programs on bare-board targets that lack an operating system.  You must
181
also have permission to send the process a signal.
182
 
183
   When you use `attach', the debugger finds the program running in the
184
process first by looking in the current working directory, then (if the
185
program is not found) by using the source file search path (*note
186
Specifying source directories: Source Path.).  You can also use the
187
`file' command to load the program.  *Note Commands to Specify Files:
188
Files.
189
 
190
   The first thing GDB does after arranging to debug the specified
191
process is to stop it.  You can examine and modify an attached process
192
with all the GDB commands that are ordinarily available when you start
193
processes with `run'.  You can insert breakpoints; you can step and
194
continue; you can modify storage.  If you would rather the process
195
continue running, you may use the `continue' command after attaching
196
GDB to the process.
197
 
198
`detach'
199
     When you have finished debugging the attached process, you can use
200
     the `detach' command to release it from GDB control.  Detaching
201
     the process continues its execution.  After the `detach' command,
202
     that process and GDB become completely independent once more, and
203
     you are ready to `attach' another process or start one with `run'.
204
     `detach' does not repeat if you press  again after executing
205
     the command.
206
 
207
   If you exit GDB or use the `run' command while you have an attached
208
process, you kill that process.  By default, GDB asks for confirmation
209
if you try to do either of these things; you can control whether or not
210
you need to confirm by using the `set confirm' command (*note Optional
211
warnings and messages: Messages/Warnings.).
212
 
213

214
File: gdb.info,  Node: Kill Process,  Next: Threads,  Prev: Attach,  Up: Running
215
 
216
Killing the child process
217
=========================
218
 
219
`kill'
220
     Kill the child process in which your program is running under GDB.
221
 
222
   This command is useful if you wish to debug a core dump instead of a
223
running process.  GDB ignores any core dump file while your program is
224
running.
225
 
226
   On some operating systems, a program cannot be executed outside GDB
227
while you have breakpoints set on it inside GDB.  You can use the
228
`kill' command in this situation to permit running your program outside
229
the debugger.
230
 
231
   The `kill' command is also useful if you wish to recompile and
232
relink your program, since on many systems it is impossible to modify an
233
executable file while it is running in a process.  In this case, when
234
you next type `run', GDB notices that the file has changed, and reads
235
the symbol table again (while trying to preserve your current
236
breakpoint settings).
237
 
238

239
File: gdb.info,  Node: Threads,  Next: Processes,  Prev: Kill Process,  Up: Running
240
 
241
Debugging programs with multiple threads
242
========================================
243
 
244
   In some operating systems, such as HP-UX and Solaris, a single
245
program may have more than one "thread" of execution.  The precise
246
semantics of threads differ from one operating system to another, but
247
in general the threads of a single program are akin to multiple
248
processes--except that they share one address space (that is, they can
249
all examine and modify the same variables).  On the other hand, each
250
thread has its own registers and execution stack, and perhaps private
251
memory.
252
 
253
   GDB provides these facilities for debugging multi-thread programs:
254
 
255
   * automatic notification of new threads
256
 
257
   * `thread THREADNO', a command to switch among threads
258
 
259
   * `info threads', a command to inquire about existing threads
260
 
261
   * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command
262
     to a list of threads
263
 
264
   * thread-specific breakpoints
265
 
266
     _Warning:_ These facilities are not yet available on every GDB
267
     configuration where the operating system supports threads.  If
268
     your GDB does not support threads, these commands have no effect.
269
     For example, a system without thread support shows no output from
270
     `info threads', and always rejects the `thread' command, like this:
271
 
272
          (gdb) info threads
273
          (gdb) thread 1
274
          Thread ID 1 not known.  Use the "info threads" command to
275
          see the IDs of currently known threads.
276
 
277
   The GDB thread debugging facility allows you to observe all threads
278
while your program runs--but whenever GDB takes control, one thread in
279
particular is always the focus of debugging.  This thread is called the
280
"current thread".  Debugging commands show program information from the
281
perspective of the current thread.
282
 
283
   Whenever GDB detects a new thread in your program, it displays the
284
target system's identification for the thread with a message in the
285
form `[New SYSTAG]'.  SYSTAG is a thread identifier whose form varies
286
depending on the particular system.  For example, on LynxOS, you might
287
see
288
 
289
     [New process 35 thread 27]
290
 
291
when GDB notices a new thread.  In contrast, on an SGI system, the
292
SYSTAG is simply something like `process 368', with no further
293
qualifier.
294
 
295
   For debugging purposes, GDB associates its own thread number--always
296
a single integer--with each thread in your program.
297
 
298
`info threads'
299
     Display a summary of all threads currently in your program.  GDB
300
     displays for each thread (in this order):
301
 
302
       1. the thread number assigned by GDB
303
 
304
       2. the target system's thread identifier (SYSTAG)
305
 
306
       3. the current stack frame summary for that thread
307
 
308
     An asterisk `*' to the left of the GDB thread number indicates the
309
     current thread.
310
 
311
     For example,
312
 
313
     (gdb) info threads
314
       3 process 35 thread 27  0x34e5 in sigpause ()
315
       2 process 35 thread 23  0x34e5 in sigpause ()
316
     * 1 process 35 thread 13  main (argc=1, argv=0x7ffffff8)
317
         at threadtest.c:68
318
 
319
   On HP-UX systems:
320
 
321
   For debugging purposes, GDB associates its own thread number--a
322
small integer assigned in thread-creation order--with each thread in
323
your program.
324
 
325
   Whenever GDB detects a new thread in your program, it displays both
326
GDB's thread number and the target system's identification for the
327
thread with a message in the form `[New SYSTAG]'.  SYSTAG is a thread
328
identifier whose form varies depending on the particular system.  For
329
example, on HP-UX, you see
330
 
331
     [New thread 2 (system thread 26594)]
332
 
333
when GDB notices a new thread.
334
 
335
`info threads'
336
     Display a summary of all threads currently in your program.  GDB
337
     displays for each thread (in this order):
338
 
339
       1. the thread number assigned by GDB
340
 
341
       2. the target system's thread identifier (SYSTAG)
342
 
343
       3. the current stack frame summary for that thread
344
 
345
     An asterisk `*' to the left of the GDB thread number indicates the
346
     current thread.
347
 
348
     For example,
349
 
350
     (gdb) info threads
351
         * 3 system thread 26607  worker (wptr=0x7b09c318 "@") \
352
 
353
     at quicksort.c:137
354
           2 system thread 26606  0x7b0030d8 in __ksleep () \
355
 
356
     from /usr/lib/libc.2
357
           1 system thread 27905  0x7b003498 in _brk () \
358
 
359
     from /usr/lib/libc.2
360
 
361
`thread THREADNO'
362
     Make thread number THREADNO the current thread.  The command
363
     argument THREADNO is the internal GDB thread number, as shown in
364
     the first field of the `info threads' display.  GDB responds by
365
     displaying the system identifier of the thread you selected, and
366
     its current stack frame summary:
367
 
368
          (gdb) thread 2
369
          [Switching to process 35 thread 23]
370
          0x34e5 in sigpause ()
371
 
372
     As with the `[New ...]' message, the form of the text after
373
     `Switching to' depends on your system's conventions for identifying
374
     threads.
375
 
376
`thread apply [THREADNO] [ALL]  ARGS'
377
     The `thread apply' command allows you to apply a command to one or
378
     more threads.  Specify the numbers of the threads that you want
379
     affected with the command argument THREADNO.  THREADNO is the
380
     internal GDB thread number, as shown in the first field of the
381
     `info threads' display.  To apply a command to all threads, use
382
     `thread apply all' ARGS.
383
 
384
   Whenever GDB stops your program, due to a breakpoint or a signal, it
385
automatically selects the thread where that breakpoint or signal
386
happened.  GDB alerts you to the context switch with a message of the
387
form `[Switching to SYSTAG]' to identify the thread.
388
 
389
   *Note Stopping and starting multi-thread programs: Thread Stops, for
390
more information about how GDB behaves when you stop and start programs
391
with multiple threads.
392
 
393
   *Note Setting watchpoints: Set Watchpoints, for information about
394
watchpoints in programs with multiple threads.
395
 
396

397
File: gdb.info,  Node: Processes,  Prev: Threads,  Up: Running
398
 
399
Debugging programs with multiple processes
400
==========================================
401
 
402
   On most systems, GDB has no special support for debugging programs
403
which create additional processes using the `fork' function.  When a
404
program forks, GDB will continue to debug the parent process and the
405
child process will run unimpeded.  If you have set a breakpoint in any
406
code which the child then executes, the child will get a `SIGTRAP'
407
signal which (unless it catches the signal) will cause it to terminate.
408
 
409
   However, if you want to debug the child process there is a workaround
410
which isn't too painful.  Put a call to `sleep' in the code which the
411
child process executes after the fork.  It may be useful to sleep only
412
if a certain environment variable is set, or a certain file exists, so
413
that the delay need not occur when you don't want to run GDB on the
414
child.  While the child is sleeping, use the `ps' program to get its
415
process ID.  Then tell GDB (a new invocation of GDB if you are also
416
debugging the parent process) to attach to the child process (*note
417 362 markom
Attach::).  From that point on you can debug the child process just
418 106 markom
like any other process which you attached to.
419
 
420
   On HP-UX (11.x and later only?), GDB provides support for debugging
421
programs that create additional processes using the `fork' or `vfork'
422
function.
423
 
424
   By default, when a program forks, GDB will continue to debug the
425
parent process and the child process will run unimpeded.
426
 
427
   If you want to follow the child process instead of the parent
428
process, use the command `set follow-fork-mode'.
429
 
430
`set follow-fork-mode MODE'
431
     Set the debugger response to a program call of `fork' or `vfork'.
432
     A call to `fork' or `vfork' creates a new process.  The MODE can
433
     be:
434
 
435
    `parent'
436
          The original process is debugged after a fork.  The child
437
          process runs unimpeded.  This is the default.
438
 
439
    `child'
440
          The new process is debugged after a fork.  The parent process
441
          runs unimpeded.
442
 
443
    `ask'
444
          The debugger will ask for one of the above choices.
445
 
446
`show follow-fork-mode'
447
     Display the current debugger response to a `fork' or `vfork' call.
448
 
449
   If you ask to debug a child process and a `vfork' is followed by an
450
`exec', GDB executes the new target up to the first breakpoint in the
451
new target.  If you have a breakpoint set on `main' in your original
452
program, the breakpoint will also be set on the child process's `main'.
453
 
454
   When a child process is spawned by `vfork', you cannot debug the
455
child or parent until an `exec' call completes.
456
 
457
   If you issue a `run' command to GDB after an `exec' call executes,
458
the new target restarts.  To restart the parent process, use the `file'
459
command with the parent executable name as its argument.
460
 
461
   You can use the `catch' command to make GDB stop whenever a `fork',
462
`vfork', or `exec' call is made.  *Note Setting catchpoints: Set
463
Catchpoints.
464
 
465

466
File: gdb.info,  Node: Stopping,  Next: Stack,  Prev: Running,  Up: Top
467
 
468
Stopping and Continuing
469
***********************
470
 
471
   The principal purposes of using a debugger are so that you can stop
472
your program before it terminates; or so that, if your program runs into
473
trouble, you can investigate and find out why.
474
 
475
   Inside GDB, your program may stop for any of several reasons, such
476
as a signal, a breakpoint, or reaching a new line after a GDB command
477
such as `step'.  You may then examine and change variables, set new
478
breakpoints or remove old ones, and then continue execution.  Usually,
479
the messages shown by GDB provide ample explanation of the status of
480
your program--but you can also explicitly request this information at
481
any time.
482
 
483
`info program'
484
     Display information about the status of your program: whether it is
485
     running or not, what process it is, and why it stopped.
486
 
487
* Menu:
488
 
489
* Breakpoints::                 Breakpoints, watchpoints, and catchpoints
490
* Continuing and Stepping::     Resuming execution
491
* Signals::                     Signals
492
* Thread Stops::                Stopping and starting multi-thread programs
493
 
494

495
File: gdb.info,  Node: Breakpoints,  Next: Continuing and Stepping,  Up: Stopping
496
 
497
Breakpoints, watchpoints, and catchpoints
498
=========================================
499
 
500
   A "breakpoint" makes your program stop whenever a certain point in
501
the program is reached.  For each breakpoint, you can add conditions to
502
control in finer detail whether your program stops.  You can set
503
breakpoints with the `break' command and its variants (*note Setting
504
breakpoints: Set Breaks.), to specify the place where your program
505
should stop by line number, function name or exact address in the
506
program.
507
 
508
   In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can
509
set breakpoints in shared libraries before the executable is run.
510
There is a minor limitation on HP-UX systems: you must wait until the
511
executable is run in order to set breakpoints in shared library
512
routines that are not called directly by the program (for example,
513
routines that are arguments in a `pthread_create' call).
514
 
515
   A "watchpoint" is a special breakpoint that stops your program when
516
the value of an expression changes.  You must use a different command
517
to set watchpoints (*note Setting watchpoints: Set Watchpoints.), but
518
aside from that, you can manage a watchpoint like any other breakpoint:
519
you enable, disable, and delete both breakpoints and watchpoints using
520
the same commands.
521
 
522
   You can arrange to have values from your program displayed
523
automatically whenever GDB stops at a breakpoint.  *Note Automatic
524
display: Auto Display.
525
 
526
   A "catchpoint" is another special breakpoint that stops your program
527
when a certain kind of event occurs, such as the throwing of a C++
528
exception or the loading of a library.  As with watchpoints, you use a
529
different command to set a catchpoint (*note Setting catchpoints: Set
530
Catchpoints.), but aside from that, you can manage a catchpoint like any
531
other breakpoint.  (To stop when your program receives a signal, use the
532
`handle' command; see *Note Signals: Signals.)
533
 
534
   GDB assigns a number to each breakpoint, watchpoint, or catchpoint
535
when you create it; these numbers are successive integers starting with
536
one.  In many of the commands for controlling various features of
537
breakpoints you use the breakpoint number to say which breakpoint you
538
want to change.  Each breakpoint may be "enabled" or "disabled"; if
539
disabled, it has no effect on your program until you enable it again.
540
 
541
   Some GDB commands accept a range of breakpoints on which to operate.
542
A breakpoint range is either a single breakpoint number, like `5', or
543
two such numbers, in increasing order, separated by a hyphen, like
544
`5-7'.  When a breakpoint range is given to a command, all breakpoint
545
in that range are operated on.
546
 
547
* Menu:
548
 
549
* Set Breaks::                  Setting breakpoints
550
* Set Watchpoints::             Setting watchpoints
551
* Set Catchpoints::             Setting catchpoints
552
* Delete Breaks::               Deleting breakpoints
553
* Disabling::                   Disabling breakpoints
554
* Conditions::                  Break conditions
555
* Break Commands::              Breakpoint command lists
556
* Breakpoint Menus::            Breakpoint menus
557
* Error in Breakpoints::        ``Cannot insert breakpoints''
558
 
559

560
File: gdb.info,  Node: Set Breaks,  Next: Set Watchpoints,  Up: Breakpoints
561
 
562
Setting breakpoints
563
-------------------
564
 
565
   Breakpoints are set with the `break' command (abbreviated `b').  The
566
debugger convenience variable `$bpnum' records the number of the
567
breakpoints you've set most recently; see *Note Convenience variables:
568
Convenience Vars, for a discussion of what you can do with convenience
569
variables.
570
 
571
   You have several ways to say where the breakpoint should go.
572
 
573
`break FUNCTION'
574
     Set a breakpoint at entry to function FUNCTION.  When using source
575
     languages that permit overloading of symbols, such as C++,
576
     FUNCTION may refer to more than one possible place to break.
577
     *Note Breakpoint menus: Breakpoint Menus, for a discussion of that
578
     situation.
579
 
580
`break +OFFSET'
581
`break -OFFSET'
582
     Set a breakpoint some number of lines forward or back from the
583
     position at which execution stopped in the currently selected
584
     "stack frame".  (*Note Frames: Frames, for a description of stack
585
     frames.)
586
 
587
`break LINENUM'
588
     Set a breakpoint at line LINENUM in the current source file.  The
589
     current source file is the last file whose source text was printed.
590
     The breakpoint will stop your program just before it executes any
591
     of the code on that line.
592
 
593
`break FILENAME:LINENUM'
594
     Set a breakpoint at line LINENUM in source file FILENAME.
595
 
596
`break FILENAME:FUNCTION'
597
     Set a breakpoint at entry to function FUNCTION found in file
598
     FILENAME.  Specifying a file name as well as a function name is
599
     superfluous except when multiple files contain similarly named
600
     functions.
601
 
602
`break *ADDRESS'
603
     Set a breakpoint at address ADDRESS.  You can use this to set
604
     breakpoints in parts of your program which do not have debugging
605
     information or source files.
606
 
607
`break'
608
     When called without any arguments, `break' sets a breakpoint at
609
     the next instruction to be executed in the selected stack frame
610
     (*note Examining the Stack: Stack.).  In any selected frame but the
611
     innermost, this makes your program stop as soon as control returns
612
     to that frame.  This is similar to the effect of a `finish'
613
     command in the frame inside the selected frame--except that
614
     `finish' does not leave an active breakpoint.  If you use `break'
615
     without an argument in the innermost frame, GDB stops the next
616
     time it reaches the current location; this may be useful inside
617
     loops.
618
 
619
     GDB normally ignores breakpoints when it resumes execution, until
620
     at least one instruction has been executed.  If it did not do
621
     this, you would be unable to proceed past a breakpoint without
622
     first disabling the breakpoint.  This rule applies whether or not
623
     the breakpoint already existed when your program stopped.
624
 
625
`break ... if COND'
626
     Set a breakpoint with condition COND; evaluate the expression COND
627
     each time the breakpoint is reached, and stop only if the value is
628
     nonzero--that is, if COND evaluates as true.  `...' stands for one
629
     of the possible arguments described above (or no argument)
630
     specifying where to break.  *Note Break conditions: Conditions,
631
     for more information on breakpoint conditions.
632
 
633
`tbreak ARGS'
634
     Set a breakpoint enabled only for one stop.  ARGS are the same as
635
     for the `break' command, and the breakpoint is set in the same
636
     way, but the breakpoint is automatically deleted after the first
637
     time your program stops there.  *Note Disabling breakpoints:
638
     Disabling.
639
 
640
`hbreak ARGS'
641
     Set a hardware-assisted breakpoint.  ARGS are the same as for the
642
     `break' command and the breakpoint is set in the same way, but the
643
     breakpoint requires hardware support and some target hardware may
644
     not have this support.  The main purpose of this is EPROM/ROM code
645
     debugging, so you can set a breakpoint at an instruction without
646
     changing the instruction.  This can be used with the new
647
     trap-generation provided by SPARClite DSU and some x86-based
648
     targets.  These targets will generate traps when a program
649
     accesses some data or instruction address that is assigned to the
650
     debug registers.  However the hardware breakpoint registers can
651
     take a limited number of breakpoints.  For example, on the DSU,
652
     only two data breakpoints can be set at a time, and GDB will
653
     reject this command if more than two are used.  Delete or disable
654
     unused hardware breakpoints before setting new ones (*note
655
     Disabling: Disabling.).  *Note Break conditions: Conditions.
656
 
657
`thbreak ARGS'
658
     Set a hardware-assisted breakpoint enabled only for one stop.  ARGS
659
     are the same as for the `hbreak' command and the breakpoint is set
660
     in the same way.  However, like the `tbreak' command, the
661
     breakpoint is automatically deleted after the first time your
662
     program stops there.  Also, like the `hbreak' command, the
663
     breakpoint requires hardware support and some target hardware may
664
     not have this support.  *Note Disabling breakpoints: Disabling.
665
     See also *Note Break conditions: Conditions.
666
 
667
`rbreak REGEX'
668
     Set breakpoints on all functions matching the regular expression
669
     REGEX.  This command sets an unconditional breakpoint on all
670
     matches, printing a list of all breakpoints it set.  Once these
671
     breakpoints are set, they are treated just like the breakpoints
672
     set with the `break' command.  You can delete them, disable them,
673
     or make them conditional the same way as any other breakpoint.
674
 
675
     The syntax of the regular expression is the standard one used with
676
     tools like `grep'.  Note that this is different from the syntax
677
     used by shells, so for instance `foo*' matches all functions that
678
     include an `fo' followed by zero or more `o's.  There is an
679
     implicit `.*' leading and trailing the regular expression you
680
     supply, so to match only functions that begin with `foo', use
681
     `^foo'.
682
 
683
     When debugging C++ programs, `rbreak' is useful for setting
684
     breakpoints on overloaded functions that are not members of any
685
     special classes.
686
 
687
`info breakpoints [N]'
688
`info break [N]'
689
`info watchpoints [N]'
690
     Print a table of all breakpoints, watchpoints, and catchpoints set
691
     and not deleted, with the following columns for each breakpoint:
692
 
693
    _Breakpoint Numbers_
694
 
695
    _Type_
696
          Breakpoint, watchpoint, or catchpoint.
697
 
698
    _Disposition_
699
          Whether the breakpoint is marked to be disabled or deleted
700
          when hit.
701
 
702
    _Enabled or Disabled_
703
          Enabled breakpoints are marked with `y'.  `n' marks
704
          breakpoints that are not enabled.
705
 
706
    _Address_
707
          Where the breakpoint is in your program, as a memory address.
708
 
709
    _What_
710
          Where the breakpoint is in the source for your program, as a
711
          file and line number.
712
 
713
     If a breakpoint is conditional, `info break' shows the condition on
714
     the line following the affected breakpoint; breakpoint commands,
715
     if any, are listed after that.
716
 
717
     `info break' with a breakpoint number N as argument lists only
718
     that breakpoint.  The convenience variable `$_' and the default
719
     examining-address for the `x' command are set to the address of
720
     the last breakpoint listed (*note Examining memory: Memory.).
721
 
722
     `info break' displays a count of the number of times the breakpoint
723
     has been hit.  This is especially useful in conjunction with the
724
     `ignore' command.  You can ignore a large number of breakpoint
725
     hits, look at the breakpoint info to see how many times the
726
     breakpoint was hit, and then run again, ignoring one less than
727
     that number.  This will get you quickly to the last hit of that
728
     breakpoint.
729
 
730
   GDB allows you to set any number of breakpoints at the same place in
731
your program.  There is nothing silly or meaningless about this.  When
732
the breakpoints are conditional, this is even useful (*note Break
733
conditions: Conditions.).
734
 
735
   GDB itself sometimes sets breakpoints in your program for special
736
purposes, such as proper handling of `longjmp' (in C programs).  These
737
internal breakpoints are assigned negative numbers, starting with `-1';
738
`info breakpoints' does not display them.
739
 
740
   You can see these breakpoints with the GDB maintenance command
741
`maint info breakpoints'.
742
 
743
`maint info breakpoints'
744
     Using the same format as `info breakpoints', display both the
745
     breakpoints you've set explicitly, and those GDB is using for
746
     internal purposes.  Internal breakpoints are shown with negative
747
     breakpoint numbers.  The type column identifies what kind of
748
     breakpoint is shown:
749
 
750
    `breakpoint'
751
          Normal, explicitly set breakpoint.
752
 
753
    `watchpoint'
754
          Normal, explicitly set watchpoint.
755
 
756
    `longjmp'
757
          Internal breakpoint, used to handle correctly stepping through
758
          `longjmp' calls.
759
 
760
    `longjmp resume'
761
          Internal breakpoint at the target of a `longjmp'.
762
 
763
    `until'
764
          Temporary internal breakpoint used by the GDB `until' command.
765
 
766
    `finish'
767
          Temporary internal breakpoint used by the GDB `finish'
768
          command.
769
 
770
    `shlib events'
771
          Shared library events.
772
 
773

774
File: gdb.info,  Node: Set Watchpoints,  Next: Set Catchpoints,  Prev: Set Breaks,  Up: Breakpoints
775
 
776
Setting watchpoints
777
-------------------
778
 
779
   You can use a watchpoint to stop execution whenever the value of an
780
expression changes, without having to predict a particular place where
781
this may happen.
782
 
783
   Depending on your system, watchpoints may be implemented in software
784
or hardware.  GDB does software watchpointing by single-stepping your
785
program and testing the variable's value each time, which is hundreds of
786
times slower than normal execution.  (But this may still be worth it, to
787
catch errors where you have no clue what part of your program is the
788
culprit.)
789
 
790
   On some systems, such as HP-UX, Linux and some other x86-based
791
targets, GDB includes support for hardware watchpoints, which do not
792
slow down the running of your program.
793
 
794
`watch EXPR'
795
     Set a watchpoint for an expression.  GDB will break when EXPR is
796
     written into by the program and its value changes.
797
 
798
`rwatch EXPR'
799
     Set a watchpoint that will break when watch EXPR is read by the
800
     program.
801
 
802
`awatch EXPR'
803
     Set a watchpoint that will break when EXPR is either read or
804
     written into by the program.
805
 
806
`info watchpoints'
807
     This command prints a list of watchpoints, breakpoints, and
808
     catchpoints; it is the same as `info break'.
809
 
810
   GDB sets a "hardware watchpoint" if possible.  Hardware watchpoints
811
execute very quickly, and the debugger reports a change in value at the
812
exact instruction where the change occurs.  If GDB cannot set a
813
hardware watchpoint, it sets a software watchpoint, which executes more
814
slowly and reports the change in value at the next statement, not the
815
instruction, after the change occurs.
816
 
817
   When you issue the `watch' command, GDB reports
818
 
819
     Hardware watchpoint NUM: EXPR
820
 
821
if it was able to set a hardware watchpoint.
822
 
823
   Currently, the `awatch' and `rwatch' commands can only set hardware
824
watchpoints, because accesses to data that don't change the value of
825
the watched expression cannot be detected without examining every
826
instruction as it is being executed, and GDB does not do that
827
currently.  If GDB finds that it is unable to set a hardware breakpoint
828
with the `awatch' or `rwatch' command, it will print a message like
829
this:
830
 
831
     Expression cannot be implemented with read/access watchpoint.
832
 
833
   Sometimes, GDB cannot set a hardware watchpoint because the data
834
type of the watched expression is wider than what a hardware watchpoint
835
on the target machine can handle.  For example, some systems can only
836
watch regions that are up to 4 bytes wide; on such systems you cannot
837
set hardware watchpoints for an expression that yields a
838
double-precision floating-point number (which is typically 8 bytes
839
wide).  As a work-around, it might be possible to break the large region
840
into a series of smaller ones and watch them with separate watchpoints.
841
 
842
   If you set too many hardware watchpoints, GDB might be unable to
843
insert all of them when you resume the execution of your program.
844
Since the precise number of active watchpoints is unknown until such
845
time as the program is about to be resumed, GDB might not be able to
846
warn you about this when you set the watchpoints, and the warning will
847
be printed only when the program is resumed:
848
 
849
     Hardware watchpoint NUM: Could not insert watchpoint
850
 
851
If this happens, delete or disable some of the watchpoints.
852
 
853
   The SPARClite DSU will generate traps when a program accesses some
854
data or instruction address that is assigned to the debug registers.
855
For the data addresses, DSU facilitates the `watch' command.  However
856
the hardware breakpoint registers can only take two data watchpoints,
857
and both watchpoints must be the same kind.  For example, you can set
858
two watchpoints with `watch' commands, two with `rwatch' commands, *or*
859
two with `awatch' commands, but you cannot set one watchpoint with one
860
command and the other with a different command.  GDB will reject the
861
command if you try to mix watchpoints.  Delete or disable unused
862
watchpoint commands before setting new ones.
863
 
864
   If you call a function interactively using `print' or `call', any
865
watchpoints you have set will be inactive until GDB reaches another
866
kind of breakpoint or the call completes.
867
 
868
   GDB automatically deletes watchpoints that watch local (automatic)
869
variables, or expressions that involve such variables, when they go out
870
of scope, that is, when the execution leaves the block in which these
871
variables were defined.  In particular, when the program being debugged
872
terminates, _all_ local variables go out of scope, and so only
873
watchpoints that watch global variables remain set.  If you rerun the
874
program, you will need to set all such watchpoints again.  One way of
875
doing that would be to set a code breakpoint at the entry to the `main'
876
function and when it breaks, set all the watchpoints.
877
 
878
     _Warning:_ In multi-thread programs, watchpoints have only limited
879
     usefulness.  With the current watchpoint implementation, GDB can
880
     only watch the value of an expression _in a single thread_.  If
881
     you are confident that the expression can only change due to the
882
     current thread's activity (and if you are also confident that no
883
     other thread can become current), then you can use watchpoints as
884
     usual.  However, GDB may not notice when a non-current thread's
885
     activity changes the expression.
886
 
887
     _HP-UX Warning:_ In multi-thread programs, software watchpoints
888
     have only limited usefulness.  If GDB creates a software
889
     watchpoint, it can only watch the value of an expression _in a
890
     single thread_.  If you are confident that the expression can only
891
     change due to the current thread's activity (and if you are also
892
     confident that no other thread can become current), then you can
893
     use software watchpoints as usual.  However, GDB may not notice
894
     when a non-current thread's activity changes the expression.
895
     (Hardware watchpoints, in contrast, watch an expression in all
896
     threads.)
897
 
898

899
File: gdb.info,  Node: Set Catchpoints,  Next: Delete Breaks,  Prev: Set Watchpoints,  Up: Breakpoints
900
 
901
Setting catchpoints
902
-------------------
903
 
904
   You can use "catchpoints" to cause the debugger to stop for certain
905
kinds of program events, such as C++ exceptions or the loading of a
906
shared library.  Use the `catch' command to set a catchpoint.
907
 
908
`catch EVENT'
909
     Stop when EVENT occurs.  EVENT can be any of the following:
910
    `throw'
911
          The throwing of a C++ exception.
912
 
913
    `catch'
914
          The catching of a C++ exception.
915
 
916
    `exec'
917
          A call to `exec'.  This is currently only available for HP-UX.
918
 
919
    `fork'
920
          A call to `fork'.  This is currently only available for HP-UX.
921
 
922
    `vfork'
923
          A call to `vfork'.  This is currently only available for
924
          HP-UX.
925
 
926
    `load'
927
    `load LIBNAME'
928
          The dynamic loading of any shared library, or the loading of
929
          the library LIBNAME.  This is currently only available for
930
          HP-UX.
931
 
932
    `unload'
933
    `unload LIBNAME'
934
          The unloading of any dynamically loaded shared library, or
935
          the unloading of the library LIBNAME.  This is currently only
936
          available for HP-UX.
937
 
938
`tcatch EVENT'
939
     Set a catchpoint that is enabled only for one stop.  The
940
     catchpoint is automatically deleted after the first time the event
941
     is caught.
942
 
943
   Use the `info break' command to list the current catchpoints.
944
 
945
   There are currently some limitations to C++ exception handling
946
(`catch throw' and `catch catch') in GDB:
947
 
948
   * If you call a function interactively, GDB normally returns control
949
     to you when the function has finished executing.  If the call
950
     raises an exception, however, the call may bypass the mechanism
951
     that returns control to you and cause your program either to abort
952
     or to simply continue running until it hits a breakpoint, catches
953
     a signal that GDB is listening for, or exits.  This is the case
954
     even if you set a catchpoint for the exception; catchpoints on
955
     exceptions are disabled within interactive calls.
956
 
957
   * You cannot raise an exception interactively.
958
 
959
   * You cannot install an exception handler interactively.
960
 
961
   Sometimes `catch' is not the best way to debug exception handling:
962
if you need to know exactly where an exception is raised, it is better
963
to stop _before_ the exception handler is called, since that way you
964
can see the stack before any unwinding takes place.  If you set a
965
breakpoint in an exception handler instead, it may not be easy to find
966
out where the exception was raised.
967
 
968
   To stop just before an exception handler is called, you need some
969
knowledge of the implementation.  In the case of GNU C++, exceptions are
970
raised by calling a library function named `__raise_exception' which
971
has the following ANSI C interface:
972
 
973
         /* ADDR is where the exception identifier is stored.
974
            ID is the exception identifier.  */
975
         void __raise_exception (void **addr, void *id);
976
 
977
To make the debugger catch all exceptions before any stack unwinding
978
takes place, set a breakpoint on `__raise_exception' (*note
979
Breakpoints; watchpoints; and exceptions: Breakpoints.).
980
 
981
   With a conditional breakpoint (*note Break conditions: Conditions.)
982
that depends on the value of ID, you can stop your program when a
983
specific exception is raised.  You can use multiple conditional
984
breakpoints to stop your program when any of a number of exceptions are
985
raised.
986
 
987

988
File: gdb.info,  Node: Delete Breaks,  Next: Disabling,  Prev: Set Catchpoints,  Up: Breakpoints
989
 
990
Deleting breakpoints
991
--------------------
992
 
993
   It is often necessary to eliminate a breakpoint, watchpoint, or
994
catchpoint once it has done its job and you no longer want your program
995
to stop there.  This is called "deleting" the breakpoint.  A breakpoint
996
that has been deleted no longer exists; it is forgotten.
997
 
998
   With the `clear' command you can delete breakpoints according to
999
where they are in your program.  With the `delete' command you can
1000
delete individual breakpoints, watchpoints, or catchpoints by specifying
1001
their breakpoint numbers.
1002
 
1003
   It is not necessary to delete a breakpoint to proceed past it.  GDB
1004
automatically ignores breakpoints on the first instruction to be
1005
executed when you continue execution without changing the execution
1006
address.
1007
 
1008
`clear'
1009
     Delete any breakpoints at the next instruction to be executed in
1010
     the selected stack frame (*note Selecting a frame: Selection.).
1011
     When the innermost frame is selected, this is a good way to delete
1012
     a breakpoint where your program just stopped.
1013
 
1014
`clear FUNCTION'
1015
`clear FILENAME:FUNCTION'
1016
     Delete any breakpoints set at entry to the function FUNCTION.
1017
 
1018
`clear LINENUM'
1019
`clear FILENAME:LINENUM'
1020
     Delete any breakpoints set at or within the code of the specified
1021
     line.
1022
 
1023
`delete [breakpoints] [RANGE...]'
1024
     Delete the breakpoints, watchpoints, or catchpoints of the
1025
     breakpoint ranges specified as arguments.  If no argument is
1026
     specified, delete all breakpoints (GDB asks confirmation, unless
1027
     you have `set confirm off').  You can abbreviate this command as
1028
     `d'.
1029
 
1030

1031
File: gdb.info,  Node: Disabling,  Next: Conditions,  Prev: Delete Breaks,  Up: Breakpoints
1032
 
1033
Disabling breakpoints
1034
---------------------
1035
 
1036
   Rather than deleting a breakpoint, watchpoint, or catchpoint, you
1037
might prefer to "disable" it.  This makes the breakpoint inoperative as
1038
if it had been deleted, but remembers the information on the breakpoint
1039
so that you can "enable" it again later.
1040
 
1041
   You disable and enable breakpoints, watchpoints, and catchpoints with
1042
the `enable' and `disable' commands, optionally specifying one or more
1043
breakpoint numbers as arguments.  Use `info break' or `info watch' to
1044
print a list of breakpoints, watchpoints, and catchpoints if you do not
1045
know which numbers to use.
1046
 
1047
   A breakpoint, watchpoint, or catchpoint can have any of four
1048
different states of enablement:
1049
 
1050
   * Enabled.  The breakpoint stops your program.  A breakpoint set
1051
     with the `break' command starts out in this state.
1052
 
1053
   * Disabled.  The breakpoint has no effect on your program.
1054
 
1055
   * Enabled once.  The breakpoint stops your program, but then becomes
1056
     disabled.
1057
 
1058
   * Enabled for deletion.  The breakpoint stops your program, but
1059
     immediately after it does so it is deleted permanently.  A
1060
     breakpoint set with the `tbreak' command starts out in this state.
1061
 
1062
   You can use the following commands to enable or disable breakpoints,
1063
watchpoints, and catchpoints:
1064
 
1065
`disable [breakpoints] [RANGE...]'
1066
     Disable the specified breakpoints--or all breakpoints, if none are
1067
     listed.  A disabled breakpoint has no effect but is not forgotten.
1068
     All options such as ignore-counts, conditions and commands are
1069
     remembered in case the breakpoint is enabled again later.  You may
1070
     abbreviate `disable' as `dis'.
1071
 
1072
`enable [breakpoints] [RANGE...]'
1073
     Enable the specified breakpoints (or all defined breakpoints).
1074
     They become effective once again in stopping your program.
1075
 
1076
`enable [breakpoints] once RANGE...'
1077
     Enable the specified breakpoints temporarily.  GDB disables any of
1078
     these breakpoints immediately after stopping your program.
1079
 
1080
`enable [breakpoints] delete RANGE...'
1081
     Enable the specified breakpoints to work once, then die.  GDB
1082
     deletes any of these breakpoints as soon as your program stops
1083
     there.
1084
 
1085
   Except for a breakpoint set with `tbreak' (*note Setting
1086
breakpoints: Set Breaks.), breakpoints that you set are initially
1087
enabled; subsequently, they become disabled or enabled only when you
1088
use one of the commands above.  (The command `until' can set and delete
1089
a breakpoint of its own, but it does not change the state of your other
1090
breakpoints; see *Note Continuing and stepping: Continuing and
1091
Stepping.)
1092
 

powered by: WebSVN 2.1.0

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