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, 0 insertions, 1165 deletions
diff --git a/gnu/usr.bin/gdb/doc/gdb.info-2 b/gnu/usr.bin/gdb/doc/gdb.info-2 deleted file mode 100644 index e8be2fa7d906..000000000000 --- a/gnu/usr.bin/gdb/doc/gdb.info-2 +++ /dev/null @@ -1,1165 +0,0 @@ -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'. - |