Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DDB(4)			 BSD Kernel Interfaces Manual			DDB(4)

     ddb -- interactive	kernel debugger

     options KDB
     options DDB

     To	prevent	activation of the debugger on kernel panic(9):
     options KDB_UNATTENDED

     The ddb kernel debugger has most of the features of the old kdb, but with
     a more rational syntax inspired by	gdb(1).	 If linked into	the running
     kernel, it	can be invoked locally with the	`debug'	keymap(5) action.  The
     debugger is also invoked on kernel	panic(9) if the
     debug.debugger_on_panic sysctl(8) MIB variable is set non-zero, which is
     the default unless	the KDB_UNATTENDED option is specified.

     The current location is called dot.  The dot is displayed with a hexadec-
     imal format at a prompt.  The commands examine and	write update dot to
     the address of the	last line examined or the last location	modified, and
     set next to the address of	the next location to be	examined or changed.
     Other commands do not change dot, and set next to be the same as dot.

     The general command syntax	is: command[/modifier] address[,count]

     A blank line repeats the previous command from the	address	next with
     count 1 and no modifiers.	Specifying address sets	dot to the address.
     Omitting address uses dot.	 A missing count is taken to be	1 for printing
     commands or infinity for stack traces.

     The ddb debugger has a pager feature (like	the more(1) command) for the
     output.  If an output line	exceeds	the number set in the lines variable,
     it	displays "--More--" and	waits for a response.  The valid responses for
     it	are:

     SPC  one more page
     RET  one more line
     q	  abort	the current command, and return	to the command input mode

     Finally, ddb provides a small (currently 10 items)	command	history, and
     offers simple emacs-style command line editing capabilities.  In addition
     to	the emacs control keys,	the usual ANSI arrow keys might	be used	to
     browse through the	history	buffer,	and move the cursor within the current

     x	     Display the addressed locations according to the formats in the
	     modifier.	Multiple modifier formats display multiple locations.
	     If	no format is specified,	the last format	specified for this
	     command is	used.

	     The format	characters are:
	     b	     look at by	bytes (8 bits)
	     h	     look at by	half words (16 bits)
	     l	     look at by	long words (32 bits)
	     a	     print the location	being displayed
	     A	     print the location	with a line number if possible
	     x	     display in	unsigned hex
	     z	     display in	signed hex
	     o	     display in	unsigned octal
	     d	     display in	signed decimal
	     u	     display in	unsigned decimal
	     r	     display in	current	radix, signed
	     c	     display low 8 bits	as a character.	 Non-printing charac-
		     ters are displayed	as an octal escape code	(e.g.,
	     s	     display the null-terminated string	at the location.  Non-
		     printing characters are displayed as octal	escapes.
	     m	     display in	unsigned hex with character dump at the	end of
		     each line.	 The location is also displayed	in hex at the
		     beginning of each line.
	     i	     display as	an instruction
	     I	     display as	an instruction with possible alternate formats
		     depending on the machine:
		     alpha    Show the registers of the	instruction.
		     amd64    No alternate format.
		     i386     No alternate format.
		     ia64     No alternate format.
		     powerpc  No alternate format.
		     sparc64  No alternate format.
	     S	     display a symbol name for the pointer stored at the ad-

     xf	     Examine forward: execute an examine command with the last speci-
	     fied parameters to	it except that the next	address	displayed by
	     it	is used	as the start address.

     xb	     Examine backward: execute an examine command with the last	speci-
	     fied parameters to	it except that the last	start address sub-
	     tracted by	the size displayed by it is used as the	start address.

	     Print addrs according to the modifier character (as described
	     above for examine).  Valid	formats	are: a,	x, z, o, d, u, r, and
	     c.	 If no modifier	is specified, the last one specified to	it is
	     used.  The	argument addr can be a string, in which	case it	is
	     printed as	it is.	For example:

		   print/x "eax	= " $eax "\necx	= " $ecx "\n"

	     will print	like:

		   eax = xxxxxx
		   ecx = yyyyyy

     write[/bhl] addr expr1 [expr2 ...]
     w[/bhl] addr expr1	[expr2 ...]
	     Write the expressions specified after addr	on the command line at
	     succeeding	locations starting with	addr.  The write unit size can
	     be	specified in the modifier with a letter	b (byte), h (half
	     word) or l	(long word) respectively.  If omitted, long word is

	     Warning: since there is no	delimiter between expressions, strange
	     things may	happen.	 It is best to enclose each expression in

     set $variable [=] expr
	     Set the named variable or register	with the value of expr.	 Valid
	     variable names are	described below.

     b[/u]   Set a break point at addr.	 If count is supplied, continues count
	     - 1 times before stopping at the break point.  If the break point
	     is	set, a break point number is printed with `#'.	This number
	     can be used in deleting the break point or	adding conditions to

	     If	the u modifier is specified, this command sets a break point
	     in	user space address.  Without the u option, the address is con-
	     sidered in	the kernel space, and wrong space address is rejected
	     with an error message.  This modifier can be used only if it is
	     supported by machine dependent routines.

	     Warning: If a user	text is	shadowed by a normal user space	debug-
	     ger, user space break points may not work correctly.  Setting a
	     break point at the	low-level code paths may also cause strange

     delete addr
     d addr
     delete #number
     d #number
	     Delete the	break point.  The target break point can be specified
	     by	a break	point number with `#', or by using the same addr spec-
	     ified in the original break command.

     watch addr,size
	     Set a watchpoint for a region.  Execution stops when an attempt
	     to	modify the region occurs.  The size argument defaults to 4.
	     If	you specify a wrong space address, the request is rejected
	     with an error message.

	     Warning: Attempts to watch	wired kernel memory may	cause unrecov-
	     erable error in some systems such as i386.	 Watchpoints on	user
	     addresses work best.

     hwatch addr,size
	     Set a hardware watchpoint for a region if supported by the	archi-
	     tecture.  Execution stops when an attempt to modify the region
	     occurs.  The size argument	defaults to 4.

	     Warning: The hardware debug facilities do not have	a concept of
	     separate address spaces like the watch command does.  Use hwatch
	     for setting watchpoints on	kernel address locations only, and
	     avoid its use on user mode	address	spaces.

     dhwatch addr,size
	     Delete specified hardware watchpoint.

     s[/p]   Single step count times (the comma	is a mandatory part of the
	     syntax).  If the p	modifier is specified, print each instruction
	     at	each step.  Otherwise, only print the last instruction.

	     Warning: depending	on machine type, it may	not be possible	to
	     single-step through some low-level	code paths or user space code.
	     On	machines with software-emulated	single-stepping	(e.g., pmax),
	     stepping through code executed by interrupt handlers will proba-
	     bly do the	wrong thing.

     c[/c]   Continue execution	until a	breakpoint or watchpoint.  If the c
	     modifier is specified, count instructions while executing.	 Some
	     machines (e.g., pmax) also	count loads and	stores.

	     Warning: when counting, the debugger is really silently single-
	     stepping.	This means that	single-stepping	on low-level code may
	     cause strange behavior.

	     Stop at the next call or return instruction.  If the p modifier
	     is	specified, print the call nesting depth	and the	cumulative in-
	     struction count at	each call or return.  Otherwise, only print
	     when the matching return is hit.

	     Stop at the matching return instruction.  If the p	modifier is
	     specified,	print the call nesting depth and the cumulative	in-
	     struction count at	each call or return.  Otherwise, only print
	     when the matching return is hit.

     trace[/u] [pid | tid] [,count]
     t[/u] [pid	| tid] [,count]
     where[/u] [pid | tid] [,count]
     bt[/u] [pid | tid]	[,count]
	     Stack trace.  The u option	traces user space; if omitted, trace
	     only traces kernel	space.	The optional argument count is the
	     number of frames to be traced.  If	count is omitted, all frames
	     are printed.

	     Warning: User space stack trace is	valid only if the machine de-
	     pendent code supports it.

     search[/bhl] addr value [mask] [,count]
	     Search memory for value.  This command might fail in interesting
	     ways if it	does not find the searched-for value.  This is because
	     ddb does not always recover from touching bad memory.  The	op-
	     tional count argument limits the search.

     show all procs[/m]
     ps[/m]  Display all process information.  The process information may not
	     be	shown if it is not supported in	the machine, or	the bottom of
	     the stack of the target process is	not in the main	memory at that
	     time.  The	m modifier will	alter the display to show VM map ad-
	     dresses for the process and not show other	info.

     show registers[/u]
	     Display the register set.	If the u modifier is specified,	it
	     displays user registers instead of	kernel or currently saved one.

	     Warning: The support of the u modifier depends on the machine.
	     If	not supported, incorrect information will be displayed.

     show sysregs
	     Show system registers (e.g., cr0-4	on i386.)  Not present on some

     show geom [addr]
	     If	the addr argument is not given,	displays the entire GEOM
	     topology.	If the addr is given, displays details about the given
	     GEOM object (class, geom, provider	or consumer).

     show jails
	     Show the list of jail(8) instances.  In addition to what jls(8)
	     shows, also list kernel internal details.

     show map[/f] addr
	     Prints the	VM map at addr.	 If the	f modifier is specified	the
	     complete map is printed.

     show object[/f] addr
	     Prints the	VM object at addr.  If the f option is specified the
	     complete object is	printed.

     show vnode	addr
	     Displays details about the	given vnode.

     show watches
	     Displays all watchpoints.

     gdb     Toggles between remote GDB	and DDB	mode.  In remote GDB mode, an-
	     other machine is required that runs gdb(1)	using the remote debug
	     feature, with a connection	to the serial console port on the tar-
	     get machine.  Currently only available on the i386	architecture.

     halt    Halt the system.

     kill sig pid
	     Send signal sig to	process	pid.  The signal is acted on upon re-
	     turning from the debugger.	 This command can be used to kill a
	     process causing resource contention in the	case of	a hung system.
	     See signal(3) for a list of signals.  Note	that the arguments are
	     reversed relative to kill(2).

     reset   Hard reset	the system.

     help    Print a short summary of the available commands and command ab-

     capture on
     capture off
     capture reset
     capture status
	     ddb supports a basic output capture facility, which can be	used
	     to	retrieve the results of	debugging commands from	userpsace us-
	     ing sysctl(2).  capture on	enables	output capture;	capture	off
	     disables capture.	capture	reset will clear the capture buffer
	     and disable capture.  capture status will report current buffer
	     use, buffer size, and disposition of output capture.

	     Userspace processes may inspect and manage	ddb capture state us-
	     ing sysctl(8):

	     debug.ddb.capture.bufsize may be used to query or set the current
	     capture buffer size.

	     debug.ddb.capture.maxbufsize may be used to query the compile-
	     time limit	on the capture buffer size.

	     debug.ddb.capture.bytes may be used to query the number of	bytes
	     of	output currently in the	capture	buffer. returns the	contents of the	buffer as a
	     string to an appropriately	privileged process.

	     This facility is particularly useful in concert with the script-
	     ing and textdump(4) facilities, allowing scripted debugging out-
	     put to be captured	and committed to disk as part of a textdump
	     for later analysis.  The contents of the capture buffer may also
	     be	inspected in a kernel core dump	using kgdb(1).

	     Run, define, list,	and delete scripts.  See the SCRIPTING section
	     for more information on the scripting facility.

     textdump set
     textdump status
     textdump unset
	     The textdump set command may be used to force the next kernel
	     core dump to be a textdump	rather than a traditional memory dump
	     or	minidump.  textdump status reports whether a textdump has been
	     scheduled.	 textdump unset	cancels	a request to perform a
	     textdump as the next kernel core dump.  More information may be
	     found in textdump(4).

     The debugger accesses registers and variables as $name.  Register names
     are as in the "show registers" command.  Some variables are suffixed with
     numbers, and may have some	modifier following a colon immediately after
     the variable name.	 For example, register variables can have a u modifier
     to	indicate user register (e.g., "$eax:u").

     Built-in variables	currently supported are:

     radix     Input and output	radix.
     maxoff    Addresses are printed as	"symbol+offset"	unless offset is
	       greater than maxoff.
     maxwidth  The width of the	displayed line.
     lines     The number of lines.  It	is used	by the built-in	pager.
     tabstops  Tab stop	width.
     workxx    Work variable; xx can take values from 0	to 31.

     Most expression operators in C are	supported except `~', `^', and unary
     `&'.  Special rules in ddb	are:

     Identifiers  The name of a	symbol is translated to	the value of the sym-
		  bol, which is	the address of the corresponding object.  `.'
		  and `:' can be used in the identifier.  If supported by an
		  object format	dependent routine, [filename:]func:lineno,
		  [filename:]variable, and [filename:]lineno can be accepted
		  as a symbol.

     Numbers	  Radix	is determined by the first two letters:	`0x': hex,
		  `0o':	octal, `0t': decimal; otherwise, follow	current	radix.

     .		  dot

     +		  next

     ..		  address of the start of the last line	examined.  Unlike dot
		  or next, this	is only	changed	by examine or write command.

     '		  last address explicitly specified.

     $variable	  Translated to	the value of the specified variable.  It may
		  be followed by a `:' and modifiers as	described above.

     a#b	  A binary operator which rounds up the	left hand side to the
		  next multiple	of right hand side.

     *expr	  Indirection.	It may be followed by a	`:' and	modifiers as
		  described above.

     ddb supports a basic scripting facility to	allow automating tasks or re-
     sponses to	specific events.  Each script consists of a list of DDB	com-
     mands to be executed sequentially,	and is assigned	a unique name.	Cer-
     tain script names have special meaning, and will be automatically run on
     various ddb events	if scripts by those names have been defined.

     The script	command	may be used to define a	script by name.	 Scripts con-
     sist of a series of ddb commands separated	with the ; character.  For ex-

	   script kdb.enter.panic=bt; show pcpu
	   script lockinfo=show	alllocks; show lockedvnods

     The scripts command lists currently defined scripts.

     The run command execute a script by name.	For example:

	   run lockinfo

     The unscript command may be used to delete	a script by name.  For exam-

	   unscript kdb.enter.panic

     These functions may also be performed from	userspace using	the ddb(8)

     Certain scripts are run automatically, if defined,	for specific ddb
     events.  The follow scripts are run when various events occur:

     kdb.enter.acpi	  The kernel debugger was entered as a result of an
			  acpi(4) event.

     kdb.enter.bootflags  The kernel debugger was entered at boot as a result
			  of the debugger boot flag being set.

     kdb.enter.break	  The kernel debugger was entered as a result of a se-
			  rial or console break.	  The kernel debugger was entered as a result of a
			  CAM(4) event.

     kdb.enter.mac	  The kernel debugger was entered as a result of an
			  assertion failure in the mac_test(4) module of the
			  TrustedBSD MAC Framework.

     kdb.enter.ndis	  The kernel debugger was entered as a result of an
			  ndis(4) breakpoint event.

     kdb.enter.netgraph	  The kernel debugger was entered as a result of a
			  netgraph(4) event.

     kdb.enter.panic	  panic(9) was called.

     kdb.enter.powerfail  The kernel debugger was entered as a result of a
			  powerfail NMI	on the sparc64 platform.

     kdb.enter.powerpc	  The kernel debugger was entered as a result of an
			  unimplemented	interrupt type on the powerpc plat-

     kdb.enter.sysctl	  The kernel debugger was entered as a result of the
			  debug.kdb.enter sysctl being set.

     kdb.enter.trapsig	  The kernel debugger was entered as a result of a
			  trapsig event	on the sparc64 or sun4v	platform.

     kdb.enter.unionfs	  The kernel debugger was entered as a result of an
			  assertion failure in the union file system.

     kdb.enter.unknown	  The kernel debugger was entered, but no reason has
			  been set.

     kdb.enter.vfslock	  The kernel debugger was entered as a result of a VFS
			  lock violation.

     kdb.enter.watchdog	  The kernel debugger was entered as a result of a
			  watchdog firing.

     kdb.enter.witness	  The kernel debugger was entered as a result of a
			  witness(4) violation.

     In	the event that none of these scripts is	found, ddb will	attempt	to ex-
     ecute a default script:

     kdb.enter.default	  The kernel debugger was entered, but a script	ex-
			  actly	matching the reason for	entering was not de-
			  fined.  This can be used as a	catch-all to handle
			  cases	not specifically of interest; for example,
			  kdb.enter.witness might be defined to	have special
			  handling, and	kdb.enter.default might	be defined to
			  simply panic and reboot.

     On	machines with an ISA expansion bus, a simple NMI generation card can
     be	constructed by connecting a push button	between	the A01	and B01
     (CHCHK# and GND) card fingers.  Momentarily shorting these	two fingers
     together may cause	the bridge chipset to generate an NMI, which causes
     the kernel	to pass	control	to ddb.	 Some bridge chipsets do not generate
     a NMI on CHCHK#, so your mileage may vary.	 The NMI allows	one to break
     into the debugger on a wedged machine to diagnose problems.  Other	bus'
     bridge chipsets may be able to generate NMI using bus specific methods.

     gdb(1), kgdb(1), acpi(4), CAM(4), mac_text(4), ndis(4), netgraph(4),
     textdump(4), witness(4), ddb(8), sysctl(8), panic(9)

     The ddb debugger was developed for	Mach, and ported to 386BSD 0.1.	 This
     manual page translated from man(7)	macros by Garrett Wollman.

     Robert N. M. Watson added support for ddb output capture, textdump(4) and
     scripting in FreeBSD 7.1.

BSD			       November	29, 2008			   BSD


Want to link to this manual page? Use this URL:

home | help