diff options
Diffstat (limited to 'gnu/usr.bin/gdb/doc/gdb.info-2')
| -rw-r--r-- | gnu/usr.bin/gdb/doc/gdb.info-2 | 1165 |
1 files changed, 1165 insertions, 0 deletions
diff --git a/gnu/usr.bin/gdb/doc/gdb.info-2 b/gnu/usr.bin/gdb/doc/gdb.info-2 new file mode 100644 index 000000000000..e8be2fa7d906 --- /dev/null +++ b/gnu/usr.bin/gdb/doc/gdb.info-2 @@ -0,0 +1,1165 @@ +This is Info file ./gdb.info, produced by Makeinfo-1.52 from the input +file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb:: The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is Edition 4.09, August 1993, of `Debugging with GDB: the GNU +Source-Level Debugger' for GDB Version 4.11. + + Copyright (C) 1988, '89, '90, '91, '92, '93 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: 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' will show 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' will 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 using `attach', you should first use the `file' command to +specify the program running in the process and load its symbol table. +*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' will 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, you will be asked 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 will notice that the file has changed, and +will re-read the symbol table (while trying to preserve your current +breakpoint settings). + + +File: gdb.info, Node: Process Information, 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' + 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: 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 exceptions + + +* Continuing and Stepping:: Resuming execution + +* Signals:: Signals + + +File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping + +Breakpoints, watchpoints, and exceptions +======================================== + + A "breakpoint" makes your program stop whenever a certain point in +the program is reached. For each breakpoint, you can add various +conditions to control in finer detail whether your program will stop. +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 languages with exception handling (such as GNU +C++), you can also set breakpoints where an exception is raised (*note +Breakpoints and exceptions: Exception Handling.). + + 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. + + GDB assigns a number to each breakpoint or watchpoint 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 + +* Exception Handling:: Breakpoints and exceptions + +* Delete Breaks:: Deleting breakpoints +* Disabling:: Disabling breakpoints +* Conditions:: Break conditions +* Break Commands:: Breakpoint command lists + +* Breakpoint Menus:: Breakpoint menus + +* Error in Breakpoints:: "Cannot insert breakpoints" + + +File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints + +Setting breakpoints +------------------- + + Breakpoints are set with the `break' command (abbreviated `b'). The +debugger convenience variable `$bpnum' records the number of the +beakpoint 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 will stop 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 will cause your program to 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 will stop + 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 disabled after the first + time your program stops there. *Note Disabling breakpoints: + Disabling. + +`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. They can be deleted, disabled, made + conditional, etc., in the standard ways. + + 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 and watchpoints set and not + deleted, with the following columns for each breakpoint: + + *Breakpoint Numbers* + *Type* + Breakpoint or watchpoint. + + *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.). + + 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: Exception Handling, 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. + + Watchpoints currently execute two orders of magnitude more slowly +than other breakpoints, but this can be well worth it to catch errors +where you have no clue what part of your program is the culprit. Some +processors provide special hardware to support watchpoint evaluation; +future releases of GDB will use such hardware if it is available. + +`watch EXPR' + Set a watchpoint for an expression. + +`info watchpoints' + This command prints a list of watchpoints and breakpoints; it is + the same as `info break'. + + +File: gdb.info, Node: Exception Handling, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints + +Breakpoints and exceptions +-------------------------- + + Some languages, such as GNU C++, implement exception handling. You +can use GDB to examine what caused your program to raise an exception, +and to list the exceptions your program is prepared to handle at a +given point in time. + +`catch EXCEPTIONS' + You can set breakpoints at active exception handlers by using the + `catch' command. EXCEPTIONS is a list of names of exceptions to + catch. + + You can use `info catch' to list active exception handlers. *Note +Information about a frame: Frame Info. + + There are currently some limitations to exception handling in GDB. +These will be corrected in a future release. + + * 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 to simply + continue running until it hits a breakpoint, catches a signal that + GDB is listening for, or exits. + + * You cannot raise an exception interactively. + + * You cannot interactively install an exception handler. + + 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: Exception Handling, Up: Breakpoints + +Deleting breakpoints +-------------------- + + It is often necessary to eliminate a breakpoint or watchpoint 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 or watchpoints 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 or watchpoints 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 or watchpoint, 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 and watchpoints 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 or watchpoints if you do not know which numbers to use. + + A breakpoint or watchpoint can have any of four different states of +enablement: + + * Enabled. The breakpoint will stop 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 will stop your program, but when it + does so it will become disabled. A breakpoint set with the + `tbreak' command starts out in this state. + + * Enabled for deletion. The breakpoint will stop your program, but + immediately after it does so it will be deleted permanently. + + You can use the following commands to enable or disable breakpoints +and watchpoints: + +`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. Each will be + disabled again the next time it stops your program. + +`enable [breakpoints] delete BNUMS...' + Enable the specified breakpoints to work once and then die. Each + of the breakpoints will be deleted the next time it stops your + program. + + Save 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 will 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 or + watchpoint number BNUM. From now on, this breakpoint will stop + 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 will not stop the next N times it is reached. + +`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 + will 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, the + condition will be checked. + + 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. + + +File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints + +Breakpoint command lists +------------------------ + + You can give any breakpoint (or watchpoint) a series of commands to +execute when your program stops due to that breakpoint. For example, +you might want to print the values of certain expressions, or enable +other breakpoints. + +`commands [BNUM]' +`... COMMAND-LIST ...' +`end' + Specify a list of commands for breakpoint number BNUM. The + commands themselves appear on the following lines. Type a line + containing just `end' to terminate the commands. + + To remove all commands from a breakpoint, type `commands' and + follow it immediately with `end'; that is, give no commands. + + With no BNUM argument, `commands' refers to the last breakpoint or + watchpoint set (not to the breakpoint most recently encountered). + + Pressing RET as a means of repeating the last GDB command is +disabled within a COMMAND-LIST. + + You can use breakpoint commands to start your program up again. +Simply use the `continue' command, or `step', or any other command that +resumes execution. + + Any other commands in the command list, after a command that resumes +execution, are ignored. This is because any time you resume execution +(even with a simple `next' or `step'), you may encounter another +breakpoint--which could have its own command list, leading to +ambiguities about which list to execute. + + If the first command you specify in a command list is `silent', the +usual message about stopping at a breakpoint is not printed. This may +be desirable for breakpoints that are to print a specific message and +then continue. If none of the remaining commands print anything, you +will see no sign that the breakpoint was reached. `silent' is +meaningful only at the beginning of a breakpoint command list. + + The commands `echo', `output', and `printf' allow you to print +precisely controlled output, and are often useful in silent +breakpoints. *Note Commands for controlled output: Output. + + For example, here is how you could use breakpoint commands to print +the value of `x' at entry to `foo' whenever `x' is positive. + + break foo if x>0 + commands + silent + printf "x is %d\n",x + cont + end + + One application for breakpoint commands is to compensate for one bug +so you can test for another. Put a breakpoint just after the erroneous +line of code, give it a condition to detect the case in which something +erroneous has been done, and give it commands to assign correct values +to any variables that need them. End with the `continue' command so +that your program does not stop, and start with the `silent' command so +that no output is produced. Here is an example: + + break 403 + commands + silent + set x = y + 4 + cont + end + + +File: gdb.info, Node: Breakpoint Menus, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints + +Breakpoint menus +---------------- + + Some programming languages (notably C++) permit a single function +name to be defined several times, for application in different contexts. +This is called "overloading". When a function name is overloaded, +`break FUNCTION' is not enough to tell GDB where you want a breakpoint. +If you realize this will be a problem, you can use something like +`break FUNCTION(TYPES)' to specify which particular version of the +function you want. Otherwise, GDB offers you a menu of numbered +choices for different possible breakpoints, and waits for your +selection with the prompt `>'. The first two options are always `[0] +cancel' and `[1] all'. Typing `1' sets a breakpoint at each definition +of FUNCTION, and typing `0' aborts the `break' command without setting +any new breakpoints. + + For example, the following session excerpt shows an attempt to set a +breakpoint at the overloaded symbol `String::after'. We choose three +particular definitions of that function name: + + (gdb) b String::after + [0] cancel + [1] all + [2] file:String.cc; line number:867 + [3] file:String.cc; line number:860 + [4] file:String.cc; line number:875 + [5] file:String.cc; line number:853 + [6] file:String.cc; line number:846 + [7] file:String.cc; line number:735 + > 2 4 6 + Breakpoint 1 at 0xb26c: file String.cc, line 867. + Breakpoint 2 at 0xb344: file String.cc, line 875. + Breakpoint 3 at 0xafcc: file String.cc, line 846. + Multiple breakpoints were set. + Use the "delete" command to delete unwanted + breakpoints. + (gdb) + + +File: gdb.info, Node: Error in Breakpoints, Prev: Breakpoint Menus, Up: Breakpoints + +"Cannot insert breakpoints" +--------------------------- + + Under some operating systems, breakpoints cannot be used in a +program if any other process is running that program. In this +situation, attempting to run or continue a program with a breakpoint +causes GDB to stop the other process. + + When this happens, you have three ways to proceed: + + 1. Remove or disable the breakpoints, then continue. + + 2. Suspend GDB, and copy the file containing your program to a new + name. Resume GDB and use the `exec-file' command to specify that + GDB should run your program under that name. Then start your + program again. + + 3. Relink your program so that the text segment is nonsharable, using + the linker option `-N'. The operating system limitation may not + apply to nonsharable executables. + + +File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping + +Continuing and stepping +======================= + + "Continuing" means resuming program execution until your program +completes normally. In contrast, "stepping" means executing just one +more "step" of your program, where "step" may mean either one line of +source code, or one machine instruction (depending on what particular +command you use). Either when continuing or when stepping, your +program may stop even sooner, due to a breakpoint or a signal. (If due +to a signal, you may want to use `handle', or use `signal 0' to resume +execution. *Note Signals: Signals.) + +`continue [IGNORE-COUNT]' +`c [IGNORE-COUNT]' +`fg [IGNORE-COUNT]' + Resume program execution, at the address where your program last + stopped; any breakpoints set at that address are bypassed. The + optional argument IGNORE-COUNT allows you to specify a further + number of times to ignore a breakpoint at this location; its + effect is like that of `ignore' (*note Break conditions: + Conditions.). + + The argument IGNORE-COUNT is meaningful only when your program + stopped due to a breakpoint. At other times, the argument to + `continue' is ignored. + + The synonyms `c' and `fg' are provided purely for convenience, and + have exactly the same behavior as `continue'. + + To resume execution at a different place, you can use `return' +(*note Returning from a function: Returning.) to go back to the calling +function; or `jump' (*note Continuing at a different address: Jumping.) +to go to an arbitrary location in your program. + + A typical technique for using stepping is to set a breakpoint (*note +Breakpoints; watchpoints; and exceptions: Breakpoints.) at the +beginning of the function or the section of your program where a +problem is believed to lie, run your program until it stops at that +breakpoint, and then step through the suspect area, examining the +variables that are interesting, until you see the problem happen. + +`step' + Continue running your program until control reaches a different + source line, then stop it and return control to GDB. This command + is abbreviated `s'. + + *Warning:* If you use the `step' command while control is + within a function that was compiled without debugging + information, execution proceeds until control reaches a + function that does have debugging information. + +`step COUNT' + Continue running as in `step', but do so COUNT times. If a + breakpoint is reached, or a signal not related to stepping occurs + before COUNT steps, stepping stops right away. + +`next [COUNT]' + Continue to the next source line in the current (innermost) stack + frame. Similar to `step', but any function calls appearing within + the line of code are executed without stopping. Execution stops + when control reaches a different line of code at the stack level + which was executing when the `next' command was given. This + command is abbreviated `n'. + + An argument COUNT is a repeat count, as for `step'. + + `next' within a function that lacks debugging information acts like + `step', but any function calls appearing within the code of the + function are executed without stopping. + +`finish' + Continue running until just after function in the selected stack + frame returns. Print the returned value (if any). + + Contrast this with the `return' command (*note Returning from a + function: Returning.). + +`until' +`u' + Continue running until a source line past the current line, in the + current stack frame, is reached. This command is used to avoid + single stepping through a loop more than once. It is like the + `next' command, except that when `until' encounters a jump, it + automatically continues execution until the program counter is + greater than the address of the jump. + + This means that when you reach the end of a loop after single + stepping though it, `until' will cause your program to continue + execution until the loop is exited. In contrast, a `next' command + at the end of a loop will simply step back to the beginning of the + loop, which would force you to step through the next iteration. + + `until' always stops your program if it attempts to exit the + current stack frame. + + `until' may produce somewhat counterintuitive results if the order + of machine code does not match the order of the source lines. For + example, in the following excerpt from a debugging session, the `f' + (`frame') command shows that execution is stopped at line `206'; + yet when we use `until', we get to line `195': + + (gdb) f + #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 + 206 expand_input(); + (gdb) until + 195 for ( ; argc > 0; NEXTARG) { + + This happened because, for execution efficiency, the compiler had + generated code for the loop closure test at the end, rather than + the start, of the loop--even though the test in a C `for'-loop is + written before the body of the loop. The `until' command appeared + to step back to the beginning of the loop when it advanced to this + expression; however, it has not really gone to an earlier + statement--not in terms of the actual machine code. + + `until' with no argument works by means of single instruction + stepping, and hence is slower than `until' with an argument. + +`until LOCATION' +`u LOCATION' + Continue running your program until either the specified location + is reached, or the current stack frame returns. LOCATION is any of + the forms of argument acceptable to `break' (*note Setting + breakpoints: Set Breaks.). This form of the command uses + breakpoints, and hence is quicker than `until' without an argument. + +`stepi' +`si' + Execute one machine instruction, then stop and return to the + debugger. + + It is often useful to do `display/i $pc' when stepping by machine + instructions. This will cause the next instruction to be executed + to be displayed automatically at each stop. *Note Automatic + display: Auto Display. + + An argument is a repeat count, as in `step'. + +`nexti' +`ni' + Execute one machine instruction, but if it is a function call, + proceed until the function returns. + + An argument is a repeat count, as in `next'. + + +File: gdb.info, Node: Signals, Prev: Continuing and Stepping, Up: Stopping + +Signals +======= + + A signal is an asynchronous event that can happen in a program. The +operating system defines the possible kinds of signals, and gives each +kind a name and a number. For example, in Unix `SIGINT' is the signal +a program gets when you type an interrupt (often `C-c'); `SIGSEGV' is +the signal a program gets from referencing a place in memory far away +from all the areas in use; `SIGALRM' occurs when the alarm clock timer +goes off (which happens only if your program has requested an alarm). + + Some signals, including `SIGALRM', are a normal part of the +functioning of your program. Others, such as `SIGSEGV', indicate +errors; these signals are "fatal" (kill your program immediately) if the +program has not specified in advance some other way to handle the +signal. `SIGINT' does not indicate an error in your program, but it is +normally fatal so it can carry out the purpose of the interrupt: to +kill the program. + + GDB has the ability to detect any occurrence of a signal in your +program. You can tell GDB in advance what to do for each kind of +signal. + + Normally, GDB is set up to ignore non-erroneous signals like +`SIGALRM' (so as not to interfere with their role in the functioning of +your program) but to stop your program immediately whenever an error +signal happens. You can change these settings with the `handle' +command. + +`info signals' + Print a table of all the kinds of signals and how GDB has been + told to handle each one. You can use this to see the signal + numbers of all the defined types of signals. + +`handle SIGNAL KEYWORDS...' + Change the way GDB handles signal SIGNAL. SIGNAL can be the + number of a signal or its name (with or without the `SIG' at the + beginning). The KEYWORDS say what change to make. + + The keywords allowed by the `handle' command can be abbreviated. +Their full names are: + +`nostop' + GDB should not stop your program when this signal happens. It may + still print a message telling you that the signal has come in. + +`stop' + GDB should stop your program when this signal happens. This + implies the `print' keyword as well. + +`print' + GDB should print a message when this signal happens. + +`noprint' + GDB should not mention the occurrence of the signal at all. This + implies the `nostop' keyword as well. + +`pass' + GDB should allow your program to see this signal; your program + will be able to handle the signal, or may be terminated if the + signal is fatal and not handled. + +`nopass' + GDB should not allow your program to see this signal. + + When a signal stops your program, the signal is not visible until you +continue. Your program will see the signal then, if `pass' is in +effect for the signal in question *at that time*. In other words, +after GDB reports a signal, you can use the `handle' command with +`pass' or `nopass' to control whether that signal will be seen by your +program when you later continue it. + + You can also use the `signal' command to prevent your program from +seeing a signal, or cause it to see a signal it normally would not see, +or to give it any signal at any time. For example, if your program +stopped due to some sort of memory reference error, you might store +correct values into the erroneous variables and continue, hoping to see +more execution; but your program would probably terminate immediately as +a result of the fatal signal once it saw the signal. To prevent this, +you can continue with `signal 0'. *Note Giving your program a signal: +Signaling. + + +File: gdb.info, Node: Stack, Next: Source, Prev: Stopping, Up: Top + +Examining the Stack +******************* + + When your program has stopped, the first thing you need to know is +where it stopped and how it got there. + + Each time your program performs a function call, the information +about where in your program the call was made from is saved in a block +of data called a "stack frame". The frame also contains the arguments +of the call and the local variables of the function that was called. +All the stack frames are allocated in a region of memory called the +"call stack". + + When your program stops, the GDB commands for examining the stack +allow you to see all of this information. + + One of the stack frames is "selected" by GDB and many GDB commands +refer implicitly to the selected frame. In particular, whenever you +ask GDB for the value of a variable in your program, the value is found +in the selected frame. There are special GDB commands to select +whichever frame you are interested in. + + When your program stops, GDB automatically selects the currently +executing frame and describes it briefly as the `frame' command does +(*note Information about a frame: Frame Info.). + +* Menu: + +* Frames:: Stack frames +* Backtrace:: Backtraces +* Selection:: Selecting a frame +* Frame Info:: Information on a frame + +* MIPS Stack:: MIPS machines and the function stack + + +File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack + +Stack frames +============ + + The call stack is divided up into contiguous pieces called "stack +frames", or "frames" for short; each frame is the data associated with +one call to one function. The frame contains the arguments given to +the function, the function's local variables, and the address at which +the function is executing. + + When your program is started, the stack has only one frame, that of +the function `main'. This is called the "initial" frame or the +"outermost" frame. Each time a function is called, a new frame is +made. Each time a function returns, the frame for that function +invocation is eliminated. If a function is recursive, there can be +many frames for the same function. The frame for the function in which +execution is actually occurring is called the "innermost" frame. This +is the most recently created of all the stack frames that still exist. + + Inside your program, stack frames are identified by their addresses. +A stack frame consists of many bytes, each of which has its own +address; each kind of computer has a convention for choosing one of +those bytes whose address serves as the address of the frame. Usually +this address is kept in a register called the "frame pointer register" +while execution is going on in that frame. + + GDB assigns numbers to all existing stack frames, starting with zero +for the innermost frame, one for the frame that called it, and so on +upward. These numbers do not really exist in your program; they are +assigned by GDB to give you a way of designating stack frames in GDB +commands. + + Some compilers provide a way to compile functions so that they +operate without stack frames. (For example, the `gcc' option +`-fomit-frame-pointer' will generate functions without a frame.) This +is occasionally done with heavily used library functions to save the +frame setup time. GDB has limited facilities for dealing with these +function invocations. If the innermost function invocation has no +stack frame, GDB will nevertheless regard it as though it had a +separate frame, which is numbered zero as usual, allowing correct +tracing of the function call chain. However, GDB has no provision for +frameless functions elsewhere in the stack. + + +File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack + +Backtraces +========== + + A backtrace is a summary of how your program got where it is. It +shows one line per frame, for many frames, starting with the currently +executing frame (frame zero), followed by its caller (frame one), and +on up the stack. + +`backtrace' +`bt' + Print a backtrace of the entire stack: one line per frame for all + frames in the stack. + + You can stop the backtrace at any time by typing the system + interrupt character, normally `C-c'. + +`backtrace N' +`bt N' + Similar, but print only the innermost N frames. + +`backtrace -N' +`bt -N' + Similar, but print only the outermost N frames. + + The names `where' and `info stack' (abbreviated `info s') are +additional aliases for `backtrace'. + + Each line in the backtrace shows the frame number and the function +name. The program counter value is also shown--unless you use `set +print address off'. The backtrace also shows the source file name and +line number, as well as the arguments to the function. The program +counter value is omitted if it is at the beginning of the code for that +line number. + + Here is an example of a backtrace. It was made with the command `bt +3', so it shows the innermost three frames. + + #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 + #1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 + #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) + at macro.c:71 + (More stack frames follow...) + +The display for frame zero does not begin with a program counter value, +indicating that your program has stopped at the beginning of the code +for line `993' of `builtin.c'. + |