| blob | 69f11ef8c7f1ff911aaad40e57dc3a329e3cafd3 |
1 .\"
2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" Copyright (c) 2007 Robert N. M. Watson
5 .\" All Rights Reserved.
6 .\"
7 .\" Permission to use, copy, modify and distribute this software and its
8 .\" documentation is hereby granted, provided that both the copyright
9 .\" notice and this permission notice appear in all copies of the
10 .\" software, derivative works or modified versions, and any portions
11 .\" thereof, and that both notices appear in supporting documentation.
12 .\"
13 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
14 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
15 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
16 .\"
17 .\" Carnegie Mellon requests users of this software to return to
18 .\"
19 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
20 .\" School of Computer Science
21 .\" Carnegie Mellon University
22 .\" Pittsburgh PA 15213-3890
23 .\"
24 .\" any improvements or extensions that they make and grant Carnegie Mellon
25 .\" the rights to redistribute these changes.
26 .\"
27 .\" changed a \# to #, since groff choked on it.
28 .\"
29 .\" HISTORY
30 .\" ddb.4,v
31 .\" Revision 1.1 1993/07/15 18:41:02 brezak
32 .\" Man page for DDB
33 .\"
34 .\" Revision 2.6 92/04/08 08:52:57 rpd
35 .\" Changes from OSF.
36 .\" [92/01/17 14:19:22 jsb]
37 .\" Changes for OSF debugger modifications.
38 .\" [91/12/12 tak]
39 .\"
40 .\" Revision 2.5 91/06/25 13:50:22 rpd
41 .\" Added some watchpoint explanation.
42 .\" [91/06/25 rpd]
43 .\"
44 .\" Revision 2.4 91/06/17 15:47:31 jsb
45 .\" Added documentation for continue/c, match, search, and watchpoints.
46 .\" I've not actually explained what a watchpoint is; maybe Rich can
47 .\" do that (hint, hint).
48 .\" [91/06/17 10:58:08 jsb]
49 .\"
50 .\" Revision 2.3 91/05/14 17:04:23 mrt
51 .\" Correcting copyright
52 .\"
53 .\" Revision 2.2 91/02/14 14:10:06 mrt
54 .\" Changed to new Mach copyright
55 .\" [91/02/12 18:10:12 mrt]
56 .\"
57 .\" Revision 2.2 90/08/30 14:23:15 dbg
58 .\" Created.
59 .\" [90/08/30 dbg]
60 .\"
61 .\" $FreeBSD$
62 .\"
63 .Dd August 20, 2008
64 .Dt DDB 4
65 .Os
66 .Sh NAME
67 .Nm ddb
68 .Nd interactive kernel debugger
69 .Sh SYNOPSIS
70 In order to enable kernel debugging facilities include:
71 .Bd -ragged -offset indent
72 .Cd options KDB
73 .Cd options DDB
74 .Ed
75 .Pp
76 To prevent activation of the debugger on kernel
77 .Xr panic 9 :
78 .Bd -ragged -offset indent
79 .Cd options KDB_UNATTENDED
80 .Ed
81 .Pp
82 In order to print a stack trace of the current thread on the console
83 for a panic:
84 .Bd -ragged -offset indent
85 .Cd options KDB_TRACE
86 .Ed
87 .Pp
88 To print the numerical value of symbols in addition to the symbolic
89 representation, define:
90 .Bd -ragged -offset indent
91 .Cd options DDB_NUMSYM
92 .Ed
93 .Pp
94 To enable the
95 .Xr gdb 1
96 backend, so that remote debugging with
97 .Xr kgdb 1
98 is possible, include:
99 .Bd -ragged -offset indent
100 .Cd options GDB
101 .Ed
102 .Sh DESCRIPTION
103 The
104 .Nm
105 kernel debugger has most of the features of the old
106 .Nm kdb ,
107 but with a more rational syntax
108 inspired by
109 .Xr gdb 1 .
110 If linked into the running kernel,
111 it can be invoked locally with the
112 .Ql debug
113 .Xr keymap 5
114 action.
115 The debugger is also invoked on kernel
116 .Xr panic 9
117 if the
118 .Va debug.debugger_on_panic
119 .Xr sysctl 8
120 MIB variable is set non-zero,
121 which is the default
122 unless the
123 .Dv KDB_UNATTENDED
124 option is specified.
125 .Pp
126 The current location is called
127 .Va dot .
128 The
129 .Va dot
130 is displayed with
131 a hexadecimal format at a prompt.
132 The commands
133 .Ic examine
134 and
135 .Ic write
136 update
137 .Va dot
138 to the address of the last line
139 examined or the last location modified, and set
140 .Va next
141 to the address of
142 the next location to be examined or changed.
143 Other commands do not change
144 .Va dot ,
145 and set
146 .Va next
147 to be the same as
148 .Va dot .
149 .Pp
150 The general command syntax is:
151 .Ar command Ns Op Li / Ns Ar modifier
152 .Ar address Ns Op Li , Ns Ar count
153 .Pp
154 A blank line repeats the previous command from the address
155 .Va next
156 with
157 count 1 and no modifiers.
158 Specifying
159 .Ar address
160 sets
161 .Va dot
162 to the address.
163 Omitting
164 .Ar address
165 uses
166 .Va dot .
167 A missing
168 .Ar count
169 is taken
170 to be 1 for printing commands or infinity for stack traces.
171 .Pp
172 The
173 .Nm
174 debugger has a pager feature (like the
175 .Xr more 1
176 command)
177 for the output.
178 If an output line exceeds the number set in the
179 .Va lines
180 variable, it displays
181 .Dq Li --More--
182 and waits for a response.
183 The valid responses for it are:
184 .Pp
185 .Bl -tag -compact -width ".Li SPC"
186 .It Li SPC
187 one more page
188 .It Li RET
189 one more line
190 .It Li q
191 abort the current command, and return to the command input mode
192 .El
193 .Pp
194 Finally,
195 .Nm
196 provides a small (currently 10 items) command history, and offers
197 simple
198 .Nm emacs Ns -style
199 command line editing capabilities.
200 In addition to
201 the
202 .Nm emacs
203 control keys, the usual
204 .Tn ANSI
205 arrow keys might be used to
206 browse through the history buffer, and move the cursor within the
207 current line.
208 .Sh COMMANDS
209 .Bl -tag -width indent -compact
210 .It Ic examine
211 .It Ic x
212 Display the addressed locations according to the formats in the modifier.
213 Multiple modifier formats display multiple locations.
214 If no format is specified, the last format specified for this command
215 is used.
216 .Pp
217 The format characters are:
218 .Bl -tag -compact -width indent
219 .It Cm b
220 look at by bytes (8 bits)
221 .It Cm h
222 look at by half words (16 bits)
223 .It Cm l
224 look at by long words (32 bits)
225 .It Cm a
226 print the location being displayed
227 .It Cm A
228 print the location with a line number if possible
229 .It Cm x
230 display in unsigned hex
231 .It Cm z
232 display in signed hex
233 .It Cm o
234 display in unsigned octal
235 .It Cm d
236 display in signed decimal
237 .It Cm u
238 display in unsigned decimal
239 .It Cm r
240 display in current radix, signed
241 .It Cm c
242 display low 8 bits as a character.
243 Non-printing characters are displayed as an octal escape code (e.g.,
244 .Ql \e000 ) .
245 .It Cm s
246 display the null-terminated string at the location.
247 Non-printing characters are displayed as octal escapes.
248 .It Cm m
249 display in unsigned hex with character dump at the end of each line.
250 The location is also displayed in hex at the beginning of each line.
251 .It Cm i
252 display as an instruction
253 .It Cm I
254 display as an instruction with possible alternate formats depending on the
255 machine:
256 .Bl -tag -width ".Tn powerpc" -compact
257 .It Tn alpha
258 Show the registers of the instruction.
259 .It Tn amd64
260 No alternate format.
261 .It Tn i386
262 No alternate format.
263 .It Tn ia64
264 No alternate format.
265 .It Tn powerpc
266 No alternate format.
267 .It Tn sparc64
268 No alternate format.
269 .El
270 .It Cm S
271 display a symbol name for the pointer stored at the address
272 .El
273 .Pp
274 .It Ic xf
275 Examine forward:
276 execute an
277 .Ic examine
278 command with the last specified parameters to it
279 except that the next address displayed by it is used as the start address.
280 .Pp
281 .It Ic xb
282 Examine backward:
283 execute an
284 .Ic examine
285 command with the last specified parameters to it
286 except that the last start address subtracted by the size displayed by it
287 is used as the start address.
288 .Pp
289 .It Ic print Ns Op Li / Ns Cm acdoruxz
290 .It Ic p Ns Op Li / Ns Cm acdoruxz
291 Print
292 .Ar addr Ns s
293 according to the modifier character (as described above for
294 .Cm examine ) .
295 Valid formats are:
296 .Cm a , x , z , o , d , u , r ,
297 and
298 .Cm c .
299 If no modifier is specified, the last one specified to it is used.
300 The argument
301 .Ar addr
302 can be a string, in which case it is printed as it is.
303 For example:
304 .Bd -literal -offset indent
305 print/x "eax = " $eax "\enecx = " $ecx "\en"
306 .Ed
307 .Pp
308 will print like:
309 .Bd -literal -offset indent
310 eax = xxxxxx
311 ecx = yyyyyy
312 .Ed
313 .Pp
314 .It Xo
315 .Ic write Ns Op Li / Ns Cm bhl
316 .Ar addr expr1 Op Ar expr2 ...
317 .Xc
318 .It Xo
319 .Ic w Ns Op Li / Ns Cm bhl
320 .Ar addr expr1 Op Ar expr2 ...
321 .Xc
322 Write the expressions specified after
323 .Ar addr
324 on the command line at succeeding locations starting with
325 .Ar addr .
326 The write unit size can be specified in the modifier with a letter
327 .Cm b
328 (byte),
329 .Cm h
330 (half word) or
331 .Cm l
332 (long word) respectively.
333 If omitted,
334 long word is assumed.
335 .Pp
336 .Sy Warning :
337 since there is no delimiter between expressions, strange
338 things may happen.
339 It is best to enclose each expression in parentheses.
340 .Pp
341 .It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr
342 Set the named variable or register with the value of
343 .Ar expr .
344 Valid variable names are described below.
345 .Pp
346 .It Ic break Ns Op Li / Ns Cm u
347 .It Ic b Ns Op Li / Ns Cm u
348 Set a break point at
349 .Ar addr .
350 If
351 .Ar count
352 is supplied, continues
353 .Ar count
354 \- 1 times before stopping at the
355 break point.
356 If the break point is set, a break point number is
357 printed with
358 .Ql # .
359 This number can be used in deleting the break point
360 or adding conditions to it.
361 .Pp
362 If the
363 .Cm u
364 modifier is specified, this command sets a break point in user
365 address space.
366 Without the
367 .Cm u
368 option, the address is considered to be in the kernel
369 space, and a wrong space address is rejected with an error message.
370 This modifier can be used only if it is supported by machine dependent
371 routines.
372 .Pp
373 .Sy Warning :
374 If a user text is shadowed by a normal user space debugger,
375 user space break points may not work correctly.
376 Setting a break
377 point at the low-level code paths may also cause strange behavior.
378 .Pp
379 .It Ic delete Ar addr
380 .It Ic d Ar addr
381 .It Ic delete Li # Ns Ar number
382 .It Ic d Li # Ns Ar number
383 Delete the break point.
384 The target break point can be specified by a
385 break point number with
386 .Ql # ,
387 or by using the same
388 .Ar addr
389 specified in the original
390 .Ic break
391 command.
392 .Pp
393 .It Ic watch Ar addr Ns Li , Ns Ar size
394 Set a watchpoint for a region.
395 Execution stops when an attempt to modify the region occurs.
396 The
397 .Ar size
398 argument defaults to 4.
399 If you specify a wrong space address, the request is rejected
400 with an error message.
401 .Pp
402 .Sy Warning :
403 Attempts to watch wired kernel memory
404 may cause unrecoverable error in some systems such as i386.
405 Watchpoints on user addresses work best.
406 .Pp
407 .It Ic hwatch Ar addr Ns Li , Ns Ar size
408 Set a hardware watchpoint for a region if supported by the
409 architecture.
410 Execution stops when an attempt to modify the region occurs.
411 The
412 .Ar size
413 argument defaults to 4.
414 .Pp
415 .Sy Warning :
416 The hardware debug facilities do not have a concept of separate
417 address spaces like the watch command does.
418 Use
419 .Ic hwatch
420 for setting watchpoints on kernel address locations only, and avoid
421 its use on user mode address spaces.
422 .Pp
423 .It Ic dhwatch Ar addr Ns Li , Ns Ar size
424 Delete specified hardware watchpoint.
425 .Pp
426 .It Ic step Ns Op Li / Ns Cm p
427 .It Ic s Ns Op Li / Ns Cm p
428 Single step
429 .Ar count
430 times (the comma is a mandatory part of the syntax).
431 If the
432 .Cm p
433 modifier is specified, print each instruction at each step.
434 Otherwise, only print the last instruction.
435 .Pp
436 .Sy Warning :
437 depending on machine type, it may not be possible to
438 single-step through some low-level code paths or user space code.
439 On machines with software-emulated single-stepping (e.g., pmax),
440 stepping through code executed by interrupt handlers will probably
441 do the wrong thing.
442 .Pp
443 .It Ic continue Ns Op Li / Ns Cm c
444 .It Ic c Ns Op Li / Ns Cm c
445 Continue execution until a breakpoint or watchpoint.
446 If the
447 .Cm c
448 modifier is specified, count instructions while executing.
449 Some machines (e.g., pmax) also count loads and stores.
450 .Pp
451 .Sy Warning :
452 when counting, the debugger is really silently single-stepping.
453 This means that single-stepping on low-level code may cause strange
454 behavior.
455 .Pp
456 .It Ic until Ns Op Li / Ns Cm p
457 Stop at the next call or return instruction.
458 If the
459 .Cm p
460 modifier is specified, print the call nesting depth and the
461 cumulative instruction count at each call or return.
462 Otherwise,
463 only print when the matching return is hit.
464 .Pp
465 .It Ic next Ns Op Li / Ns Cm p
466 .It Ic match Ns Op Li / Ns Cm p
467 Stop at the matching return instruction.
468 If the
469 .Cm p
470 modifier is specified, print the call nesting depth and the
471 cumulative instruction count at each call or return.
472 Otherwise, only print when the matching return is hit.
473 .Pp
474 .It Xo
475 .Ic trace Ns Op Li / Ns Cm u
476 .Op Ar pid | tid
477 .Op Li , Ns Ar count
478 .Xc
479 .It Xo
480 .Ic t Ns Op Li / Ns Cm u
481 .Op Ar pid | tid
482 .Op Li , Ns Ar count
483 .Xc
484 .It Xo
485 .Ic where Ns Op Li / Ns Cm u
486 .Op Ar pid | tid
487 .Op Li , Ns Ar count
488 .Xc
489 .It Xo
490 .Ic bt Ns Op Li / Ns Cm u
491 .Op Ar pid | tid
492 .Op Li , Ns Ar count
493 .Xc
494 Stack trace.
495 The
496 .Cm u
497 option traces user space; if omitted,
498 .Ic trace
499 only traces
500 kernel space.
501 The optional argument
502 .Ar count
503 is the number of frames to be traced.
504 If
505 .Ar count
506 is omitted, all frames are printed.
507 .Pp
508 .Sy Warning :
509 User space stack trace is valid
510 only if the machine dependent code supports it.
511 .Pp
512 .It Xo
513 .Ic search Ns Op Li / Ns Cm bhl
514 .Ar addr
515 .Ar value
516 .Op Ar mask
517 .Op Li , Ns Ar count
518 .Xc
519 Search memory for
520 .Ar value .
521 This command might fail in interesting
522 ways if it does not find the searched-for value.
523 This is because
524 .Nm
525 does not always recover from touching bad memory.
526 The optional
527 .Ar count
528 argument limits the search.
529 .\"
530 .Pp
531 .It Ic show Cm all procs Ns Op Li / Ns Cm m
532 .It Ic ps Ns Op Li / Ns Cm m
533 Display all process information.
534 The process information may not be shown if it is not
535 supported in the machine, or the bottom of the stack of the
536 target process is not in the main memory at that time.
537 The
538 .Cm m
539 modifier will alter the display to show VM map
540 addresses for the process and not show other information.
541 .\"
542 .Pp
543 .It Ic show Cm allchains
544 Show the same information like "show lockchain" does, but
545 for every thread in the system.
546 .\"
547 .Pp
548 .It Ic show Cm alllocks
549 Show all locks that are currently held.
550 .\"
551 .Pp
552 .It Ic show Cm allpcpu
553 The same as "show pcpu", but for every CPU present in the system.
554 .\"
555 .Pp
556 .It Ic show Cm allrman
557 Show information related with resource management, including
558 interrupt request lines, DMA request lines, I/O ports and I/O memory
559 addresses.
560 .\"
561 .Pp
562 .It Ic show Cm apic
563 Dump data about APIC IDT vector mappings.
564 .\"
565 .Pp
566 .It Ic show Cm breaks
567 Show breakpoints set with the "break" command.
568 .\"
569 .Pp
570 .It Ic show Cm buffer
571 Show buffer structure of
572 .Vt struct buf
573 type.
574 Such a structure is used within the
575 .Fx
576 kernel for the I/O subsystem
577 implementation.
578 For an exact interpretation of the output, please see the
579 .Pa sys/buf.h
580 header file.
581 .\"
582 .Pp
583 .It Ic show Cm cbstat
584 Show brief information about the TTY subsystem.
585 .\"
586 .Pp
587 .It Ic show Cm conifhk
588 Lists hooks currently waiting for completion in
589 run_interrupt_driven_config_hooks().
590 .\"
591 .Pp
592 .It Ic show Cm cpusets
593 Print numbered root and assigned CPU affinity sets.
594 See
595 .Xr cpuset 2
596 for more details.
597 .\"
598 .Pp
599 .It Ic show Cm cyrixreg
600 Show registers specific to the Cyrix processor.
601 .\"
602 .Pp
603 .It Ic show Cm domain Ar addr
604 Print protocol domain structure
605 .Vt struct domain
606 at address
607 .Ar addr .
608 See the
609 .Pa sys/domain.h
610 header file for more details on the exact meaning of the structure fields.
611 .\"
612 .Pp
613 .It Ic show Cm file Ar addr
614 Show information about the file structure
615 .Vt struct file
616 present at address
617 .Ar addr .
618 .\"
619 .Pp
620 .It Ic show Cm files
621 Show information about every file structure in the system.
622 .\"
623 .Pp
624 .It Ic show Cm freepages
625 Show the number of physical pages in each of the free lists.
626 .\"
627 .Pp
628 .It Ic show Cm geom Op Ar addr
629 If the
630 .Ar addr
631 argument is not given, displays the entire GEOM topology.
632 If
633 .Ar addr
634 is given, displays details about the given GEOM object (class, geom,
635 provider or consumer).
636 .\"
637 .Pp
638 .It Ic show Cm idt
639 Show IDT layout.
640 The first column specifies the IDT vector.
641 The second one is the name of the interrupt/trap handler.
642 Those functions are machine dependent.
643 .\"
644 .Pp
645 .It Ic show Cm inpcb Ar addr
646 Show information on IP Control Block
647 .Vt struct in_pcb
648 present at
649 .Ar addr .
650 .\"
651 .Pp
652 .It Ic show Cm intr
653 Dump information about interrupt handlers.
654 .\"
655 .Pp
656 .It Ic show Cm intrcnt
657 Dump the interrupt statistics.
658 .\"
659 .Pp
660 .It Ic show Cm irqs
661 Show interrupt lines and their respective kernel threads.
662 .\"
663 .Pp
664 .It Ic show Cm lapic
665 Show information from the local APIC registers for this CPU.
666 .\"
667 .Pp
668 .It Ic show Cm lock Ar addr
669 Show lock structure.
670 The output format is as follows:
671 .Bl -tag -offset 0 -width "flags"
672 .It Ic class:
673 Class of the lock.
674 Possible types include
675 .Xr mutex 9 ,
676 .Xr rmlock 9 ,
677 .Xr rwlock 9 ,
678 .Xr sx 9 .
679 .It Ic name:
680 Name of the lock.
681 .It Ic flags:
682 Flags passed to the lock initialization function.
683 For exact possibilities see manual pages of possible lock types.
684 .It Ic state:
685 Current state of a lock.
686 As well as
687 .Ic flags
688 it's lock-specific.
689 .It Ic owner:
690 Lock owner.
691 .El
692 .\"
693 .Pp
694 .It Ic show Cm lockchain Ar addr
695 Show all threads a particular thread at address
696 .Ar addr
697 is waiting on based on non-sleepable and non-spin locks.
698 .\"
699 .Pp
700 .It Ic show Cm lockedbufs
701 Show the same information as "show buf", but for every locked
702 .Vt struct buf
703 object.
704 .\"
705 .Pp
706 .It Ic show Cm lockedvnods
707 List all locked vnodes in the system.
708 .\"
709 .Pp
710 .It Ic show Cm locks
711 Prints all locks that are currently acquired.
712 .\"
713 .Pp
714 .It Ic show Cm locktree
715 .\"
716 .Pp
717 .It Ic show Cm malloc
718 Prints
719 .Xr malloc 9
720 memory allocator statistics.
721 The output format is as follows:
722 .Pp
723 .Bl -tag -compact -offset indent -width "Requests"
724 .It Ic Type
725 Specifies a type of memory.
726 It is the same as a description string used while defining the
727 given memory type with
728 .Xr MALLOC_DECLARE 9 .
729 .It Ic InUse
730 Number of memory allocations of the given type, for which
731 .Xr free 9
732 has not been called yet.
733 .It Ic MemUse
734 Total memory consumed by the given allocation type.
735 .It Ic Requests
736 Number of memory allocation requests for the given
737 memory type.
738 .El
739 .Pp
740 The same information can be gathered in userspace with
741 .Dq Nm vmstat Fl m .
742 .\"
743 .Pp
744 .It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr
745 Prints the VM map at
746 .Ar addr .
747 If the
748 .Cm f
749 modifier is specified the
750 complete map is printed.
751 .\"
752 .Pp
753 .It Ic show Cm msgbuf
754 Print the system's message buffer.
755 It is the same output as in the
756 .Dq Nm dmesg
757 case.
758 It is useful if you got a kernel panic, attached a serial cable
759 to the machine and want to get the boot messages from before the
760 system hang.
761 .\"
762 .It Ic show Cm mount
763 Displays short info about all currently mounted file systems.
764 .Pp
765 .It Ic show Cm mount Ar addr
766 Displays details about the given mount point.
767 .Pp
768 .\"
769 .Pp
770 .It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr
771 Prints the VM object at
772 .Ar addr .
773 If the
774 .Cm f
775 option is specified the
776 complete object is printed.
777 .\"
778 .Pp
779 .It Ic show Cm page
780 Show statistics on VM pages.
781 .\"
782 .Pp
783 .It Ic show Cm pageq
784 Show statistics on VM page queues.
785 .\"
786 .Pp
787 .It Ic show Cm pciregs
788 Print PCI bus registers.
789 The same information can be gathered in userspace by running
790 .Dq Nm pciconf Fl lv .
791 .\"
792 .Pp
793 .It Ic show Cm pcpu
794 Print current processor state.
795 The output format is as follows:
796 .Pp
797 .Bl -tag -compact -offset indent -width "spin locks held:"
798 .It Ic cpuid
799 Processor identifier.
800 .It Ic curthread
801 Thread pointer, process identifier and the name of the process.
802 .It Ic curpcb
803 Control block pointer.
804 .It Ic fpcurthread
805 FPU thread pointer.
806 .It Ic idlethread
807 Idle thread pointer.
808 .It Ic APIC ID
809 CPU identifier coming from APIC.
810 .It Ic currentldt
811 LDT pointer.
812 .It Ic spin locks held
813 Names of spin locks held.
814 .El
815 .\"
816 .Pp
817 .It Ic show Cm pgrpdump
818 Dump process groups present within the system.
819 .\"
820 .Pp
821 .It Ic show Cm proc Op Ar addr
822 If no
823 .Op Ar addr
824 is specified, print information about the current process.
825 Otherwise, show information about the process at address
826 .Ar addr .
827 .\"
828 .Pp
829 .It Ic show Cm procvm
830 Show process virtual memory layout.
831 .\"
832 .Pp
833 .It Ic show Cm protosw Ar addr
834 Print protocol switch structure
835 .Vt struct protosw
836 at address
837 .Ar addr .
838 .\"
839 .Pp
840 .It Ic show Cm registers Ns Op Li / Ns Cm u
841 Display the register set.
842 If the
843 .Cm u
844 modifier is specified, it displays user registers instead of
845 kernel registers or the currently saved one.
846 .Pp
847 .Sy Warning :
848 The support of the
849 .Cm u
850 modifier depends on the machine.
851 If not supported, incorrect information will be displayed.
852 .\"
853 .Pp
854 .It Ic show Cm rman Ar addr
855 Show resource manager object
856 .Vt struct rman
857 at address
858 .Ar addr .
859 Addresses of particular pointers can be gathered with "show allrman"
860 command.
861 .\"
862 .Pp
863 .It Ic show Cm rtc
864 Show real time clock value.
865 Useful for long debugging sessions.
866 .\"
867 .Pp
868 .It Ic show Cm sleepchain
869 Show all the threads a particular thread is waiting on based on
870 sleepable locks.
871 .\"
872 .Pp
873 .It Ic show Cm sleepq
874 .It Ic show Cm sleepqueue
875 Both commands provide the same functionality.
876 They show sleepqueue
877 .Vt struct sleepqueue
878 structure.
879 Sleepqueues are used within the
880 .Fx
881 kernel to implement sleepable
882 synchronization primitives (thread holding a lock might sleep or
883 be context switched), which at the time of writing are:
884 .Xr condvar 9 ,
885 .Xr sx 9
886 and standard
887 .Xr msleep 9
888 interface.
889 .\"
890 .Pp
891 .It Ic show Cm sockbuf Ar addr
892 .It Ic show Cm socket Ar addr
893 Those commands print
894 .Vt struct sockbuf
895 and
896 .Vt struct socket
897 objects placed at
898 .Ar addr .
899 Output consists of all values present in structures mentioned.
900 For exact interpretation and more details, visit
901 .Pa sys/socket.h
902 header file.
903 .\"
904 .Pp
905 .It Ic show Cm sysregs
906 Show system registers (e.g.,
907 .Li cr0-4
908 on i386.)
909 Not present on some platforms.
910 .\"
911 .Pp
912 .It Ic show Cm tcpcb Ar addr
913 Print TCP control block
914 .Vt struct tcpcb
915 lying at address
916 .Ar addr .
917 For exact interpretation of output, visit
918 .Pa netinet/tcp.h
919 header file.
920 .\"
921 .Pp
922 .It Ic show Cm thread Op Ar addr
923 If no
924 .Ar addr
925 is specified, show detailed information about current thread.
926 Otherwise, information about thread at
927 .Ar addr
928 is printed.
929 .\"
930 .Pp
931 .It Ic show Cm threads
932 Show all threads within the system.
933 Output format is as follows:
934 .Pp
935 .Bl -tag -width "PPID" -compact -offset indent -width "Second column"
936 .It Ic First column
937 Thread identifier (TID)
938 .It Ic Second column
939 Thread structure address
940 .It Ic Third column
941 Backtrace.
942 .El
943 .\"
944 .Pp
945 .It Ic show Cm ttys
946 Show all TTY's within the system.
947 Output is similar to
948 .Xr pstat 8 .
949 .\"
950 .Pp
951 .It Ic show Cm turnstile Ar addr
952 Show turnstile
953 .Vt struct turnstile
954 structure at address
955 .Ar addr .
956 Turnstiles are structures used within the
957 .Fx
958 kernel to implement
959 synchronization primitives which, while holding a specific type of lock, cannot
960 sleep or context switch to another thread.
961 Currently, those are:
962 .Xr mutex 9 ,
963 .Xr rwlock 9 ,
964 .Xr rmlock 9 .
965 .\"
966 .Pp
967 .It Ic show Cm uma
968 Show UMA allocator statistics.
969 Output consists five columns:
970 .Pp
971 .Bl -tag -compact -offset indent -width "Requests"
972 .It Cm "Zone"
973 Name of the UMA zone.
974 The same string that was passed to
975 .Xr uma_zcreate 9
976 as a first argument.
977 .It Cm "Size"
978 Size of a given memory object (slab).
979 .It Cm "Used"
980 Number of slabs being currently used.
981 .It Cm "Free"
982 Number of free slabs within the UMA zone.
983 .It Cm "Requests"
984 Number of allocations requests to the given zone.
985 .El
986 .Pp
987 The very same information might be gathered in the userspace
988 with the help of
989 .Dq Nm vmstat Fl z
990 .\"
991 .Pp
992 .It Ic show Cm unpcb Ar addr
993 Shows UNIX domain socket private control block
994 .Vt struct unpcb
995 present at the address
996 .Ar addr
997 .\"
998 .Pp
999 .It Ic show Cm vmochk
1000 Prints, whether the internal VM objects are in a map somewhere
1001 and none have zero ref counts.
1002 .\"
1003 .Pp
1004 .It Ic show Cm vmopag
1005 This is supposed to show physical addresses consumed by a
1006 VM object.
1007 Currently, it is not possible to use this command when
1008 .Xr witness 9
1009 is compiled in the kernel.
1010 .\"
1011 .Pp
1012 .It Ic show Cm vnode Op Ar addr
1013 Prints vnode
1014 .Vt struct vnode
1015 structure lying at
1016 .Op Ar addr .
1017 For the exact interpretation of the output, look at the
1018 .Pa sys/vnode.h
1019 header file.
1020 .\"
1021 .Pp
1022 .It Ic show Cm watches
1023 Displays all watchpoints.
1024 Shows watchpoints set with "watch" command.
1025 .\"
1026 .Pp
1027 .It Ic show Cm witness
1028 Shows information about lock acquisition coming from the
1029 .Xr witness 9
1030 subsystem.
1031 .\"
1032 .Pp
1033 .It Ic gdb
1034 Toggles between remote GDB and DDB mode.
1035 In remote GDB mode, another machine is required that runs
1036 .Xr gdb 1
1037 using the remote debug feature, with a connection to the serial
1038 console port on the target machine.
1039 Currently only available on the
1040 i386
1041 architecture.
1042 .Pp
1043 .It Ic halt
1044 Halt the system.
1045 .Pp
1046 .It Ic kill Ar sig pid
1047 Send signal
1048 .Ar sig
1049 to process
1050 .Ar pid .
1051 The signal is acted on upon returning from the debugger.
1052 This command can be used to kill a process causing resource contention
1053 in the case of a hung system.
1054 See
1055 .Xr signal 3
1056 for a list of signals.
1057 Note that the arguments are reversed relative to
1058 .Xr kill 2 .
1059 .Pp
1060 .It Ic reboot
1061 .It Ic reset
1062 Hard reset the system.
1063 .Pp
1064 .It Ic help
1065 Print a short summary of the available commands and command
1066 abbreviations.
1067 .Pp
1068 .It Ic capture on
1069 .It Ic capture off
1070 .It Ic capture reset
1071 .It Ic capture status
1072 .Nm
1073 supports a basic output capture facility, which can be used to retrieve the
1074 results of debugging commands from userpsace using
1075 .Xr sysctl 2 .
1076 .Ic capture on
1077 enables output capture;
1078 .Ic capture off
1079 disables capture.
1080 .Ic capture reset
1081 will clear the capture buffer and disable capture.
1082 .Ic capture status
1083 will report current buffer use, buffer size, and disposition of output
1084 capture.
1085 .Pp
1086 Userspace processes may inspect and manage
1087 .Nm
1088 capture state using
1089 .Xr sysctl 8 :
1090 .Pp
1091 .Dv debug.ddb.capture.bufsize
1092 may be used to query or set the current capture buffer size.
1093 .Pp
1094 .Dv debug.ddb.capture.maxbufsize
1095 may be used to query the compile-time limit on the capture buffer size.
1096 .Pp
1097 .Dv debug.ddb.capture.bytes
1098 may be used to query the number of bytes of output currently in the capture
1099 buffer.
1100 .Pp
1101 .Dv debug.ddb.capture.data
1102 returns the contents of the buffer as a string to an appropriately privileged
1103 process.
1104 .Pp
1105 This facility is particularly useful in concert with the scripting and
1106 .Xr textdump 4
1107 facilities, allowing scripted debugging output to be captured and
1108 committed to disk as part of a textdump for later analysis.
1109 The contents of the capture buffer may also be inspected in a kernel core dump
1110 using
1111 .Xr kgdb 1 .
1112 .Pp
1113 .It Ic run
1114 .It Ic script
1115 .It Ic scripts
1116 .It Ic unscript
1117 Run, define, list, and delete scripts.
1118 See the
1119 .Sx SCRIPTING
1120 section for more information on the scripting facility.
1121 .Pp
1122 .It Ic textdump set
1123 .It Ic textdump status
1124 .It Ic textdump unset
1125 The
1126 .Ic textdump set
1127 command may be used to force the next kernel core dump to be a textdump
1128 rather than a traditional memory dump or minidump.
1129 .Ic textdump status
1130 reports whether a textdump has been scheduled.
1131 .Ic textdump unset
1132 cancels a request to perform a textdump as the next kernel core dump.
1133 More information may be found in
1134 .Xr textdump 4 .
1135 .El
1136 .Sh VARIABLES
1137 The debugger accesses registers and variables as
1138 .Li $ Ns Ar name .
1139 Register names are as in the
1140 .Dq Ic show Cm registers
1141 command.
1142 Some variables are suffixed with numbers, and may have some modifier
1143 following a colon immediately after the variable name.
1144 For example, register variables can have a
1145 .Cm u
1146 modifier to indicate user register (e.g.,
1147 .Dq Li $eax:u ) .
1148 .Pp
1149 Built-in variables currently supported are:
1150 .Pp
1151 .Bl -tag -width ".Va tabstops" -compact
1152 .It Va radix
1153 Input and output radix.
1154 .It Va maxoff
1155 Addresses are printed as
1156 .Dq Ar symbol Ns Li + Ns Ar offset
1157 unless
1158 .Ar offset
1159 is greater than
1160 .Va maxoff .
1161 .It Va maxwidth
1162 The width of the displayed line.
1163 .It Va lines
1164 The number of lines.
1165 It is used by the built-in pager.
1166 .It Va tabstops
1167 Tab stop width.
1168 .It Va work Ns Ar xx
1169 Work variable;
1170 .Ar xx
1171 can take values from 0 to 31.
1172 .El
1173 .Sh EXPRESSIONS
1174 Most expression operators in C are supported except
1175 .Ql ~ ,
1176 .Ql ^ ,
1177 and unary
1178 .Ql & .
1179 Special rules in
1180 .Nm
1181 are:
1182 .Bl -tag -width ".No Identifiers"
1183 .It Identifiers
1184 The name of a symbol is translated to the value of the symbol, which
1185 is the address of the corresponding object.
1186 .Ql \&.
1187 and
1188 .Ql \&:
1189 can be used in the identifier.
1190 If supported by an object format dependent routine,
1191 .Sm off
1192 .Oo Ar filename : Oc Ar func : lineno ,
1193 .Sm on
1194 .Oo Ar filename : Oc Ns Ar variable ,
1195 and
1196 .Oo Ar filename : Oc Ns Ar lineno
1197 can be accepted as a symbol.
1198 .It Numbers
1199 Radix is determined by the first two letters:
1200 .Ql 0x :
1201 hex,
1202 .Ql 0o :
1203 octal,
1204 .Ql 0t :
1205 decimal; otherwise, follow current radix.
1206 .It Li \&.
1207 .Va dot
1208 .It Li +
1209 .Va next
1210 .It Li ..
1211 address of the start of the last line examined.
1212 Unlike
1213 .Va dot
1214 or
1215 .Va next ,
1216 this is only changed by
1217 .Ic examine
1218 or
1219 .Ic write
1220 command.
1221 .It Li '
1222 last address explicitly specified.
1223 .It Li $ Ns Ar variable
1224 Translated to the value of the specified variable.
1225 It may be followed by a
1226 .Ql \&:
1227 and modifiers as described above.
1228 .It Ar a Ns Li # Ns Ar b
1229 A binary operator which rounds up the left hand side to the next
1230 multiple of right hand side.
1231 .It Li * Ns Ar expr
1232 Indirection.
1233 It may be followed by a
1234 .Ql \&:
1235 and modifiers as described above.
1236 .El
1237 .Sh SCRIPTING
1238 .Nm
1239 supports a basic scripting facility to allow automating tasks or responses to
1240 specific events.
1241 Each script consists of a list of DDB commands to be executed sequentially,
1242 and is assigned a unique name.
1243 Certain script names have special meaning, and will be automatically run on
1244 various
1245 .Nm
1246 events if scripts by those names have been defined.
1247 .Pp
1248 The
1249 .Ic script
1250 command may be used to define a script by name.
1251 Scripts consist of a series of
1252 .Nm
1253 commands separated with the
1254 .Ic ;
1255 character.
1256 For example:
1257 .Bd -literal -offset indent
1258 script kdb.enter.panic=bt; show pcpu
1259 script lockinfo=show alllocks; show lockedvnods
1260 .Ed
1261 .Pp
1262 The
1263 .Ic scripts
1264 command lists currently defined scripts.
1265 .Pp
1266 The
1267 .Ic run
1268 command execute a script by name.
1269 For example:
1270 .Bd -literal -offset indent
1271 run lockinfo
1272 .Ed
1273 .Pp
1274 The
1275 .Ic unscript
1276 command may be used to delete a script by name.
1277 For example:
1278 .Bd -literal -offset indent
1279 unscript kdb.enter.panic
1280 .Ed
1281 .Pp
1282 These functions may also be performed from userspace using the
1283 .Xr ddb 8
1284 command.
1285 .Pp
1286 Certain scripts are run automatically, if defined, for specific
1287 .Nm
1288 events.
1289 The follow scripts are run when various events occur:
1290 .Bl -tag -width kdb.enter.powerfail
1291 .It Dv kdb.enter.acpi
1292 The kernel debugger was entered as a result of an
1293 .Xr acpi 4
1294 event.
1295 .It Dv kdb.enter.bootflags
1296 The kernel debugger was entered at boot as a result of the debugger boot
1297 flag being set.
1298 .It Dv kdb.enter.break
1299 The kernel debugger was entered as a result of a serial or console break.
1300 .It Dv kdb.enter.cam
1301 The kernel debugger was entered as a result of a
1302 .Xr CAM 4
1303 event.
1304 .It Dv kdb.enter.mac
1305 The kernel debugger was entered as a result of an assertion failure in the
1306 .Xr mac_test 4
1307 module of the
1308 TrustedBSD MAC Framework.
1309 .It Dv kdb.enter.ndis
1310 The kernel debugger was entered as a result of an
1311 .Xr ndis 4
1312 breakpoint event.
1313 .It Dv kdb.enter.netgraph
1314 The kernel debugger was entered as a result of a
1315 .Xr netgraph 4
1316 event.
1317 .It Dv kdb.enter.panic
1318 .Xr panic 9
1319 was called.
1320 .It Dv kdb.enter.powerfail
1321 The kernel debugger was entered as a result of a powerfail NMI on the sparc64
1322 platform.
1323 .It Dv kdb.enter.powerpc
1324 The kernel debugger was entered as a result of an unimplemented interrupt
1325 type on the powerpc platform.
1326 .It Dv kdb.enter.sysctl
1327 The kernel debugger was entered as a result of the
1328 .Dv debug.kdb.enter
1329 sysctl being set.
1330 .It Dv kdb.enter.trapsig
1331 The kernel debugger was entered as a result of a trapsig event on the sparc64
1332 or sun4v platform.
1333 .It Dv kdb.enter.unionfs
1334 The kernel debugger was entered as a result of an assertion failure in the
1335 union file system.
1336 .It Dv kdb.enter.unknown
1337 The kernel debugger was entered, but no reason has been set.
1338 .It Dv kdb.enter.vfslock
1339 The kernel debugger was entered as a result of a VFS lock violation.
1340 .It Dv kdb.enter.watchdog
1341 The kernel debugger was entered as a result of a watchdog firing.
1342 .It Dv kdb.enter.witness
1343 The kernel debugger was entered as a result of a
1344 .Xr witness 4
1345 violation.
1346 .El
1347 .Pp
1348 In the event that none of these scripts is found,
1349 .Nm
1350 will attempt to execute a default script:
1351 .Bl -tag -width kdb.enter.powerfail
1352 .It Dv kdb.enter.default
1353 The kernel debugger was entered, but a script exactly matching the reason for
1354 entering was not defined.
1355 This can be used as a catch-all to handle cases not specifically of interest;
1356 for example,
1357 .Dv kdb.enter.witness
1358 might be defined to have special handling, and
1359 .Dv kdb.enter.default
1360 might be defined to simply panic and reboot.
1361 .El
1362 .Sh HINTS
1363 On machines with an ISA expansion bus, a simple NMI generation card can be
1364 constructed by connecting a push button between the A01 and B01 (CHCHK# and
1365 GND) card fingers.
1366 Momentarily shorting these two fingers together may cause the bridge chipset to
1367 generate an NMI, which causes the kernel to pass control to
1368 .Nm .
1369 Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary.
1370 The NMI allows one to break into the debugger on a wedged machine to
1371 diagnose problems.
1372 Other bus' bridge chipsets may be able to generate NMI using bus specific
1373 methods.
1374 .Sh FILES
1375 Header files mention in this manual page can be found below
1376 .Pa /usr/include
1377 directory.
1378 .Pp
1379 .Bl -dash -compact
1380 .It
1381 .Pa sys/buf.h
1382 .It
1383 .Pa sys/domain.h
1384 .It
1385 .Pa netinet/in_pcb.h
1386 .It
1387 .Pa sys/socket.h
1388 .It
1389 .Pa sys/vnode.h
1390 .El
1391 .Sh SEE ALSO
1392 .Xr gdb 1 ,
1393 .Xr kgdb 1 ,
1394 .Xr acpi 4 ,
1395 .Xr CAM 4 ,
1396 .Xr mac_test 4 ,
1397 .Xr ndis 4 ,
1398 .Xr netgraph 4 ,
1399 .Xr textdump 4 ,
1400 .Xr witness 4 ,
1401 .Xr ddb 8 ,
1402 .Xr sysctl 8 ,
1403 .Xr panic 9 ,
1404 .Xr witness 9
1405 .Sh HISTORY
1406 The
1407 .Nm
1408 debugger was developed for Mach, and ported to
1409 .Bx 386 0.1 .
1410 This manual page translated from
1411 .Xr man 7
1412 macros by
1413 .An Garrett Wollman .
1414 .Pp
1415 .An Robert N. M. Watson
1416 added support for
1417 .Nm
1418 output capture,
1419 .Xr textdump 4
1420 and scripting in
1421 .Fx 7.1 .