<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN" > -->

<!--  This is part of the lcrash HOWTO. -->
<!--  Copyright (C) 2001, 2002 IBM Deutschland Entwicklung GmbH, -->
<!--                           IBM Corporation -->
<!--  See the file lcrash.sgml for copying conditions. -->

<chapter id="cha.generalusage">
  <title>General Usage</title>
  <section id="sec.invokinglcrash">
    <title>Invoking Lcrash</title>
    <para>Three input files are needed for <command>lcrash</command>:
    </para>
    <itemizedlist>
      <listitem>
	<para>a map file providing the symbol table of the Kernel,
	</para>
      </listitem>
      <listitem>
	<para>a dump file containing the image of a system's memory to be
	  analyzed,
	</para>
      </listitem>
      <listitem>
	<para> an object file in "stabs" debug format providing information of
	  Kernel data types.
	  <footnote>
	    <para>In fact <command>lcrash</command> uses only type information
	      contained in the "stabs" format. Further debug information of
	      this format is not used. For more information about the
	      "stabs" format please refer to <citation>stabs1997</citation>.
	    </para>
	  </footnote>
	</para>
      </listitem>
    </itemizedlist>

    <para>Currently <command>lcrash</command> uses positional arguments. To
      invoke <command>lcrash</command> you can use the following command
      line: <command>lcrash <parameter>symbol-table</parameter> 
	<parameter>dump-file</parameter> <parameter>kern-types</parameter>
      </command>
    </para>

    <para>Lcrash knows defaults for its arguments. They are given in table
      <xref linkend="tab.defaultvalues">.
    </para>

    <table id="tab.defaultvalues">
      <title>Default values</title>
      <tgroup cols="2" colsep="1" rowsep="1" align="left">
	<colspec colname="parameter" colwidth="1*">
	<colspec colname="default" colwidth="1*">
	<thead>
	  <row>
	    <entry>Parameter</entry>
	    <entry>Default</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry><parameter>symbol-table</parameter></entry>
	    <entry><filename>/boot/System.map</filename></entry>
	  </row>
	  <row>
	    <entry><parameter>dump-file</parameter></entry>
	    <entry><filename>/dev/mem</filename></entry>
	  </row>
	  <row>
	    <entry><parameter>kern-types</parameter></entry>
	    <entry><filename>/boot/Kerntypes</filename></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <para>If you are happy with all default values you can call
      <command>lcrash</command> without any arguments - as shown in the
      following example.
    </para>
    <example id="ex.startinglcrash">
      <title>Starting Lcrash</title>
      <screen>
<!-- Do not indent following text! It should be printed as is. -->
bash# lcrash                 
map = /boot/System.map, vmdump = /dev/mem, outfile = stdout, kerntypes = /boot/Kerntypes

Please wait...
    Loading system map .................... Done.
    Loading type info (Kerntypes) ... Done.
    Loading ksyms from dump ...... Done.
