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>