crash



CRASH(8)                                                              CRASH(8)




NAME

       crash - Analyze Linux crash data or a live system


SYNAPSIS

       crash [ -h [ opt ] ] [ -v ] [ -s ] [ -i file ] [ -d num ] [ -S ] [ map-
       file ] [ namelist ] [ dumpfile ]


DESCRIPTION

       Crash is a tool for interactively analyzing the state of the Linux sys-
       tem  while  it  is  running, or after a kernel crash has occurred and a
       core dump has been created by the Red  Hat  netdump  facility.   It  is
       loosely based on the SVR4 UNIX crash command, but has been signficantly
       enhanced by completely merging it with the gdb debugger.  The  marriage
       of  the two effectively combines the kernel-specific nature of the tra-
       ditional UNIX crash utility with the source code level debugging  capa-
       bilities of gdb.

       The  current  set  of  commands  consist of common kernel core analysis
       tools such as kernel stack back traces of all  processes,  source  code
       disassembly,  formatted kernel structure and variable displays, virtual
       memory data, dumps of linked-lists, etc., along with  several  commands
       that  delve  deeper  into  specific kernel subsystems.  Appropriate gdb
       commands may also be entered, which in turn are passed on  to  the  gdb
       module for execution.

       The crash utility is designed to be independent of Linux version depen-
       dencies. When new kernel source code impacts the correct  functionality
       of  crash and its command set, the utility will be updated to recognize
       new kernel code changes, while maintaining backwards compatibility with
       earlier releases.


OPTIONS

       -h opt Crash  displays a help message.  If the optional opt argument is
              a crash command name, the help page for  that  command  is  dis-
              played.  If it is the string "input", a page describing the var-
              ious crash command line input options is displayed.   If  it  is
              the  string  "output",  a  page  describing  command line output
              options is displayed.

       -v     Crash displays the  versions  of  the  original  gdb  and  crash
              libraries that make up the crash executable.

       -s     Crash does not display any version, GPL, or crash initialization
              data during startup.   It  proceeds  directly  to  the  "crash>"
              prompt.

       -i file
              Crash  reads and executes the crash command(s) contained in file
              before accepting any user input.

       -d num Crash sets its internal debug level.  The higher the number, the
              more debugging data will be printed while crash runs.

       -S     Crash uses "/boot/System.map" as the mapfile.

       namelist
              This  is  a  pathname to an uncompressed kernel image (a vmlinux
              file) that has been compiled with the "-g" option, or  that  has
              an  accessible,  associated,  debuginfo  file.   If the dumpfile
              argument is entered, then this argument must also be  used.   If
              the namelist argument is not entered and no dumpfile argument is
              entered, crash will search in several typical directories for  a
              kernel namelist that matches the live system.

       mapfile
              If the live system kernel, or the kernel from which the dumpfile
              was derived, was not compiled with the -g switch, then the addi-
              tional mapfile argument is required.  It may be either the asso-
              ciated System.map file, or the non-debug kernel namelist.   How-
              ever,  if  the mapfile argument is used, then the namelist argu-
              ment must be a kernel namelist of a similar kernel version  that
              was built with the -g switch.

       dumpfile
              This  is  a  pathname to a kernel memory core dump file.  If the
              dumpfile argument is not entered, the session will be invoked on
              the  live  system  using  /dev/mem,  which usually requires root
              privileges.


