1.\" 2.\" Mach Operating System 3.\" Copyright (c) 1991,1990 Carnegie Mellon University 4.\" All Rights Reserved. 5.\" 6.\" Permission to use, copy, modify and distribute this software and its 7.\" documentation is hereby granted, provided that both the copyright 8.\" notice and this permission notice appear in all copies of the 9.\" software, derivative works or modified versions, and any portions 10.\" thereof, and that both notices appear in supporting documentation. 11.\" 12.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" 13.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR 14.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. 15.\" 16.\" Carnegie Mellon requests users of this software to return to 17.\" 18.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU 19.\" School of Computer Science 20.\" Carnegie Mellon University 21.\" Pittsburgh PA 15213-3890 22.\" 23.\" any improvements or extensions that they make and grant Carnegie Mellon 24.\" the rights to redistribute these changes. 25.\" 26.\" changed a \# to #, since groff choked on it. 27.\" 28.\" HISTORY 29.\" ddb.4,v 30.\" Revision 1.1 1993/07/15 18:41:02 brezak 31.\" Man page for DDB 32.\" 33.\" Revision 2.6 92/04/08 08:52:57 rpd 34.\" Changes from OSF. 35.\" [92/01/17 14:19:22 jsb] 36.\" Changes for OSF debugger modifications. 37.\" [91/12/12 tak] 38.\" 39.\" Revision 2.5 91/06/25 13:50:22 rpd 40.\" Added some watchpoint explanation. 41.\" [91/06/25 rpd] 42.\" 43.\" Revision 2.4 91/06/17 15:47:31 jsb 44.\" Added documentation for continue/c, match, search, and watchpoints. 45.\" I've not actually explained what a watchpoint is; maybe Rich can 46.\" do that (hint, hint). 47.\" [91/06/17 10:58:08 jsb] 48.\" 49.\" Revision 2.3 91/05/14 17:04:23 mrt 50.\" Correcting copyright 51.\" 52.\" Revision 2.2 91/02/14 14:10:06 mrt 53.\" Changed to new Mach copyright 54.\" [91/02/12 18:10:12 mrt] 55.\" 56.\" Revision 2.2 90/08/30 14:23:15 dbg 57.\" Created. 58.\" [90/08/30 dbg] 59.\" 60.\" $FreeBSD: src/share/man/man4/ddb.4,v 1.7.2.6 2001/08/17 13:08:37 ru Exp $ 61.\" $DragonFly: src/share/man/man4/ddb.4,v 1.2 2003/06/17 04:36:58 dillon Exp $ 62.Dd January 16, 1996 63.Dt DDB 4 64.Os 65.Sh NAME 66.Nm ddb 67.Nd interactive kernel debugger 68.Sh SYNOPSIS 69.Cd options DDB 70.Pp 71To prevent activation of the debugger on kernel 72.Xr panic 9 : 73.Cd options DDB_UNATTENDED 74.Sh DESCRIPTION 75The 76.Nm 77kernel debugger has most of the features of the old kdb, 78but with a more rational syntax 79inspired by 80.Xr gdb 1 . 81If linked into the running kernel, 82it can be invoked locally with the 83.Ql debug 84.Xr keymap 5 85action. 86The debugger is also invoked on kernel 87.Xr panic 9 88if the 89.Va debug.debugger_on_panic 90.Xr sysctl 8 91MIB variable is set non-zero, 92which is the default 93unless the 94.Dv DDB_UNATTENDED 95option is specified. 96.Pp 97The current location is called `dot'. The `dot' is displayed with 98a hexadecimal format at a prompt. 99Examine and write commands update `dot' to the address of the last line 100examined or the last location modified, and set `next' to the address of 101the next location to be examined or changed. 102Other commands don't change `dot', and set `next' to be the same as `dot'. 103.Pp 104The general command syntax is: 105.Cm command Ns Op Li \&/ Ns Ar modifier 106.Ar address Ns Op Li , Ns Ar count 107.Pp 108A blank line repeats the previous command from the address `next' with 109count 1 and no modifiers. Specifying 110.Ar address 111sets `dot' to the 112address. Omitting 113.Ar address 114uses `dot'. A missing 115.Ar count 116is taken 117to be 1 for printing commands or infinity for stack traces. 118.Pp 119The 120.Nm 121debugger has a feature like the 122.Xr more 1 123command 124for the output. If an output line exceeds the number set in the 125.Li \&$lines 126variable, it displays 127.Dq Em --db_more-- 128and waits for a response. 129The valid responses for it are: 130.Pp 131.Bl -tag -compact -width SPC 132.It Li SPC 133one more page 134.It Li RET 135one more line 136.It Li q 137abort the current command, and return to the command input mode 138.El 139.Pp 140Finally, 141.Nm 142provides a small (currently 10 items) command history, and offers 143simple emacs-style command line editing capabilities. In addition to 144the emacs control keys, the usual ANSI arrow keys might be used to 145browse through the history buffer, and move the cursor within the 146current line. 147.Sh COMMANDS 148.Bl -ohang 149.It Cm examine 150.It Cm x 151Display the addressed locations according to the formats in the modifier. 152Multiple modifier formats display multiple locations. 153If no format is specified, the last formats specified for this command 154is used. 155.Pp 156The format characters are: 157.Bl -tag -compact -width indent 158.It Li b 159look at by bytes (8 bits) 160.It Li h 161look at by half words (16 bits) 162.It Li l 163look at by long words (32 bits) 164.It Li a 165print the location being displayed 166.It Li A 167print the location with a line number if possible 168.It Li x 169display in unsigned hex 170.It Li z 171display in signed hex 172.It Li o 173display in unsigned octal 174.It Li d 175display in signed decimal 176.It Li u 177display in unsigned decimal 178.It Li r 179display in current radix, signed 180.It Li c 181display low 8 bits as a character. 182Non-printing characters are displayed as an octal escape code (e.g., `\e000'). 183.It Li s 184display the null-terminated string at the location. 185Non-printing characters are displayed as octal escapes. 186.It Li m 187display in unsigned hex with character dump at the end of each line. 188The location is also displayed in hex at the beginning of each line. 189.It Li i 190display as an instruction 191.It Li I 192display as an instruction with possible alternate formats depending on the 193machine: 194.Bl -tag -width MIPS -compact 195.It Tn VAX 196don't assume that each external label is a procedure entry mask 197.It Tn i386 198don't round to the next long word boundary 199.It Tn MIPS 200print register contents 201.El 202.El 203.It Cm xf 204Examine forward: 205Execute an examine command with the last specified parameters to it 206except that the next address displayed by it is used as the start address. 207.It Cm xb 208Examine backward: 209Execute an examine command with the last specified parameters to it 210except that the last start address subtracted by the size displayed by it 211is used as the start address. 212.It Cm print Ns Op Cm /acdoruxz 213Print 214.Ar addr Ns s 215according to the modifier character (as described above for 216.Li examine ) . 217Valid formats are: 218.Li a , 219.Li x , 220.Li z , 221.Li o , 222.Li d , 223.Li u , 224.Li r , 225and 226.Li c . 227If no modifier is specified, the last one specified to it is used. 228.Ar addr 229can be a string, in which case it is printed as it is. For example: 230.Bd -literal -offset indent 231print/x \&"eax = \&" $eax \&"\enecx = \&" $ecx \&"\en\&" 232.Ed 233.Pp 234will print like: 235.Bd -literal -offset indent 236eax = xxxxxx 237ecx = yyyyyy 238.Ed 239.It Xo 240.Cm write Ns Op Cm /bhl 241.Ar addr Ar expr1 Op Ar "expr2 ..." 242.Xc 243Write the expressions specified after 244.Ar addr 245on the command line at succeeding locations starting with 246.Ar addr 247The write unit size can be specified in the modifier with a letter 248.Li b 249(byte), 250.Li h 251(half word) or 252.Li l 253(long word) respectively. If omitted, 254long word is assumed. 255.Pp 256.Sy Warning : 257since there is no delimiter between expressions, strange 258things may happen. 259It's best to enclose each expression in parentheses. 260.It Xo 261.Cm set 262.Li \&$ Ns Ar variable 263.Op Li = 264.Ar expr 265.Xc 266Set the named variable or register with the value of 267.Ar expr . 268Valid variable names are described below. 269.It Cm break Ns Op Cm /u 270Set a break point at 271.Ar addr . 272If 273.Ar count 274is supplied, continues 275.Ar count 276- 1 times before stopping at the 277break point. If the break point is set, a break point number is 278printed with 279.Sq Li \&# . 280This number can be used in deleting the break point 281or adding conditions to it. 282.Pp 283If the 284.Li u 285modifier is specified, this command sets a break point in user space 286address. Without the 287.Li u 288option, the address is considered in the kernel 289space, and wrong space address is rejected with an error message. 290This modifier can be used only if it is supported by machine dependent 291routines. 292.Pp 293.Sy Warning : 294If a user text is shadowed by a normal user space debugger, 295user space break points may not work correctly. Setting a break 296point at the low-level code paths may also cause strange behavior. 297.It Cm delete Ar addr 298.It Cm delete Li \&# Ns Ar number 299Delete the break point. The target break point can be specified by a 300break point number with 301.Li # , 302or by using the same 303.Ar addr 304specified in the original 305.Cm break 306command. 307.It Cm step Ns Op Cm /p 308Single step 309.Ar count 310times (the comma is a mandatory part of the syntax). 311If the 312.Li p 313modifier is specified, print each instruction at each step. 314Otherwise, only print the last instruction. 315.Pp 316.Sy Warning : 317depending on machine type, it may not be possible to 318single-step through some low-level code paths or user space code. 319On machines with software-emulated single-stepping (e.g., pmax), 320stepping through code executed by interrupt handlers will probably 321do the wrong thing. 322.It Cm continue Ns Op Cm /c 323Continue execution until a breakpoint or watchpoint. 324If the 325.Li c 326modifier is specified, count instructions while executing. 327Some machines (e.g., pmax) also count loads and stores. 328.Pp 329.Sy Warning : 330when counting, the debugger is really silently single-stepping. 331This means that single-stepping on low-level code may cause strange 332behavior. 333.It Cm until Ns Op Cm /p 334Stop at the next call or return instruction. 335If the 336.Li p 337modifier is specified, print the call nesting depth and the 338cumulative instruction count at each call or return. Otherwise, 339only print when the matching return is hit. 340.It Cm next Ns Op Cm /p 341.It Cm match Ns Op Cm /p 342Stop at the matching return instruction. 343If the 344.Li p 345modifier is specified, print the call nesting depth and the 346cumulative instruction count at each call or return. Otherwise, 347only print when the matching return is hit. 348.It Xo 349.Cm trace Ns Op Cm /u 350.Op Ar frame 351.Op , Ns Ar count 352.Xc 353Stack trace. The 354.Li u 355option traces user space; if omitted, 356.Cm trace 357only traces 358kernel space. 359.Ar count 360is the number of frames to be traced. 361If 362.Ar count 363is omitted, all frames are printed. 364.Pp 365.Sy Warning : 366User space stack trace is valid 367only if the machine dependent code supports it. 368.It Xo 369.Cm search Ns Op Cm /bhl 370.Ar addr 371.Ar value 372.Op Ar mask 373.Op , Ns Ar count 374.Xc 375Search memory for 376.Ar value . 377This command might fail in interesting 378ways if it doesn't find the searched-for value. This is because 379ddb doesn't always recover from touching bad memory. The optional 380.Ar count 381argument limits the search. 382.It Cm show all procs Ns Op Cm /m 383.It Cm ps Ns Op Cm /m 384Display all process information. 385The process information may not be shown if it is not 386supported in the machine, or the bottom of the stack of the 387target process is not in the main memory at that time. 388The 389.Li m 390modifier will alter the display to show VM map 391addresses for the process and not show other info. 392.It Cm show registers Ns Op Cm /u 393Display the register set. 394If the 395.Li u 396option is specified, it displays user registers instead of 397kernel or currently saved one. 398.Pp 399.Sy Warning : 400The support of the 401.Li u 402modifier depends on the machine. If 403not supported, incorrect information will be displayed. 404.It Xo 405.Cm show map Ns Op Cm /f 406.Ar addr 407.Xc 408Prints the VM map at 409.Ar addr . 410If the 411.Li f 412modifier is specified the 413complete map is printed. 414.It Xo 415.Cm show object Ns Op Cm /f 416.Ar addr 417.Xc 418Prints the VM object at 419.Ar addr . 420If the 421.Li f 422option is specified the 423complete object is printed. 424.It Cm "show watches" 425Displays all watchpoints. 426.It Xo 427.Cm watch 428.Ar addr Ns Li \&, Ns Ar size 429.Xc 430Set a watchpoint for a region. Execution stops 431when an attempt to modify the region occurs. 432The 433.Ar size 434argument defaults to 4. 435If you specify a wrong space address, the request is rejected 436with an error message. 437.Pp 438.Sy Warning : 439Attempts to watch wired kernel memory 440may cause unrecoverable error in some systems such as i386. 441Watchpoints on user addresses work best. 442.It Cm gdb 443Toggles between remote GDB and DDB mode. In remote GDB mode, another 444machine is required that runs 445.Xr gdb 1 446using the remote debug feature, with a connection to the serial 447console port on the target machine. Currently only available on the 448.Em i386 449architecture. 450.It Cm help 451Print a short summary of the available commands and command 452abbreviations. 453.El 454.Sh VARIABLES 455The debugger accesses registers and variables as 456.Li \&$ Ns Em name . 457Register names are as in the 458.Dq Cm show registers 459command. 460Some variables are suffixed with numbers, and may have some modifier 461following a colon immediately after the variable name. 462For example, register variables can have a 463.Li u 464modifier to indicate user register (e.g., 465.Li $eax:u ) . 466.Pp 467Built-in variables currently supported are: 468.Bl -tag -width tabstops -compact 469.It Li radix 470Input and output radix 471.It Li maxoff 472Addresses are printed as 'symbol'+offset unless offset is greater than maxoff. 473.It Li maxwidth 474The width of the displayed line. 475.It Li lines 476The number of lines. It is used by "more" feature. 477.It Li tabstops 478Tab stop width. 479.It Li work Ns Ar xx 480Work variable. 481.Ar xx 482can be 0 to 31. 483.El 484.Sh EXPRESSIONS 485Almost all expression operators in C are supported except 486.Sq Li \&~ , 487.Sq Li \&^ , 488and unary 489.Sq Li \&& . 490Special rules in 491.Nm 492are: 493.Bl -tag -width Identifiers 494.It Em Identifiers 495The name of a symbol is translated to the value of the symbol, which 496is the address of the corresponding object. 497.Sq Li \&. 498and 499.Sq Li \&: 500can be used in the identifier. 501If supported by an object format dependent routine, 502.Sm off 503.Oo Em filename : Oc Em func : lineno , 504.Sm on 505.Oo Em filename : Oc Ns Em variable , 506and 507.Oo Em filename : Oc Ns Em lineno 508can be accepted as a symbol. 509.It Em Numbers 510Radix is determined by the first two letters: 511.Li 0x : 512hex, 513.Li 0o : 514octal, 515.Li 0t : 516decimal; otherwise, follow current radix. 517.It Li \&. 518`dot' 519.It Li \&+ 520`next' 521.It Li \&.. 522address of the start of the last line examined. 523Unlike `dot' or `next', this is only changed by 524.Dq Li examine 525or 526.Dq Li write 527command. 528.It Li \&' 529last address explicitly specified. 530.It Li \&$ Ns Em variable 531Translated to the value of the specified variable. 532It may be followed by a 533.Li : 534and modifiers as described above. 535.It Em a Ns Li \&# Ns Em b 536a binary operator which rounds up the left hand side to the next 537multiple of right hand side. 538.It Li \&* Ns Em expr 539indirection. It may be followed by a 540.Sq Li : 541and modifiers as described above. 542.El 543.Sh SEE ALSO 544.Xr gdb 1 545.Sh HISTORY 546The 547.Nm 548debugger was developed for Mach, and ported to 549.Bx 386 0.1 . 550This manual page translated from 551.Fl man 552macros by Garrett Wollman. 553