1 files changed, 279 insertions, 0 deletions
diff --git a/gdb/doc/gdb.stack-m4 b/gdb/doc/gdb.stack-m4
new file mode 100755
index 0000000..fa88c9e
--- /dev/null
+++ b/gdb/doc/gdb.stack-m4
@@ -0,0 +1,279 @@
+_dnl__								-*- Texinfo -*-
+_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
+_dnl__ This file is part of the source for the GDB manual.
+_dnl__ $Id$
+@node Stack, Source, Stopping, Top
+@chapter Examining the Stack
+
+When your program has stopped, the first thing you need to know is where it
+stopped and how it got there.
+
+@cindex call stack
+Each time your program performs a function call, the information about
+where in the program the call was made from is saved in a block of data
+called a @dfn{stack frame}.  The frame also contains the arguments of the
+call and the local variables of the function that was called.  All the
+stack frames are allocated in a region of memory called the @dfn{call
+stack}.
+
+When your program stops, the _GDBN__ commands for examining the stack allow you
+to see all of this information.
+
+@cindex selected frame
+One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
+refer implicitly to the selected frame.  In particular, whenever you ask
+_GDBN__ for the value of a variable in the program, the value is found in the
+selected frame.  There are special _GDBN__ commands to select whichever frame
+you are interested in.
+
+When the program stops, _GDBN__ automatically selects the currently executing
+frame and describes it briefly as the @code{frame} command does
+(@pxref{Frame Info, Info}).
+
+@menu
+* Frames::			Stack Frames
+* Backtrace::			Backtraces
+* Selection::			Selecting a Frame
+* Frame Info::			Information on a Frame
+@end menu
+
+@node Frames, Backtrace, Stack, Stack
+@section Stack Frames
+
+@cindex frame
+@cindex stack frame
+The call stack is divided up into contiguous pieces called @dfn{stack
+frames}, or @dfn{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.
+
+@cindex initial frame
+@cindex outermost frame
+@cindex innermost frame
+When your program is started, the stack has only one frame, that of the
+function @code{main}.  This is called the @dfn{initial} frame or the
+@dfn{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 @dfn{innermost} frame.  This is the most
+recently created of all the stack frames that still exist.
+
+@cindex frame pointer
+Inside your program, stack frames are identified by their addresses.  A
+stack frame consists of many bytes, each of which has its own address; each
+kind of computer has a convention for choosing one of those bytes whose
+address serves as the address of the frame.  Usually this address is kept
+in a register called the @dfn{frame pointer register} while execution is
+going on in that frame.
+
+@cindex frame number
+_GDBN__ 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 _GDBN__ to give you a way of designating stack
+frames in _GDBN__ commands.
+
+@cindex frameless execution
+Some compilers allow functions to be compiled so that they operate
+without stack frames.  (For example, the @code{_GCC__} option
+@samp{-fomit-frame-pointer} will generate functions without a frame.)
+This is occasionally done with heavily used library functions to save
+the frame setup time.  _GDBN__ has limited facilities for dealing with
+these function invocations.  If the innermost function invocation has no
+stack frame, _GDBN__ will nevertheless regard it as though it had a
+separate frame, which is numbered zero as usual, allowing correct
+tracing of the function call chain.  However, _GDBN__ has no provision
+for frameless functions elsewhere in the stack.
+
+@node Backtrace, Selection, Frames, Stack
+@section Backtraces
+
+A backtrace is a summary of how the 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.
+
+@table @code
+@item backtrace
+@itemx bt
+@kindex backtrace
+@kindex 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 @kbd{Control-C}.
+
+@item backtrace @var{n}
+@itemx bt @var{n}
+Similar, but print only the innermost @var{n} frames.
+
+@item backtrace -@var{n}
+@itemx bt -@var{n}
+Similar, but print only the outermost @var{n} frames.
+@end table
+
+@kindex where
+@kindex info stack
+@kindex info s
+The names @code{where} and @code{info stack} (abbreviated @code{info s})
+are additional aliases for @code{backtrace}.
+
+Each line in the backtrace shows the frame number and the function name.
+The program counter value is also shown---unless you use @code{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
+@samp{bt 3}, so it shows the innermost three frames.
+
+@smallexample
+@group
+#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...)
+@end group
+@end smallexample
+
+@noindent
+The display for frame zero doesn't begin with a program counter
+value, indicating that the program has stopped at the beginning of the
+code for line @code{993} of @code{builtin.c}.
+
+@node Selection, Frame Info, Backtrace, Stack
+@section Selecting a Frame
+
+Most commands for examining the stack and other data in the 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.
+
+@table @code
+@item frame @var{n}
+@itemx f @var{n}
+@kindex frame
+@kindex f
+Select frame number @var{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 @code{main}'s
+frame.
+
+@item frame @var{addr}
+@itemx f @var{addr}
+Select the frame at address @var{addr}.  This is useful mainly if the
+chaining of stack frames has been damaged by a bug, making it
+impossible for _GDBN__ to assign numbers properly to all frames.  In
+addition, this can be useful when the program has multiple stacks and
+switches between them.
+
+_if_(_SPARC__)
+On the SPARC architecture, @code{frame} needs two addresses to
+select an arbitrary frame: a frame pointer and a stack pointer.  
+@c note to future updaters: this is conditioned on a flag
+@c FRAME_SPECIFICATION_DYADIC in the tm-*.h files, currently only used
+@c by SPARC, hence the specific attribution.  Generalize or list all
+@c possibilities if more supported machines start doing this.
+_fi_(_SPARC__)
+
+@item up @var{n}
+@kindex up
+Move @var{n} frames up the stack.  For positive numbers @var{n}, this
+advances toward the outermost frame, to higher frame numbers, to frames
+that have existed longer.  @var{n} defaults to one.
+
+@item down @var{n}
+@kindex down
+@kindex do
+Move @var{n} frames down the stack.  For positive numbers @var{n}, this
+advances toward the innermost frame, to lower frame numbers, to frames
+that were created more recently.  @var{n} defaults to one.  You may
+abbreviate @code{down} as @code{do}.
+@end table
+
+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:
+
+@smallexample
+(_GDBP__) up
+#1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
+10              read_input_file (argv[i]);
+@end smallexample
+
+After such a printout, the @code{list} command with no arguments will print
+ten lines centered on the point of execution in the frame.  @xref{List}.
+
+@table @code
+@item up-silently @var{n}
+@itemx down-silently @var{n}
+@kindex down-silently
+@kindex up-silently
+These two commands are variants of @code{up} and @code{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 _GDBN__ command scripts, where the output might be unnecessary and
+distracting. 
+
+@end table
+
+@node Frame Info,  , Selection, Stack
+@section Information About a Frame
+
+There are several other commands to print information about the selected
+stack frame.
+
+@table @code
+@item frame
+@itemx 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 @code{f}.  With an
+argument, this command is used to select a stack frame (@pxref{Selection}).
+
+@item info frame
+@kindex info frame
+@itemx info f
+@kindex info f
+This command prints a verbose description of the selected stack frame,
+including the address of the frame, the addresses of the next frame down
+(called by this frame) and the next frame up (caller of this frame),
+the address of the frame's arguments, the program counter saved in it
+(the address of execution in the caller frame), and 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.
+
+@item info frame @var{addr}
+@itemx info f @var{addr}
+Print a verbose description of the frame at address @var{addr},
+without selecting that frame.  The selected frame remains unchanged by
+this command.
+
+@item info args
+@kindex info args
+Print the arguments of the selected frame, each on a separate line.
+
+@item info locals
+@kindex info locals
+Print the local variables of the selected frame, each on a separate
+line.  These are all variables declared static or automatic within all
+program blocks that execution in this frame is currently inside of.
+
+@item info catch
+@kindex info catch
+@cindex catch exceptions
+@cindex exception handlers
+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 @code{up},
+@code{down}, or @code{frame} commands); then type @code{info catch}.
+@xref{Exception Handling}.
+@end table