kdb command

Allows examining of a system dump or a running kernel.

Syntax

kdb -h

kdb [-c CommandFile] [-cp] [-i HeaderFile] [-l] [-script] -w -u KernelFile

kdb [-c CommandFile] [-cp] [-i HeaderFile] [-l] [-script] [-v] [SystemImageFile [KernelFile [KernelModule ...]]]

kdb [-c CommandFile] [-cp] [-i HeaderFile] [-l] [-script] [-v] [-m SystemImageFile] [-u KernelFile] [-k KernelModule]

Description

The kdb command is an interactive utility for examining an operating system image or the running kernel. The kdb command interprets and formats control structures in the system and provides miscellaneous functions for examining a dump.

The SystemImageFile parameter specifies the file that contains the system image. The value can indicate a system dump, the name of a dump device, or the /dev/pmem special file. The default SystemImageFile is /dev/pmem.

The KernelFile parameter specifies the AIX kernel that kdb will use to resolve kernel symbol definitions. A kernel file must be available. When examining a system dump it is imperative that the kernel file be the same as the kernel that was used to take the system dump. The default for the KernelFile is /unix.

The KernelModule parameters specify the file names of any additional kernel modules which the kdb command uses to resolve symbol definitions not found in the kernel file itself.

Root permissions are required for use of the kdb command on the active system. This is required because the special file /dev/pmem is used. To run the kdb command on the active system, type the following:

kdb

Note: Stack tracing of the current process on a running system does not work.

To invoke the kdb command on a system image file, type:

kdb SystemImageFile

When kdb starts, it looks for a .kdbinit file in the user's home directory and in the current working directory. If a .kdbinit file exists in either of these locations, kdb runs all the commands inside the file as if they were entered at the interactive kdb prompt. If a .kdbinit file exists in both of these locations, the file in the home directory will be processed first followed by the file in the current working directory (unless the current directory is the home directory, in which case the file is processed only once).

Flags

Item	Description
-c CommandFile	Specifies a different name for the startup script file. If this option is used, then kdb will search for the CommandFile parameter in the home and current directories, instead of the .kdbinit file.
-cp	Causes kdb to print out each command in the startup script files as that command is run This may be used to aid in the debugging of .kdbinit files (or any other file specified with the -c flag). Each command will be printed with a `+` (plus) sign in front of it.
-h	Displays a short help message in regard to command line usage and a brief listing of the available command line options.
-i HeaderFile	Makes all of the C structures defined in the HeaderFile parameter available for use with the kdb print subcommand. This option requires a C compiler to be installed on the system. If the HeaderFile variable needs additional .h files to compile, these may have to be specified with separate -i options as well.
-k Module	Instructs kdb to use the Module parameter as an additional kernel module for resolving symbol definitions not found in the kernel itself. Using this option is equivalent to specifying the kernel module with the KernelModule parameter.
-l	Disables the inline pager (that is, the `more (^C to quit) ?` prompt) in kdb. In this case the set scroll subcommand in kdb has no effect, and the inline pager is always disabled regardless of the scroll setting.
-m Image	Instructs kdb to use the Image parameter as the system image file. Using this option is equivalent to specifying the system image file with the SystemImageFile parameter.
-script	Disables the inline pager (that is, the `more (^C to quit) ?` prompt) and disables printing of most status information when kdb starts. This option facilitates parsing of the output from the kdb command by scripts and other programs that act as a front end for kdb.
-u Kernel	Instructs kdb to use the Kernel as the kernel file for resolving symbol definitions. Using this option is equivalent to specifying the kernel with the KernelFile parameter.
-v	Displays a list of all Component Dump Tables (CDTs) in the system dump file when kdb starts. CDTs list which memory regions are actually included in the system dump. If kdb is used on a live system, this option is ignored.
-w	Examines a kernel file directly instead of a system image. All kdb subcommands which normally display memory locations from the system image file will instead read data directly from KernelFile. Subcommands which write memory are not available.

Examples

The following examples demonstrate invocation options for the kdb command

To invoke the kdb command with the default system image and kernel image files, type:
```
kdb
```
The kdb program returns a (0)> prompt and waits for entry of a subcommand.
To invoke the kdb command using a dump file named /var/adm/ras/vmcore.0 and the UNIX kernel file named /unix, type:
```
kdb /var/adm/ras/vmcore.0 /unix
```
The kdb program returns a (0)> prompt and waits for entry of a subcommand.

Files

Item	Description
/usr/sbin/kdb	Contains the kdb command.
/dev/pmem	Default system image file
/unix	Default kernel file