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