gdb/doc/gdb.stack-m4

   1 _dnl__                                                          -*- Texinfo -*-
   2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
   3 _dnl__ This file is part of the source for the GDB manual.
   4 @c M4 FRAGMENT: $Id$
   5 @node Stack, Source, Stopping, Top
   6 @chapter Examining the Stack
   7
   8 When your program has stopped, the first thing you need to know is where it
   9 stopped and how it got there.
  10
  11 @cindex call stack
  12 Each time your program performs a function call, the information about
  13 where in the program the call was made from is saved in a block of data
  14 called a @dfn{stack frame}.  The frame also contains the arguments of the
  15 call and the local variables of the function that was called.  All the
  16 stack frames are allocated in a region of memory called the @dfn{call
  17 stack}.
  18
  19 When your program stops, the _GDBN__ commands for examining the stack allow you
  20 to see all of this information.
  21
  22 @cindex selected frame
  23 One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
  24 refer implicitly to the selected frame.  In particular, whenever you ask
  25 _GDBN__ for the value of a variable in the program, the value is found in the
  26 selected frame.  There are special _GDBN__ commands to select whichever frame
  27 you are interested in.
  28
  29 When the program stops, _GDBN__ automatically selects the currently executing
  30 frame and describes it briefly as the @code{frame} command does
  31 (@pxref{Frame Info, Info}).
  32
  33 @menu
  34 * Frames::                      Stack Frames
  35 * Backtrace::                   Backtraces
  36 * Selection::                   Selecting a Frame
  37 * Frame Info::                  Information on a Frame
  38 @end menu
  39
  40 @node Frames, Backtrace, Stack, Stack
  41 @section Stack Frames
  42
  43 @cindex frame
  44 @cindex stack frame
  45 The call stack is divided up into contiguous pieces called @dfn{stack
  46 frames}, or @dfn{frames} for short; each frame is the data associated
  47 with one call to one function.  The frame contains the arguments given
  48 to the function, the function's local variables, and the address at
  49 which the function is executing.
  50
  51 @cindex initial frame
  52 @cindex outermost frame
  53 @cindex innermost frame
  54 When your program is started, the stack has only one frame, that of the
  55 function @code{main}.  This is called the @dfn{initial} frame or the
  56 @dfn{outermost} frame.  Each time a function is called, a new frame is
  57 made.  Each time a function returns, the frame for that function invocation
  58 is eliminated.  If a function is recursive, there can be many frames for
  59 the same function.  The frame for the function in which execution is
  60 actually occurring is called the @dfn{innermost} frame.  This is the most
  61 recently created of all the stack frames that still exist.
  62
  63 @cindex frame pointer
  64 Inside your program, stack frames are identified by their addresses.  A
  65 stack frame consists of many bytes, each of which has its own address; each
  66 kind of computer has a convention for choosing one of those bytes whose
  67 address serves as the address of the frame.  Usually this address is kept
  68 in a register called the @dfn{frame pointer register} while execution is
  69 going on in that frame.
  70
  71 @cindex frame number
  72 _GDBN__ assigns numbers to all existing stack frames, starting with
  73 zero for the innermost frame, one for the frame that called it,
  74 and so on upward.  These numbers do not really exist in your program;
  75 they are assigned by _GDBN__ to give you a way of designating stack
  76 frames in _GDBN__ commands.
  77
  78 @cindex frameless execution
  79 Some compilers allow functions to be compiled so that they operate
  80 without stack frames.  (For example, the @code{_GCC__} option
  81 @samp{-fomit-frame-pointer} will generate functions without a frame.)
  82 This is occasionally done with heavily used library functions to save
  83 the frame setup time.  _GDBN__ has limited facilities for dealing with
  84 these function invocations.  If the innermost function invocation has no
  85 stack frame, _GDBN__ will nevertheless regard it as though it had a
  86 separate frame, which is numbered zero as usual, allowing correct
  87 tracing of the function call chain.  However, _GDBN__ has no provision
  88 for frameless functions elsewhere in the stack.
  89
  90 @node Backtrace, Selection, Frames, Stack
  91 @section Backtraces
  92
  93 A backtrace is a summary of how the program got where it is.  It shows one
  94 line per frame, for many frames, starting with the currently executing
  95 frame (frame zero), followed by its caller (frame one), and on up the
  96 stack.
  97
  98 @table @code
  99 @item backtrace
 100 @itemx bt
 101 @kindex backtrace
 102 @kindex bt
 103 Print a backtrace of the entire stack: one line per frame for all
 104 frames in the stack.
 105
 106 You can stop the backtrace at any time by typing the system interrupt
 107 character, normally @kbd{Control-C}.
 108
 109 @item backtrace @var{n}
 110 @itemx bt @var{n}
 111 Similar, but print only the innermost @var{n} frames.
 112
 113 @item backtrace -@var{n}
 114 @itemx bt -@var{n}
 115 Similar, but print only the outermost @var{n} frames.
 116 @end table
 117
 118 @kindex where
 119 @kindex info stack
 120 @kindex info s
 121 The names @code{where} and @code{info stack} (abbreviated @code{info s})
 122 are additional aliases for @code{backtrace}.
 123
 124 Each line in the backtrace shows the frame number and the function name.
 125 The program counter value is also shown---unless you use @code{set
 126 print address off}.  The backtrace also shows the source file name and
 127 line number, as well as the arguments to the function.  The program
 128 counter value is omitted if it is at the beginning of the code for that
 129 line number.
 130
 131 Here is an example of a backtrace.  It was made with the command
 132 @samp{bt 3}, so it shows the innermost three frames.
 133
 134 @smallexample
 135 @group
 136 #0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) at builtin.c:993
 137 #1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
 138 #2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
 139     at macro.c:71
 140 (More stack frames follow...)
 141 @end group
 142 @end smallexample
 143
 144 @noindent
 145 The display for frame zero doesn't begin with a program counter
 146 value, indicating that the program has stopped at the beginning of the
 147 code for line @code{993} of @code{builtin.c}.
 148
 149 @node Selection, Frame Info, Backtrace, Stack
 150 @section Selecting a Frame
 151
 152 Most commands for examining the stack and other data in the program work on
 153 whichever stack frame is selected at the moment.  Here are the commands for
 154 selecting a stack frame; all of them finish by printing a brief description
 155 of the stack frame just selected.
 156
 157 @table @code
 158 @item frame @var{n}
 159 @itemx f @var{n}
 160 @kindex frame
 161 @kindex f
 162 Select frame number @var{n}.  Recall that frame zero is the innermost
 163 (currently executing) frame, frame one is the frame that called the
 164 innermost one, and so on.  The highest-numbered frame is @code{main}'s
 165 frame.
 166
 167 @item frame @var{addr}
 168 @itemx f @var{addr}
 169 Select the frame at address @var{addr}.  This is useful mainly if the
 170 chaining of stack frames has been damaged by a bug, making it
 171 impossible for _GDBN__ to assign numbers properly to all frames.  In
 172 addition, this can be useful when the program has multiple stacks and
 173 switches between them.
 174
 175 _if_(_SPARC__)
 176 On the SPARC architecture, @code{frame} needs two addresses to
 177 select an arbitrary frame: a frame pointer and a stack pointer.
 178 @c note to future updaters: this is conditioned on a flag
 179 @c FRAME_SPECIFICATION_DYADIC in the tm-*.h files, currently only used
 180 @c by SPARC, hence the specific attribution.  Generalize or list all
 181 @c possibilities if more supported machines start doing this.
 182 _fi_(_SPARC__)
 183
 184 @item up @var{n}
 185 @kindex up
 186 Move @var{n} frames up the stack.  For positive numbers @var{n}, this
 187 advances toward the outermost frame, to higher frame numbers, to frames
 188 that have existed longer.  @var{n} defaults to one.
 189
 190 @item down @var{n}
 191 @kindex down
 192 @kindex do
 193 Move @var{n} frames down the stack.  For positive numbers @var{n}, this
 194 advances toward the innermost frame, to lower frame numbers, to frames
 195 that were created more recently.  @var{n} defaults to one.  You may
 196 abbreviate @code{down} as @code{do}.
 197 @end table
 198
 199 All of these commands end by printing two lines of output describing the
 200 frame.  The first line shows the frame number, the function name, the
 201 arguments, and the source file and line number of execution in that
 202 frame.  The second line shows the text of that source line.  For
 203 example:
 204
 205 @smallexample
 206 (_GDBP__) up
 207 #1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
 208 10              read_input_file (argv[i]);
 209 @end smallexample
 210
 211 After such a printout, the @code{list} command with no arguments will print
 212 ten lines centered on the point of execution in the frame.  @xref{List}.
 213
 214 @table @code
 215 @item up-silently @var{n}
 216 @itemx down-silently @var{n}
 217 @kindex down-silently
 218 @kindex up-silently
 219 These two commands are variants of @code{up} and @code{down},
 220 respectively; they differ in that they do their work silently, without
 221 causing display of the new frame.  They are intended primarily for use
 222 in _GDBN__ command scripts, where the output might be unnecessary and
 223 distracting.
 224
 225 @end table
 226
 227 @node Frame Info,  , Selection, Stack
 228 @section Information About a Frame
 229
 230 There are several other commands to print information about the selected
 231 stack frame.
 232
 233 @table @code
 234 @item frame
 235 @itemx f
 236 When used without any argument, this command does not change which frame
 237 is selected, but prints a brief description of the currently
 238 selected stack frame.  It can be abbreviated @code{f}.  With an
 239 argument, this command is used to select a stack frame (@pxref{Selection}).
 240
 241 @item info frame
 242 @kindex info frame
 243 @itemx info f
 244 @kindex info f
 245 This command prints a verbose description of the selected stack frame,
 246 including the address of the frame, the addresses of the next frame down
 247 (called by this frame) and the next frame up (caller of this frame),
 248 the address of the frame's arguments, the program counter saved in it
 249 (the address of execution in the caller frame), and which registers
 250 were saved in the frame.  The verbose description is useful when
 251 something has gone wrong that has made the stack format fail to fit
 252 the usual conventions.
 253
 254 @item info frame @var{addr}
 255 @itemx info f @var{addr}
 256 Print a verbose description of the frame at address @var{addr},
 257 without selecting that frame.  The selected frame remains unchanged by
 258 this command.
 259
 260 @item info args
 261 @kindex info args
 262 Print the arguments of the selected frame, each on a separate line.
 263
 264 @item info locals
 265 @kindex info locals
 266 Print the local variables of the selected frame, each on a separate
 267 line.  These are all variables declared static or automatic within all
 268 program blocks that execution in this frame is currently inside of.
 269
 270 @item info catch
 271 @kindex info catch
 272 @cindex catch exceptions
 273 @cindex exception handlers
 274 Print a list of all the exception handlers that are active in the
 275 current stack frame at the current point of execution.  To see other
 276 exception handlers, visit the associated frame (using the @code{up},
 277 @code{down}, or @code{frame} commands); then type @code{info catch}.
 278 @xref{Exception Handling}.
 279 @end table