<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="debug-stack">

  <info xmlns:facet="http://projectmallard.org/facet/1.0/">
    <facet:tag key="all-pages" value="whatever"/> <!--Include page in index-->
    <link type="guide" xref="debug-data" group="fourth"/>
    <revision pkgversion="3.0" version="0.1" date="2011-03-27" status="incomplete"/>
    <desc>
      Examine the stack.
    </desc>
    <credit type="author">
      <name>Sébastien Granjoux</name>
      <email>seb.sfo@free.fr</email>
    </credit>
    <credit type="editor">
      <name>Philip Chimento</name>
      <email>philip.chimento@gmail.com</email>
    </credit>
  </info>

  <title>Stack</title>

  <section>
    <title>List stack frames</title>

    <p>A stack frame is the area of the stack associated to each function call.
    It lists all functions and their arguments in the sequence they were called.
    Each stack frame is numbered starting from 0 for the current function.
    You can only view the stack frames while the debugger is running.</p>

    <p>Moreover, a program can be composed of several threads. Each thread is
    executed independently and has its own registers, stack and local
    variables, but shares all global variables.</p>

    <steps>
      <item>
        <p>From the <gui>main menu</gui>, select <guiseq><gui>View</gui>
        <gui>Stack</gui></guiseq> to open the <gui>Stack</gui>
        window.</p>
      </item>
    </steps>

    <p>The stacks are displayed in a tree view having their corresponding
    thread as parent and displaying the following information:</p>	

    <terms>
      <item>
        <title>Active</title>
        <p>This contains a yellow arrow to represent the active stack frame. By
        default it is frame 0, the current function. All evaluations and
        local variables are relative to this active frame. You can change
        the active stack frame to examine local variables in other functions.</p>
      </item>
      <item>
        <title>Thread</title>
        <p>This is a number corresponding to each thread.</p>
      </item>
      <item>
        <title>Frame</title>
        <p>This is the frame number starting from 0 for the current function.
        The first function of your program, for example <code>main()</code> in a C program,
        has the highest number.</p>
      </item>
      <item>
        <title>File</title>
        <p>The name of the file containing the function corresponding to
        this frame.</p>
      </item>
      <item>
        <title>Line</title>
        <p>The line number of the function corresponding to this frame.</p>
      </item>
      <item>
        <title>Function</title>
        <p>The name of the function corresponding to this frame.</p>
      </item>
      <item>
        <title>Address</title>
        <p>The address of the function corresponding to this frame.</p>
      </item>
      <item>
        <title>Arguments</title>
        <p>The function arguments.</p>
      </item>
    </terms>

  </section>


  <section>
    <title>Change the current stack frame or thread</title>

    <steps>
      <item>
        <p>In the <gui>Stack</gui> window, select the frame you want.</p>
      </item>
      <item>
        <p>Right-click and select <gui>Set current frame</gui>.</p>
      </item>
    </steps>

    <p>Clicking on a stack frame in the same thread changes only the
    stack frame, allowing to see other local variables. But doing it
    in another thread will change both the stack frame
    and the thread. The register values will be different and the
    debugger will restart in the selected thread.</p>
  </section>


  <section>
    <title>View the current function</title>

    <steps>
      <item>
        <p>In the <gui>Stack</gui> window, select the frame you want.</p>
      </item>
      <item>
        <p>Double-click, or right-click and select <gui>View Source</gui>.</p>
      </item>
    </steps>
  </section>


  <section>
    <title>Get a stack trace</title>
 
    <steps>
      <item>
        <p>In the <gui>Stack</gui> window, right-click and select
        <gui>Get stack trace</gui>.</p>
      </item>
    </steps>
  </section>


</page>
