[BACK]Return to ddb.4 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / share / man / man4

Annotation of src/share/man/man4/ddb.4, Revision 1.4

1.4     ! mycroft     1: .\" -*- nroff -*-
1.1       brezak      2: .\"
                      3: .\" Mach Operating System
                      4: .\" Copyright (c) 1991,1990 Carnegie Mellon University
                      5: .\" All Rights Reserved.
                      6: .\"
                      7: .\" Permission to use, copy, modify and distribute this software and its
                      8: .\" documentation is hereby granted, provided that both the copyright
                      9: .\" notice and this permission notice appear in all copies of the
                     10: .\" software, derivative works or modified versions, and any portions
                     11: .\" thereof, and that both notices appear in supporting documentation.
                     12: .\"
                     13: .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
                     14: .\" CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
                     15: .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
                     16: .\"
                     17: .\" Carnegie Mellon requests users of this software to return to
                     18: .\"
                     19: .\"  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
                     20: .\"  School of Computer Science
                     21: .\"  Carnegie Mellon University
                     22: .\"  Pittsburgh PA 15213-3890
                     23: .\"
                     24: .\" any improvements or extensions that they make and grant Carnegie Mellon
                     25: .\" the rights to redistribute these changes.
                     26: .\"
1.4     ! mycroft    27: .\"    $Id: $
1.1       brezak     28: .\"
                     29: .TH ddb 4
                     30: .SH NAME
                     31: ddb \- kernel debugger
                     32: .de XX
                     33: .sp
                     34: .ti -4n
                     35: \\$1
                     36: .br
                     37: .sp
                     38: ..
                     39: .de XS
                     40: .nr )R +\\$1
                     41: ..
                     42: .de XE
                     43: .nr )R -\\$1
                     44: ..
                     45: .SH DESCRIPTION
                     46: .br
                     47: .sp
                     48: The kernel debugger has most of the features of the old kdb,
                     49: but with a more rational (gdb-like) syntax.
                     50: .sp
                     51: The current location is called 'dot'.  The 'dot' is displayed with
                     52: a hexadecimal format at a prompt.
                     53: Examine and write commands update 'dot' to the address of the last line
                     54: examined or the last location modified, and set 'next' to the address of
                     55: the next location to be examined or changed.
                     56: Other commands don't change 'dot', and set 'next' to be the same as 'dot'.
                     57: .sp
                     58: The general command syntax is:
                     59: .sp
                     60: .ti +4n
                     61: \fIcommand[/modifier] address [,count]\fR
                     62: .sp
                     63: A blank line repeats from the address 'next' with count 1 and no modifiers.
                     64: Specifying 'address' sets 'dot' to the address.
                     65: Omitting 'address' uses 'dot'.
                     66: A missing 'count' is taken to be 1 for printing commands or infinity
                     67: for stack traces.
                     68: .sp
                     69: "\fBddb\fR" has a feature like a command "\fBmore\fR"
                     70: for the output.  If an output line exceeds the number set in the $lines
                     71: variable, it displays "\fI--db_more--\fR"
                     72: and waits for a response.
                     73: The valid responses for it are:
                     74: .XS 4n
                     75: .IP \fI\<space>\fR 10n
                     76: one more page
                     77: .IP \fI\<return>\fR 10n
                     78: one more line
                     79: .IP \fB\q\fR 10n
                     80: abort the current command, and return to the command input mode.
                     81: .LP
                     82: .sp
                     83: .XE 4n
                     84: .LP
                     85: .B COMMANDS
                     86: .sp
                     87: .XS 4n
                     88: .LP
                     89: .XX "\fBexamine(x) \fI[/<modifier>] <addr>[,<count>]\fR"
                     90: Display the addressed locations according to the formats in the modifier.
                     91: Multiple modifier formats display multiple locations.
                     92: If no format is specified, the last formats specified for this command
                     93: is used.
                     94: .br
                     95: The format characters are
                     96: .sp
                     97: .LP
                     98: .XS 2n
                     99: .IP b 5n
                    100: look at by bytes(8 bits)
                    101: .IP h 5n
                    102: look at by half words(16 bits)
                    103: .IP l 5n
                    104: look at by long words(32 bits)
                    105: .IP a 5n
                    106: print the location being displayed
                    107: .IP A 5n
                    108: print the location with a line number if possible
                    109: .IP x 5n
                    110: display in unsigned hex
                    111: .IP z 5n
                    112: display in signed hex
                    113: .IP o 5n
                    114: display in unsigned octal
                    115: .IP d 5n
                    116: display in signed decimal
                    117: .IP u 5n
                    118: display in unsigned decimal
                    119: .IP r 5n
                    120: display in current radix, signed
                    121: .IP c 5n
                    122: display low 8 bits as a character.
                    123: Non-printing characters are displayed as an octal escape code (e.g. '\\000').
                    124: .IP s 5n
                    125: display the null-terminated string at the location.
                    126: Non-printing characters are displayed as octal escapes.
                    127: .IP m 5n
                    128: display in unsigned hex with character dump at the end of each line.
                    129: The location is also displayed in hex at the beginning of each line.
                    130: .IP i 5n
                    131: display as an instruction
                    132: .IP I 5n
                    133: display as an instruction with possible alternate formats depending on the
                    134: machine:
                    135: .XE 2n
                    136: .LP
                    137: .XS 5n
                    138: .LP
                    139: .IP vax 6n
                    140: don't assume that each external label is a procedure entry mask
                    141: .IP i386 6n
                    142: don't round to the next long word boundary
                    143: .IP mips 6n
                    144: print register contents
                    145: .LP
                    146: .XE 5n
                    147: .LP
                    148: .XX xf
                    149: Examine forward.
                    150: It executes an examine command with the last specified parameters to it
                    151: except that the next address displayed by it is used as the start address.
                    152: .XX xb
                    153: Examine backward.
                    154: It executes an examine command with the last specified parameters to it
                    155: except that the last start address subtracted by the size displayed by it
                    156: is used as the start address.
                    157: .XX "\fBprint[/axzodurc] \fI<addr1> [ <addr2> ... ]\fR"
                    158: Print 'addr's according to the modifier character.
                    159: Valid formats are: a x z o d u r c.
                    160: If no modifier is specified, the last one specified to it is used.  'addr'
                    161: can be a string, and it is printed as it is.  For example,
                    162: .br
                    163: .sp
                    164: .ti +4n
                    165: print/x "eax = " $eax "\\necx = " $ecx "\\n"
                    166: .br
                    167: .sp
                    168: will print like
                    169: .sp
                    170: .in +4n
                    171: eax = xxxxxx
                    172: .br
                    173: ecx = yyyyyy
                    174: .in -4n
                    175: .sp
                    176: .br
                    177: .XX "\fBwrite[/bhl] \fI<addr> <expr1> [ <expr2> ... ]\fR"
                    178: Write the expressions at succeeding locations.
                    179: The write unit size can be specified in the modifier with a letter
                    180: b (byte), h (half word) or l(long word) respectively.  If omitted,
                    181: long word is assumed.
                    182: .br
                    183: Warning: since there is no delimiter between expressions, strange
                    184: things may happen.
                    185: It's best to enclose each expression in parentheses.
                    186: .XX "\fBset \fI$<variable> [=] <expr>\fR"
                    187: Set the named variable or register with the value of 'expr'.
                    188: Valid variable names are described below.
                    189: .XX "\fBbreak[/u] \fI<addr>[,<count>]\fR"
                    190: Set a break point at 'addr'.
                    191: If count is supplied, continues (count-1) times before stopping at the
                    192: break point.  If the break point is set, a break point number is
                    193: printed with '#'.  This number can be used in deleting the break point
                    194: or adding conditions to it.
                    195: .LP
                    196: .XS 2n
                    197: .IP u 5n
                    198: Set a break point in user space address. Without 'u' option,
                    199: the address is considered in the kernel space, and wrong space address
                    200: is rejected with an error message.
                    201: This option can be used only if it is supported by machine dependent
                    202: routines.
                    203: .LP
                    204: .XE 2n
                    205: Warning: if a user text is shadowed by a normal user space debugger,
                    206: user space break points may not work correctly.  Setting a break
                    207: point at the low-level code paths may also cause strange behavior.
                    208: .XX "\fBdelete \fI<addr>|#<number>\fR"
                    209: Delete the break point.  The target break point can be specified by a
                    210: break point number with '#', or by 'addr' like specified in 'break'
                    211: command.
                    212: .XX "\fBstep[/p] \fI[,<count>]\fR"
                    213: Single step 'count' times.
                    214: If 'p' option is specified, print each instruction at each step.
                    215: Otherwise, only print the last instruction.
                    216: .br
                    217: .sp
                    218: Warning: depending on machine type, it may not be possible to
                    219: single-step through some low-level code paths or user space code.
                    220: On machines with software-emulated single-stepping (e.g., pmax),
                    221: stepping through code executed by interrupt handlers will probably
                    222: do the wrong thing.
                    223: .XX "\fBcontinue[/c]\fR"
                    224: Continue execution until a breakpoint or watchpoint.
                    225: If /c, count instructions while executing.
                    226: Some machines (e.g., pmax) also count loads and stores.
                    227: .br
                    228: .sp
                    229: Warning: when counting, the debugger is really silently single-stepping.
                    230: This means that single-stepping on low-level code may cause strange
                    231: behavior.
                    232: .XX "\fBuntil[/p]\fR"
                    233: Stop at the next call or return instruction.
                    234: If 'p' option is specified, print the call nesting depth and the
                    235: cumulative instruction count at each call or return.  Otherwise,
                    236: only print when the matching return is hit.
                    237: .XX "\fBnext[/p]\fR"
                    238: Stop at the matching return instruction.
                    239: If 'p' option is specified, print the call nesting depth and the
                    240: cumulative instruction count at each call or return.  Otherwise,
                    241: only print when the matching return is hit.
                    242: .XX "\fBmatch[/p]\fR"
                    243: A synonym for 'next'.
                    244: .XX "\fBtrace[/u] \fI[ <frame_addr> ][,<count>]\fR"
                    245: Stack trace.  'u' option traces user space; if omitted, only traces
                    246: kernel space. 'count' is the number of frames to be traced.
                    247: If the 'count' is omitted, all frames are printed.
                    248: .br
                    249: .sp
                    250: Warning: User space stack trace is valid
                    251: only if the machine dependent code supports it.
                    252: .XX "\fBsearch[/bhl] \fI<addr> <value> [<mask>] [,<count>]\fR"
                    253: Search memory for a value. This command might fail in interesting
                    254: ways if it doesn't find the searched-for value.  This is because
                    255: ddb doesn't always recover from touching bad memory.  The optional
                    256: count argument limits the search.
                    257: .XX "\fBshow all procs[/m]\fR"
                    258: Display all process information.
                    259: This version of "\fBddb\fR"
                    260: prints more information than previous one.
                    261: It shows UNIX process information like "ps".
                    262: The UNIX process information may not be shown if it is not
                    263: supported in the machine, or the bottom of the stack of the
                    264: target process is not in the main memory at that time.
                    265: The 'm' options will alter the 'ps' display to show vm_map
                    266: addresses for the process and not show other info.
                    267: .br
                    268: .XX "\fBps[/m]\fR"
                    269: A synonym for 'show all procs'.
                    270: .XX "\fBshow registers\fR"
                    271: Display the register set.
                    272: If 'u' option is specified, it displays user registers instead of
                    273: kernel or currently saved one.
                    274: .br
                    275: .sp
                    276: Warning: The support of 'u' option depends on the machine.  If
                    277: not supported, incorrect information will be displayed.
                    278: .XX "\fBshow map[/f] \fI<addr>\fR"
                    279: Prints the vm_map at 'addr'. If the 'f' option is specified the
                    280: complete map is printed.
                    281: .XX "\fBshow object[/f]  \fI<addr>\fR"
                    282: Prints the vm_object at 'addr'. If the 'f' option is specified the
                    283: complete object is printed.
                    284: .XX "\fBshow watches\fR"
                    285: Displays all watchpoints.
                    286: .XX "\fBwatch \fI<addr>,<size>\fR"
                    287: Set a watchpoint for a region.  Execution stops
                    288: when an attempt to modify the region occurs.
                    289: The 'size' argument defaults to 4.
                    290: .br
                    291: If you specify a wrong space address, the request is rejected
                    292: with an error message.
                    293: .br
                    294: .sp
                    295: Warning: Attempts to watch wired kernel memory
                    296: may cause unrecoverable error in some systems such as i386.
                    297: Watchpoints on user addresses work best.
                    298: .br
                    299: .LP
                    300: .XE 4n
                    301: .LP
                    302: .sp
                    303: .B VARIABLES
                    304: .sp
                    305: The debugger accesses registers and variables as
                    306: .I $<name>.
                    307: Register names are as in the "\fBshow registers\fR"
                    308: command.
                    309: Some variables are suffixed with numbers, and may have some modifier
                    310: following a colon immediately after the variable name.
                    311: For example, register variables can have 'u' modifier to indicate
                    312: user register (e.g. $eax:u).
                    313: .br
                    314: .sp
                    315: Built-in variables currently supported are:
                    316: .sp
                    317: .IP radix 12n
                    318: Input and output radix
                    319: .IP maxoff 12n
                    320: Addresses are printed as 'symbol'+offset unless offset is greater than maxoff.
                    321: .IP maxwidth 12n
                    322: The width of the displayed line.
                    323: .IP lines 12n
                    324: The number of lines.  It is used by "more" feature.
                    325: .IP tabstops 12n
                    326: Tab stop width.
                    327: .IP work\fIxx\fR
                    328: Work variable.
                    329: .I 'xx'
                    330: can be 0 to 31.
                    331: .LP
                    332: .LP
                    333: .sp
                    334: .B EXPRESSIONS
                    335: .sp
                    336: Almost all expression operators in C are supported except '~', '^',
                    337: and unary '&'.
                    338: Special rules in "\fBddb\fR"
                    339: are:
                    340: .br
                    341: .IP "<identifier>" 15n
                    342: name of a symbol.  It is translated to the address(or value) of it.  '.'
                    343: and ':' can be used in the identifier.  If supported by an object format
                    344: dependent routine,
                    345: [\fI<file_name>\fR:]\fI<func>\fR[:\fI<line_number>\fR]
                    346: [\fI<file_name>\fR:]\fI<variable>\fR, and
                    347: \fI<file_name>\fR[:\fI<line_number>\fR]
                    348: can be accepted as a symbol.
                    349: The symbol may be prefixed with '\fI<symbol_table_name>\fR::'
                    350: like 'emulator::mach_msg_trap' to specify other than kernel symbols.
                    351: .IP "<number>" 15n
                    352: radix is determined by the first two letters:
                    353: 0x: hex, 0o: octal, 0t: decimal, otherwise, follow current radix.
                    354: .IP \. 15n
                    355: \'dot'
                    356: .IP \+ 15n
                    357: \'next'
                    358: .IP \.. 15n
                    359: address of the start of the last line examined.
                    360: Unlike 'dot' or 'next', this is only changed by "examine" or
                    361: "write" command.
                    362: .IP \' 15n
                    363: last address explicitly specified.
                    364: .IP "$<variable>" 15n
                    365: register name or variable.  It is translated to the value of it.
                    366: It may be followed by a ':' and modifiers as described above.
                    367: .IP \# 15n
                    368: a binary operator which rounds up the left hand side to the next
                    369: multiple of right hand side.
                    370: .IP "*<expr>" 15n
                    371: indirection.  It may be followed by a ':' and  modifiers as described above.

CVSweb <webmaster@jp.NetBSD.org>