[external/binutils.git] / gdb / doc / gdb.info-3

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.

\1f
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

\1f
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)

\1f
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'.

\1f
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.

\1f
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.

\1f
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

\1f
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'.

\1f
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'.

\1f
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.

\1f
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.

\1f
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.

\1f
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

\1f
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.

\1f
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'.

\1f
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.

\1f
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'.

\1f
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

\1f
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.

\1f
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.