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