diff options
Diffstat (limited to 'gdb/doc/gdb.info-3')
| -rw-r--r-- | gdb/doc/gdb.info-3 | 1224 |
1 files changed, 1224 insertions, 0 deletions
diff --git a/gdb/doc/gdb.info-3 b/gdb/doc/gdb.info-3 new file mode 100644 index 00000000000..571568304aa --- /dev/null +++ b/gdb/doc/gdb.info-3 @@ -0,0 +1,1224 @@ +This is Info file ./gdb.info, produced by Makeinfo version 1.68 from +the input file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is the Seventh Edition, February 1999, of `Debugging with GDB: +the GNU Source-Level Debugger' for GDB Version 4.18. + + Copyright (C) 1988-1999 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the entire resulting derived work is distributed under the terms +of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions. + + +File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints + +Breakpoint command lists +------------------------ + + You can give any breakpoint (or watchpoint or catchpoint) 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, + watchpoint, or catchpoint 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 +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, 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 is 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: 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 catchpoints: 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. Likewise, it + will not step into a function which is compiled without + debugging information. To step through functions without + debugging information, use the `stepi' command, described + below. + + The `step' command now only stops at the first instruction of a + source line. This prevents the multiple stops that used to occur + in switch statements, for loops, etc. `step' continues to stop if + a function that has debugging information is called within the + line. + + Also, the `step' command now only enters a subroutine if there is + line number information for the subroutine. Otherwise it acts + like the `next' command. This avoids problems when using `cc -gl' + on MIPS machines. Previously, `step' entered subroutines if there + was any debugging information about the routine. + +`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. This is similar to `step', but function calls that appear + within the line of code are executed without stopping. Execution + stops when control reaches a different line of code at the + original stack level that was executing when you gave the `next' + command. This command is abbreviated `n'. + + An argument COUNT is a repeat count, as for `step'. + + The `next' command now only stops at the first instruction of a + source line. This prevents the multiple stops that used to occur + in switch statements, for loops, etc. + +`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' makes your program continue execution + until it exits the loop. In contrast, a `next' command at the end + of a loop simply steps back to the beginning of the loop, which + forces 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 makes GDB automatically display the next + instruction to be executed, each time your program stops. *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, Next: Thread Stops, 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. + + `info handle' is the new alias for `info 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 can + handle the signal, or else it may terminate 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 sees 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 your program sees that signal when you +continue. + + 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: Thread Stops, Prev: Signals, Up: Stopping + +Stopping and starting multi-thread programs +=========================================== + + When your program has multiple threads (*note Debugging programs +with multiple threads: Threads.), you can choose whether to set +breakpoints on all threads, or on a particular thread. + +`break LINESPEC thread THREADNO' +`break LINESPEC thread THREADNO if ...' + LINESPEC specifies source lines; there are several ways of writing + them, but the effect is always to specify some source line. + + Use the qualifier `thread THREADNO' with a breakpoint command to + specify that you only want GDB to stop the program when a + particular thread reaches this breakpoint. THREADNO is one of the + numeric thread identifiers assigned by GDB, shown in the first + column of the `info threads' display. + + If you do not specify `thread THREADNO' when you set a breakpoint, + the breakpoint applies to *all* threads of your program. + + You can use the `thread' qualifier on conditional breakpoints as + well; in this case, place `thread THREADNO' before the breakpoint + condition, like this: + + (gdb) break frik.c:13 thread 28 if bartab > lim + + Whenever your program stops under GDB for any reason, *all* threads +of execution stop, not just the current thread. This allows you to +examine the overall state of the program, including switching between +threads, without worrying that things may change underfoot. + + Conversely, whenever you restart the program, *all* threads start +executing. *This is true even when single-stepping* with commands like +`step' or `next'. + + In particular, GDB cannot single-step all threads in lockstep. +Since thread scheduling is up to your debugging target's operating +system (not controlled by GDB), other threads may execute more than one +statement while the current thread completes a single step. Moreover, +in general other threads stop in the middle of a statement, rather than +at a clean statement boundary, when the program stops. + + You might even find your program stopped in another thread after +continuing or even single-stepping. This happens whenever some other +thread runs into a breakpoint, a signal, or an exception before the +first thread completes whatever you requested. + + On some OSes, you can lock the OS scheduler and thus allow only a +single thread to run. + +`set scheduler-locking MODE' + Set the scheduler locking mode. If it is `off', then there is no + locking and any thread may run at any time. If `on', then only the + current thread may run when the inferior is resumed. The `step' + mode optimizes for single-stepping. It stops other threads from + "seizing the prompt" by preempting the current thread while you are + stepping. Other threads will only rarely (or never) get a chance + to run when you step. They are more likely to run when you "next" + over a function call, and they are completely free to run when you + use commands like "continue", "until", or "finish". However, + unless another thread hits a breakpoint during its timeslice, they + will never steal the GDB prompt away from the thread that you are + debugging. + +`show scheduler-locking' + Display the current scheduler locking mode. + + +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, information about +the call is generated. That information includes the location of the +call in your program, the arguments of the call, and the local +variables of the function being called. The information is saved in a +block of data called a "stack frame". 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. *Note Selecting a frame: +Selection. + + When your program stops, GDB automatically selects the currently +executing frame and describes it briefly, similar to the `frame' +command (*note Information about a frame: Frame Info.). + +* Menu: + +* Frames:: Stack frames +* Backtrace:: Backtraces +* Selection:: Selecting a frame +* Frame Info:: Information on a frame +* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack + + +File: gdb.info, Node: Frames, Next: Backtrace, Prev: Stack, 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 byte +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' generates 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 nevertheless regards 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. + +`frame ARGS' + The `frame' command allows you to move from one stack frame to + another, and to print the stack frame you select. ARGS may be + either the address of the frame or the stack frame number. + Without an argument, `frame' prints the current stack frame. + +`select-frame' + The `select-frame' command allows you to move from one stack frame + to another without printing the frame. This is the silent version + of `frame'. + + +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'. + + +File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack + +Selecting a frame +================= + + Most commands for examining the stack and other data in your program +work on whichever stack frame is selected at the moment. Here are the +commands for selecting a stack frame; all of them finish by printing a +brief description of the stack frame just selected. + +`frame N' +`f N' + Select frame number N. Recall that frame zero is the innermost + (currently executing) frame, frame one is the frame that called the + innermost one, and so on. The highest-numbered frame is the one + for `main'. + +`frame ADDR' +`f ADDR' + Select the frame at address ADDR. This is useful mainly if the + chaining of stack frames has been damaged by a bug, making it + impossible for GDB to assign numbers properly to all frames. In + addition, this can be useful when your program has multiple stacks + and switches between them. + + On the SPARC architecture, `frame' needs two addresses to select + an arbitrary frame: a frame pointer and a stack pointer. + + On the MIPS and Alpha architecture, it needs two addresses: a stack + pointer and a program counter. + + On the 29k architecture, it needs three addresses: a register stack + pointer, a program counter, and a memory stack pointer. + +`up N' + Move N frames up the stack. For positive numbers N, this advances + toward the outermost frame, to higher frame numbers, to frames + that have existed longer. N defaults to one. + +`down N' + Move N frames down the stack. For positive numbers N, this + advances toward the innermost frame, to lower frame numbers, to + frames that were created more recently. N defaults to one. You + may abbreviate `down' as `do'. + + All of these commands end by printing two lines of output describing +the frame. The first line shows the frame number, the function name, +the arguments, and the source file and line number of execution in that +frame. The second line shows the text of that source line. + + For example: + + (gdb) up + #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) + at env.c:10 + 10 read_input_file (argv[i]); + + After such a printout, the `list' command with no arguments prints +ten lines centered on the point of execution in the frame. *Note +Printing source lines: List. + +`up-silently N' +`down-silently N' + These two commands are variants of `up' and `down', respectively; + they differ in that they do their work silently, without causing + display of the new frame. They are intended primarily for use in + GDB command scripts, where the output might be unnecessary and + distracting. + + +File: gdb.info, Node: Frame Info, Next: Alpha/MIPS Stack, Prev: Selection, Up: Stack + +Information about a frame +========================= + + There are several other commands to print information about the +selected stack frame. + +`frame' +`f' + When used without any argument, this command does not change which + frame is selected, but prints a brief description of the currently + selected stack frame. It can be abbreviated `f'. With an + argument, this command is used to select a stack frame. *Note + Selecting a frame: Selection. + +`info frame' +`info f' + This command prints a verbose description of the selected stack + frame, including: + + * the address of the frame + + * the address of the next frame down (called by this frame) + + * the address of the next frame up (caller of this frame) + + * the language in which the source code corresponding to this + frame is written + + * the address of the frame's arguments + + * the program counter saved in it (the address of execution in + the caller frame) + + * which registers were saved in the frame + + The verbose description is useful when something has gone wrong + that has made the stack format fail to fit the usual conventions. + +`info frame ADDR' +`info f ADDR' + Print a verbose description of the frame at address ADDR, without + selecting that frame. The selected frame remains unchanged by this + command. This requires the same kind of address (more than one + for some architectures) that you specify in the `frame' command. + *Note Selecting a frame: Selection. + +`info args' + Print the arguments of the selected frame, each on a separate line. + +`info locals' + Print the local variables of the selected frame, each on a separate + line. These are all variables (declared either static or + automatic) accessible at the point of execution of the selected + frame. + +`info catch' + Print a list of all the exception handlers that are active in the + current stack frame at the current point of execution. To see + other exception handlers, visit the associated frame (using the + `up', `down', or `frame' commands); then type `info catch'. *Note + Setting catchpoints: Set Catchpoints. + + +File: gdb.info, Node: Alpha/MIPS Stack, Prev: Frame Info, Up: Stack + +MIPS/Alpha machines and the function stack +========================================== + + Alpha- and MIPS-based computers use an unusual stack frame, which +sometimes requires GDB to search backward in the object code to find +the beginning of a function. + + To improve response time (especially for embedded applications, where +GDB may be restricted to a slow serial line for this search) you may +want to limit the size of this search, using one of these commands: + +`set heuristic-fence-post LIMIT' + Restrict GDB to examining at most LIMIT bytes in its search for + the beginning of a function. A value of 0 (the default) means + there is no limit. However, except for 0, the larger the limit + the more bytes `heuristic-fence-post' must search and therefore + the longer it takes to run. + +`show heuristic-fence-post' + Display the current limit. + +These commands are available *only* when GDB is configured for +debugging programs on Alpha or MIPS processors. + + +File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top + +Examining Source Files +********************** + + GDB can print parts of your program's source, since the debugging +information recorded in the program tells GDB what source files were +used to build it. When your program stops, GDB spontaneously prints +the line where it stopped. Likewise, when you select a stack frame +(*note Selecting a frame: Selection.), GDB prints the line where +execution in that frame has stopped. You can print other portions of +source files by explicit command. + + If you use GDB through its GNU Emacs interface, you may prefer to use +Emacs facilities to view source; *note Using GDB under GNU Emacs: +Emacs.. + +* Menu: + +* List:: Printing source lines + +* Search:: Searching source files + +* Source Path:: Specifying source directories +* Machine Code:: Source and machine code + + +File: gdb.info, Node: List, Next: Search, Prev: Source, Up: Source + +Printing source lines +===================== + + To print lines from a source file, use the `list' command +(abbreviated `l'). By default, ten lines are printed. There are +several ways to specify what part of the file you want to print. + + Here are the forms of the `list' command most commonly used: + +`list LINENUM' + Print lines centered around line number LINENUM in the current + source file. + +`list FUNCTION' + Print lines centered around the beginning of function FUNCTION. + +`list' + Print more lines. If the last lines printed were printed with a + `list' command, this prints lines following the last lines + printed; however, if the last line printed was a solitary line + printed as part of displaying a stack frame (*note Examining the + Stack: Stack.), this prints lines centered around that line. + +`list -' + Print lines just before the lines last printed. + + By default, GDB prints ten source lines with any of these forms of +the `list' command. You can change this using `set listsize': + +`set listsize COUNT' + Make the `list' command display COUNT source lines (unless the + `list' argument explicitly specifies some other number). + +`show listsize' + Display the number of lines that `list' prints. + + Repeating a `list' command with <RET> discards the argument, so it +is equivalent to typing just `list'. This is more useful than listing +the same lines again. An exception is made for an argument of `-'; +that argument is preserved in repetition so that each repetition moves +up in the source file. + + In general, the `list' command expects you to supply zero, one or two +"linespecs". Linespecs specify source lines; there are several ways of +writing them but the effect is always to specify some source line. +Here is a complete description of the possible arguments for `list': + +`list LINESPEC' + Print lines centered around the line specified by LINESPEC. + +`list FIRST,LAST' + Print lines from FIRST to LAST. Both arguments are linespecs. + +`list ,LAST' + Print lines ending with LAST. + +`list FIRST,' + Print lines starting with FIRST. + +`list +' + Print lines just after the lines last printed. + +`list -' + Print lines just before the lines last printed. + +`list' + As described in the preceding table. + + Here are the ways of specifying a single source line--all the kinds +of linespec. + +`NUMBER' + Specifies line NUMBER of the current source file. When a `list' + command has two linespecs, this refers to the same source file as + the first linespec. + +`+OFFSET' + Specifies the line OFFSET lines after the last line printed. When + used as the second linespec in a `list' command that has two, this + specifies the line OFFSET lines down from the first linespec. + +`-OFFSET' + Specifies the line OFFSET lines before the last line printed. + +`FILENAME:NUMBER' + Specifies line NUMBER in the source file FILENAME. + +`FUNCTION' + Specifies the line that begins the body of the function FUNCTION. + For example: in C, this is the line with the open brace. + +`FILENAME:FUNCTION' + Specifies the line of the open-brace that begins the body of the + function FUNCTION in the file FILENAME. You only need the file + name with a function name to avoid ambiguity when there are + identically named functions in different source files. + +`*ADDRESS' + Specifies the line containing the program address ADDRESS. + ADDRESS may be any expression. + + +File: gdb.info, Node: Search, Next: Source Path, Prev: List, Up: Source + +Searching source files +====================== + + There are two commands for searching through the current source file +for a regular expression. + +`forward-search REGEXP' +`search REGEXP' + The command `forward-search REGEXP' checks each line, starting + with the one following the last line listed, for a match for + REGEXP. It lists the line that is found. You can use the synonym + `search REGEXP' or abbreviate the command name as `fo'. + +`reverse-search REGEXP' + The command `reverse-search REGEXP' checks each line, starting + with the one before the last line listed and going backward, for a + match for REGEXP. It lists the line that is found. You can + abbreviate this command as `rev'. + + +File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source + +Specifying source directories +============================= + + Executable programs sometimes do not record the directories of the +source files from which they were compiled, just the names. Even when +they do, the directories could be moved between the compilation and +your debugging session. GDB has a list of directories to search for +source files; this is called the "source path". Each time GDB wants a +source file, it tries all the directories in the list, in the order +they are present in the list, until it finds a file with the desired +name. Note that the executable search path is *not* used for this +purpose. Neither is the current working directory, unless it happens +to be in the source path. + + If GDB cannot find a source file in the source path, and the object +program records a directory, GDB tries that directory too. If the +source path is empty, and there is no record of the compilation +directory, GDB looks in the current directory as a last resort. + + Whenever you reset or rearrange the source path, GDB clears out any +information it has cached about where source files are found and where +each line is in the file. + + When you start GDB, its source path is empty. To add other +directories, use the `directory' command. + +`directory DIRNAME ...' + +`dir DIRNAME ...' + Add directory DIRNAME to the front of the source path. Several + directory names may be given to this command, separated by `:' or + whitespace. You may specify a directory that is already in the + source path; this moves it forward, so GDB searches it sooner. + + You can use the string `$cdir' to refer to the compilation + directory (if one is recorded), and `$cwd' to refer to the current + working directory. `$cwd' is not the same as `.'--the former + tracks the current working directory as it changes during your GDB + session, while the latter is immediately expanded to the current + directory at the time you add an entry to the source path. + +`directory' + Reset the source path to empty again. This requires confirmation. + +`show directories' + Print the source path: show which directories it contains. + + If your source path is cluttered with directories that are no longer +of interest, GDB may sometimes cause confusion by finding the wrong +versions of source. You can correct the situation as follows: + + 1. Use `directory' with no argument to reset the source path to empty. + + 2. Use `directory' with suitable arguments to reinstall the + directories you want in the source path. You can add all the + directories in one command. + + +File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source + +Source and machine code +======================= + + You can use the command `info line' to map source lines to program +addresses (and vice versa), and the command `disassemble' to display a +range of addresses as machine instructions. When run under GNU Emacs +mode, the `info line' command now causes the arrow to point to the line +specified. Also, `info line' prints addresses in symbolic form as well +as hex. + +`info line LINESPEC' + Print the starting and ending addresses of the compiled code for + source line LINESPEC. You can specify source lines in any of the + ways understood by the `list' command (*note Printing source + lines: List.). + + For example, we can use `info line' to discover the location of the +object code for the first line of function `m4_changequote': + + (gdb) info line m4_changecom + Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. + +We can also inquire (using `*ADDR' as the form for LINESPEC) what +source line covers a particular address: + (gdb) info line *0x63ff + Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. + + After `info line', the default address for the `x' command is +changed to the starting address of the line, so that `x/i' is +sufficient to begin examining the machine code (*note Examining memory: +Memory.). Also, this address is saved as the value of the convenience +variable `$_' (*note Convenience variables: Convenience Vars.). + +`disassemble' + This specialized command dumps a range of memory as machine + instructions. The default memory range is the function + surrounding the program counter of the selected frame. A single + argument to this command is a program counter value; GDB dumps the + function surrounding this value. Two arguments specify a range of + addresses (first inclusive, second exclusive) to dump. + + The following example shows the disassembly of a range of addresses +of HP PA-RISC 2.0 code: + + (gdb) disas 0x32c4 0x32e4 + Dump of assembler code from 0x32c4 to 0x32e4: + 0x32c4 <main+204>: addil 0,dp + 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 + 0x32cc <main+212>: ldil 0x3000,r31 + 0x32d0 <main+216>: ble 0x3f8(sr4,r31) + 0x32d4 <main+220>: ldo 0(r31),rp + 0x32d8 <main+224>: addil -0x800,dp + 0x32dc <main+228>: ldo 0x588(r1),r26 + 0x32e0 <main+232>: ldil 0x3000,r31 + End of assembler dump. + + Some architectures have more than one commonly-used set of +instruction mnemonics or other syntax. + +`set assembly-language INSTRUCTION-SET' + Select the instruction set to use when disassembling the program + via the `disassemble' or `x/i' commands. + + Currently this command is only defined for the Intel x86 family. + You can set INSTRUCTION-SET to either `i386' or `i8086'. The + default is `i386'. + + +File: gdb.info, Node: Data, Next: Languages, Prev: Source, Up: Top + +Examining Data +************** + + The usual way to examine data in your program is with the `print' +command (abbreviated `p'), or its synonym `inspect'. It evaluates and +prints the value of an expression of the language your program is +written in (*note Using GDB with Different Languages: Languages.). + +`print EXP' +`print /F EXP' + EXP is an expression (in the source language). By default the + value of EXP is printed in a format appropriate to its data type; + you can choose a different format by specifying `/F', where F is a + letter specifying the format; *note Output formats: Output + Formats.. + +`print' +`print /F' + If you omit EXP, GDB displays the last value again (from the + "value history"; *note Value history: Value History.). This + allows you to conveniently inspect the same value in an + alternative format. + + A more low-level way of examining data is with the `x' command. It +examines data in memory at a specified address and prints it in a +specified format. *Note Examining memory: Memory. + + If you are interested in information about types, or about how the +fields of a struct or class are declared, use the `ptype EXP' command +rather than `print'. *Note Examining the Symbol Table: Symbols. + +* Menu: + +* Expressions:: Expressions +* Variables:: Program variables +* Arrays:: Artificial arrays +* Output Formats:: Output formats +* Memory:: Examining memory +* Auto Display:: Automatic display +* Print Settings:: Print settings +* Value History:: Value history +* Convenience Vars:: Convenience variables +* Registers:: Registers + +* Floating Point Hardware:: Floating point hardware + + +File: gdb.info, Node: Expressions, Next: Variables, Prev: Data, Up: Data + +Expressions +=========== + + `print' and many other GDB commands accept an expression and compute +its value. Any kind of constant, variable or operator defined by the +programming language you are using is valid in an expression in GDB. +This includes conditional expressions, function calls, casts and string +constants. It unfortunately does not include symbols defined by +preprocessor `#define' commands. + + GDB now supports array constants in expressions input by the user. +The syntax is {ELEMENT, ELEMENT...}. For example, you can now use the +command `print {1, 2, 3}' to build up an array in memory that is +malloc'd in the target program. + + Because C is so widespread, most of the expressions shown in +examples in this manual are in C. *Note Using GDB with Different +Languages: Languages, for information on how to use expressions in other +languages. + + In this section, we discuss operators that you can use in GDB +expressions regardless of your programming language. + + Casts are supported in all languages, not just in C, because it is so +useful to cast a number into a pointer in order to examine a structure +at that address in memory. + + GDB supports these operators, in addition to those common to +programming languages: + +`@' + `@' is a binary operator for treating parts of memory as arrays. + *Note Artificial arrays: Arrays, for more information. + +`::' + `::' allows you to specify a variable in terms of the file or + function where it is defined. *Note Program variables: Variables. + +`{TYPE} ADDR' + Refers to an object of type TYPE stored at address ADDR in memory. + ADDR may be any expression whose value is an integer or pointer + (but parentheses are required around binary operators, just as in + a cast). This construct is allowed regardless of what kind of + data is normally supposed to reside at ADDR. + + +File: gdb.info, Node: Variables, Next: Arrays, Prev: Expressions, Up: Data + +Program variables +================= + + The most common kind of expression to use is the name of a variable +in your program. + + Variables in expressions are understood in the selected stack frame +(*note Selecting a frame: Selection.); they must be either: + + * global (or file-static) + +or + + * visible according to the scope rules of the programming language + from the point of execution in that frame + +This means that in the function + + foo (a) + int a; + { + bar (a); + { + int b = test (); + bar (b); + } + } + +you can examine and use the variable `a' whenever your program is +executing within the function `foo', but you can only use or examine +the variable `b' while your program is executing inside the block where +`b' is declared. + + There is an exception: you can refer to a variable or function whose +scope is a single source file even if the current execution point is not +in this file. But it is possible to have more than one such variable or +function with the same name (in different source files). If that +happens, referring to that name has unpredictable effects. If you wish, +you can specify a static variable in a particular function or file, +using the colon-colon notation: + + FILE::VARIABLE + FUNCTION::VARIABLE + +Here FILE or FUNCTION is the name of the context for the static +VARIABLE. In the case of file names, you can use quotes to make sure +GDB parses the file name as a single word--for example, to print a +global value of `x' defined in `f2.c': + + (gdb) p 'f2.c'::x + + This use of `::' is very rarely in conflict with the very similar +use of the same notation in C++. GDB also supports use of the C++ +scope resolution operator in GDB expressions. + + *Warning:* Occasionally, a local variable may appear to have the + wrong value at certain points in a function--just after entry to a + new scope, and just before exit. + You may see this problem when you are stepping by machine +instructions. This is because, on most machines, it takes more than +one instruction to set up a stack frame (including local variable +definitions); if you are stepping by machine instructions, variables +may appear to have the wrong values until the stack frame is completely +built. On exit, it usually also takes more than one machine +instruction to destroy a stack frame; after you begin stepping through +that group of instructions, local variable definitions may be gone. + + This may also happen when the compiler does significant +optimizations. To be sure of always seeing accurate values, turn off +all optimization when compiling. + |