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