>>
      </screen>
    </example>

    <para>Lcrash only works correctly if <parameter>symbol-table</parameter>,
      <parameter>kern-types</parameter> and <parameter>dump-file</parameter>
      are from the same Kernel.
    </para>
    <para>The <filename>System.map</filename> file is generated automatically
      when the Kernel is built. It contains symbol names of the Kernel and
      their corresponding Kernel addresses. Normally it is installed under
      <filename>/boot/System.map</filename>.
    </para>
    <para>The file <filename>/dev/mem</filename> is used for analyzing the
      running Linux system. For parameter <parameter>dump-file</parameter>
      you can specify a file containing a dump that was generated
      with dump tools (see chapter \ref{chapter:DumpTools}).
    </para>
    <para>The <filename>Kerntypes</filename> file is also generated in the
      Kernel build. But since <filename>Kerntypes</filename> is not in the
      standard Linux tree it is necessary to apply a specific "Kerntypes
      patch" before. The <filename>Kerntypes</filename> file is compiled with
      the <option>-gstabs</option> compile option which generates type
      information for all types defined in the Kerntypes source file.
      In the Kerntypes source file there are several 
      includes for Kernel header files with important Kernel structures.
    </para>
    <para>The mentioned "Kerntypes patch" and the s390 dump tools can be
      downloaded from <ulink url="http://oss.software.ibm.com/developerworks/opensource/linux390/exp_src.html"></ulink>
    </para>
  </section>


  <section id="sec.userinterface">
    <title>User Interface</title>
    <para>Lcrash provides a command line interface. This comes with
      basic command line editing and history mechanism, which will be
      described here.
    </para>
    <section id="sec.historymechanism">
      <title>History Mechanism</title>
      <para> The default history size is 100 command lines and the maximum
	history size is 1000. Command line length is restricted to 1024
	characters. To view history list or to change number of lines in
	history use the lcrash command \htmlref{'history'}{cmd:history}. An
	explanation of the history mechanism is given in
	<xref linkend="tab.cmdlinehistory">.
      </para>
      <table id="tab.cmdlinehistory">
	<title>Command Line History</title>
	<tgroup cols="2" colsep="1" rowsep="1" align="left">
	  <colspec colname="key" colwidth="1*">
	  <colspec colname="action" colwidth="4*">
	  <tbody>
	    <row>
	      <entry><command>!!</command></entry>
	      <entry>Refer to the previous command. By itself, this
		substitution repeats the previous command.
	      </entry>
	    </row>
	    <row>
	      <entry><command>!<parameter>n</parameter></command></entry>
	      <entry>Refer to command line <parameter>n</parameter>.</entry>
	    </row>
	    <row>
	      <entry><command>!-<parameter>n</parameter></command></entry>
	      <entry>Refer to the current command line minus
		<parameter>n</parameter>.</entry>
	    </row>
	    <row>
	      <entry><command>!<parameter>str</parameter></command></entry>
	      <entry>Refer to the most recent command starting with
		<parameter>str</parameter>.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </section>

    <section id="sec.cmdlineediting">
      <title>Command Line Editing</title>
      <para> Supported keys for line editing are given in
	<xref linkend="tab.cmdlinekeys">
      </para>
      <table id="tab.cmdlinekeys">
	<title>Command Line Keys</title>
	  <tgroup cols="2" colsep="1" rowsep="1" align="left">
	    <colspec colname="key" colwidth="1*">
	    <colspec colname="action" colwidth="4*">
	  <tbody>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>W</keycap></keycombo></entry>
	      <entry>delete to previous word</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>D</keycap></keycombo></entry>
	      <entry>delete current character</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>A</keycap></keycombo></entry>
	      <entry>goto start of line</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>E</keycap></keycombo></entry>
	      <entry>goto end of line</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>F</keycap></keycombo></entry>
	      <entry>forward one character</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>B</keycap></keycombo></entry>
	      <entry>backward one character</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>H</keycap></keycombo></entry>
	      <entry>delete previous character</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>N</keycap></keycombo></entry>
	      <entry>down history</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>K</keycap></keycombo></entry>
	      <entry>erase to end of line (from cursor)</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>L</keycap></keycombo></entry>
	      <entry>clear screen and redisplay prompt</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>P</keycap></keycombo></entry>
	      <entry>up history</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>U</keycap></keycombo></entry>
	      <entry>erase to beginning of line (from cursor)</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Ctrl</keycap><keycap>R</keycap></keycombo></entry>
	      <entry>redraw input line</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Esc</keycap><keycap>F</keycap></keycombo></entry>
	      <entry>forward one word</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Esc</keycap><keycap>B</keycap></keycombo></entry>
	      <entry>backward one word</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Esc</keycap><keycap>D</keycap></keycombo></entry>
	      <entry>delete next work</entry>
	    </row>
	    <row>
	      <entry><keycombo>
		  <keycap>Esc</keycap><keycap>Del</keycap></keycombo></entry>
	      <entry>delete previous word</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </section>
  </section>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-always-quote-attributes:t
sgml-auto-insert-required-elements:t
sgml-balanced-tag-edit:t
sgml-exposed-tags:nil
sgml-general-insert-case:lower
sgml-indent-data:t
sgml-indent-step:2
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
sgml-minimize-attributes:nil
sgml-namecase-general:t
sgml-omittag:t
sgml-parent-document:("lcrash.sgml" "book" "chapter")
sgml-shorttag:t
sgml-tag-region-if-active:t
End:
-->
