share/man/man4/ddb.4

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