3 16d2fe7d 2005-01-31 devnull db, stack \- debugger
4 6e18e03e 2004-04-11 devnull .SH SYNOPSIS
7 6e18e03e 2004-04-11 devnull .I option ...
12 3264d2e2 2005-01-23 devnull .I corefile
15 6e18e03e 2004-04-11 devnull .I textfile
22 6e18e03e 2004-04-11 devnull .I corefile
27 69e002b8 2006-06-26 devnull .I textfile
29 6e18e03e 2004-04-11 devnull .SH DESCRIPTION
31 6e18e03e 2004-04-11 devnull is a general purpose debugging program.
32 6e18e03e 2004-04-11 devnull It may be used to examine files and to provide
33 6e18e03e 2004-04-11 devnull a controlled environment for the execution
34 6e18e03e 2004-04-11 devnull of programs.
37 6e18e03e 2004-04-11 devnull .I textfile
38 6e18e03e 2004-04-11 devnull is a file containing the text and initialized
39 6e18e03e 2004-04-11 devnull data of an executable program.
43 6e18e03e 2004-04-11 devnull .I corefile
44 6e18e03e 2004-04-11 devnull specifies the memory image of a process.
47 6e18e03e 2004-04-11 devnull gives the id of an executing process to be accessed via
48 d32deab1 2020-08-16 rsc .MR ptrace (2) .
50 6e18e03e 2004-04-11 devnull .I corefile
51 6e18e03e 2004-04-11 devnull specifies the name of a core dump (see
53 6e18e03e 2004-04-11 devnull on your system of choice) containing the
54 6e18e03e 2004-04-11 devnull memory image of a terminated process.
55 6e18e03e 2004-04-11 devnull This manual refers to the memory image specified by
58 6e18e03e 2004-04-11 devnull .I corefile
60 6e18e03e 2004-04-11 devnull .IR memfile .
64 6e18e03e 2004-04-11 devnull associated with each
65 6e18e03e 2004-04-11 devnull .I textfile
67 6e18e03e 2004-04-11 devnull .I memfile
68 6e18e03e 2004-04-11 devnull supports accesses to instructions and data in the file;
69 6e18e03e 2004-04-11 devnull see `Addresses'.
71 6e18e03e 2004-04-11 devnull An argument consisting entirely of digits is assumed
72 6e18e03e 2004-04-11 devnull to be a process id; otherwise, it is the name of a
73 6e18e03e 2004-04-11 devnull .I textfile
75 6e18e03e 2004-04-11 devnull .IR corefile .
77 6e18e03e 2004-04-11 devnull .I textfile
78 6e18e03e 2004-04-11 devnull is given, the textfile map
79 6e18e03e 2004-04-11 devnull is associated with it.
80 6e18e03e 2004-04-11 devnull If only a
81 6e18e03e 2004-04-11 devnull .I memfile
82 6e18e03e 2004-04-11 devnull is given, the textfile map is
83 6e18e03e 2004-04-11 devnull derived from the corresponding
84 6e18e03e 2004-04-11 devnull .IR textfile ,
85 6e18e03e 2004-04-11 devnull if it can be determined
86 6e18e03e 2004-04-11 devnull (this varies from system to system).
88 6e18e03e 2004-04-11 devnull .I memfile
89 6e18e03e 2004-04-11 devnull is given, the memfile map is associated with it;
90 6e18e03e 2004-04-11 devnull otherwise the map is undefined and accesses to it
91 6e18e03e 2004-04-11 devnull are not permitted.
94 3264d2e2 2005-01-23 devnull takes the same arguments as
96 3264d2e2 2005-01-23 devnull It prints a stack trace (see the
98 3264d2e2 2005-01-23 devnull command below) and then exits.
99 69e002b8 2006-06-26 devnull If the first argument is a process name,
101 69e002b8 2006-06-26 devnull .I stack
102 69e002b8 2006-06-26 devnull prints the stack trace of every running process
103 69e002b8 2006-06-26 devnull with the given name
105 69e002b8 2006-06-26 devnull owned by the current user.
107 6e18e03e 2004-04-11 devnull Commands to
109 6e18e03e 2004-04-11 devnull are read from the standard input and
110 6e18e03e 2004-04-11 devnull responses are to the standard output.
111 6e18e03e 2004-04-11 devnull The options are
114 8b0e19f7 2005-01-23 devnull Quiet mode:
115 8b0e19f7 2005-01-23 devnull suppress informational prints at startup.
119 6e18e03e 2004-04-11 devnull .I textfile
121 6e18e03e 2004-04-11 devnull .I memfile
122 6e18e03e 2004-04-11 devnull for writing as well as reading.
124 6e18e03e 2004-04-11 devnull .BI -I path
125 6e18e03e 2004-04-11 devnull Directory in which to look for relative path names in
129 6e18e03e 2004-04-11 devnull commands.
131 6e18e03e 2004-04-11 devnull .BI -m machine
132 6e18e03e 2004-04-11 devnull Assume instructions are for the given CPU type
133 6e18e03e 2004-04-11 devnull (possible names include
136 6e18e03e 2004-04-11 devnull .BR powerpc ;
138 6e18e03e 2004-04-11 devnull the suffix
141 6e18e03e 2004-04-11 devnull .B 386-co
143 6e18e03e 2004-04-11 devnull .B powerpc-co
144 6e18e03e 2004-04-11 devnull selects disassembly in the manufacturer's syntax, if
145 6e18e03e 2004-04-11 devnull available,
146 6e18e03e 2004-04-11 devnull rather than the default Plan 9 syntax).
150 6e18e03e 2004-04-11 devnull commands have the following form:
152 6e18e03e 2004-04-11 devnull .RI [ address ]
154 6e18e03e 2004-04-11 devnull .IR count ]
155 6e18e03e 2004-04-11 devnull .RI [ command ]
158 6e18e03e 2004-04-11 devnull .I address
159 6e18e03e 2004-04-11 devnull is present then the current position, called `dot',
160 6e18e03e 2004-04-11 devnull is set to
161 6e18e03e 2004-04-11 devnull .IR address .
162 6e18e03e 2004-04-11 devnull Initially dot
163 6e18e03e 2004-04-11 devnull is set to 0.
164 6e18e03e 2004-04-11 devnull Most commands are repeated
165 6e18e03e 2004-04-11 devnull .I count
166 6e18e03e 2004-04-11 devnull times with
167 6e18e03e 2004-04-11 devnull dot advancing between repetitions.
168 6e18e03e 2004-04-11 devnull The default
169 6e18e03e 2004-04-11 devnull .I count
171 6e18e03e 2004-04-11 devnull .I Address
173 6e18e03e 2004-04-11 devnull .I count
174 6e18e03e 2004-04-11 devnull are expressions.
175 6e18e03e 2004-04-11 devnull Multiple commands on one line must be separated by
177 6e18e03e 2004-04-11 devnull .SS Expressions
178 6e18e03e 2004-04-11 devnull Expressions are evaluated as long
179 6e18e03e 2004-04-11 devnull .IR ints .
180 6e18e03e 2004-04-11 devnull .TP 7.2n
182 6e18e03e 2004-04-11 devnull The value of dot.
183 6e18e03e 2004-04-11 devnull .TP 7.2n
185 6e18e03e 2004-04-11 devnull The value of dot
186 6e18e03e 2004-04-11 devnull incremented by the current increment.
187 6e18e03e 2004-04-11 devnull .TP 7.2n
189 6e18e03e 2004-04-11 devnull The value of dot
190 6e18e03e 2004-04-11 devnull decremented by the current increment.
191 6e18e03e 2004-04-11 devnull .TP 7.2n
193 6e18e03e 2004-04-11 devnull The last
194 6e18e03e 2004-04-11 devnull .I address
196 6e18e03e 2004-04-11 devnull .TP 7.2n
197 6e18e03e 2004-04-11 devnull .I integer
198 6e18e03e 2004-04-11 devnull A number, in decimal radix by default.
199 6e18e03e 2004-04-11 devnull The prefixes
205 6e18e03e 2004-04-11 devnull (zero oh) force interpretation
206 6e18e03e 2004-04-11 devnull in octal radix; the prefixes
210 6e18e03e 2004-04-11 devnull force interpretation in
211 6e18e03e 2004-04-11 devnull decimal radix; the prefixes
212 6e18e03e 2004-04-11 devnull .LR 0x ,
213 6e18e03e 2004-04-11 devnull .LR 0X ,
216 6e18e03e 2004-04-11 devnull force interpretation in
217 6e18e03e 2004-04-11 devnull hexadecimal radix.
219 6e18e03e 2004-04-11 devnull .LR 020 ,
220 6e18e03e 2004-04-11 devnull .LR 0o20 ,
221 6e18e03e 2004-04-11 devnull .LR 0t16 ,
224 6e18e03e 2004-04-11 devnull all represent sixteen.
225 6e18e03e 2004-04-11 devnull .TP 7.2n
226 6e18e03e 2004-04-11 devnull .IB integer . fraction
227 6e18e03e 2004-04-11 devnull A single-precision floating point number.
228 6e18e03e 2004-04-11 devnull .TP 7.2n
229 6e18e03e 2004-04-11 devnull .BI \' c\| \'
232 6e18e03e 2004-04-11 devnull value of a character.
234 6e18e03e 2004-04-11 devnull may be used to escape a
235 6e18e03e 2004-04-11 devnull .LR \' .
236 6e18e03e 2004-04-11 devnull .TP 7.2n
237 6e18e03e 2004-04-11 devnull .BI < name
238 6e18e03e 2004-04-11 devnull The value of
239 6e18e03e 2004-04-11 devnull .IR name ,
240 6e18e03e 2004-04-11 devnull which is a register name.
241 6e18e03e 2004-04-11 devnull The register names are
242 6e18e03e 2004-04-11 devnull those printed by the
244 6e18e03e 2004-04-11 devnull command.
245 6e18e03e 2004-04-11 devnull .TP 7.2n
246 6e18e03e 2004-04-11 devnull .I symbol
248 6e18e03e 2004-04-11 devnull .I symbol
249 6e18e03e 2004-04-11 devnull is a sequence
250 6e18e03e 2004-04-11 devnull of upper or lower case letters, underscores or
251 6e18e03e 2004-04-11 devnull digits, not starting with a digit.
253 6e18e03e 2004-04-11 devnull may be used to escape other characters.
254 6e18e03e 2004-04-11 devnull The location of the
255 6e18e03e 2004-04-11 devnull .I symbol
256 6e18e03e 2004-04-11 devnull is calculated from the symbol table
258 6e18e03e 2004-04-11 devnull .IR textfile .
259 6e18e03e 2004-04-11 devnull .TP 7.2n
260 6e18e03e 2004-04-11 devnull .IB routine . name
261 6e18e03e 2004-04-11 devnull The address of the variable
263 6e18e03e 2004-04-11 devnull in the specified
264 6e18e03e 2004-04-11 devnull C routine.
266 6e18e03e 2004-04-11 devnull .I routine
270 6e18e03e 2004-04-11 devnull .IR symbols .
273 6e18e03e 2004-04-11 devnull is omitted the value is the address of the
274 6e18e03e 2004-04-11 devnull most recently activated stack frame
275 6e18e03e 2004-04-11 devnull corresponding to
276 6e18e03e 2004-04-11 devnull .IR routine ;
278 6e18e03e 2004-04-11 devnull .I routine
279 6e18e03e 2004-04-11 devnull is omitted,
280 6e18e03e 2004-04-11 devnull the active procedure
281 6e18e03e 2004-04-11 devnull is assumed.
282 6e18e03e 2004-04-11 devnull .TP 7.2n
283 6e18e03e 2004-04-11 devnull .IB file : integer
284 6e18e03e 2004-04-11 devnull The address of the instruction corresponding
285 6e18e03e 2004-04-11 devnull to the source statement at the indicated
286 6e18e03e 2004-04-11 devnull line number of the file. If the source line contains
287 6e18e03e 2004-04-11 devnull no executable statement, the address of the
288 6e18e03e 2004-04-11 devnull instruction associated with the nearest
289 6e18e03e 2004-04-11 devnull executable source line is returned. Files
290 6e18e03e 2004-04-11 devnull begin at line 1. If multiple files of the same
291 6e18e03e 2004-04-11 devnull name are loaded, an expression of this form resolves
292 6e18e03e 2004-04-11 devnull to the first file encountered in the symbol table.
293 6e18e03e 2004-04-11 devnull .TP 7.2n
294 6e18e03e 2004-04-11 devnull .BI ( exp )
295 6e18e03e 2004-04-11 devnull The value of the expression
296 6e18e03e 2004-04-11 devnull .IR exp .
298 6e18e03e 2004-04-11 devnull .I Monadic operators
300 6e18e03e 2004-04-11 devnull .TP 7.2n
301 6e18e03e 2004-04-11 devnull .BI * exp
302 6e18e03e 2004-04-11 devnull The contents of the location addressed
306 6e18e03e 2004-04-11 devnull .IR memfile .
307 6e18e03e 2004-04-11 devnull .TP 7.2n
308 6e18e03e 2004-04-11 devnull .BI @ exp
309 6e18e03e 2004-04-11 devnull The contents of the location addressed by
312 6e18e03e 2004-04-11 devnull .IR textfile .
313 6e18e03e 2004-04-11 devnull .TP 7.2n
314 6e18e03e 2004-04-11 devnull .BI - exp
315 6e18e03e 2004-04-11 devnull Integer negation.
316 6e18e03e 2004-04-11 devnull .TP 7.2n
317 6e18e03e 2004-04-11 devnull .BI ~ exp
318 6e18e03e 2004-04-11 devnull Bitwise complement.
319 6e18e03e 2004-04-11 devnull .TP 7.2n
320 6e18e03e 2004-04-11 devnull .BI % exp
321 6e18e03e 2004-04-11 devnull When used as an
322 6e18e03e 2004-04-11 devnull .IR address ,
324 6e18e03e 2004-04-11 devnull is an offset into the segment named
325 6e18e03e 2004-04-11 devnull .IR ublock ;
326 6e18e03e 2004-04-11 devnull see `Addresses'.
329 6e18e03e 2004-04-11 devnull .I "Dyadic\ operators"
330 6e18e03e 2004-04-11 devnull are left-associative
331 6e18e03e 2004-04-11 devnull and are less binding than monadic operators.
333 6e18e03e 2004-04-11 devnull .TP 7.2n
334 6e18e03e 2004-04-11 devnull .IB e1 + e2
335 6e18e03e 2004-04-11 devnull Integer addition.
336 6e18e03e 2004-04-11 devnull .TP 7.2n
337 6e18e03e 2004-04-11 devnull .IB e1 - e2
338 6e18e03e 2004-04-11 devnull Integer subtraction.
339 6e18e03e 2004-04-11 devnull .TP 7.2n
340 6e18e03e 2004-04-11 devnull .IB e1 * e2
341 6e18e03e 2004-04-11 devnull Integer multiplication.
342 6e18e03e 2004-04-11 devnull .TP 7.2n
343 6e18e03e 2004-04-11 devnull .IB e1 % e2
344 6e18e03e 2004-04-11 devnull Integer division.
345 6e18e03e 2004-04-11 devnull .TP 7.2n
346 6e18e03e 2004-04-11 devnull .IB e1 & e2
347 6e18e03e 2004-04-11 devnull Bitwise conjunction.
348 6e18e03e 2004-04-11 devnull .TP 7.2n
349 6e18e03e 2004-04-11 devnull .IB e1 | e2
350 6e18e03e 2004-04-11 devnull Bitwise disjunction.
351 6e18e03e 2004-04-11 devnull .TP 7.2n
352 6e18e03e 2004-04-11 devnull .IB e1 # e2
354 6e18e03e 2004-04-11 devnull rounded up to the next multiple of
355 6e18e03e 2004-04-11 devnull .IR e2 .
358 6e18e03e 2004-04-11 devnull .SS Commands
359 6e18e03e 2004-04-11 devnull Most commands have the following syntax:
362 6e18e03e 2004-04-11 devnull Locations starting at
363 6e18e03e 2004-04-11 devnull .I address
365 6e18e03e 2004-04-11 devnull .I textfile
366 6e18e03e 2004-04-11 devnull are printed according to the format
370 6e18e03e 2004-04-11 devnull Locations starting at
371 6e18e03e 2004-04-11 devnull .I address
373 6e18e03e 2004-04-11 devnull .I memfile
374 6e18e03e 2004-04-11 devnull are printed according to the format
378 6e18e03e 2004-04-11 devnull The value of
379 6e18e03e 2004-04-11 devnull .I address
380 6e18e03e 2004-04-11 devnull itself is printed according to the format
384 6e18e03e 2004-04-11 devnull .I format
385 6e18e03e 2004-04-11 devnull consists of one or more characters that specify a style
386 6e18e03e 2004-04-11 devnull of printing.
387 6e18e03e 2004-04-11 devnull Each format character may be preceded by a decimal integer
388 6e18e03e 2004-04-11 devnull that is a repeat count for the format character.
389 6e18e03e 2004-04-11 devnull If no format is given then the last format is used.
391 6e18e03e 2004-04-11 devnull Most format letters fetch some data,
392 6e18e03e 2004-04-11 devnull print it,
393 6e18e03e 2004-04-11 devnull and advance (a local copy of) dot
394 6e18e03e 2004-04-11 devnull by the number of bytes fetched.
395 6e18e03e 2004-04-11 devnull The total number of bytes in a format becomes the
396 6e18e03e 2004-04-11 devnull .IR current increment .
397 6e18e03e 2004-04-11 devnull .ta 2.5n .5i
402 6e18e03e 2004-04-11 devnull Print two-byte integer in octal.
405 6e18e03e 2004-04-11 devnull Print four-byte integer in octal.
408 6e18e03e 2004-04-11 devnull Print two-byte integer in signed octal.
411 6e18e03e 2004-04-11 devnull Print four-byte integer in signed octal.
414 6e18e03e 2004-04-11 devnull Print two-byte integer in decimal.
417 6e18e03e 2004-04-11 devnull Print four-byte integer in decimal.
420 6e18e03e 2004-04-11 devnull Print eight-byte integer in decimal.
423 6e18e03e 2004-04-11 devnull Print eight-byte integer in unsigned decimal.
426 6e18e03e 2004-04-11 devnull Print two-byte integer in hexadecimal.
429 6e18e03e 2004-04-11 devnull Print four-byte integer in hexadecimal.
432 6e18e03e 2004-04-11 devnull Print eight-byte integer in hexadecimal.
435 6e18e03e 2004-04-11 devnull Print two-byte integer in unsigned decimal.
438 6e18e03e 2004-04-11 devnull Print four-byte integer in unsigned decimal.
442 6e18e03e 2004-04-11 devnull as a single-precision floating point number.
445 6e18e03e 2004-04-11 devnull Print double-precision floating point.
448 6e18e03e 2004-04-11 devnull Print the addressed byte in hexadecimal.
451 6e18e03e 2004-04-11 devnull Print the addressed byte as an
452 6e18e03e 2004-04-11 devnull .SM ASCII
453 6e18e03e 2004-04-11 devnull character.
456 6e18e03e 2004-04-11 devnull Print the addressed byte as a character.
457 6e18e03e 2004-04-11 devnull Printable
458 6e18e03e 2004-04-11 devnull .SM ASCII
459 6e18e03e 2004-04-11 devnull characters
460 6e18e03e 2004-04-11 devnull are represented normally; others
461 6e18e03e 2004-04-11 devnull are printed in the form
462 6e18e03e 2004-04-11 devnull .BR \exnn .
465 6e18e03e 2004-04-11 devnull Print the addressed characters, as a
467 6e18e03e 2004-04-11 devnull string, until a zero byte
468 6e18e03e 2004-04-11 devnull is reached.
469 6e18e03e 2004-04-11 devnull Advance dot
470 6e18e03e 2004-04-11 devnull by the length of the string,
471 6e18e03e 2004-04-11 devnull including the zero terminator.
474 6e18e03e 2004-04-11 devnull Print a string using
475 6e18e03e 2004-04-11 devnull the escape convention (see
480 6e18e03e 2004-04-11 devnull Print as
482 6e18e03e 2004-04-11 devnull the addressed two-byte integer (rune).
485 6e18e03e 2004-04-11 devnull Print as
487 6e18e03e 2004-04-11 devnull the addressed two-byte integers as runes
488 6e18e03e 2004-04-11 devnull until a zero rune is reached.
489 6e18e03e 2004-04-11 devnull Advance dot
490 6e18e03e 2004-04-11 devnull by the length of the string,
491 6e18e03e 2004-04-11 devnull including the zero terminator.
494 6e18e03e 2004-04-11 devnull Print as machine instructions. Dot is
495 6e18e03e 2004-04-11 devnull incremented by the size of the instruction.
500 6e18e03e 2004-04-11 devnull above, but print the machine instructions in
501 6e18e03e 2004-04-11 devnull an alternate form if possible.
504 6e18e03e 2004-04-11 devnull Print the addressed machine instruction in a
505 6e18e03e 2004-04-11 devnull machine-dependent hexadecimal form.
508 6e18e03e 2004-04-11 devnull Print the value of dot
509 6e18e03e 2004-04-11 devnull in symbolic form.
510 6e18e03e 2004-04-11 devnull Dot is unaffected.
513 6e18e03e 2004-04-11 devnull Print the value of dot
514 6e18e03e 2004-04-11 devnull in hexadecimal.
515 6e18e03e 2004-04-11 devnull Dot is unaffected.
518 6e18e03e 2004-04-11 devnull Print the function name, source file, and line number
519 6e18e03e 2004-04-11 devnull corresponding to dot (textfile only). Dot is unaffected.
522 6e18e03e 2004-04-11 devnull Print the addressed value in symbolic form.
523 6e18e03e 2004-04-11 devnull Dot is advanced by the size of a machine address.
526 6e18e03e 2004-04-11 devnull When preceded by an integer, tabs to the next
527 6e18e03e 2004-04-11 devnull appropriate tab stop.
528 6e18e03e 2004-04-11 devnull For example,
530 6e18e03e 2004-04-11 devnull moves to the next 8-space tab stop.
531 6e18e03e 2004-04-11 devnull Dot is unaffected.
534 6e18e03e 2004-04-11 devnull Print a newline.
535 6e18e03e 2004-04-11 devnull Dot is unaffected.
538 6e18e03e 2004-04-11 devnull .BR ' ... '
539 6e18e03e 2004-04-11 devnull Print the enclosed string.
540 6e18e03e 2004-04-11 devnull Dot is unaffected.
545 6e18e03e 2004-04-11 devnull Dot is decremented by the current increment.
546 6e18e03e 2004-04-11 devnull Nothing is printed.
549 6e18e03e 2004-04-11 devnull Dot is incremented by 1.
550 6e18e03e 2004-04-11 devnull Nothing is printed.
553 6e18e03e 2004-04-11 devnull Dot is decremented by 1.
554 6e18e03e 2004-04-11 devnull Nothing is printed.
558 6e18e03e 2004-04-11 devnull Other commands include:
561 6e18e03e 2004-04-11 devnull Update dot by the current increment.
562 6e18e03e 2004-04-11 devnull Repeat the previous command with a
563 6e18e03e 2004-04-11 devnull .I count
566 6e18e03e 2004-04-11 devnull .RB [ ?/ ] l "\fI value mask\fR"
567 6e18e03e 2004-04-11 devnull Words starting at dot
568 6e18e03e 2004-04-11 devnull are masked with
570 6e18e03e 2004-04-11 devnull and compared with
571 6e18e03e 2004-04-11 devnull .I value
573 6e18e03e 2004-04-11 devnull a match is found.
576 6e18e03e 2004-04-11 devnull is used,
577 6e18e03e 2004-04-11 devnull the match is for a two-byte integer;
579 6e18e03e 2004-04-11 devnull matches four bytes.
580 6e18e03e 2004-04-11 devnull If no match is found then dot
581 6e18e03e 2004-04-11 devnull is unchanged; otherwise dot
582 6e18e03e 2004-04-11 devnull is set to the matched location.
585 6e18e03e 2004-04-11 devnull is omitted then ~0 is used.
587 6e18e03e 2004-04-11 devnull .RB [ ?/ ] w "\fI value ...\fR"
588 6e18e03e 2004-04-11 devnull Write the two-byte
589 6e18e03e 2004-04-11 devnull .I value
590 6e18e03e 2004-04-11 devnull into the addressed
591 6e18e03e 2004-04-11 devnull location.
592 6e18e03e 2004-04-11 devnull If the command is
594 6e18e03e 2004-04-11 devnull write four bytes.
596 6e18e03e 2004-04-11 devnull .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
598 6e18e03e 2004-04-11 devnull New values for
599 6e18e03e 2004-04-11 devnull .RI ( b,\ e,\ f )
600 6e18e03e 2004-04-11 devnull in the segment named
602 6e18e03e 2004-04-11 devnull are recorded. Valid segment names are
603 6e18e03e 2004-04-11 devnull .IR text ,
604 6e18e03e 2004-04-11 devnull .IR data ,
606 6e18e03e 2004-04-11 devnull .IR ublock .
607 6e18e03e 2004-04-11 devnull If less than three address expressions are given,
608 6e18e03e 2004-04-11 devnull the remaining parameters are left unchanged.
609 6e18e03e 2004-04-11 devnull If the list is terminated by
613 6e18e03e 2004-04-11 devnull then the file
614 6e18e03e 2004-04-11 devnull .RI ( textfile
616 6e18e03e 2004-04-11 devnull .I memfile
617 6e18e03e 2004-04-11 devnull respectively) is used
618 6e18e03e 2004-04-11 devnull for subsequent requests.
619 6e18e03e 2004-04-11 devnull For example,
623 6e18e03e 2004-04-11 devnull to refer to
624 6e18e03e 2004-04-11 devnull .IR textfile .
626 6e18e03e 2004-04-11 devnull .BI > name
627 6e18e03e 2004-04-11 devnull Dot is assigned to the variable or register named.
630 6e18e03e 2004-04-11 devnull The rest of the line is passed to
632 6e18e03e 2004-04-11 devnull for execution.
634 6e18e03e 2004-04-11 devnull .BI $ modifier
635 6e18e03e 2004-04-11 devnull Miscellaneous commands.
636 6e18e03e 2004-04-11 devnull The available
637 6e18e03e 2004-04-11 devnull .I modifiers
643 6e18e03e 2004-04-11 devnull Read commands from the file
645 6e18e03e 2004-04-11 devnull If this command is executed in a file, further commands
646 6e18e03e 2004-04-11 devnull in the file are not seen.
649 6e18e03e 2004-04-11 devnull is omitted, the current input stream is terminated.
651 6e18e03e 2004-04-11 devnull .I count
652 6e18e03e 2004-04-11 devnull is given, and is zero, the command is ignored.
654 6e18e03e 2004-04-11 devnull .BI << f
655 6e18e03e 2004-04-11 devnull Similar to
657 6e18e03e 2004-04-11 devnull except it can be used in a file of commands without
658 6e18e03e 2004-04-11 devnull causing the file to be closed.
659 6e18e03e 2004-04-11 devnull There is a (small) limit to the number of
661 6e18e03e 2004-04-11 devnull files that can be open at once.
666 6e18e03e 2004-04-11 devnull Append output to the file
668 6e18e03e 2004-04-11 devnull which is created if it does not exist.
671 6e18e03e 2004-04-11 devnull is omitted, output is returned to the terminal.
674 6e18e03e 2004-04-11 devnull Print process id, the condition which caused stopping or termination,
675 6e18e03e 2004-04-11 devnull the registers and the instruction addressed by
676 6e18e03e 2004-04-11 devnull .BR pc .
677 6e18e03e 2004-04-11 devnull This is the default if
678 6e18e03e 2004-04-11 devnull .I modifier
679 6e18e03e 2004-04-11 devnull is omitted.
682 6e18e03e 2004-04-11 devnull Print the general registers and
683 6e18e03e 2004-04-11 devnull the instruction addressed by
684 6e18e03e 2004-04-11 devnull .BR pc .
685 6e18e03e 2004-04-11 devnull Dot is set to
686 6e18e03e 2004-04-11 devnull .BR pc .
690 6e18e03e 2004-04-11 devnull .BR $r ,
691 6e18e03e 2004-04-11 devnull but include miscellaneous processor control registers
692 6e18e03e 2004-04-11 devnull and floating point registers.
695 6e18e03e 2004-04-11 devnull Print floating-point register values as
696 6e18e03e 2004-04-11 devnull single-precision floating point numbers.
699 6e18e03e 2004-04-11 devnull Print floating-point register values as
700 6e18e03e 2004-04-11 devnull double-precision floating point numbers.
703 6e18e03e 2004-04-11 devnull Print all breakpoints
704 6e18e03e 2004-04-11 devnull and their associated counts and commands. `B' produces the same results.
707 6e18e03e 2004-04-11 devnull Stack backtrace.
709 6e18e03e 2004-04-11 devnull .I address
710 6e18e03e 2004-04-11 devnull is given, it specifies the address of a pair of 32-bit
711 6e18e03e 2004-04-11 devnull values containing the
715 6e18e03e 2004-04-11 devnull of an active process. This allows selecting
716 6e18e03e 2004-04-11 devnull among various contexts of a multi-threaded
717 6e18e03e 2004-04-11 devnull process.
720 6e18e03e 2004-04-11 devnull is used, the names and (long) values of all
721 6e18e03e 2004-04-11 devnull parameters,
722 6e18e03e 2004-04-11 devnull automatic
723 6e18e03e 2004-04-11 devnull and static variables are printed for each active function.
725 6e18e03e 2004-04-11 devnull .I count
726 6e18e03e 2004-04-11 devnull is given, only the first
727 6e18e03e 2004-04-11 devnull .I count
728 6e18e03e 2004-04-11 devnull frames are printed.
731 6e18e03e 2004-04-11 devnull Attach to the running process whose pid
732 6e18e03e 2004-04-11 devnull is contained in
733 6e18e03e 2004-04-11 devnull .IR address .
736 6e18e03e 2004-04-11 devnull The names and values of all
737 6e18e03e 2004-04-11 devnull external variables are printed.
740 6e18e03e 2004-04-11 devnull Set the page width for output to
741 6e18e03e 2004-04-11 devnull .I address
742 6e18e03e 2004-04-11 devnull (default 80).
745 6e18e03e 2004-04-11 devnull Exit from
746 6e18e03e 2004-04-11 devnull .IR db .
749 6e18e03e 2004-04-11 devnull Print the address maps.
752 6e18e03e 2004-04-11 devnull Simulate kernel memory management.
754 6e18e03e 2004-04-11 devnull .BI M machine
756 6e18e03e 2004-04-11 devnull .I machine
757 6e18e03e 2004-04-11 devnull type used for disassembling instructions.
761 6e18e03e 2004-04-11 devnull .BI : modifier
762 6e18e03e 2004-04-11 devnull Manage a subprocess.
763 6e18e03e 2004-04-11 devnull Available modifiers are:
769 6e18e03e 2004-04-11 devnull an asynchronously running process to allow breakpointing.
770 6e18e03e 2004-04-11 devnull Unnecessary for processes created under
771 6e18e03e 2004-04-11 devnull .IR db ,
773 6e18e03e 2004-04-11 devnull .BR :r .
776 6e18e03e 2004-04-11 devnull Set breakpoint at
777 6e18e03e 2004-04-11 devnull .IR address .
778 6e18e03e 2004-04-11 devnull The breakpoint is executed
779 6e18e03e 2004-04-11 devnull .IR count \-1
780 6e18e03e 2004-04-11 devnull times before
781 6e18e03e 2004-04-11 devnull causing a stop.
782 6e18e03e 2004-04-11 devnull Also, if a command
784 6e18e03e 2004-04-11 devnull is given it is executed at each
785 6e18e03e 2004-04-11 devnull breakpoint and if it sets dot to zero
786 6e18e03e 2004-04-11 devnull the breakpoint causes a stop.
789 6e18e03e 2004-04-11 devnull Delete breakpoint at
790 6e18e03e 2004-04-11 devnull .IR address .
794 6e18e03e 2004-04-11 devnull .I textfile
795 6e18e03e 2004-04-11 devnull as a subprocess.
797 6e18e03e 2004-04-11 devnull .I address
798 6e18e03e 2004-04-11 devnull is given the
799 6e18e03e 2004-04-11 devnull program is entered at that point; otherwise
800 6e18e03e 2004-04-11 devnull the standard entry point is used.
801 6e18e03e 2004-04-11 devnull .I Count
802 6e18e03e 2004-04-11 devnull specifies how many breakpoints are to be
803 6e18e03e 2004-04-11 devnull ignored before stopping.
804 6e18e03e 2004-04-11 devnull Arguments to the subprocess may be supplied on the
805 6e18e03e 2004-04-11 devnull same line as the command.
806 6e18e03e 2004-04-11 devnull An argument starting with < or > causes the standard
807 6e18e03e 2004-04-11 devnull input or output to be established for the command.
810 6e18e03e 2004-04-11 devnull The subprocess is continued.
813 6e18e03e 2004-04-11 devnull is omitted
814 6e18e03e 2004-04-11 devnull or nonzero,
815 6e18e03e 2004-04-11 devnull the subprocess
816 6e18e03e 2004-04-11 devnull is sent the note that caused it to stop.
818 6e18e03e 2004-04-11 devnull is specified,
819 6e18e03e 2004-04-11 devnull no note is sent.
820 6e18e03e 2004-04-11 devnull (If the stop was due to a breakpoint or single-step,
821 6e18e03e 2004-04-11 devnull the corresponding note is elided before continuing.)
822 6e18e03e 2004-04-11 devnull Breakpoint skipping is the same
829 6e18e03e 2004-04-11 devnull except that
830 6e18e03e 2004-04-11 devnull the subprocess is single stepped for
831 6e18e03e 2004-04-11 devnull .I count
832 6e18e03e 2004-04-11 devnull machine instructions.
833 6e18e03e 2004-04-11 devnull If a note is pending,
834 6e18e03e 2004-04-11 devnull it is received
835 6e18e03e 2004-04-11 devnull before the first instruction is executed.
836 6e18e03e 2004-04-11 devnull If there is no current subprocess then
837 6e18e03e 2004-04-11 devnull .I textfile
839 6e18e03e 2004-04-11 devnull as a subprocess as for
841 6e18e03e 2004-04-11 devnull In this case no note can be sent; the remainder of the line
842 6e18e03e 2004-04-11 devnull is treated as arguments to the subprocess.
845 6e18e03e 2004-04-11 devnull Identical to
847 6e18e03e 2004-04-11 devnull except the subprocess is single stepped for
848 6e18e03e 2004-04-11 devnull .I count
849 6e18e03e 2004-04-11 devnull lines of C source. In optimized code, the correspondence
850 6e18e03e 2004-04-11 devnull between C source and the machine instructions is
851 6e18e03e 2004-04-11 devnull approximate at best.
854 6e18e03e 2004-04-11 devnull The current subprocess, if any, is released by
856 6e18e03e 2004-04-11 devnull and allowed to continue executing normally.
859 6e18e03e 2004-04-11 devnull The current subprocess, if any, is terminated.
862 6e18e03e 2004-04-11 devnull Display the pending notes for the process.
865 6e18e03e 2004-04-11 devnull is specified, first delete
867 6e18e03e 2004-04-11 devnull pending note.
870 6e18e03e 2004-04-11 devnull .SS Addresses
871 6e18e03e 2004-04-11 devnull The location in a file or memory image associated with
872 6e18e03e 2004-04-11 devnull an address is calculated from a map
873 6e18e03e 2004-04-11 devnull associated with the file.
874 6e18e03e 2004-04-11 devnull Each map contains one or more quadruples
875 6e18e03e 2004-04-11 devnull .RI ( "t, f, b, e, o" ),
876 6e18e03e 2004-04-11 devnull defining a segment named
878 6e18e03e 2004-04-11 devnull (usually,
879 6e18e03e 2004-04-11 devnull .IR text ,
880 6e18e03e 2004-04-11 devnull .IR data ,
882 6e18e03e 2004-04-11 devnull .IR core )
885 6e18e03e 2004-04-11 devnull mapping addresses in the range
889 6e18e03e 2004-04-11 devnull to the part of the file
890 6e18e03e 2004-04-11 devnull beginning at
893 6e18e03e 2004-04-11 devnull If segments overlap, later segments obscure earlier ones.
894 6e18e03e 2004-04-11 devnull An address
896 6e18e03e 2004-04-11 devnull is translated
897 6e18e03e 2004-04-11 devnull to a file address
898 6e18e03e 2004-04-11 devnull by finding the last segment in the list
899 6e18e03e 2004-04-11 devnull for which
900 6e18e03e 2004-04-11 devnull .IR b ≤ a < e ;
901 6e18e03e 2004-04-11 devnull the location in the file
903 6e18e03e 2004-04-11 devnull .IR address + f \- b .
905 6e18e03e 2004-04-11 devnull Usually,
906 6e18e03e 2004-04-11 devnull the text and initialized data of a program
907 6e18e03e 2004-04-11 devnull are mapped by segments called
908 6e18e03e 2004-04-11 devnull .IR text ,
909 6e18e03e 2004-04-11 devnull .IR data ,
911 6e18e03e 2004-04-11 devnull .IR bss .
912 6e18e03e 2004-04-11 devnull Since a program file does not contain stack data,
913 6e18e03e 2004-04-11 devnull this data is
914 6e18e03e 2004-04-11 devnull not mapped.
915 6e18e03e 2004-04-11 devnull The text segment is mapped similarly in
916 6e18e03e 2004-04-11 devnull a normal (i.e., non-kernel)
917 6e18e03e 2004-04-11 devnull .IR memfile .
918 6e18e03e 2004-04-11 devnull However, one or more segments called
920 6e18e03e 2004-04-11 devnull provide access to process memory.
921 6e18e03e 2004-04-11 devnull This region contains the program's static data, the bss, the
922 6e18e03e 2004-04-11 devnull heap and the stack.
924 6e18e03e 2004-04-11 devnull Sometimes it is useful to define a map with a single segment
925 6e18e03e 2004-04-11 devnull mapping the region from 0 to 0xFFFFFFFF; a map of this type
926 6e18e03e 2004-04-11 devnull allows an entire file to be examined
927 6e18e03e 2004-04-11 devnull without address translation.
931 6e18e03e 2004-04-11 devnull command dumps the currently active maps. The
935 6e18e03e 2004-04-11 devnull commands modify the segment parameters in the
936 6e18e03e 2004-04-11 devnull .I textfile
938 6e18e03e 2004-04-11 devnull .I memfile
939 6e18e03e 2004-04-11 devnull maps, respectively.
940 6e18e03e 2004-04-11 devnull .SH EXAMPLES
941 6e18e03e 2004-04-11 devnull To set a breakpoint at the beginning of
942 6e18e03e 2004-04-11 devnull .B write()
943 6e18e03e 2004-04-11 devnull in extant process 27:
952 6e18e03e 2004-04-11 devnull To set a breakpoint at the entry of function
953 6e18e03e 2004-04-11 devnull .B parse
954 6e18e03e 2004-04-11 devnull when the local variable
958 6e18e03e 2004-04-11 devnull is equal to 1:
961 6e18e03e 2004-04-11 devnull parse:b *main.argc-1=X
964 6e18e03e 2004-04-11 devnull This prints the value of
965 6e18e03e 2004-04-11 devnull .B argc-1
966 6e18e03e 2004-04-11 devnull which as a side effect sets dot; when
968 6e18e03e 2004-04-11 devnull is one the breakpoint will fire.
969 6e18e03e 2004-04-11 devnull Beware that local variables may be stored in registers; see the
970 6e18e03e 2004-04-11 devnull BUGS section.
971 6e18e03e 2004-04-11 devnull .SH "SEE ALSO"
972 d32deab1 2020-08-16 rsc .MR acid (1) ,
973 d32deab1 2020-08-16 rsc .MR core (1)
974 6e18e03e 2004-04-11 devnull .SH SOURCE
975 c3674de4 2005-01-11 devnull .B \*9/src/cmd/db
976 6e18e03e 2004-04-11 devnull .SH DIAGNOSTICS
977 6e18e03e 2004-04-11 devnull Exit status is 0, unless the last command failed or
978 6e18e03e 2004-04-11 devnull returned non-zero status.
979 6e18e03e 2004-04-11 devnull .SH BUGS
980 6e18e03e 2004-04-11 devnull Examining a local variable with
981 6e18e03e 2004-04-11 devnull .I routine.name
982 6e18e03e 2004-04-11 devnull returns the contents of the memory allocated for the variable, but
983 6e18e03e 2004-04-11 devnull with optimization, variables often reside in registers.
984 6e18e03e 2004-04-11 devnull Also, on some architectures, the first argument is always
985 6e18e03e 2004-04-11 devnull passed in a register.
987 6e18e03e 2004-04-11 devnull Variables and parameters that have been
988 6e18e03e 2004-04-11 devnull optimized away do not appear in the
989 6e18e03e 2004-04-11 devnull symbol table, returning the error
990 6e18e03e 2004-04-11 devnull .IR "bad local variable"
991 6e18e03e 2004-04-11 devnull when accessed by
992 6e18e03e 2004-04-11 devnull .IR db .
994 6e18e03e 2004-04-11 devnull Breakpoints should not be set on instructions scheduled
995 6e18e03e 2004-04-11 devnull in delay slots. When a program stops on such a breakpoint,
996 6e18e03e 2004-04-11 devnull it is usually impossible to continue its execution.
