1CRASH(8) System Manager's Manual CRASH(8)
2
6 crash - Analyze Linux crash data or a live system
7
9 crash [ -h [ opt ] ] [ -v ] [ -s ] [ -i file ] [ -d num ] [ -S ] [ map‐
10 file ] [ namelist ] [ dumpfile ]
11
13 Crash is a tool for interactively analyzing the state of the Linux sys‐
14 tem while it is running, or after a kernel crash has occurred and a
15 core dump has been created by the Red Hat netdump, diskdump, kdump, or
16 xendump facilities. It is loosely based on the SVR4 UNIX crash com‐
17 mand, but has been significantly enhanced by completely merging it with
18 the gdb debugger. The marriage of the two effectively combines the ker‐
19 nel-specific nature of the traditional UNIX crash utility with the
20 source code level debugging capabilities of gdb.
21 The current set of commands consist of common kernel core analysis
23 tools such as kernel stack back traces of all processes, source code
24 disassembly, formatted kernel structure and variable displays, virtual
25 memory data, dumps of linked-lists, etc., along with several commands
26 that delve deeper into specific kernel subsystems. Appropriate gdb
27 commands may also be entered, which in turn are passed on to the gdb
28 module for execution.
29 The crash utility is designed to be independent of Linux version depen‐
31 dencies. When new kernel source code impacts the correct functionality
32 of crash and its command set, the utility will be updated to recognize
33 new kernel code changes, while maintaining backwards compatibility with
34 earlier releases.
35
37 -h opt Crash displays a help message. If the optional opt argument is
38 a crash command name, the help page for that command is dis‐
39 played. If it is the string "input", a page describing the var‐
40 ious crash command line input options is displayed. If it is
41 the string "output", a page describing command line output
42 options is displayed.
43 -v Crash displays the versions of the original gdb and crash
45 libraries that make up the crash executable.
46 -s Crash does not display any version, GPL, or crash initialization
48 data during startup. It proceeds directly to the "crash>"
49 prompt.
50 -i file
52 Crash reads and executes the crash command(s) contained in file
53 before accepting any user input.
54 -d num Crash sets its internal debug level. The higher the number, the
56 more debugging data will be printed while crash runs.
57 -S Crash uses "/boot/System.map" as the mapfile.
59 namelist
61 This is a pathname to an uncompressed kernel image (a vmlinux
62 file) that has been compiled with the "-g" option, or that has
63 an accessible, associated, debuginfo file. If the dumpfile
64 argument is entered, then this argument must also be used. If
65 the namelist argument is not entered and no dumpfile argument is
66 entered, crash will search in several typical directories for a
67 kernel namelist that matches the live system.
68 mapfile
70 If the live system kernel, or the kernel from which the dumpfile
71 was derived, was not compiled with the -g switch, then the addi‐
72 tional mapfile argument is required. It may be either the asso‐
73 ciated System.map file, or the non-debug kernel namelist. How‐
74 ever, if the mapfile argument is used, then the namelist argu‐
75 ment must be a kernel namelist of a similar kernel version that
76 was built with the -g switch.
77 dumpfile
79 This is a pathname to a kernel memory core dump file. If the
80 dumpfile argument is not entered, the session will be invoked on
81 the live system using /dev/mem, which usually requires root
82 privileges.
83
85 Each crash command generally falls into one of the following cate‐
86 gories:
87 Symbolic display
89 Displays of kernel text/data, which take full advantage of the
90 power of gdb to format and display data structures symbolically.
91 System state
93 The majority of crash commands come consist of a set of "kernel-
94 aware" commands, which delve into various kernel subsystems on a
95 system-wide or per-task basis.
96 Utility functions
98 A set of useful helper commands serving various purposes, some
99 simple, others quite powerful.
100 Session control
102 Commands that control the crash session itself.
103 The following alphabetical list consists of a very simple overview of
105 each crash command. However, since individual commands often have sev‐
106 eral options resulting in significantly different output, it is sug‐
107 gested that the full description of each command be viewed by entering
108 the command crash -h command, or during a crash session by simply
109 entering help command.
110 * "pointer to" is shorthand for either the struct or union com‐
112 mands. It displays the contents of a kernel structure or union.
113 alias creates a single-word alias for a command.
115 ascii displays an ascii chart or translates a numeric value into its
117 ascii components.
118 bt displays a task's kernel-stack backtrace. If it is given the -a
120 option, it displays the stack traces of the active tasks on all
121 CPUs. It is often used with the foreach command to display the
122 backtraces of all tasks with one command.
123 btop translates a byte value (physical offset) to it's page number.
125 dev displays data concerning the character and block device assign‐
127 ments, I/O port usage, I/O memory usage, and PCI device data.
128 dis disassembles memory, either entire kernel functions, from a
130 location for a specified number of instructions, or from the
131 start of a function up to a specified memory location.
132 eval evalues an expression or numeric type and displays the result in
134 hexadecimal, decimal, octal and binary.
135 exit causes crash to exit.
137 extend dynamically loads or unloads crash extension shared object
139 libraries.
140 files displays information about open files in a context.
142 foreach
144 repeats a specified command for the specified (or all) tasks in
145 the system.
146 fuser displays the tasks using the specified file or socket.
148 gdb passes its argument to the underlying gdb program. It is useful
150 for executing GDB commands that have the same name as crash com‐
151 mands.
152 help alone displays the command menu; if followed by a command name,
154 a full description of a command, its options, and examples are
155 displayed. Its output is far more complete and useful than this
156 man page.
157 irq displays data concerning interrupt request numbers and bottom-
159 half interrupt handling.
160 kmem displays information about the use of kernel memory.
162 list displays the contents of a linked list.
164 log displays the kernel log_buf contents in chronological order.
166 mach displays data specific to the machine type.
168 mod displays information about the currently installed kernel mod‐
170 ules, or adds or deletes symbolic or debugging information about
171 specified kernel modules.
172 mount displays information about the currently-mounted filesystems.
174 net display various network related data.
176 p passes its arguments to the gdb "print" command for evaluation
178 and display.
179 ps displays process status for specified, or all, processes in the
181 system.
182 pte translates the hexadecimal contents of a PTE into its physical
184 page address and page bit settings.
185 ptob translates a page frame number to its byte value.
187 ptov translates a hexadecimal physical address into a kernel virtual
189 address.
190 q is an alias for the "exit" command.
192 rd displays the contents of memory, with the output formatted in
194 several different manners.
195 repeat repeats a command indefinitely, optionally delaying a given num‐
197 ber of seconds between each command execution.
198 runq displays the tasks on the run queue.
200 search searches a range of user or kernel memory space for given value.
202 set either sets a new context, or gets the current context for dis‐
204 play.
205 sig displays signal-handling data of one or more tasks.
207 struct displays either a structure definition or the contents of a ker‐
209 nel structure at a specified address.
210 swap displays information about each configured swap device.
212 sym translates a symbol to its virtual address, or a static kernel
214 virtual address to its symbol -- or to a symbol-plus-offset
215 value, if appropriate.
216 sys displays system-specific data.
218 task displays the contents of a task_struct.
220 timer displays the timer queue entries, both old- and new-style, in
222 chronological order.
223 union is similar to the struct command, except that it works on kernel
225 unions.
226 vm displays basic virtual memory information of a context.
228 vtop translates a user or kernel virtual address to its physical
230 address.
231 waitq walks the wait queue list displaying the tasks which are blocked
233 on the specified wait queue.
234 whatis displays the definition of structures, unions, typedefs or
236 text/data symbols.
237 wr modifies the contents of memory. When writing to memory on a
239 live system, this command should obviously be used with great
240 care.
241
243 .crashrc
244 Initialization commands. The file can be located in the user's
245 HOME directory and/or the current directory. Commands found in
246 the .crashrc file in the HOME directory are executed before
247 those in the current directory's .crashrc file.
248
250 EDITOR Command input is read using readline(3). If EDITOR is set to
251 emacs or vi then suitable keybindings are used. If EDITOR is
252 not set, then vi is used. This can be overridden by set vi or
253 set emacs commands located in a .crashrc file, or by entering -e
254 emacs on the crash command line.
255 CRASHPAGER
257 If CRASHPAGER is set, its value is used as the name of the pro‐
258 gram to which command output will be sent. If not, then command
259 output is sent to /usr/bin/less -E -X by default.
260
262 If crash does not work, look for a newer version: kernel evolution fre‐
263 quently makes crash updates necessary.
264 The command set scroll off will cause output to be sent directly to the
266 terminal rather than through a paging program. This is useful, for
267 example, if you are running crash in a window of emacs.
268
270 Dave Anderson <anderson@redhat.com> wrote crash
271 Jay Fenlason <fenlason@redhat.com> wrote this man page.
273
275 The help command within crash provides more complete and accurate docu‐
276 mentation than this man page.
277 http://people.redhat.com/anderson - the home page of the crash utility.
279 netdump(8), gdb(1)
281 CRASH(8)