Man Linux: Main Page and Category List

NAME

       crash - Analyze Linux crash data or a live system

SYNOPSIS

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

DESCRIPTION

       Crash is a tool for interactively analyzing  the  state  of  the  Linux
       system  while it is running, or after a kernel crash has occurred and a
       core dump has been created by the Red Hat netdump, diskdump, kdump,  or
       xendump  facilities.   It  is  loosely  based  on  the  SVR4 UNIX crash
       command, but has been significantly enhanced by completely  merging  it
       with the gdb debugger. The marriage of the two effectively combines the
       kernel-specific nature of the traditional UNIX crash utility  with  the
       source code level debugging capabilities 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
       dependencies.  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
              displayed.   If  it is the string "input", a page describing the
              various 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
              additional  mapfile  argument is required.  It may be either the
              associated System.map file, or the  non-debug  kernel  namelist.
              However,  if  the  mapfile  argument  is used, then the namelist
              argument 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
       categories:

       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
       several options resulting in  significantly  different  output,  it  is
       suggested  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
              commands.  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
              assignments, 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 function up to a specified memory location.

       eval   evalues an expression or numeric type and displays the result in
              hexadecimal, 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 specified 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
              commands.

       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
              modules,  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 arguments 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
              number 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
              display.

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

       struct displays either a structure definition  or  the  contents  of  a
              kernel 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 obviously be used with great
              care.

FILES

       .crashrc
              Initialization commands.  The file can be located in the  user’s
              HOME  directory and/or the current directory.  Commands found in
              the .crashrc file in the  HOME  directory  are  executed  before
              those in the current directory’s .crashrc file.

ENVIRONMENT

       EDITOR Command  input  is  read using readline(3).  If EDITOR is set to
              emacs or vi then suitable keybindings are used.   If  EDITOR  is
              not  set,  then vi is used.  This can be overridden by set vi or
              set emacs commands located in a .crashrc file, or by entering -e
              emacs on the crash command line.

       CRASHPAGER
              If  CRASHPAGER  is  set,  its  value  is used as the name of the
              program to which command output will  be  sent.   If  not,  then
              command output is sent to /usr/bin/less -E -X by default.

NOTES

       If  crash  does  not  work,  look for a newer version: kernel evolution
       frequently makes crash updates necessary.

       The command set scroll off will cause output to be sent directly to the
       terminal  rather  than  through  a paging program.  This is useful, for
       example, if you are running crash in a window of emacs.

AUTHOR

       Dave Anderson <anderson@redhat.com> wrote crash

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

SEE ALSO

       The help command within  crash  provides  more  complete  and  accurate
       documentation than this man page.

       http://people.redhat.com/anderson - the home page of the crash utility.

       netdump(8), gdb(1)