1 This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
2 the input file gdb.texinfo.
5 * Gdb: (gdb). The GNU debugger.
7 This file documents the GNU debugger GDB.
9 This is the Seventh Edition, February 1999, of `Debugging with GDB:
10 the GNU Source-Level Debugger' for GDB Version 4.18.
12 Copyright (C) 1988-1999 Free Software Foundation, Inc.
14 Permission is granted to make and distribute verbatim copies of this
15 manual provided the copyright notice and this permission notice are
16 preserved on all copies.
18 Permission is granted to copy and distribute modified versions of
19 this manual under the conditions for verbatim copying, provided also
20 that the entire resulting derived work is distributed under the terms
21 of a permission notice identical to this one.
23 Permission is granted to copy and distribute translations of this
24 manual into another language, under the above conditions for modified
28 File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
35 Use the `run' command to start your program under GDB. You must
36 first specify the program name (except on VxWorks) with an
37 argument to GDB (*note Getting In and Out of GDB: Invocation.), or
38 by using the `file' or `exec-file' command (*note Commands to
39 specify files: Files.).
41 If you are running your program in an execution environment that
42 supports processes, `run' creates an inferior process and makes that
43 process run your program. (In environments without processes, `run'
44 jumps to the start of your program.)
46 The execution of a program is affected by certain information it
47 receives from its superior. GDB provides ways to specify this
48 information, which you must do *before* starting your program. (You
49 can change it after starting your program, but such changes only affect
50 your program the next time you start it.) This information may be
51 divided into four categories:
54 Specify the arguments to give your program as the arguments of the
55 `run' command. If a shell is available on your target, the shell
56 is used to pass the arguments, so that you may use normal
57 conventions (such as wildcard expansion or variable substitution)
58 in describing the arguments. In Unix systems, you can control
59 which shell is used with the `SHELL' environment variable. *Note
60 Your program's arguments: Arguments.
63 Your program normally inherits its environment from GDB, but you
64 can use the GDB commands `set environment' and `unset environment'
65 to change parts of the environment that affect your program.
66 *Note Your program's environment: Environment.
68 The *working directory.*
69 Your program inherits its working directory from GDB. You can set
70 the GDB working directory with the `cd' command in GDB. *Note
71 Your program's working directory: Working Directory.
73 The *standard input and output.*
74 Your program normally uses the same device for standard input and
75 standard output as GDB is using. You can redirect input and output
76 in the `run' command line, or you can use the `tty' command to set
77 a different device for your program. *Note Your program's input
78 and output: Input/Output.
80 *Warning:* While input and output redirection work, you cannot use
81 pipes to pass the output of the program you are debugging to
82 another program; if you attempt this, GDB is likely to wind up
83 debugging the wrong program.
85 When you issue the `run' command, your program begins to execute
86 immediately. *Note Stopping and continuing: Stopping, for discussion
87 of how to arrange for your program to stop. Once your program has
88 stopped, you may call functions in your program, using the `print' or
89 `call' commands. *Note Examining Data: Data.
91 If the modification time of your symbol file has changed since the
92 last time GDB read its symbols, GDB discards its symbol table, and
93 reads it again. When it does this, GDB tries to retain your current
97 File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
99 Your program's arguments
100 ========================
102 The arguments to your program can be specified by the arguments of
103 the `run' command. They are passed to a shell, which expands wildcard
104 characters and performs redirection of I/O, and thence to your program.
105 Your `SHELL' environment variable (if it exists) specifies what shell
106 GDB uses. If you do not define `SHELL', GDB uses `/bin/sh'.
108 `run' with no arguments uses the same arguments used by the previous
109 `run', or those set by the `set args' command.
112 Specify the arguments to be used the next time your program is
113 run. If `set args' has no arguments, `run' executes your program
114 with no arguments. Once you have run your program with arguments,
115 using `set args' before the next `run' is the only way to run it
116 again without arguments.
119 Show the arguments to give your program when it is started.
122 File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running
124 Your program's environment
125 ==========================
127 The "environment" consists of a set of environment variables and
128 their values. Environment variables conventionally record such things
129 as your user name, your home directory, your terminal type, and your
130 search path for programs to run. Usually you set up environment
131 variables with the shell and they are inherited by all the other
132 programs you run. When debugging, it can be useful to try running your
133 program with a modified environment without having to start GDB over
137 Add DIRECTORY to the front of the `PATH' environment variable (the
138 search path for executables), for both GDB and your program. You
139 may specify several directory names, separated by `:' or
140 whitespace. If DIRECTORY is already in the path, it is moved to
141 the front, so it is searched sooner.
143 You can use the string `$cwd' to refer to whatever is the current
144 working directory at the time GDB searches the path. If you use
145 `.' instead, it refers to the directory where you executed the
146 `path' command. GDB replaces `.' in the DIRECTORY argument (with
147 the current path) before adding DIRECTORY to the search path.
150 Display the list of search paths for executables (the `PATH'
151 environment variable).
153 `show environment [VARNAME]'
154 Print the value of environment variable VARNAME to be given to
155 your program when it starts. If you do not supply VARNAME, print
156 the names and values of all environment variables to be given to
157 your program. You can abbreviate `environment' as `env'.
159 `set environment VARNAME [=] VALUE'
160 Set environment variable VARNAME to VALUE. The value changes for
161 your program only, not for GDB itself. VALUE may be any string;
162 the values of environment variables are just strings, and any
163 interpretation is supplied by your program itself. The VALUE
164 parameter is optional; if it is eliminated, the variable is set to
167 For example, this command:
171 tells a Unix program, when subsequently run, that its user is named
172 `foo'. (The spaces around `=' are used for clarity here; they are
173 not actually required.)
175 `unset environment VARNAME'
176 Remove variable VARNAME from the environment to be passed to your
177 program. This is different from `set env VARNAME ='; `unset
178 environment' removes the variable from the environment, rather
179 than assigning it an empty value.
181 *Warning:* GDB runs your program using the shell indicated by your
182 `SHELL' environment variable if it exists (or `/bin/sh' if not). If
183 your `SHELL' variable names a shell that runs an initialization
184 file--such as `.cshrc' for C-shell, or `.bashrc' for BASH--any
185 variables you set in that file affect your program. You may wish to
186 move setting of environment variables to files that are only run when
187 you sign on, such as `.login' or `.profile'.
190 File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running
192 Your program's working directory
193 ================================
195 Each time you start your program with `run', it inherits its working
196 directory from the current working directory of GDB. The GDB working
197 directory is initially whatever it inherited from its parent process
198 (typically the shell), but you can specify a new working directory in
199 GDB with the `cd' command.
201 The GDB working directory also serves as a default for the commands
202 that specify files for GDB to operate on. *Note Commands to specify
206 Set the GDB working directory to DIRECTORY.
209 Print the GDB working directory.
212 File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running
214 Your program's input and output
215 ===============================
217 By default, the program you run under GDB does input and output to
218 the same terminal that GDB uses. GDB switches the terminal to its own
219 terminal modes to interact with you, but it records the terminal modes
220 your program was using and switches back to them when you continue
221 running your program.
224 Displays information recorded by GDB about the terminal modes your
227 You can redirect your program's input and/or output using shell
228 redirection with the `run' command. For example,
232 starts your program, diverting its output to the file `outfile'.
234 Another way to specify where your program should do input and output
235 is with the `tty' command. This command accepts a file name as
236 argument, and causes this file to be the default for future `run'
237 commands. It also resets the controlling terminal for the child
238 process, for future `run' commands. For example,
242 directs that processes started with subsequent `run' commands default
243 to do input and output on the terminal `/dev/ttyb' and have that as
244 their controlling terminal.
246 An explicit redirection in `run' overrides the `tty' command's
247 effect on the input/output device, but not its effect on the controlling
250 When you use the `tty' command or redirect input in the `run'
251 command, only the input *for your program* is affected. The input for
252 GDB still comes from your terminal.
255 File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running
257 Debugging an already-running process
258 ====================================
261 This command attaches to a running process--one that was started
262 outside GDB. (`info files' shows your active targets.) The
263 command takes as argument a process ID. The usual way to find out
264 the process-id of a Unix process is with the `ps' utility, or with
265 the `jobs -l' shell command.
267 `attach' does not repeat if you press <RET> a second time after
268 executing the command.
270 To use `attach', your program must be running in an environment
271 which supports processes; for example, `attach' does not work for
272 programs on bare-board targets that lack an operating system. You must
273 also have permission to send the process a signal.
275 When you use `attach', the debugger finds the program running in the
276 process first by looking in the current working directory, then (if the
277 program is not found) by using the source file search path (*note
278 Specifying source directories: Source Path.). You can also use the
279 `file' command to load the program. *Note Commands to Specify Files:
282 The first thing GDB does after arranging to debug the specified
283 process is to stop it. You can examine and modify an attached process
284 with all the GDB commands that are ordinarily available when you start
285 processes with `run'. You can insert breakpoints; you can step and
286 continue; you can modify storage. If you would rather the process
287 continue running, you may use the `continue' command after attaching
291 When you have finished debugging the attached process, you can use
292 the `detach' command to release it from GDB control. Detaching
293 the process continues its execution. After the `detach' command,
294 that process and GDB become completely independent once more, and
295 you are ready to `attach' another process or start one with `run'.
296 `detach' does not repeat if you press <RET> again after executing
299 If you exit GDB or use the `run' command while you have an attached
300 process, you kill that process. By default, GDB asks for confirmation
301 if you try to do either of these things; you can control whether or not
302 you need to confirm by using the `set confirm' command (*note Optional
303 warnings and messages: Messages/Warnings.).
306 File: gdb.info, Node: Kill Process, Next: Process Information, Prev: Attach, Up: Running
308 Killing the child process
309 =========================
312 Kill the child process in which your program is running under GDB.
314 This command is useful if you wish to debug a core dump instead of a
315 running process. GDB ignores any core dump file while your program is
318 On some operating systems, a program cannot be executed outside GDB
319 while you have breakpoints set on it inside GDB. You can use the
320 `kill' command in this situation to permit running your program outside
323 The `kill' command is also useful if you wish to recompile and
324 relink your program, since on many systems it is impossible to modify an
325 executable file while it is running in a process. In this case, when
326 you next type `run', GDB notices that the file has changed, and reads
327 the symbol table again (while trying to preserve your current
328 breakpoint settings).
331 File: gdb.info, Node: Process Information, Next: Threads, Prev: Kill Process, Up: Running
333 Additional process information
334 ==============================
336 Some operating systems provide a facility called `/proc' that can be
337 used to examine the image of a running process using file-system
338 subroutines. If GDB is configured for an operating system with this
339 facility, the command `info proc' is available to report on several
340 kinds of information about the process running your program. `info
341 proc' works only on SVR4 systems that support `procfs'.
344 Summarize available information about the process.
347 Report on the address ranges accessible in the program, with
348 information on whether your program may read, write, or execute
352 Starting time, user CPU time, and system CPU time for your program
356 Report on the process IDs related to your program: its own process
357 ID, the ID of its parent, the process group ID, and the session ID.
360 General information on the state of the process. If the process is
361 stopped, this report includes the reason for stopping, and any
365 Show all the above information about the process.
368 File: gdb.info, Node: Threads, Next: Processes, Prev: Process Information, Up: Running
370 Debugging programs with multiple threads
371 ========================================
373 In some operating systems, such as HP-UX and Solaris, a single
374 program may have more than one "thread" of execution. The precise
375 semantics of threads differ from one operating system to another, but
376 in general the threads of a single program are akin to multiple
377 processes--except that they share one address space (that is, they can
378 all examine and modify the same variables). On the other hand, each
379 thread has its own registers and execution stack, and perhaps private
382 GDB provides these facilities for debugging multi-thread programs:
384 * automatic notification of new threads
386 * `thread THREADNO', a command to switch among threads
388 * `info threads', a command to inquire about existing threads
390 * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command
393 * thread-specific breakpoints
395 *Warning:* These facilities are not yet available on every GDB
396 configuration where the operating system supports threads. If
397 your GDB does not support threads, these commands have no effect.
398 For example, a system without thread support shows no output from
399 `info threads', and always rejects the `thread' command, like this:
403 Thread ID 1 not known. Use the "info threads" command to
404 see the IDs of currently known threads.
406 The GDB thread debugging facility allows you to observe all threads
407 while your program runs--but whenever GDB takes control, one thread in
408 particular is always the focus of debugging. This thread is called the
409 "current thread". Debugging commands show program information from the
410 perspective of the current thread.
412 Whenever GDB detects a new thread in your program, it displays the
413 target system's identification for the thread with a message in the
414 form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies
415 depending on the particular system. For example, on LynxOS, you might
418 [New process 35 thread 27]
420 when GDB notices a new thread. In contrast, on an SGI system, the
421 SYSTAG is simply something like `process 368', with no further
424 For debugging purposes, GDB associates its own thread number--always
425 a single integer--with each thread in your program.
428 Display a summary of all threads currently in your program. GDB
429 displays for each thread (in this order):
431 1. the thread number assigned by GDB
433 2. the target system's thread identifier (SYSTAG)
435 3. the current stack frame summary for that thread
437 An asterisk `*' to the left of the GDB thread number indicates the
443 3 process 35 thread 27 0x34e5 in sigpause ()
444 2 process 35 thread 23 0x34e5 in sigpause ()
445 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
449 Make thread number THREADNO the current thread. The command
450 argument THREADNO is the internal GDB thread number, as shown in
451 the first field of the `info threads' display. GDB responds by
452 displaying the system identifier of the thread you selected, and
453 its current stack frame summary:
456 [Switching to process 35 thread 23]
457 0x34e5 in sigpause ()
459 As with the `[New ...]' message, the form of the text after
460 `Switching to' depends on your system's conventions for identifying
463 `thread apply [THREADNO] [ALL] ARGS'
464 The `thread apply' command allows you to apply a command to one or
465 more threads. Specify the numbers of the threads that you want
466 affected with the command argument THREADNO. THREADNO is the
467 internal GDB thread number, as shown in the first field of the
468 `info threads' display. To apply a command to all threads, use
469 `thread apply all' ARGS.
471 Whenever GDB stops your program, due to a breakpoint or a signal, it
472 automatically selects the thread where that breakpoint or signal
473 happened. GDB alerts you to the context switch with a message of the
474 form `[Switching to SYSTAG]' to identify the thread.
476 *Note Stopping and starting multi-thread programs: Thread Stops, for
477 more information about how GDB behaves when you stop and start programs
478 with multiple threads.
480 *Note Setting watchpoints: Set Watchpoints, for information about
481 watchpoints in programs with multiple threads.
484 File: gdb.info, Node: Processes, Prev: Threads, Up: Running
486 Debugging programs with multiple processes
487 ==========================================
489 GDB has no special support for debugging programs which create
490 additional processes using the `fork' function. When a program forks,
491 GDB will continue to debug the parent process and the child process
492 will run unimpeded. If you have set a breakpoint in any code which the
493 child then executes, the child will get a `SIGTRAP' signal which
494 (unless it catches the signal) will cause it to terminate.
496 However, if you want to debug the child process there is a workaround
497 which isn't too painful. Put a call to `sleep' in the code which the
498 child process executes after the fork. It may be useful to sleep only
499 if a certain environment variable is set, or a certain file exists, so
500 that the delay need not occur when you don't want to run GDB on the
501 child. While the child is sleeping, use the `ps' program to get its
502 process ID. Then tell GDB (a new invocation of GDB if you are also
503 debugging the parent process) to attach to the child process (see *Note
504 Attach::). From that point on you can debug the child process just
505 like any other process which you attached to.
508 File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top
510 Stopping and Continuing
511 ***********************
513 The principal purposes of using a debugger are so that you can stop
514 your program before it terminates; or so that, if your program runs into
515 trouble, you can investigate and find out why.
517 Inside GDB, your program may stop for any of several reasons, such as
518 a signal, a breakpoint, or reaching a new line after a GDB command such
519 as `step'. You may then examine and change variables, set new
520 breakpoints or remove old ones, and then continue execution. Usually,
521 the messages shown by GDB provide ample explanation of the status of
522 your program--but you can also explicitly request this information at
526 Display information about the status of your program: whether it is
527 running or not, what process it is, and why it stopped.
531 * Breakpoints:: Breakpoints, watchpoints, and catchpoints
532 * Continuing and Stepping:: Resuming execution
537 * Thread Stops:: Stopping and starting multi-thread programs
540 File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Prev: Stopping, Up: Stopping
542 Breakpoints, watchpoints, and catchpoints
543 =========================================
545 A "breakpoint" makes your program stop whenever a certain point in
546 the program is reached. For each breakpoint, you can add conditions to
547 control in finer detail whether your program stops. You can set
548 breakpoints with the `break' command and its variants (*note Setting
549 breakpoints: Set Breaks.), to specify the place where your program
550 should stop by line number, function name or exact address in the
553 In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can
554 set breakpoints in shared libraries before the executable is run.
555 There is a minor limitation on HP-UX systems: you must wait until the
556 executable is run in order to set breakpoints in shared library
557 routines that are not called directly by the program (for example,
558 routines that are arguments in a `pthread_create' call).
560 A "watchpoint" is a special breakpoint that stops your program when
561 the value of an expression changes. You must use a different command
562 to set watchpoints (*note Setting watchpoints: Set Watchpoints.), but
563 aside from that, you can manage a watchpoint like any other breakpoint:
564 you enable, disable, and delete both breakpoints and watchpoints using
567 You can arrange to have values from your program displayed
568 automatically whenever GDB stops at a breakpoint. *Note Automatic
569 display: Auto Display.
571 A "catchpoint" is another special breakpoint that stops your program
572 when a certain kind of event occurs, such as the throwing of a C++
573 exception or the loading of a library. As with watchpoints, you use a
574 different command to set a catchpoint (*note Setting catchpoints: Set
575 Catchpoints.), but aside from that, you can manage a catchpoint like any
576 other breakpoint. (To stop when your program receives a signal, use the
577 `handle' command; *note Signals: Signals..)
579 GDB assigns a number to each breakpoint, watchpoint, or catchpoint
580 when you create it; these numbers are successive integers starting with
581 one. In many of the commands for controlling various features of
582 breakpoints you use the breakpoint number to say which breakpoint you
583 want to change. Each breakpoint may be "enabled" or "disabled"; if
584 disabled, it has no effect on your program until you enable it again.
588 * Set Breaks:: Setting breakpoints
589 * Set Watchpoints:: Setting watchpoints
590 * Set Catchpoints:: Setting catchpoints
591 * Delete Breaks:: Deleting breakpoints
592 * Disabling:: Disabling breakpoints
593 * Conditions:: Break conditions
594 * Break Commands:: Breakpoint command lists
596 * Breakpoint Menus:: Breakpoint menus
599 File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Prev: Breakpoints, Up: Breakpoints
604 Breakpoints are set with the `break' command (abbreviated `b'). The
605 debugger convenience variable `$bpnum' records the number of the
606 breakpoints you've set most recently; see *Note Convenience variables:
607 Convenience Vars, for a discussion of what you can do with convenience
610 You have several ways to say where the breakpoint should go.
613 Set a breakpoint at entry to function FUNCTION. When using source
614 languages that permit overloading of symbols, such as C++,
615 FUNCTION may refer to more than one possible place to break.
616 *Note Breakpoint menus: Breakpoint Menus, for a discussion of that
621 Set a breakpoint some number of lines forward or back from the
622 position at which execution stopped in the currently selected
626 Set a breakpoint at line LINENUM in the current source file. That
627 file is the last file whose source text was printed. This
628 breakpoint stops your program just before it executes any of the
631 `break FILENAME:LINENUM'
632 Set a breakpoint at line LINENUM in source file FILENAME.
634 `break FILENAME:FUNCTION'
635 Set a breakpoint at entry to function FUNCTION found in file
636 FILENAME. Specifying a file name as well as a function name is
637 superfluous except when multiple files contain similarly named
641 Set a breakpoint at address ADDRESS. You can use this to set
642 breakpoints in parts of your program which do not have debugging
643 information or source files.
646 When called without any arguments, `break' sets a breakpoint at
647 the next instruction to be executed in the selected stack frame
648 (*note Examining the Stack: Stack.). In any selected frame but the
649 innermost, this makes your program stop as soon as control returns
650 to that frame. This is similar to the effect of a `finish'
651 command in the frame inside the selected frame--except that
652 `finish' does not leave an active breakpoint. If you use `break'
653 without an argument in the innermost frame, GDB stops the next
654 time it reaches the current location; this may be useful inside
657 GDB normally ignores breakpoints when it resumes execution, until
658 at least one instruction has been executed. If it did not do
659 this, you would be unable to proceed past a breakpoint without
660 first disabling the breakpoint. This rule applies whether or not
661 the breakpoint already existed when your program stopped.
664 Set a breakpoint with condition COND; evaluate the expression COND
665 each time the breakpoint is reached, and stop only if the value is
666 nonzero--that is, if COND evaluates as true. `...' stands for one
667 of the possible arguments described above (or no argument)
668 specifying where to break. *Note Break conditions: Conditions,
669 for more information on breakpoint conditions.
672 Set a breakpoint enabled only for one stop. ARGS are the same as
673 for the `break' command, and the breakpoint is set in the same
674 way, but the breakpoint is automatically deleted after the first
675 time your program stops there. *Note Disabling breakpoints:
679 Set a hardware-assisted breakpoint. ARGS are the same as for the
680 `break' command and the breakpoint is set in the same way, but the
681 breakpoint requires hardware support and some target hardware may
682 not have this support. The main purpose of this is EPROM/ROM code
683 debugging, so you can set a breakpoint at an instruction without
684 changing the instruction. This can be used with the new
685 trap-generation provided by SPARClite DSU. DSU will generate
686 traps when a program accesses some data or instruction address
687 that is assigned to the debug registers. However the hardware
688 breakpoint registers can only take two data breakpoints, and GDB
689 will reject this command if more than two are used. Delete or
690 disable unused hardware breakpoints before setting new ones.
691 *Note Break conditions: Conditions.
694 Set a hardware-assisted breakpoint enabled only for one stop. ARGS
695 are the same as for the `hbreak' command and the breakpoint is set
696 in the same way. However, like the `tbreak' command, the
697 breakpoint is automatically deleted after the first time your
698 program stops there. Also, like the `hbreak' command, the
699 breakpoint requires hardware support and some target hardware may
700 not have this support. *Note Disabling breakpoints: Disabling.
701 Also *Note Break conditions: Conditions.
704 Set breakpoints on all functions matching the regular expression
705 REGEX. This command sets an unconditional breakpoint on all
706 matches, printing a list of all breakpoints it set. Once these
707 breakpoints are set, they are treated just like the breakpoints
708 set with the `break' command. You can delete them, disable them,
709 or make them conditional the same way as any other breakpoint.
711 When debugging C++ programs, `rbreak' is useful for setting
712 breakpoints on overloaded functions that are not members of any
715 `info breakpoints [N]'
717 `info watchpoints [N]'
718 Print a table of all breakpoints, watchpoints, and catchpoints set
719 and not deleted, with the following columns for each breakpoint:
724 Breakpoint, watchpoint, or catchpoint.
727 Whether the breakpoint is marked to be disabled or deleted
730 *Enabled or Disabled*
731 Enabled breakpoints are marked with `y'. `n' marks
732 breakpoints that are not enabled.
735 Where the breakpoint is in your program, as a memory address
738 Where the breakpoint is in the source for your program, as a
739 file and line number.
741 If a breakpoint is conditional, `info break' shows the condition on
742 the line following the affected breakpoint; breakpoint commands,
743 if any, are listed after that.
745 `info break' with a breakpoint number N as argument lists only
746 that breakpoint. The convenience variable `$_' and the default
747 examining-address for the `x' command are set to the address of
748 the last breakpoint listed (*note Examining memory: Memory.).
750 `info break' displays a count of the number of times the breakpoint
751 has been hit. This is especially useful in conjunction with the
752 `ignore' command. You can ignore a large number of breakpoint
753 hits, look at the breakpoint info to see how many times the
754 breakpoint was hit, and then run again, ignoring one less than
755 that number. This will get you quickly to the last hit of that
758 GDB allows you to set any number of breakpoints at the same place in
759 your program. There is nothing silly or meaningless about this. When
760 the breakpoints are conditional, this is even useful (*note Break
761 conditions: Conditions.).
763 GDB itself sometimes sets breakpoints in your program for special
764 purposes, such as proper handling of `longjmp' (in C programs). These
765 internal breakpoints are assigned negative numbers, starting with `-1';
766 `info breakpoints' does not display them.
768 You can see these breakpoints with the GDB maintenance command
769 `maint info breakpoints'.
771 `maint info breakpoints'
772 Using the same format as `info breakpoints', display both the
773 breakpoints you've set explicitly, and those GDB is using for
774 internal purposes. Internal breakpoints are shown with negative
775 breakpoint numbers. The type column identifies what kind of
779 Normal, explicitly set breakpoint.
782 Normal, explicitly set watchpoint.
785 Internal breakpoint, used to handle correctly stepping through
789 Internal breakpoint at the target of a `longjmp'.
792 Temporary internal breakpoint used by the GDB `until' command.
795 Temporary internal breakpoint used by the GDB `finish'
799 File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints
804 You can use a watchpoint to stop execution whenever the value of an
805 expression changes, without having to predict a particular place where
808 Depending on your system, watchpoints may be implemented in software
809 or hardware. GDB does software watchpointing by single-stepping your
810 program and testing the variable's value each time, which is hundreds of
811 times slower than normal execution. (But this may still be worth it, to
812 catch errors where you have no clue what part of your program is the
815 On some systems, such as HP-UX and Linux, GDB includes support for
816 hardware watchpoints, which do not slow down the running of your
820 Set a watchpoint for an expression. GDB will break when EXPR is
821 written into by the program and its value changes.
824 Set a watchpoint that will break when watch EXPR is read by the
825 program. If you use both watchpoints, both must be set with the
829 Set a watchpoint that will break when ARGS is read and written into
830 by the program. If you use both watchpoints, both must be set
831 with the `awatch' command.
834 This command prints a list of watchpoints, breakpoints, and
835 catchpoints; it is the same as `info break'.
837 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints
838 execute very quickly, and the debugger reports a change in value at the
839 exact instruction where the change occurs. If GDB cannot set a
840 hardware watchpoint, it sets a software watchpoint, which executes more
841 slowly and reports the change in value at the next statement, not the
842 instruction, after the change occurs.
844 When you issue the `watch' command, GDB reports
846 Hardware watchpoint NUM: EXPR
848 if it was able to set a hardware watchpoint.
850 The SPARClite DSU will generate traps when a program accesses some
851 data or instruction address that is assigned to the debug registers.
852 For the data addresses, DSU facilitates the `watch' command. However
853 the hardware breakpoint registers can only take two data watchpoints,
854 and both watchpoints must be the same kind. For example, you can set
855 two watchpoints with `watch' commands, two with `rwatch' commands, *or*
856 two with `awatch' commands, but you cannot set one watchpoint with one
857 command and the other with a different command. GDB will reject the
858 command if you try to mix watchpoints. Delete or disable unused
859 watchpoint commands before setting new ones.
861 If you call a function interactively using `print' or `call', any
862 watchpoints you have set will be inactive until GDB reaches another
863 kind of breakpoint or the call completes.
865 *Warning:* In multi-thread programs, watchpoints have only limited
866 usefulness. With the current watchpoint implementation, GDB can
867 only watch the value of an expression *in a single thread*. If
868 you are confident that the expression can only change due to the
869 current thread's activity (and if you are also confident that no
870 other thread can become current), then you can use watchpoints as
871 usual. However, GDB may not notice when a non-current thread's
872 activity changes the expression.
875 File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints
880 You can use "catchpoints" to cause the debugger to stop for certain
881 kinds of program events, such as C++ exceptions or the loading of a
882 shared library. Use the `catch' command to set a catchpoint.
885 Stop when EVENT occurs. EVENT can be any of the following:
887 The throwing of a C++ exception.
890 The catching of a C++ exception.
893 A call to `exec'. This is currently only available for HP-UX.
896 A call to `fork'. This is currently only available for HP-UX.
899 A call to `vfork'. This is currently only available for
904 The dynamic loading of any shared library, or the loading of
905 the library LIBNAME. This is currently only available for
910 The unloading of any dynamically loaded shared library, or
911 the unloading of the library LIBNAME. This is currently only
915 Set a catchpoint that is enabled only for one stop. The
916 catchpoint is automatically deleted after the first time the event
919 Use the `info break' command to list the current catchpoints.
921 There are currently some limitations to C++ exception handling
922 (`catch throw' and `catch catch') in GDB:
924 * If you call a function interactively, GDB normally returns control
925 to you when the function has finished executing. If the call
926 raises an exception, however, the call may bypass the mechanism
927 that returns control to you and cause your program either to abort
928 or to simply continue running until it hits a breakpoint, catches
929 a signal that GDB is listening for, or exits. This is the case
930 even if you set a catchpoint for the exception; catchpoints on
931 exceptions are disabled within interactive calls.
933 * You cannot raise an exception interactively.
935 * You cannot install an exception handler interactively.
937 Sometimes `catch' is not the best way to debug exception handling:
938 if you need to know exactly where an exception is raised, it is better
939 to stop *before* the exception handler is called, since that way you
940 can see the stack before any unwinding takes place. If you set a
941 breakpoint in an exception handler instead, it may not be easy to find
942 out where the exception was raised.
944 To stop just before an exception handler is called, you need some
945 knowledge of the implementation. In the case of GNU C++, exceptions are
946 raised by calling a library function named `__raise_exception' which
947 has the following ANSI C interface:
949 /* ADDR is where the exception identifier is stored.
950 ID is the exception identifier. */
951 void __raise_exception (void **ADDR, void *ID);
953 To make the debugger catch all exceptions before any stack unwinding
954 takes place, set a breakpoint on `__raise_exception' (*note
955 Breakpoints; watchpoints; and exceptions: Breakpoints.).
957 With a conditional breakpoint (*note Break conditions: Conditions.)
958 that depends on the value of ID, you can stop your program when a
959 specific exception is raised. You can use multiple conditional
960 breakpoints to stop your program when any of a number of exceptions are
964 File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints
969 It is often necessary to eliminate a breakpoint, watchpoint, or
970 catchpoint once it has done its job and you no longer want your program
971 to stop there. This is called "deleting" the breakpoint. A breakpoint
972 that has been deleted no longer exists; it is forgotten.
974 With the `clear' command you can delete breakpoints according to
975 where they are in your program. With the `delete' command you can
976 delete individual breakpoints, watchpoints, or catchpoints by specifying
977 their breakpoint numbers.
979 It is not necessary to delete a breakpoint to proceed past it. GDB
980 automatically ignores breakpoints on the first instruction to be
981 executed when you continue execution without changing the execution
985 Delete any breakpoints at the next instruction to be executed in
986 the selected stack frame (*note Selecting a frame: Selection.).
987 When the innermost frame is selected, this is a good way to delete
988 a breakpoint where your program just stopped.
991 `clear FILENAME:FUNCTION'
992 Delete any breakpoints set at entry to the function FUNCTION.
995 `clear FILENAME:LINENUM'
996 Delete any breakpoints set at or within the code of the specified
999 `delete [breakpoints] [BNUMS...]'
1000 Delete the breakpoints, watchpoints, or catchpoints of the numbers
1001 specified as arguments. If no argument is specified, delete all
1002 breakpoints (GDB asks confirmation, unless you have `set confirm
1003 off'). You can abbreviate this command as `d'.
1006 File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints
1008 Disabling breakpoints
1009 ---------------------
1011 Rather than deleting a breakpoint, watchpoint, or catchpoint, you
1012 might prefer to "disable" it. This makes the breakpoint inoperative as
1013 if it had been deleted, but remembers the information on the breakpoint
1014 so that you can "enable" it again later.
1016 You disable and enable breakpoints, watchpoints, and catchpoints with
1017 the `enable' and `disable' commands, optionally specifying one or more
1018 breakpoint numbers as arguments. Use `info break' or `info watch' to
1019 print a list of breakpoints, watchpoints, and catchpoints if you do not
1020 know which numbers to use.
1022 A breakpoint, watchpoint, or catchpoint can have any of four
1023 different states of enablement:
1025 * Enabled. The breakpoint stops your program. A breakpoint set
1026 with the `break' command starts out in this state.
1028 * Disabled. The breakpoint has no effect on your program.
1030 * Enabled once. The breakpoint stops your program, but then becomes
1031 disabled. A breakpoint set with the `tbreak' command starts out in
1034 * Enabled for deletion. The breakpoint stops your program, but
1035 immediately after it does so it is deleted permanently.
1037 You can use the following commands to enable or disable breakpoints,
1038 watchpoints, and catchpoints:
1040 `disable [breakpoints] [BNUMS...]'
1041 Disable the specified breakpoints--or all breakpoints, if none are
1042 listed. A disabled breakpoint has no effect but is not forgotten.
1043 All options such as ignore-counts, conditions and commands are
1044 remembered in case the breakpoint is enabled again later. You may
1045 abbreviate `disable' as `dis'.
1047 `enable [breakpoints] [BNUMS...]'
1048 Enable the specified breakpoints (or all defined breakpoints).
1049 They become effective once again in stopping your program.
1051 `enable [breakpoints] once BNUMS...'
1052 Enable the specified breakpoints temporarily. GDB disables any of
1053 these breakpoints immediately after stopping your program.
1055 `enable [breakpoints] delete BNUMS...'
1056 Enable the specified breakpoints to work once, then die. GDB
1057 deletes any of these breakpoints as soon as your program stops
1060 Except for a breakpoint set with `tbreak' (*note Setting
1061 breakpoints: Set Breaks.), breakpoints that you set are initially
1062 enabled; subsequently, they become disabled or enabled only when you
1063 use one of the commands above. (The command `until' can set and delete
1064 a breakpoint of its own, but it does not change the state of your other
1065 breakpoints; see *Note Continuing and stepping: Continuing and
1069 File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints
1074 The simplest sort of breakpoint breaks every time your program
1075 reaches a specified place. You can also specify a "condition" for a
1076 breakpoint. A condition is just a Boolean expression in your
1077 programming language (*note Expressions: Expressions.). A breakpoint
1078 with a condition evaluates the expression each time your program
1079 reaches it, and your program stops only if the condition is *true*.
1081 This is the converse of using assertions for program validation; in
1082 that situation, you want to stop when the assertion is violated--that
1083 is, when the condition is false. In C, if you want to test an
1084 assertion expressed by the condition ASSERT, you should set the
1085 condition `! ASSERT' on the appropriate breakpoint.
1087 Conditions are also accepted for watchpoints; you may not need them,
1088 since a watchpoint is inspecting the value of an expression anyhow--but
1089 it might be simpler, say, to just set a watchpoint on a variable name,
1090 and specify a condition that tests whether the new value is an
1093 Break conditions can have side effects, and may even call functions
1094 in your program. This can be useful, for example, to activate functions
1095 that log program progress, or to use your own print functions to format
1096 special data structures. The effects are completely predictable unless
1097 there is another enabled breakpoint at the same address. (In that
1098 case, GDB might see the other breakpoint first and stop your program
1099 without checking the condition of this one.) Note that breakpoint
1100 commands are usually more convenient and flexible for the purpose of
1101 performing side effects when a breakpoint is reached (*note Breakpoint
1102 command lists: Break Commands.).
1104 Break conditions can be specified when a breakpoint is set, by using
1105 `if' in the arguments to the `break' command. *Note Setting
1106 breakpoints: Set Breaks. They can also be changed at any time with the
1107 `condition' command. The `watch' command does not recognize the `if'
1108 keyword; `condition' is the only way to impose a further condition on a
1111 `condition BNUM EXPRESSION'
1112 Specify EXPRESSION as the break condition for breakpoint,
1113 watchpoint, or catchpoint number BNUM. After you set a condition,
1114 breakpoint BNUM stops your program only if the value of EXPRESSION
1115 is true (nonzero, in C). When you use `condition', GDB checks
1116 EXPRESSION immediately for syntactic correctness, and to determine
1117 whether symbols in it have referents in the context of your
1118 breakpoint. GDB does not actually evaluate EXPRESSION at the time
1119 the `condition' command is given, however. *Note Expressions:
1123 Remove the condition from breakpoint number BNUM. It becomes an
1124 ordinary unconditional breakpoint.
1126 A special case of a breakpoint condition is to stop only when the
1127 breakpoint has been reached a certain number of times. This is so
1128 useful that there is a special way to do it, using the "ignore count"
1129 of the breakpoint. Every breakpoint has an ignore count, which is an
1130 integer. Most of the time, the ignore count is zero, and therefore has
1131 no effect. But if your program reaches a breakpoint whose ignore count
1132 is positive, then instead of stopping, it just decrements the ignore
1133 count by one and continues. As a result, if the ignore count value is
1134 N, the breakpoint does not stop the next N times your program reaches
1138 Set the ignore count of breakpoint number BNUM to COUNT. The next
1139 COUNT times the breakpoint is reached, your program's execution
1140 does not stop; other than to decrement the ignore count, GDB takes
1143 To make the breakpoint stop the next time it is reached, specify a
1146 When you use `continue' to resume execution of your program from a
1147 breakpoint, you can specify an ignore count directly as an
1148 argument to `continue', rather than using `ignore'. *Note
1149 Continuing and stepping: Continuing and Stepping.
1151 If a breakpoint has a positive ignore count and a condition, the
1152 condition is not checked. Once the ignore count reaches zero, GDB
1153 resumes checking the condition.
1155 You could achieve the effect of the ignore count with a condition
1156 such as `$foo-- <= 0' using a debugger convenience variable that
1157 is decremented each time. *Note Convenience variables:
1160 Ignore counts apply to breakpoints, watchpoints, and catchpoints.
projects / external / binutils.git / blob