COMMANDS

       Each crash command generally falls into  one  of  the  following  cate-
       gories:

       Symbolic display
              Displays  of  kernel text/data, which take full advantage of the
              power of gdb to format and display data structures symbolically.

       System state
              The majority of crash commands come consist of a set of "kernel-
              aware" commands, which delve into various kernel subsystems on a
              system-wide or per-task basis.

       Utility functions
              A  set  of useful helper commands serving various purposes, some
              simple, others quite powerful.

       Session control
              Commands that control the crash session itself.

       The following alphabetical list consists of a very simple  overview  of
       each crash command.  However, since individual commands often have sev-
       eral options resulting in significantly different output,  it  is  sug-
       gested  that the full description of each command be viewed by entering
       the command crash -h command, or  during  a  crash  session  by  simply
       entering help command.

       *      "pointer  to"  is  shorthand for either the struct or union com-
              mands.  It displays the contents of a kernel structure or union.

       alias  creates a single-word alias for a command.

       ascii  displays  an  ascii chart or translates a numeric value into its
              ascii components.

       bt     displays a task’s kernel-stack backtrace.  If it is given the -a
              option,  it displays the stack traces of the active tasks on all
              CPUs.  It is often used with the foreach command to display  the
              backtraces of all tasks with one command.

       btop   translates a byte value (physical offset) to it’s page number.

       dev    displays  data concerning the character and block device assign-
              ments, I/O port usage, I/O memory usage, and PCI device data.

       dis    disassembles memory, either  entire  kernel  functions,  from  a
              location  for  a  specified  number of instructions, or from the
              start of a fuction up to a specified memory location.

       eval   evalues an expression or numeric type and displays the result in
              hexidecimal, decimal, octal and binary.

       exit   causes crash to exit.

       extend dynamically  loads  or  unloads  crash  extension  shared object
              libraries.

       files  displays information about open files in a context.

       foreach
              repeats a specified command for the specified (or all) tasks  in
              the system.

       fuser  displays the tasks using the specifed file or socket.

       gdb    passes its argument to the underlying gdb program.  It is useful
              for executing GDB commands that have the same name as crash com-
              mands.

       help   alone  displays the command menu; if followed by a command name,
              a full description of a command, its options, and  examples  are
              displayed.  Its output is far more complete and useful than this
              man page.

       irq    displays data concerning interrupt request numbers  and  bottom-
              half interrupt handling.

       kmem   displays information about the use of kernel memory.

       list   displays the contents of a linked list.

       log    displays the kernel log_buf contents in chronological order.

       mach   displays data specific to the machine type.

       mod    displays  information  about the currently installed kernel mod-
              ules, or adds or deletes symbolic or debugging information about
              specified kernel modules.

       mount  displays information about the currently-mounted filesystems.

       net    display various network related data.

       p      passes  its  argumnts  to the gdb "print" command for evaluation
              and display.

       ps     displays process status for specified, or all, processes in  the
              system.

       pte    translates  the  hexadecimal contents of a PTE into its physical
              page address and page bit settings.

       ptob   translates a page frame number to its byte value.

       ptov   translates a hexadecimal physical address into a kernel  virtual
              address.

       q      is an alias for the "exit" command.

       rd     displays  the  contents  of memory, with the output formatted in
              several different manners.

       repeat repeats a command indefinitely, optionally delaying a given num-
              ber of seconds between each command execution.

       runq   displays the tasks on the run queue.

       search searches a range of user or kernel memory space for given value.

       set    either sets a new context, or gets the current context for  dis-
              play.

       sig    displays signal-handling data of one or more tasks.

       struct displays either a structure definition or the contents of a ker-
              nel structure at a specified address.

       swap   displays information about each configured swap device.

       sym    translates a symbol to its virtual address, or a  static  kernel
              virtual  address  to  its  symbol  -- or to a symbol-plus-offset
              value, if appropriate.

       sys    displays system-specific data.

       task   displays the contents of a task_struct.

       timer  displays the timer queue entries, both old-  and  new-style,  in
              chronological order.

       union  is similar to the struct command, except that it works on kernel
              unions.

       vm     displays basic virtual memory information of a context.

       vtop   translates a user or kernel  virtual  address  to  its  physical
              address.

       waitq  walks the wait queue list displaying the tasks which are blocked
              on the specified wait queue.

       whatis displays the  definition  of  structures,  unions,  typedefs  or
              text/data  symbols.   wr  modifies the contents of memory.  When
              writing to memory on a live system, this  command  should  obvi-
              ously be used with great care.


AUTHOR

       Dave Anderson <anderson@redhat.com> wrote Crash

       Jay Fenlason <fenlason@redhat.com> wrote this man page.


SEE ALSO

       netdump(8) gdb(1)



                                                                      CRASH(8)

Man(1) output converted with man2html