kdb Command

Purpose

Allows for the examining of a system or live 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.

Root permissions are required to use the kdb command on the active system because the /dev/pmem special file 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 the following:

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 will execute all of 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 searches 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 the command is run. This can be used to help debug the .kdbinit files, or any other file specified with the -c flag. Each command is 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 might have to be specified with separate -i options as well.
-k Module	Instructs kdb to use the specified 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 specified 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 specified 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 dump file when the kdb command starts. CDTs list the memory regions that are actually included in the dump. If the kdb command 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.

Parameters

Item	Description
KernelFile	Specifies the AIX® kernel that the kdb command uses to resolve kernel symbol definitions. A kernel file must be available. When examining a dump, the kernel file must be the same as the kernel that was used to take the system or live dump. The default value is /unix.
KernelModule	Specifies the file names of any additional kernel modules that kdb uses to resolve symbol definitions not found in the kernel file itself.
SystemImageFile	Specifies the file that contains the system image. The value can indicate a system or live dump, the name of a dump device, or the /dev/pmem special file. The default value is /dev/pmem.

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 the following:
```
kdb
```
The kdb program returns a (0)> prompt and waits for the 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 the following:
```
kdb /var/adm/ras/vmcore.0 /unix
```
The kdb program returns a (0)> prompt and waits for the entry of a subcommand.
To invoke the kdb command using a live dump file named /var/adm/ras/livedump/trc1.nocomp.200705222009.00 and the kernel file /unix, type the following:
```
kdb /var/adm/ras/livedump/trc1.nocomp.200705222009.00
```
Note: The default kernel file is /unix. Unlike a system dump, in a live dump, only selected data is present. For example, only the kernel thread data for threads explicitly included in the dump is present.

Files

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