kdbx(8)kdbx(8)NAMEkdbx - Analyzes running kernels and dump files
SYNOPSIS
/usr/bin/kdbx [-dbx dbx-path] -k [dbx-flags] object-file [core-file]
DESCRIPTION
The kdbx debugger is a crash analysis and kernel debugging tool; it is
an interactive program that serves as a front-end to the dbx debugger.
The kdbx debugger is extensible, customizable, and insensitive to
changes of offsets and sizes of fields in structures. The only depen‐
dencies on kernel header files are for bit definitions in flag fields.
The kdbx debugger lets you examine either the running kernel or dump
files created by the savecore command. In either case, you examine an
object file and a core file. For running systems, these files are usu‐
ally /vmunix and /dev/mem, respectively. Dump files created by
savecore are saved in the directory specified by the
/sbin/init.d/savecore script. By default, the directory is
/var/adm/crash.
The kdbx debugger has facilities for interpreting various symbols and
data structures. It can format and display the symbols and data struc‐
tures in the following ways: In a predefined form as specified in the
modules that currently accompany the kdbx debugger As defined in user-
written source code modules according to a standardized format for the
contents of the kdbx modules
All dbx commands are available through kdbx using the dbx flag to kdbx.
Defaults
If you do not specify a core file, kdbx uses the dbx default of
/dev/mem. Therefore, you can use kdbx with /vmunix as its only argu‐
ment to examine an active system. In general, kdbx assumes that
addresses are specified in hexadecimal in commands that perform input
or output.
When you begin a debugging session, kdbx executes the commands in the
system initialization file /var/kdbx/SYSTEM.kdbxrc. The initialization
file contains setup commands and alias definitions. The Aliases section
lists the aliases defined in this file. You can further customize the
kdbx environment by adding commands and aliases to one of the following
initialization files: Contains customized commands and alias defini‐
tions for a particular system. Contains customized commands and alias
definitions for a specific user. Contains customized commands and
alias definitions for a specific project. This file must reside in the
current working directory when kdbx is invoked.
Invocation
To use kdbx to examine a running system, issue the following kdbx com‐
mand: # kdbx-k /vmunix /dev/mem dbx version 3.11.1 Type 'help' for
help.
stopped at [thread_block:1403 ,0xfffffc000032e3c0]
Source not available (kdbx)
To use kdbx to examine an object file and core file created by the
savecore utility, issue a kdbx command like the following one: # kdbx-k /usr/adm/crash/vmunix.1 /usr/adm/crash/dev/vmcore.1 dbx version
3.11.1 Type 'help' for help.
stopped at [thread_block:1403 ,0xfffffc000032e3c0]
Source not available (kdbx)
In this case, the version number in the bounds file is one.
Commands
The kdbx debugger provides the following commands: Sets or displays
aliases. If you specify the alias command without arguments, kdbx dis‐
plays all aliases. If you specify only the variable name, the command
displays the alias for name, if one exists. If you specify both name
and command-string, name is established as an alias for command-string.
Sets the context to user's aliases or extension's aliases. This command
is used only by extensions. Dumps, in hexadecimal, the contents of the
core file starting at start-address and ending before end-address.
Passes the variable command-string to dbx. Specifying dbx is optional;
if the command is not recognized by kdbx, it is passed to dbx automati‐
cally. See the dbx(1) reference page for a complete description of the
dbx commands. Displays help text. Executes an extension and gives it
control of the kdbx session until it quits. The variable extension
specifies the named extension file and passes it arguments as specified
by the arg variables. Valid proc flags are as follows: Causes I/O to
and from the extension to be displayed on the screen. Used in conjunc‐
tion with the dbx debugger for debugging extensions. The file in-pipe
takes output from the dbx session and directs it as input to the kdbx
session. The file out-pipe takes output from the kdbx session and
directs it as input to the dbx session. Causes the output of the pro‐
cedure to be sent to the invoker of the procedure without interpreta‐
tion as kdbx commands. Used by extensions that execute other exten‐
sions to receive the output from the called extension instead of the
user receiving it. Causes kdbx to talk to the subprocess through a tty
line instead of pipes. If you also specify the -pipe flag, proc
ignores it. Displays string on the terminal. If this command is used
by an extension, the extension receives no output. Exits the current
command loop. If the current command loop is the top level loop that
the user is using, kdbx exits. Otherwise, control is given to the next
lowest loop. Reads and interprets files as kdbx commands in the con‐
text of the current aliases. The -x flag causes commands to be dis‐
played as they are executed. Removes an alias, if any, from name.
Predefined kdbx Aliases
The following aliases are defined in the kdbx startup file
/var/kdbx/system.kdbxrc:
───────────────────────────────────────────────────────────────────
Alias Definition
───────────────────────────────────────────────────────────────────
arp "proc" arp
array_action "proc" array_action
buf "proc" buf
buf_action list_action "struct buf *" b_forw buf buf
callout_action list_action "struct callout *" c_next 0 callout
cast "proc" cast
clua "proc" clua
convert "proc" convert
config "proc" config
dis "proc" dis
echo "proc" echo
export "proc" export
fields "proc" fields
file "proc" file
h help
inpcb "proc" inpcb
inpcb_action list_action "struct inpcb *" inp_next
ipv6 "proc" ipv6
list_action "proc" list_action
mount_action list_action "struct mount *" m_next rootfs rootfs
mount "proc" mount
namecache "proc" namecache
netstat "proc" netstat
ofile "proc" ofile
paddr "proc" paddr
pcb "proc" pcb
pr "proc"
printf "proc" printf
proc "proc" proc
procaddr "proc" procaddr
procp "proc" -pipe /tmp/pipein /tmp/pipeout
procpd "proc" -debug -pipe /tmp/pipein /tmp/pipeout
proc_action list_action "struct proc *" p_nxt 0 allproc
ps "dbx" kps
route "proc" route
sh "proc" -print_output -tty
socket "proc" socket
sum "proc" sum
swap "proc" swap
task "proc" task
thread "proc" thread
u "proc" u
ucred "proc" ucred
unaliasall "proc" unaliasall
vnode "proc" vnode
───────────────────────────────────────────────────────────────────
Extensions
For extensions that display addresses as part of their output, some use
a shorthand notation for the upper 32-bits of an address to keep the
output readable. The following table lists the notation for each
address type.
───────────────────────────────────────────────────────────
Notation Address Type Replaces Example
───────────────────────────────────────────────────────────
v virtual ffffffff v0x902416f0
k kseg fffffc00 k0x363076f4
u user space 00000000 u0x86406200
? Unrecognized or random ?0x0033aa24
type
───────────────────────────────────────────────────────────
The extensions available to kdbx are as follows: Displays the contents
of the address resolution protocol (ARP) table. This command is super‐
seded by the route -h command. Performs a command action on each ele‐
ment of an array. This extension allows you to step through any array
in the operating system kernel and display specific components or val‐
ues as described in the list of command flags. The arguments to the
array_action extension are as follows: The type of address of the array
element. The number of elements in the array. The address of the
array. A variable name or a number can be used to specify
start_address. The more common syntax or notation used to refer to the
start_address is usually of the form &arrayname[0]. Valid flags for
the array_action extension are as follows: If you specify the -head
flag, kdbx displays the next argument as the table header. If you
specify the -size flag, kdbx uses the next argument as the array ele‐
ment size. Otherwise, kdbx calculates the size from the element type.
If you specify the -cond flag, kdbx uses the next argument as a filter.
The dbx debugger evaluates the condition for each array element, and if
it evaluates to TRUE, takes the action on the array element. The same
substitutions that are applied to the command are applied to the condi‐
tion. The name of the kdbx or dbx command that is to be performed on
each element of the array.
Note that the kdbx debugger includes several aliases, such as
file_action, that might be easier to use than directly using the
array_action extension.
Substitutions similar to printf can be performed on the command
for each array element. The possible substitutions are as fol‐
lows:
%a Address of element
%c Cast of address to pointer to array element
%i Index of element within the array
%s Size of element
%t Type of pointer to element
Displays the buffer table. If no arguments are specified, the
buffers on the hash list are displayed.
If addresses are specified, the buffers at those addresses are
displayed. If you specify the -free flag, kdbx displays all the
buffers on the free list. If you specify the -all flag, kdbx
displays buffers on the hash list first, followed by buffers on
the free list. Displays the callout table. Forces dbx to dis‐
play a piece of memory as a given type. This extension is equiv‐
alent to dbx print *((type)address). Displays cluster alias-
specific information. The optional flags for the clua extension
are as follows: Displays information on the specified aliasid.
Displays per alias connection entries (clua cnx table). Dis‐
plays locked port information. Displays information on the
specified port. Displays registered port information Displays
sticky table. Displays verbose information. Displays help
information. Displays the configuration of the machine. Con‐
verts numbers from one base to another. The -in and -out flags
specify the input and output bases, respectively. If you omit
-in, kdbx infers the input base from the arguments. The argu‐
ments can be either numbers or variables. Displays CPU use sta‐
tistics on a per-CPU basis. If you specify -update, kdbx updates
the display every n seconds. Disassembles some number of
instructions as specified in the num-instructions instructions
starting at start-address. If you omit the number of instruc‐
tions, kdbx disassembles one instruction. Displays the exported
entries that are mounted remotely. Displays the file table. If
no addresses are specified, all file entries with nonzero refer‐
ence counts are displayed. Otherwise, the file entries at the
specified addresses are displayed. Displays the udb and tcb
tables. If no arguments are specified, both tables are dis‐
played. If you specify either -udp or -tcp, kdbx displays the
corresponding table. Displays PID information for each connec‐
tion. Displays the network address in numerical format with
network masks in CIDR format. When -n is not specified, the
address is displayed as hostname and port number. This option
can be used with any of the display formats. Shows TCP socket
in listening mode. If addresses are specified, -udp and -tcp
are ignored and the entries at the specified addresses are dis‐
played. Displays IPv6 system information. The options for the
ipv6 extension are as follows. Displays the Mobile IPv6 binding
cache. Displays the local IPv6 address table. Displays the
Mobile IPv6 prefix list. Displays network addresses in numeric
format. Prints verbose information. Performs some command on
each element of a linked list. This extension makes it possible
to walk through any linked list in the operating system kernel
and display particular components while walking through the
linked list. The arguments to the list_action extension are as
follows: The type of address of an element in the specified
list. The name of the field that points to the next element.
The value of the next field that terminates the list. If the
list is NULL-terminated, the value of end-addr is 0. If the
list is circular, the value of end-addr is equal to start-addr.
The address of a list. The address can be specified as a vari‐
able name or a number. Valid flags for the list_action exten‐
sion are as follows: If you specify the -head header flag, kdbx
displays the header argument as the table header. If you spec‐
ify -cond, the next arg is used as a filter. The dbx debugger
evaluates the condition for each list element, and if it evalu‐
ates to true, takes the action on the list element. The same
substitutions that are applied to the command are applied to the
condition. The kdbx or dbx command to perform on each element
of the list.
Note that kdbx includes several aliases, such as file_action,
that might be easier to use than directly using the list_action
extension.
Substitutions similar to printf substitutions are performed on
the command for each element. The possible substitutions are as
follows:
%a Address of element
%c Cast of address to pointer to list element
%i Index of element within the list
%n Name of next field
%t Type of pointer to element
Displays the static lock type information contained in the lock‐
info structures. This extension is available only when the
lockmode system attribute is set to four. The -class flag allows
you to display information about a particular class of locks.
Displays statistics about locks recorded in the lockstats struc‐
ture. These statistics are dynamic. This extension is available
only when the lockmode system attribute is set to four.
Statistics displayed include information about the number of
instances of a particular lock type, the number of times pro‐
cesses tried to get a lock type, the number of times processes
tried and failed to get a particular lock type and the amount of
time spent waiting for locks.
The flags for the lockstats extension are as follows: Displays
the lockstats structures of the specified lock type Displays the
lockstats structures associated with the specified CPU Displays
the reads, sleeps attributes, and summary of time spent waiting
or number of misses Displays summary data for all CPUs and all
lock types Displays summary data for all CPUs Updates the dis‐
play every n seconds Displays the mount table. The -s flag out‐
puts a short form of the table. If addresses are specified, the
mount entries at the specified addresses are displayed. Dis‐
plays the per-processor namecache entries on the system. If no
flags are specified, namecache entries on the primary cpu are
displayed. The flags for the namecache extension are as follows:
Displays the list of flags, usage information, and tips. Dis‐
plays the list of flags and usage information. Displays the
namecache entries of the global negative namecache list. Dis‐
plays the namecache entries, including negative namecache
entries. Displays the namecache entries on the specified cpu.
Displays the namecache entries with the specified vpid. Dis‐
plays the namecache entries under the directory with the speci‐
fied dvpid. Displays the namecache entries with the specified
name.
For example, to see all the negative entries on processor 1:
kdbx> namecache -v 0 -p 1 -all
To see all the entries with the file name Makefile on processor
2: kdbx> namecache -p 2 -n Makefile Displays the state of the
network interfaces. The optional flags for the netstat extension
are as follows: Displays the IP and link-level addresses. Dis‐
plays timer information. Displays network addresses in numeric
formal. Displays the number of dropped packets. Displays pro‐
tocol statistics for all configured interafces.
When used in conjunction with the -i option, -s displays inter‐
face statistics for all configured interfaces. When used without
-i, it displays protocol statistics. Displays verbose informa‐
tion (including hardware addresses) about all interfaces that
are configured on a system. Displays the files opened by pro‐
cesses. If no arguments are specified, the extension displays
the files opened by each process. If you specify either -proc
address or -pid pid, kdbx displays the open files of the given
process. The -v flag displays more information about the open
files. Converts a range of memory to symbolic references. The
argument address is the starting address. The argument number-
of-longwords is the number of words to dump out. Displays the
process control block for a given thread at the specified
address. For integer and floating-point registers, only nonzero
contents are displayed. Formats one argument at a time to work
around the dbx debugger's command length limitation. It also
implements the %s string substitution, which the dbx printf com‐
mand does not. The argument format-string specifies a character
string combining literal characters with conversion specifica‐
tions. Displays the process table. If addresses are specified,
the proc structures at the specified addresses are displayed.
Otherwise, all proc structures are displayed. Converts the
specified address to a procedure name. Displays the route and
Address Resolution Protocol (ARP) tables. The optional flags for
the route extension are as follows: Print verbose route or ARP
tables. Display network addresses in numeric format. Display
route information on all Resource Affinity Domains (RADs). Dis‐
play ARP tables. Displays the files that are sockets with
nonzero reference counts in the file table. Displays a summary
of the system. Displays a summary of swap space. Displays the
task structures associated with the specified addresses. If no
addresses are specified, all tasks are displayed. Displays
information about the threads associated with the specified
addresses. If no addresses are specified, all threads are dis‐
played. Displays the stack trace of one or more threads. If
you specify thread_address, the extension displays the stack
trace of the specified thread. If you omit the argument and all
the flags, trace displays the stack trace of all threads. You
can specify the following flags: Display the stack trace of the
active thread on each CPU. Display the stack trace of all ker‐
nel threads. Display the stack trace of all user threads. Dis‐
play all ucred structures referenced by the buf structures.
Display all references to a given ucred structure. Check the
reference count of a particular ucred structure. Check the ref‐
erence count of all ucred structures (mismatch marked by *).
Displays a u structure at the address proc-addr. Displays or
checks references to ucred structures. If no flags are speci‐
fied, this extension displays all references to ucred structures
on the system. Possible flags are as follows: Display all ucred
structures referenced by the proc structures. Display all ucred
structures referenced by the uthread structures. Display all
ucred structures referenced by the file structures. Display all
ucred structures referenced by the buf structures. Display all
references to a given ucred structure. Check the reference
count of a particular ucred structure. Check the reference
count of all ucred structures (mismatch marked by *). Removes
all aliases including the predefined aliases described in the
Predefined kdbx Aliases section. Displays the vnode table. If
no arguments are specified, all ACTIVE vnodes on the system are
displayed. ACTIVE means nonzero usecount or nonzero holdcnt.
Possible flags are listed as follows: Display INACTIVE (both
usecount and holdcnt are zeros) entries in the vnode table.
Display ALL (both ACTIVE and INACTIVE) entries in the vnode ta‐
ble. Display all UFS vnodes. Display all NFS vnodes. Display
all CDFS vnodes. Display vnode entries of a mounted file sys‐
tem. Display vnode entries of a particular user. Display vnode
entries of a particular group. Display related
inode/rnode/cdnode information (used with -ufs, -nfs, or -cdfs
only).
SEE ALSO
Commands: dbx(1), savecore(8)
Kernel Debugging
Programmer's Guide
kdbx(8)
