diff options
Diffstat (limited to 'gdb/doc/gdb.info-2')
| -rw-r--r-- | gdb/doc/gdb.info-2 | 1161 |
1 files changed, 1161 insertions, 0 deletions
diff --git a/gdb/doc/gdb.info-2 b/gdb/doc/gdb.info-2 new file mode 100644 index 0000000..ab5549f --- /dev/null +++ b/gdb/doc/gdb.info-2 @@ -0,0 +1,1161 @@ +This is Info file ./gdb.info, produced by Makeinfo version 1.68 from +the input file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is the Seventh Edition, February 1999, of `Debugging with GDB: +the GNU Source-Level Debugger' for GDB Version 4.18. + + Copyright (C) 1988-1999 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the entire resulting derived work is distributed under the terms +of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions. + + +File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running + +Starting your program +===================== + +`run' +`r' + Use the `run' command to start your program under GDB. You must + first specify the program name (except on VxWorks) with an + argument to GDB (*note Getting In and Out of GDB: Invocation.), or + by using the `file' or `exec-file' command (*note Commands to + specify files: Files.). + + If you are running your program in an execution environment that +supports processes, `run' creates an inferior process and makes that +process run your program. (In environments without processes, `run' +jumps to the start of your program.) + + The execution of a program is affected by certain information it +receives from its superior. GDB provides ways to specify this +information, which you must do *before* starting your program. (You +can change it after starting your program, but such changes only affect +your program the next time you start it.) This information may be +divided into four categories: + +The *arguments.* + Specify the arguments to give your program as the arguments of the + `run' command. If a shell is available on your target, the shell + is used to pass the arguments, so that you may use normal + conventions (such as wildcard expansion or variable substitution) + in describing the arguments. In Unix systems, you can control + which shell is used with the `SHELL' environment variable. *Note + Your program's arguments: Arguments. + +The *environment.* + Your program normally inherits its environment from GDB, but you + can use the GDB commands `set environment' and `unset environment' + to change parts of the environment that affect your program. + *Note Your program's environment: Environment. + +The *working directory.* + Your program inherits its working directory from GDB. You can set + the GDB working directory with the `cd' command in GDB. *Note + Your program's working directory: Working Directory. + +The *standard input and output.* + Your program normally uses the same device for standard input and + standard output as GDB is using. You can redirect input and output + in the `run' command line, or you can use the `tty' command to set + a different device for your program. *Note Your program's input + and output: Input/Output. + + *Warning:* While input and output redirection work, you cannot use + pipes to pass the output of the program you are debugging to + another program; if you attempt this, GDB is likely to wind up + debugging the wrong program. + + When you issue the `run' command, your program begins to execute +immediately. *Note Stopping and continuing: Stopping, for discussion +of how to arrange for your program to stop. Once your program has +stopped, you may call functions in your program, using the `print' or +`call' commands. *Note Examining Data: Data. + + If the modification time of your symbol file has changed since the +last time GDB read its symbols, GDB discards its symbol table, and +reads it again. When it does this, GDB tries to retain your current +breakpoints. + + +File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running + +Your program's arguments +======================== + + The arguments to your program can be specified by the arguments of +the `run' command. They are passed to a shell, which expands wildcard +characters and performs redirection of I/O, and thence to your program. +Your `SHELL' environment variable (if it exists) specifies what shell +GDB uses. If you do not define `SHELL', GDB uses `/bin/sh'. + + `run' with no arguments uses the same arguments used by the previous +`run', or those set by the `set args' command. + +`set args' + Specify the arguments to be used the next time your program is + run. If `set args' has no arguments, `run' executes your program + with no arguments. Once you have run your program with arguments, + using `set args' before the next `run' is the only way to run it + again without arguments. + +`show args' + Show the arguments to give your program when it is started. + + +File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running + +Your program's environment +========================== + + The "environment" consists of a set of environment variables and +their values. Environment variables conventionally record such things +as your user name, your home directory, your terminal type, and your +search path for programs to run. Usually you set up environment +variables with the shell and they are inherited by all the other +programs you run. When debugging, it can be useful to try running your +program with a modified environment without having to start GDB over +again. + +`path DIRECTORY' + Add DIRECTORY to the front of the `PATH' environment variable (the + search path for executables), for both GDB and your program. You + may specify several directory names, separated by `:' or + whitespace. If DIRECTORY is already in the path, it is moved to + the front, so it is searched sooner. + + You can use the string `$cwd' to refer to whatever is the current + working directory at the time GDB searches the path. If you use + `.' instead, it refers to the directory where you executed the + `path' command. GDB replaces `.' in the DIRECTORY argument (with + the current path) before adding DIRECTORY to the search path. + +`show paths' + Display the list of search paths for executables (the `PATH' + environment variable). + +`show environment [VARNAME]' + Print the value of environment variable VARNAME to be given to + your program when it starts. If you do not supply VARNAME, print + the names and values of all environment variables to be given to + your program. You can abbreviate `environment' as `env'. + +`set environment VARNAME [=] VALUE' + Set environment variable VARNAME to VALUE. The value changes for + your program only, not for GDB itself. VALUE may be any string; + the values of environment variables are just strings, and any + interpretation is supplied by your program itself. The VALUE + parameter is optional; if it is eliminated, the variable is set to + a null value. + + For example, this command: + + set env USER = foo + + tells a Unix program, when subsequently run, that its user is named + `foo'. (The spaces around `=' are used for clarity here; they are + not actually required.) + +`unset environment VARNAME' + Remove variable VARNAME from the environment to be passed to your + program. This is different from `set env VARNAME ='; `unset + environment' removes the variable from the environment, rather + than assigning it an empty value. + + *Warning:* GDB runs your program using the shell indicated by your +`SHELL' environment variable if it exists (or `/bin/sh' if not). If +your `SHELL' variable names a shell that runs an initialization +file--such as `.cshrc' for C-shell, or `.bashrc' for BASH--any +variables you set in that file affect your program. You may wish to +move setting of environment variables to files that are only run when +you sign on, such as `.login' or `.profile'. + + +File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running + +Your program's working directory +================================ + + Each time you start your program with `run', it inherits its working +directory from the current working directory of GDB. The GDB working +directory is initially whatever it inherited from its parent process +(typically the shell), but you can specify a new working directory in +GDB with the `cd' command. + + The GDB working directory also serves as a default for the commands +that specify files for GDB to operate on. *Note Commands to specify +files: Files. + +`cd DIRECTORY' + Set the GDB working directory to DIRECTORY. + +`pwd' + Print the GDB working directory. + + +File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running + +Your program's input and output +=============================== + + By default, the program you run under GDB does input and output to +the same terminal that GDB uses. GDB switches the terminal to its own +terminal modes to interact with you, but it records the terminal modes +your program was using and switches back to them when you continue +running your program. + +`info terminal' + Displays information recorded by GDB about the terminal modes your + program is using. + + You can redirect your program's input and/or output using shell +redirection with the `run' command. For example, + + run > outfile + +starts your program, diverting its output to the file `outfile'. + + Another way to specify where your program should do input and output +is with the `tty' command. This command accepts a file name as +argument, and causes this file to be the default for future `run' +commands. It also resets the controlling terminal for the child +process, for future `run' commands. For example, + + tty /dev/ttyb + +directs that processes started with subsequent `run' commands default +to do input and output on the terminal `/dev/ttyb' and have that as +their controlling terminal. + + An explicit redirection in `run' overrides the `tty' command's +effect on the input/output device, but not its effect on the controlling +terminal. + + When you use the `tty' command or redirect input in the `run' +command, only the input *for your program* is affected. The input for +GDB still comes from your terminal. + + +File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running + +Debugging an already-running process +==================================== + +`attach PROCESS-ID' + This command attaches to a running process--one that was started + outside GDB. (`info files' shows your active targets.) The + command takes as argument a process ID. The usual way to find out + the process-id of a Unix process is with the `ps' utility, or with + the `jobs -l' shell command. + + `attach' does not repeat if you press <RET> a second time after + executing the command. + + To use `attach', your program must be running in an environment +which supports processes; for example, `attach' does not work for +programs on bare-board targets that lack an operating system. You must +also have permission to send the process a signal. + + When you use `attach', the debugger finds the program running in the +process first by looking in the current working directory, then (if the +program is not found) by using the source file search path (*note +Specifying source directories: Source Path.). You can also use the +`file' command to load the program. *Note Commands to Specify Files: +Files. + + The first thing GDB does after arranging to debug the specified +process is to stop it. You can examine and modify an attached process +with all the GDB commands that are ordinarily available when you start +processes with `run'. You can insert breakpoints; you can step and +continue; you can modify storage. If you would rather the process +continue running, you may use the `continue' command after attaching +GDB to the process. + +`detach' + When you have finished debugging the attached process, you can use + the `detach' command to release it from GDB control. Detaching + the process continues its execution. After the `detach' command, + that process and GDB become completely independent once more, and + you are ready to `attach' another process or start one with `run'. + `detach' does not repeat if you press <RET> again after executing + the command. + + If you exit GDB or use the `run' command while you have an attached +process, you kill that process. By default, GDB asks for confirmation +if you try to do either of these things; you can control whether or not +you need to confirm by using the `set confirm' command (*note Optional +warnings and messages: Messages/Warnings.). + + +File: gdb.info, Node: Kill Process, Next: Process Information, Prev: Attach, Up: Running + +Killing the child process +========================= + +`kill' + Kill the child process in which your program is running under GDB. + + This command is useful if you wish to debug a core dump instead of a +running process. GDB ignores any core dump file while your program is +running. + + On some operating systems, a program cannot be executed outside GDB +while you have breakpoints set on it inside GDB. You can use the +`kill' command in this situation to permit running your program outside +the debugger. + + The `kill' command is also useful if you wish to recompile and +relink your program, since on many systems it is impossible to modify an +executable file while it is running in a process. In this case, when +you next type `run', GDB notices that the file has changed, and reads +the symbol table again (while trying to preserve your current +breakpoint settings). + + +File: gdb.info, Node: Process Information, Next: Threads, Prev: Kill Process, Up: Running + +Additional process information +============================== + + Some operating systems provide a facility called `/proc' that can be +used to examine the image of a running process using file-system +subroutines. If GDB is configured for an operating system with this +facility, the command `info proc' is available to report on several +kinds of information about the process running your program. `info +proc' works only on SVR4 systems that support `procfs'. + +`info proc' + Summarize available information about the process. + +`info proc mappings' + Report on the address ranges accessible in the program, with + information on whether your program may read, write, or execute + each range. + +`info proc times' + Starting time, user CPU time, and system CPU time for your program + and its children. + +`info proc id' + Report on the process IDs related to your program: its own process + ID, the ID of its parent, the process group ID, and the session ID. + +`info proc status' + General information on the state of the process. If the process is + stopped, this report includes the reason for stopping, and any + signal received. + +`info proc all' + Show all the above information about the process. + + +File: gdb.info, Node: Threads, Next: Processes, Prev: Process Information, Up: Running + +Debugging programs with multiple threads +======================================== + + In some operating systems, such as HP-UX and Solaris, a single +program may have more than one "thread" of execution. The precise +semantics of threads differ from one operating system to another, but +in general the threads of a single program are akin to multiple +processes--except that they share one address space (that is, they can +all examine and modify the same variables). On the other hand, each +thread has its own registers and execution stack, and perhaps private +memory. + + GDB provides these facilities for debugging multi-thread programs: + + * automatic notification of new threads + + * `thread THREADNO', a command to switch among threads + + * `info threads', a command to inquire about existing threads + + * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command + to a list of threads + + * thread-specific breakpoints + + *Warning:* These facilities are not yet available on every GDB + configuration where the operating system supports threads. If + your GDB does not support threads, these commands have no effect. + For example, a system without thread support shows no output from + `info threads', and always rejects the `thread' command, like this: + + (gdb) info threads + (gdb) thread 1 + Thread ID 1 not known. Use the "info threads" command to + see the IDs of currently known threads. + + The GDB thread debugging facility allows you to observe all threads +while your program runs--but whenever GDB takes control, one thread in +particular is always the focus of debugging. This thread is called the +"current thread". Debugging commands show program information from the +perspective of the current thread. + + Whenever GDB detects a new thread in your program, it displays the +target system's identification for the thread with a message in the +form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies +depending on the particular system. For example, on LynxOS, you might +see + + [New process 35 thread 27] + +when GDB notices a new thread. In contrast, on an SGI system, the +SYSTAG is simply something like `process 368', with no further +qualifier. + + For debugging purposes, GDB associates its own thread number--always +a single integer--with each thread in your program. + +`info threads' + Display a summary of all threads currently in your program. GDB + displays for each thread (in this order): + + 1. the thread number assigned by GDB + + 2. the target system's thread identifier (SYSTAG) + + 3. the current stack frame summary for that thread + + An asterisk `*' to the left of the GDB thread number indicates the + current thread. + + For example, + + (gdb) info threads + 3 process 35 thread 27 0x34e5 in sigpause () + 2 process 35 thread 23 0x34e5 in sigpause () + * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + at threadtest.c:68 + +`thread THREADNO' + Make thread number THREADNO the current thread. The command + argument THREADNO is the internal GDB thread number, as shown in + the first field of the `info threads' display. GDB responds by + displaying the system identifier of the thread you selected, and + its current stack frame summary: + + (gdb) thread 2 + [Switching to process 35 thread 23] + 0x34e5 in sigpause () + + As with the `[New ...]' message, the form of the text after + `Switching to' depends on your system's conventions for identifying + threads. + +`thread apply [THREADNO] [ALL] ARGS' + The `thread apply' command allows you to apply a command to one or + more threads. Specify the numbers of the threads that you want + affected with the command argument THREADNO. THREADNO is the + internal GDB thread number, as shown in the first field of the + `info threads' display. To apply a command to all threads, use + `thread apply all' ARGS. + + Whenever GDB stops your program, due to a breakpoint or a signal, it +automatically selects the thread where that breakpoint or signal +happened. GDB alerts you to the context switch with a message of the +form `[Switching to SYSTAG]' to identify the thread. + + *Note Stopping and starting multi-thread programs: Thread Stops, for +more information about how GDB behaves when you stop and start programs +with multiple threads. + + *Note Setting watchpoints: Set Watchpoints, for information about +watchpoints in programs with multiple threads. + + +File: gdb.info, Node: Processes, Prev: Threads, Up: Running + +Debugging programs with multiple processes +========================================== + + GDB has no special support for debugging programs which create +additional processes using the `fork' function. When a program forks, +GDB will continue to debug the parent process and the child process +will run unimpeded. If you have set a breakpoint in any code which the +child then executes, the child will get a `SIGTRAP' signal which +(unless it catches the signal) will cause it to terminate. + + However, if you want to debug the child process there is a workaround +which isn't too painful. Put a call to `sleep' in the code which the +child process executes after the fork. It may be useful to sleep only +if a certain environment variable is set, or a certain file exists, so +that the delay need not occur when you don't want to run GDB on the +child. While the child is sleeping, use the `ps' program to get its +process ID. Then tell GDB (a new invocation of GDB if you are also +debugging the parent process) to attach to the child process (see *Note +Attach::). From that point on you can debug the child process just +like any other process which you attached to. + + +File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top + +Stopping and Continuing +*********************** + + The principal purposes of using a debugger are so that you can stop +your program before it terminates; or so that, if your program runs into +trouble, you can investigate and find out why. + + Inside GDB, your program may stop for any of several reasons, such as +a signal, a breakpoint, or reaching a new line after a GDB command such +as `step'. You may then examine and change variables, set new +breakpoints or remove old ones, and then continue execution. Usually, +the messages shown by GDB provide ample explanation of the status of +your program--but you can also explicitly request this information at +any time. + +`info program' + Display information about the status of your program: whether it is + running or not, what process it is, and why it stopped. + +* Menu: + +* Breakpoints:: Breakpoints, watchpoints, and catchpoints +* Continuing and Stepping:: Resuming execution + +* Signals:: Signals + + +* Thread Stops:: Stopping and starting multi-thread programs + + +File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Prev: Stopping, Up: Stopping + +Breakpoints, watchpoints, and catchpoints +========================================= + + A "breakpoint" makes your program stop whenever a certain point in +the program is reached. For each breakpoint, you can add conditions to +control in finer detail whether your program stops. You can set +breakpoints with the `break' command and its variants (*note Setting +breakpoints: Set Breaks.), to specify the place where your program +should stop by line number, function name or exact address in the +program. + + In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can +set breakpoints in shared libraries before the executable is run. +There is a minor limitation on HP-UX systems: you must wait until the +executable is run in order to set breakpoints in shared library +routines that are not called directly by the program (for example, +routines that are arguments in a `pthread_create' call). + + A "watchpoint" is a special breakpoint that stops your program when +the value of an expression changes. You must use a different command +to set watchpoints (*note Setting watchpoints: Set Watchpoints.), but +aside from that, you can manage a watchpoint like any other breakpoint: +you enable, disable, and delete both breakpoints and watchpoints using +the same commands. + + You can arrange to have values from your program displayed +automatically whenever GDB stops at a breakpoint. *Note Automatic +display: Auto Display. + + A "catchpoint" is another special breakpoint that stops your program +when a certain kind of event occurs, such as the throwing of a C++ +exception or the loading of a library. As with watchpoints, you use a +different command to set a catchpoint (*note Setting catchpoints: Set +Catchpoints.), but aside from that, you can manage a catchpoint like any +other breakpoint. (To stop when your program receives a signal, use the +`handle' command; *note Signals: Signals..) + + GDB assigns a number to each breakpoint, watchpoint, or catchpoint +when you create it; these numbers are successive integers starting with +one. In many of the commands for controlling various features of +breakpoints you use the breakpoint number to say which breakpoint you +want to change. Each breakpoint may be "enabled" or "disabled"; if +disabled, it has no effect on your program until you enable it again. + +* Menu: + +* Set Breaks:: Setting breakpoints +* Set Watchpoints:: Setting watchpoints +* Set Catchpoints:: Setting catchpoints +* Delete Breaks:: Deleting breakpoints +* Disabling:: Disabling breakpoints +* Conditions:: Break conditions +* Break Commands:: Breakpoint command lists + +* Breakpoint Menus:: Breakpoint menus + + +File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Prev: Breakpoints, Up: Breakpoints + +Setting breakpoints +------------------- + + Breakpoints are set with the `break' command (abbreviated `b'). The +debugger convenience variable `$bpnum' records the number of the +breakpoints you've set most recently; see *Note Convenience variables: +Convenience Vars, for a discussion of what you can do with convenience +variables. + + You have several ways to say where the breakpoint should go. + +`break FUNCTION' + Set a breakpoint at entry to function FUNCTION. When using source + languages that permit overloading of symbols, such as C++, + FUNCTION may refer to more than one possible place to break. + *Note Breakpoint menus: Breakpoint Menus, for a discussion of that + situation. + +`break +OFFSET' +`break -OFFSET' + Set a breakpoint some number of lines forward or back from the + position at which execution stopped in the currently selected + frame. + +`break LINENUM' + Set a breakpoint at line LINENUM in the current source file. That + file is the last file whose source text was printed. This + breakpoint stops your program just before it executes any of the + code on that line. + +`break FILENAME:LINENUM' + Set a breakpoint at line LINENUM in source file FILENAME. + +`break FILENAME:FUNCTION' + Set a breakpoint at entry to function FUNCTION found in file + FILENAME. Specifying a file name as well as a function name is + superfluous except when multiple files contain similarly named + functions. + +`break *ADDRESS' + Set a breakpoint at address ADDRESS. You can use this to set + breakpoints in parts of your program which do not have debugging + information or source files. + +`break' + When called without any arguments, `break' sets a breakpoint at + the next instruction to be executed in the selected stack frame + (*note Examining the Stack: Stack.). In any selected frame but the + innermost, this makes your program stop as soon as control returns + to that frame. This is similar to the effect of a `finish' + command in the frame inside the selected frame--except that + `finish' does not leave an active breakpoint. If you use `break' + without an argument in the innermost frame, GDB stops the next + time it reaches the current location; this may be useful inside + loops. + + GDB normally ignores breakpoints when it resumes execution, until + at least one instruction has been executed. If it did not do + this, you would be unable to proceed past a breakpoint without + first disabling the breakpoint. This rule applies whether or not + the breakpoint already existed when your program stopped. + +`break ... if COND' + Set a breakpoint with condition COND; evaluate the expression COND + each time the breakpoint is reached, and stop only if the value is + nonzero--that is, if COND evaluates as true. `...' stands for one + of the possible arguments described above (or no argument) + specifying where to break. *Note Break conditions: Conditions, + for more information on breakpoint conditions. + +`tbreak ARGS' + Set a breakpoint enabled only for one stop. ARGS are the same as + for the `break' command, and the breakpoint is set in the same + way, but the breakpoint is automatically deleted after the first + time your program stops there. *Note Disabling breakpoints: + Disabling. + +`hbreak ARGS' + Set a hardware-assisted breakpoint. ARGS are the same as for the + `break' command and the breakpoint is set in the same way, but the + breakpoint requires hardware support and some target hardware may + not have this support. The main purpose of this is EPROM/ROM code + debugging, so you can set a breakpoint at an instruction without + changing the instruction. This can be used with the new + trap-generation provided by SPARClite DSU. DSU will generate + traps when a program accesses some data or instruction address + that is assigned to the debug registers. However the hardware + breakpoint registers can only take two data breakpoints, and GDB + will reject this command if more than two are used. Delete or + disable unused hardware breakpoints before setting new ones. + *Note Break conditions: Conditions. + +`thbreak ARGS' + Set a hardware-assisted breakpoint enabled only for one stop. ARGS + are the same as for the `hbreak' command and the breakpoint is set + in the same way. However, like the `tbreak' command, the + breakpoint is automatically deleted after the first time your + program stops there. Also, like the `hbreak' command, the + breakpoint requires hardware support and some target hardware may + not have this support. *Note Disabling breakpoints: Disabling. + Also *Note Break conditions: Conditions. + +`rbreak REGEX' + Set breakpoints on all functions matching the regular expression + REGEX. This command sets an unconditional breakpoint on all + matches, printing a list of all breakpoints it set. Once these + breakpoints are set, they are treated just like the breakpoints + set with the `break' command. You can delete them, disable them, + or make them conditional the same way as any other breakpoint. + + When debugging C++ programs, `rbreak' is useful for setting + breakpoints on overloaded functions that are not members of any + special classes. + +`info breakpoints [N]' +`info break [N]' +`info watchpoints [N]' + Print a table of all breakpoints, watchpoints, and catchpoints set + and not deleted, with the following columns for each breakpoint: + + *Breakpoint Numbers* + + *Type* + Breakpoint, watchpoint, or catchpoint. + + *Disposition* + Whether the breakpoint is marked to be disabled or deleted + when hit. + + *Enabled or Disabled* + Enabled breakpoints are marked with `y'. `n' marks + breakpoints that are not enabled. + + *Address* + Where the breakpoint is in your program, as a memory address + + *What* + Where the breakpoint is in the source for your program, as a + file and line number. + + If a breakpoint is conditional, `info break' shows the condition on + the line following the affected breakpoint; breakpoint commands, + if any, are listed after that. + + `info break' with a breakpoint number N as argument lists only + that breakpoint. The convenience variable `$_' and the default + examining-address for the `x' command are set to the address of + the last breakpoint listed (*note Examining memory: Memory.). + + `info break' displays a count of the number of times the breakpoint + has been hit. This is especially useful in conjunction with the + `ignore' command. You can ignore a large number of breakpoint + hits, look at the breakpoint info to see how many times the + breakpoint was hit, and then run again, ignoring one less than + that number. This will get you quickly to the last hit of that + breakpoint. + + GDB allows you to set any number of breakpoints at the same place in +your program. There is nothing silly or meaningless about this. When +the breakpoints are conditional, this is even useful (*note Break +conditions: Conditions.). + + GDB itself sometimes sets breakpoints in your program for special +purposes, such as proper handling of `longjmp' (in C programs). These +internal breakpoints are assigned negative numbers, starting with `-1'; +`info breakpoints' does not display them. + + You can see these breakpoints with the GDB maintenance command +`maint info breakpoints'. + +`maint info breakpoints' + Using the same format as `info breakpoints', display both the + breakpoints you've set explicitly, and those GDB is using for + internal purposes. Internal breakpoints are shown with negative + breakpoint numbers. The type column identifies what kind of + breakpoint is shown: + + `breakpoint' + Normal, explicitly set breakpoint. + + `watchpoint' + Normal, explicitly set watchpoint. + + `longjmp' + Internal breakpoint, used to handle correctly stepping through + `longjmp' calls. + + `longjmp resume' + Internal breakpoint at the target of a `longjmp'. + + `until' + Temporary internal breakpoint used by the GDB `until' command. + + `finish' + Temporary internal breakpoint used by the GDB `finish' + command. + + +File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints + +Setting watchpoints +------------------- + + You can use a watchpoint to stop execution whenever the value of an +expression changes, without having to predict a particular place where +this may happen. + + Depending on your system, watchpoints may be implemented in software +or hardware. GDB does software watchpointing by single-stepping your +program and testing the variable's value each time, which is hundreds of +times slower than normal execution. (But this may still be worth it, to +catch errors where you have no clue what part of your program is the +culprit.) + + On some systems, such as HP-UX and Linux, GDB includes support for +hardware watchpoints, which do not slow down the running of your +program. + +`watch EXPR' + Set a watchpoint for an expression. GDB will break when EXPR is + written into by the program and its value changes. + +`rwatch EXPR' + Set a watchpoint that will break when watch EXPR is read by the + program. If you use both watchpoints, both must be set with the + `rwatch' command. + +`awatch EXPR' + Set a watchpoint that will break when ARGS is read and written into + by the program. If you use both watchpoints, both must be set + with the `awatch' command. + +`info watchpoints' + This command prints a list of watchpoints, breakpoints, and + catchpoints; it is the same as `info break'. + + GDB sets a "hardware watchpoint" if possible. Hardware watchpoints +execute very quickly, and the debugger reports a change in value at the +exact instruction where the change occurs. If GDB cannot set a +hardware watchpoint, it sets a software watchpoint, which executes more +slowly and reports the change in value at the next statement, not the +instruction, after the change occurs. + + When you issue the `watch' command, GDB reports + + Hardware watchpoint NUM: EXPR + +if it was able to set a hardware watchpoint. + + The SPARClite DSU will generate traps when a program accesses some +data or instruction address that is assigned to the debug registers. +For the data addresses, DSU facilitates the `watch' command. However +the hardware breakpoint registers can only take two data watchpoints, +and both watchpoints must be the same kind. For example, you can set +two watchpoints with `watch' commands, two with `rwatch' commands, *or* +two with `awatch' commands, but you cannot set one watchpoint with one +command and the other with a different command. GDB will reject the +command if you try to mix watchpoints. Delete or disable unused +watchpoint commands before setting new ones. + + If you call a function interactively using `print' or `call', any +watchpoints you have set will be inactive until GDB reaches another +kind of breakpoint or the call completes. + + *Warning:* In multi-thread programs, watchpoints have only limited + usefulness. With the current watchpoint implementation, GDB can + only watch the value of an expression *in a single thread*. If + you are confident that the expression can only change due to the + current thread's activity (and if you are also confident that no + other thread can become current), then you can use watchpoints as + usual. However, GDB may not notice when a non-current thread's + activity changes the expression. + + +File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints + +Setting catchpoints +------------------- + + You can use "catchpoints" to cause the debugger to stop for certain +kinds of program events, such as C++ exceptions or the loading of a +shared library. Use the `catch' command to set a catchpoint. + +`catch EVENT' + Stop when EVENT occurs. EVENT can be any of the following: + `throw' + The throwing of a C++ exception. + + `catch' + The catching of a C++ exception. + + `exec' + A call to `exec'. This is currently only available for HP-UX. + + `fork' + A call to `fork'. This is currently only available for HP-UX. + + `vfork' + A call to `vfork'. This is currently only available for + HP-UX. + + `load' + `load LIBNAME' + The dynamic loading of any shared library, or the loading of + the library LIBNAME. This is currently only available for + HP-UX. + + `unload' + `unload LIBNAME' + The unloading of any dynamically loaded shared library, or + the unloading of the library LIBNAME. This is currently only + available for HP-UX. + +`tcatch EVENT' + Set a catchpoint that is enabled only for one stop. The + catchpoint is automatically deleted after the first time the event + is caught. + + Use the `info break' command to list the current catchpoints. + + There are currently some limitations to C++ exception handling +(`catch throw' and `catch catch') in GDB: + + * If you call a function interactively, GDB normally returns control + to you when the function has finished executing. If the call + raises an exception, however, the call may bypass the mechanism + that returns control to you and cause your program either to abort + or to simply continue running until it hits a breakpoint, catches + a signal that GDB is listening for, or exits. This is the case + even if you set a catchpoint for the exception; catchpoints on + exceptions are disabled within interactive calls. + + * You cannot raise an exception interactively. + + * You cannot install an exception handler interactively. + + Sometimes `catch' is not the best way to debug exception handling: +if you need to know exactly where an exception is raised, it is better +to stop *before* the exception handler is called, since that way you +can see the stack before any unwinding takes place. If you set a +breakpoint in an exception handler instead, it may not be easy to find +out where the exception was raised. + + To stop just before an exception handler is called, you need some +knowledge of the implementation. In the case of GNU C++, exceptions are +raised by calling a library function named `__raise_exception' which +has the following ANSI C interface: + + /* ADDR is where the exception identifier is stored. + ID is the exception identifier. */ + void __raise_exception (void **ADDR, void *ID); + +To make the debugger catch all exceptions before any stack unwinding +takes place, set a breakpoint on `__raise_exception' (*note +Breakpoints; watchpoints; and exceptions: Breakpoints.). + + With a conditional breakpoint (*note Break conditions: Conditions.) +that depends on the value of ID, you can stop your program when a +specific exception is raised. You can use multiple conditional +breakpoints to stop your program when any of a number of exceptions are +raised. + + +File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints + +Deleting breakpoints +-------------------- + + It is often necessary to eliminate a breakpoint, watchpoint, or +catchpoint once it has done its job and you no longer want your program +to stop there. This is called "deleting" the breakpoint. A breakpoint +that has been deleted no longer exists; it is forgotten. + + With the `clear' command you can delete breakpoints according to +where they are in your program. With the `delete' command you can +delete individual breakpoints, watchpoints, or catchpoints by specifying +their breakpoint numbers. + + It is not necessary to delete a breakpoint to proceed past it. GDB +automatically ignores breakpoints on the first instruction to be +executed when you continue execution without changing the execution +address. + +`clear' + Delete any breakpoints at the next instruction to be executed in + the selected stack frame (*note Selecting a frame: Selection.). + When the innermost frame is selected, this is a good way to delete + a breakpoint where your program just stopped. + +`clear FUNCTION' +`clear FILENAME:FUNCTION' + Delete any breakpoints set at entry to the function FUNCTION. + +`clear LINENUM' +`clear FILENAME:LINENUM' + Delete any breakpoints set at or within the code of the specified + line. + +`delete [breakpoints] [BNUMS...]' + Delete the breakpoints, watchpoints, or catchpoints of the numbers + specified as arguments. If no argument is specified, delete all + breakpoints (GDB asks confirmation, unless you have `set confirm + off'). You can abbreviate this command as `d'. + + +File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints + +Disabling breakpoints +--------------------- + + Rather than deleting a breakpoint, watchpoint, or catchpoint, you +might prefer to "disable" it. This makes the breakpoint inoperative as +if it had been deleted, but remembers the information on the breakpoint +so that you can "enable" it again later. + + You disable and enable breakpoints, watchpoints, and catchpoints with +the `enable' and `disable' commands, optionally specifying one or more +breakpoint numbers as arguments. Use `info break' or `info watch' to +print a list of breakpoints, watchpoints, and catchpoints if you do not +know which numbers to use. + + A breakpoint, watchpoint, or catchpoint can have any of four +different states of enablement: + + * Enabled. The breakpoint stops your program. A breakpoint set + with the `break' command starts out in this state. + + * Disabled. The breakpoint has no effect on your program. + + * Enabled once. The breakpoint stops your program, but then becomes + disabled. A breakpoint set with the `tbreak' command starts out in + this state. + + * Enabled for deletion. The breakpoint stops your program, but + immediately after it does so it is deleted permanently. + + You can use the following commands to enable or disable breakpoints, +watchpoints, and catchpoints: + +`disable [breakpoints] [BNUMS...]' + Disable the specified breakpoints--or all breakpoints, if none are + listed. A disabled breakpoint has no effect but is not forgotten. + All options such as ignore-counts, conditions and commands are + remembered in case the breakpoint is enabled again later. You may + abbreviate `disable' as `dis'. + +`enable [breakpoints] [BNUMS...]' + Enable the specified breakpoints (or all defined breakpoints). + They become effective once again in stopping your program. + +`enable [breakpoints] once BNUMS...' + Enable the specified breakpoints temporarily. GDB disables any of + these breakpoints immediately after stopping your program. + +`enable [breakpoints] delete BNUMS...' + Enable the specified breakpoints to work once, then die. GDB + deletes any of these breakpoints as soon as your program stops + there. + + Except for a breakpoint set with `tbreak' (*note Setting +breakpoints: Set Breaks.), breakpoints that you set are initially +enabled; subsequently, they become disabled or enabled only when you +use one of the commands above. (The command `until' can set and delete +a breakpoint of its own, but it does not change the state of your other +breakpoints; see *Note Continuing and stepping: Continuing and +Stepping.) + + +File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints + +Break conditions +---------------- + + The simplest sort of breakpoint breaks every time your program +reaches a specified place. You can also specify a "condition" for a +breakpoint. A condition is just a Boolean expression in your +programming language (*note Expressions: Expressions.). A breakpoint +with a condition evaluates the expression each time your program +reaches it, and your program stops only if the condition is *true*. + + This is the converse of using assertions for program validation; in +that situation, you want to stop when the assertion is violated--that +is, when the condition is false. In C, if you want to test an +assertion expressed by the condition ASSERT, you should set the +condition `! ASSERT' on the appropriate breakpoint. + + Conditions are also accepted for watchpoints; you may not need them, +since a watchpoint is inspecting the value of an expression anyhow--but +it might be simpler, say, to just set a watchpoint on a variable name, +and specify a condition that tests whether the new value is an +interesting one. + + Break conditions can have side effects, and may even call functions +in your program. This can be useful, for example, to activate functions +that log program progress, or to use your own print functions to format +special data structures. The effects are completely predictable unless +there is another enabled breakpoint at the same address. (In that +case, GDB might see the other breakpoint first and stop your program +without checking the condition of this one.) Note that breakpoint +commands are usually more convenient and flexible for the purpose of +performing side effects when a breakpoint is reached (*note Breakpoint +command lists: Break Commands.). + + Break conditions can be specified when a breakpoint is set, by using +`if' in the arguments to the `break' command. *Note Setting +breakpoints: Set Breaks. They can also be changed at any time with the +`condition' command. The `watch' command does not recognize the `if' +keyword; `condition' is the only way to impose a further condition on a +watchpoint. + +`condition BNUM EXPRESSION' + Specify EXPRESSION as the break condition for breakpoint, + watchpoint, or catchpoint number BNUM. After you set a condition, + breakpoint BNUM stops your program only if the value of EXPRESSION + is true (nonzero, in C). When you use `condition', GDB checks + EXPRESSION immediately for syntactic correctness, and to determine + whether symbols in it have referents in the context of your + breakpoint. GDB does not actually evaluate EXPRESSION at the time + the `condition' command is given, however. *Note Expressions: + Expressions. + +`condition BNUM' + Remove the condition from breakpoint number BNUM. It becomes an + ordinary unconditional breakpoint. + + A special case of a breakpoint condition is to stop only when the +breakpoint has been reached a certain number of times. This is so +useful that there is a special way to do it, using the "ignore count" +of the breakpoint. Every breakpoint has an ignore count, which is an +integer. Most of the time, the ignore count is zero, and therefore has +no effect. But if your program reaches a breakpoint whose ignore count +is positive, then instead of stopping, it just decrements the ignore +count by one and continues. As a result, if the ignore count value is +N, the breakpoint does not stop the next N times your program reaches +it. + +`ignore BNUM COUNT' + Set the ignore count of breakpoint number BNUM to COUNT. The next + COUNT times the breakpoint is reached, your program's execution + does not stop; other than to decrement the ignore count, GDB takes + no action. + + To make the breakpoint stop the next time it is reached, specify a + count of zero. + + When you use `continue' to resume execution of your program from a + breakpoint, you can specify an ignore count directly as an + argument to `continue', rather than using `ignore'. *Note + Continuing and stepping: Continuing and Stepping. + + If a breakpoint has a positive ignore count and a condition, the + condition is not checked. Once the ignore count reaches zero, GDB + resumes checking the condition. + + You could achieve the effect of the ignore count with a condition + such as `$foo-- <= 0' using a debugger convenience variable that + is decremented each time. *Note Convenience variables: + Convenience Vars. + + Ignore counts apply to breakpoints, watchpoints, and catchpoints. + |