1 6e18e03e 2004-04-11 devnull .TH DB 1
  2 6e18e03e 2004-04-11 devnull .SH NAME
  3 16d2fe7d 2005-01-31 devnull db, stack \- debugger
  4 6e18e03e 2004-04-11 devnull .SH SYNOPSIS
  5 6e18e03e 2004-04-11 devnull .B db
  6 6e18e03e 2004-04-11 devnull [
  7 6e18e03e 2004-04-11 devnull .I option ...
  8 6e18e03e 2004-04-11 devnull ]
  9 3264d2e2 2005-01-23 devnull [
 10 3264d2e2 2005-01-23 devnull .I textfile
 11 3264d2e2 2005-01-23 devnull ]
 12 3264d2e2 2005-01-23 devnull [
 13 3264d2e2 2005-01-23 devnull .I pid
 14 3264d2e2 2005-01-23 devnull |
 15 3264d2e2 2005-01-23 devnull .I corefile
 16 3264d2e2 2005-01-23 devnull ]
 17 3264d2e2 2005-01-23 devnull .PP
 18 3264d2e2 2005-01-23 devnull .B stack
 19 6e18e03e 2004-04-11 devnull [
 20 6e18e03e 2004-04-11 devnull .I textfile
 21 6e18e03e 2004-04-11 devnull ]
 22 6e18e03e 2004-04-11 devnull [
 23 6e18e03e 2004-04-11 devnull .I pid
 24 6e18e03e 2004-04-11 devnull |
 25 6e18e03e 2004-04-11 devnull .I corefile
 26 6e18e03e 2004-04-11 devnull ]
 27 6e18e03e 2004-04-11 devnull .SH DESCRIPTION
 28 6e18e03e 2004-04-11 devnull .I Db
 29 6e18e03e 2004-04-11 devnull is a general purpose debugging program.
 30 6e18e03e 2004-04-11 devnull It may be used to examine files and to provide
 31 6e18e03e 2004-04-11 devnull a controlled environment for the execution
 32 6e18e03e 2004-04-11 devnull of programs.
 33 6e18e03e 2004-04-11 devnull .PP
 34 6e18e03e 2004-04-11 devnull A
 35 6e18e03e 2004-04-11 devnull .I textfile
 36 6e18e03e 2004-04-11 devnull is a file containing the text and initialized
 37 6e18e03e 2004-04-11 devnull data of an executable program.
 38 6e18e03e 2004-04-11 devnull A
 39 6e18e03e 2004-04-11 devnull .I pid
 40 6e18e03e 2004-04-11 devnull or
 41 6e18e03e 2004-04-11 devnull .I corefile
 42 6e18e03e 2004-04-11 devnull specifies the memory image of a process.
 43 6e18e03e 2004-04-11 devnull A 
 44 6e18e03e 2004-04-11 devnull .I pid
 45 6e18e03e 2004-04-11 devnull gives the id of an executing process to be accessed via
 46 058b0118 2005-01-03 devnull .IR ptrace (2).
 47 6e18e03e 2004-04-11 devnull A
 48 6e18e03e 2004-04-11 devnull .I corefile
 49 6e18e03e 2004-04-11 devnull specifies the name of a core dump (see
 50 6e18e03e 2004-04-11 devnull .IR core (5)
 51 6e18e03e 2004-04-11 devnull on your system of choice) containing the
 52 6e18e03e 2004-04-11 devnull memory image of a terminated process.
 53 6e18e03e 2004-04-11 devnull This manual refers to the memory image specified by
 54 6e18e03e 2004-04-11 devnull .I pid
 55 6e18e03e 2004-04-11 devnull or
 56 6e18e03e 2004-04-11 devnull .I corefile
 57 6e18e03e 2004-04-11 devnull as a
 58 6e18e03e 2004-04-11 devnull .IR memfile .
 59 6e18e03e 2004-04-11 devnull .PP
 60 6e18e03e 2004-04-11 devnull A
 61 6e18e03e 2004-04-11 devnull .I map
 62 6e18e03e 2004-04-11 devnull associated with each
 63 6e18e03e 2004-04-11 devnull .I textfile
 64 6e18e03e 2004-04-11 devnull or
 65 6e18e03e 2004-04-11 devnull .I memfile
 66 6e18e03e 2004-04-11 devnull supports accesses to instructions and data in the file;
 67 6e18e03e 2004-04-11 devnull see `Addresses'.
 68 6e18e03e 2004-04-11 devnull .PP
 69 6e18e03e 2004-04-11 devnull An argument consisting entirely of digits is assumed
 70 6e18e03e 2004-04-11 devnull to be a process id; otherwise, it is the name of a
 71 6e18e03e 2004-04-11 devnull .I textfile
 72 6e18e03e 2004-04-11 devnull or
 73 6e18e03e 2004-04-11 devnull .IR corefile .
 74 6e18e03e 2004-04-11 devnull When a
 75 6e18e03e 2004-04-11 devnull .I textfile
 76 6e18e03e 2004-04-11 devnull is given, the textfile map
 77 6e18e03e 2004-04-11 devnull is associated with it.
 78 6e18e03e 2004-04-11 devnull If only a
 79 6e18e03e 2004-04-11 devnull .I memfile
 80 6e18e03e 2004-04-11 devnull is given, the textfile map is
 81 6e18e03e 2004-04-11 devnull derived from the corresponding
 82 6e18e03e 2004-04-11 devnull .IR textfile ,
 83 6e18e03e 2004-04-11 devnull if it can be determined
 84 6e18e03e 2004-04-11 devnull (this varies from system to system).
 85 6e18e03e 2004-04-11 devnull When a
 86 6e18e03e 2004-04-11 devnull .I memfile
 87 6e18e03e 2004-04-11 devnull is given, the memfile map is associated with it;
 88 6e18e03e 2004-04-11 devnull otherwise the map is undefined and accesses to it
 89 6e18e03e 2004-04-11 devnull are not permitted.
 90 3264d2e2 2005-01-23 devnull .PP
 91 3264d2e2 2005-01-23 devnull .I Stack
 92 3264d2e2 2005-01-23 devnull takes the same arguments as
 93 3264d2e2 2005-01-23 devnull .IR db .
 94 3264d2e2 2005-01-23 devnull It prints a stack trace (see the
 95 3264d2e2 2005-01-23 devnull .B $c
 96 3264d2e2 2005-01-23 devnull command below) and then exits.
 97 6e18e03e 2004-04-11 devnull .PP
 98 6e18e03e 2004-04-11 devnull Commands to
 99 6e18e03e 2004-04-11 devnull .I db
100 6e18e03e 2004-04-11 devnull are read from the standard input and
101 6e18e03e 2004-04-11 devnull responses are to the standard output.
102 6e18e03e 2004-04-11 devnull The options are
103 8b0e19f7 2005-01-23 devnull .TP
104 8b0e19f7 2005-01-23 devnull .B -q
105 8b0e19f7 2005-01-23 devnull Quiet mode: 
106 8b0e19f7 2005-01-23 devnull suppress informational prints at startup.
107 6e18e03e 2004-04-11 devnull .TP
108 6e18e03e 2004-04-11 devnull .B -w
109 6e18e03e 2004-04-11 devnull Open
110 6e18e03e 2004-04-11 devnull .I textfile
111 6e18e03e 2004-04-11 devnull and
112 6e18e03e 2004-04-11 devnull .I memfile
113 6e18e03e 2004-04-11 devnull for writing as well as reading.
114 6e18e03e 2004-04-11 devnull .TP
115 6e18e03e 2004-04-11 devnull .BI -I path
116 6e18e03e 2004-04-11 devnull Directory in which to look for relative path names in
117 6e18e03e 2004-04-11 devnull .B $<
118 6e18e03e 2004-04-11 devnull and
119 6e18e03e 2004-04-11 devnull .B $<<
120 6e18e03e 2004-04-11 devnull commands.
121 6e18e03e 2004-04-11 devnull .TP
122 6e18e03e 2004-04-11 devnull .BI -m machine
123 6e18e03e 2004-04-11 devnull Assume instructions are for the given CPU type
124 6e18e03e 2004-04-11 devnull (possible names include
125 6e18e03e 2004-04-11 devnull .B 386
126 6e18e03e 2004-04-11 devnull and
127 6e18e03e 2004-04-11 devnull .BR powerpc ;
128 6e18e03e 2004-04-11 devnull adding
129 6e18e03e 2004-04-11 devnull the suffix
130 6e18e03e 2004-04-11 devnull .B -co
131 6e18e03e 2004-04-11 devnull as in
132 6e18e03e 2004-04-11 devnull .B 386-co
133 6e18e03e 2004-04-11 devnull and
134 6e18e03e 2004-04-11 devnull .B powerpc-co
135 6e18e03e 2004-04-11 devnull selects disassembly in the manufacturer's syntax, if
136 6e18e03e 2004-04-11 devnull available,
137 6e18e03e 2004-04-11 devnull rather than the default Plan 9 syntax).
138 6e18e03e 2004-04-11 devnull .PP
139 6e18e03e 2004-04-11 devnull Most
140 6e18e03e 2004-04-11 devnull .I db
141 6e18e03e 2004-04-11 devnull commands have the following form:
142 6e18e03e 2004-04-11 devnull .IP
143 6e18e03e 2004-04-11 devnull .RI [ address ]
144 6e18e03e 2004-04-11 devnull .RB [ ,
145 6e18e03e 2004-04-11 devnull .IR count ]
146 6e18e03e 2004-04-11 devnull .RI [ command ]
147 6e18e03e 2004-04-11 devnull .PP
148 6e18e03e 2004-04-11 devnull If
149 6e18e03e 2004-04-11 devnull .I address
150 6e18e03e 2004-04-11 devnull is present then the current position, called `dot',
151 6e18e03e 2004-04-11 devnull is set to
152 6e18e03e 2004-04-11 devnull .IR address .
153 6e18e03e 2004-04-11 devnull Initially dot
154 6e18e03e 2004-04-11 devnull is set to 0.
155 6e18e03e 2004-04-11 devnull Most commands are repeated
156 6e18e03e 2004-04-11 devnull .I count
157 6e18e03e 2004-04-11 devnull times with
158 6e18e03e 2004-04-11 devnull dot advancing between repetitions.
159 6e18e03e 2004-04-11 devnull The default
160 6e18e03e 2004-04-11 devnull .I count
161 6e18e03e 2004-04-11 devnull is 1.
162 6e18e03e 2004-04-11 devnull .I Address
163 6e18e03e 2004-04-11 devnull and
164 6e18e03e 2004-04-11 devnull .I count
165 6e18e03e 2004-04-11 devnull are expressions.
166 6e18e03e 2004-04-11 devnull Multiple commands on one line must be separated by
167 6e18e03e 2004-04-11 devnull .LR ; .
168 6e18e03e 2004-04-11 devnull .SS Expressions
169 6e18e03e 2004-04-11 devnull Expressions are evaluated as long
170 6e18e03e 2004-04-11 devnull .IR ints .
171 6e18e03e 2004-04-11 devnull .TP 7.2n
172 6e18e03e 2004-04-11 devnull .B .
173 6e18e03e 2004-04-11 devnull The value of dot.
174 6e18e03e 2004-04-11 devnull .TP 7.2n
175 6e18e03e 2004-04-11 devnull .B +
176 6e18e03e 2004-04-11 devnull The value of dot
177 6e18e03e 2004-04-11 devnull incremented by the current increment.
178 6e18e03e 2004-04-11 devnull .TP 7.2n
179 6e18e03e 2004-04-11 devnull .B ^
180 6e18e03e 2004-04-11 devnull The value of dot
181 6e18e03e 2004-04-11 devnull decremented by the current increment.
182 6e18e03e 2004-04-11 devnull .TP 7.2n
183 6e18e03e 2004-04-11 devnull .B \&"
184 6e18e03e 2004-04-11 devnull The last
185 6e18e03e 2004-04-11 devnull .I address
186 6e18e03e 2004-04-11 devnull typed.
187 6e18e03e 2004-04-11 devnull .TP 7.2n
188 6e18e03e 2004-04-11 devnull .I integer
189 6e18e03e 2004-04-11 devnull A number, in decimal radix by default.
190 6e18e03e 2004-04-11 devnull The prefixes
191 6e18e03e 2004-04-11 devnull .L 0
192 6e18e03e 2004-04-11 devnull and
193 6e18e03e 2004-04-11 devnull .L 0o
194 6e18e03e 2004-04-11 devnull and
195 6e18e03e 2004-04-11 devnull .L 0O
196 6e18e03e 2004-04-11 devnull (zero oh) force interpretation
197 6e18e03e 2004-04-11 devnull in octal radix; the prefixes
198 6e18e03e 2004-04-11 devnull .L 0t
199 6e18e03e 2004-04-11 devnull and
200 6e18e03e 2004-04-11 devnull .L 0T
201 6e18e03e 2004-04-11 devnull force interpretation in
202 6e18e03e 2004-04-11 devnull decimal radix; the prefixes
203 6e18e03e 2004-04-11 devnull .LR 0x ,
204 6e18e03e 2004-04-11 devnull .LR 0X ,
205 6e18e03e 2004-04-11 devnull and
206 6e18e03e 2004-04-11 devnull .L #
207 6e18e03e 2004-04-11 devnull force interpretation in
208 6e18e03e 2004-04-11 devnull hexadecimal radix.
209 6e18e03e 2004-04-11 devnull Thus
210 6e18e03e 2004-04-11 devnull .LR 020 ,
211 6e18e03e 2004-04-11 devnull .LR 0o20 ,
212 6e18e03e 2004-04-11 devnull .LR 0t16 ,
213 6e18e03e 2004-04-11 devnull and
214 6e18e03e 2004-04-11 devnull .L #10 
215 6e18e03e 2004-04-11 devnull all represent sixteen.
216 6e18e03e 2004-04-11 devnull .TP 7.2n
217 6e18e03e 2004-04-11 devnull .IB integer . fraction
218 6e18e03e 2004-04-11 devnull A single-precision floating point number.
219 6e18e03e 2004-04-11 devnull .TP 7.2n
220 6e18e03e 2004-04-11 devnull .BI \' c\| \'
221 6e18e03e 2004-04-11 devnull The
222 6e18e03e 2004-04-11 devnull 16-bit
223 6e18e03e 2004-04-11 devnull value of a character.
224 6e18e03e 2004-04-11 devnull .L \e
225 6e18e03e 2004-04-11 devnull may be used to escape a
226 6e18e03e 2004-04-11 devnull .LR \' .
227 6e18e03e 2004-04-11 devnull .TP 7.2n
228 6e18e03e 2004-04-11 devnull .BI < name
229 6e18e03e 2004-04-11 devnull The value of
230 6e18e03e 2004-04-11 devnull .IR name ,
231 6e18e03e 2004-04-11 devnull which is a register name.
232 6e18e03e 2004-04-11 devnull The register names are
233 6e18e03e 2004-04-11 devnull those printed by the
234 6e18e03e 2004-04-11 devnull .B $r
235 6e18e03e 2004-04-11 devnull command.
236 6e18e03e 2004-04-11 devnull .TP 7.2n
237 6e18e03e 2004-04-11 devnull .I symbol
238 6e18e03e 2004-04-11 devnull A
239 6e18e03e 2004-04-11 devnull .I symbol
240 6e18e03e 2004-04-11 devnull is a sequence
241 6e18e03e 2004-04-11 devnull of upper or lower case letters, underscores or
242 6e18e03e 2004-04-11 devnull digits, not starting with a digit.
243 6e18e03e 2004-04-11 devnull .L \e
244 6e18e03e 2004-04-11 devnull may be used to escape other characters.
245 6e18e03e 2004-04-11 devnull The location of the
246 6e18e03e 2004-04-11 devnull .I symbol
247 6e18e03e 2004-04-11 devnull is calculated from the symbol table
248 6e18e03e 2004-04-11 devnull in
249 6e18e03e 2004-04-11 devnull .IR textfile .
250 6e18e03e 2004-04-11 devnull .TP 7.2n
251 6e18e03e 2004-04-11 devnull .IB routine . name
252 6e18e03e 2004-04-11 devnull The address of the variable
253 6e18e03e 2004-04-11 devnull .I name
254 6e18e03e 2004-04-11 devnull in the specified
255 6e18e03e 2004-04-11 devnull C routine.
256 6e18e03e 2004-04-11 devnull Both
257 6e18e03e 2004-04-11 devnull .I routine
258 6e18e03e 2004-04-11 devnull and
259 6e18e03e 2004-04-11 devnull .I name
260 6e18e03e 2004-04-11 devnull are
261 6e18e03e 2004-04-11 devnull .IR symbols .
262 6e18e03e 2004-04-11 devnull If
263 6e18e03e 2004-04-11 devnull .I name
264 6e18e03e 2004-04-11 devnull is omitted the value is the address of the
265 6e18e03e 2004-04-11 devnull most recently activated stack frame
266 6e18e03e 2004-04-11 devnull corresponding to
267 6e18e03e 2004-04-11 devnull .IR routine ;
268 6e18e03e 2004-04-11 devnull if
269 6e18e03e 2004-04-11 devnull .I routine
270 6e18e03e 2004-04-11 devnull is omitted,
271 6e18e03e 2004-04-11 devnull the active procedure
272 6e18e03e 2004-04-11 devnull is assumed.
273 6e18e03e 2004-04-11 devnull .TP 7.2n
274 6e18e03e 2004-04-11 devnull .IB file : integer
275 6e18e03e 2004-04-11 devnull The address of the instruction corresponding
276 6e18e03e 2004-04-11 devnull to the source statement at the indicated
277 6e18e03e 2004-04-11 devnull line number of the file.  If the source line contains
278 6e18e03e 2004-04-11 devnull no executable statement, the address of the
279 6e18e03e 2004-04-11 devnull instruction associated with the nearest
280 6e18e03e 2004-04-11 devnull executable source line is returned.  Files
281 6e18e03e 2004-04-11 devnull begin at line 1.  If multiple files of the same
282 6e18e03e 2004-04-11 devnull name are loaded, an expression of this form resolves
283 6e18e03e 2004-04-11 devnull to the first file encountered in the symbol table.
284 6e18e03e 2004-04-11 devnull .TP 7.2n
285 6e18e03e 2004-04-11 devnull .BI ( exp )
286 6e18e03e 2004-04-11 devnull The value of the expression
287 6e18e03e 2004-04-11 devnull .IR exp .
288 6e18e03e 2004-04-11 devnull .LP
289 6e18e03e 2004-04-11 devnull .I  Monadic operators
290 6e18e03e 2004-04-11 devnull .RS
291 6e18e03e 2004-04-11 devnull .TP 7.2n
292 6e18e03e 2004-04-11 devnull .BI * exp
293 6e18e03e 2004-04-11 devnull The contents of the location addressed
294 6e18e03e 2004-04-11 devnull by
295 6e18e03e 2004-04-11 devnull .I exp
296 6e18e03e 2004-04-11 devnull in
297 6e18e03e 2004-04-11 devnull .IR memfile .
298 6e18e03e 2004-04-11 devnull .TP 7.2n
299 6e18e03e 2004-04-11 devnull .BI @ exp
300 6e18e03e 2004-04-11 devnull The contents of the location addressed by
301 6e18e03e 2004-04-11 devnull .I exp
302 6e18e03e 2004-04-11 devnull in
303 6e18e03e 2004-04-11 devnull .IR textfile .
304 6e18e03e 2004-04-11 devnull .TP 7.2n
305 6e18e03e 2004-04-11 devnull .BI - exp
306 6e18e03e 2004-04-11 devnull Integer negation.
307 6e18e03e 2004-04-11 devnull .TP 7.2n
308 6e18e03e 2004-04-11 devnull .BI ~ exp
309 6e18e03e 2004-04-11 devnull Bitwise complement.
310 6e18e03e 2004-04-11 devnull .TP 7.2n
311 6e18e03e 2004-04-11 devnull .BI % exp
312 6e18e03e 2004-04-11 devnull When used as an
313 6e18e03e 2004-04-11 devnull .IR address ,
314 6e18e03e 2004-04-11 devnull .I exp
315 6e18e03e 2004-04-11 devnull is an offset into the segment named
316 6e18e03e 2004-04-11 devnull .IR ublock ;
317 6e18e03e 2004-04-11 devnull see `Addresses'.
318 6e18e03e 2004-04-11 devnull .RE
319 6e18e03e 2004-04-11 devnull .LP
320 6e18e03e 2004-04-11 devnull .I "Dyadic\ operators"
321 6e18e03e 2004-04-11 devnull are left-associative
322 6e18e03e 2004-04-11 devnull and are less binding than monadic operators.
323 6e18e03e 2004-04-11 devnull .RS
324 6e18e03e 2004-04-11 devnull .TP 7.2n
325 6e18e03e 2004-04-11 devnull .IB e1 + e2
326 6e18e03e 2004-04-11 devnull Integer addition.
327 6e18e03e 2004-04-11 devnull .TP 7.2n
328 6e18e03e 2004-04-11 devnull .IB e1 - e2
329 6e18e03e 2004-04-11 devnull Integer subtraction.
330 6e18e03e 2004-04-11 devnull .TP 7.2n
331 6e18e03e 2004-04-11 devnull .IB e1 * e2
332 6e18e03e 2004-04-11 devnull Integer multiplication.
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 division.
336 6e18e03e 2004-04-11 devnull .TP 7.2n
337 6e18e03e 2004-04-11 devnull .IB e1 & e2
338 6e18e03e 2004-04-11 devnull Bitwise conjunction.
339 6e18e03e 2004-04-11 devnull .TP 7.2n
340 6e18e03e 2004-04-11 devnull .IB e1 | e2
341 6e18e03e 2004-04-11 devnull Bitwise disjunction.
342 6e18e03e 2004-04-11 devnull .TP 7.2n
343 6e18e03e 2004-04-11 devnull .IB e1 # e2
344 6e18e03e 2004-04-11 devnull .I E1
345 6e18e03e 2004-04-11 devnull rounded up to the next multiple of
346 6e18e03e 2004-04-11 devnull .IR e2 .
347 6e18e03e 2004-04-11 devnull .RE
348 6e18e03e 2004-04-11 devnull .DT
349 6e18e03e 2004-04-11 devnull .SS Commands
350 6e18e03e 2004-04-11 devnull Most commands have the following syntax:
351 6e18e03e 2004-04-11 devnull .TP .5i
352 6e18e03e 2004-04-11 devnull .BI ? f
353 6e18e03e 2004-04-11 devnull Locations starting at
354 6e18e03e 2004-04-11 devnull .I address
355 6e18e03e 2004-04-11 devnull in
356 6e18e03e 2004-04-11 devnull .I  textfile
357 6e18e03e 2004-04-11 devnull are printed according to the format
358 6e18e03e 2004-04-11 devnull .IR f .
359 6e18e03e 2004-04-11 devnull .TP
360 6e18e03e 2004-04-11 devnull .BI / f
361 6e18e03e 2004-04-11 devnull Locations starting at
362 6e18e03e 2004-04-11 devnull .I address
363 6e18e03e 2004-04-11 devnull in
364 6e18e03e 2004-04-11 devnull .I  memfile
365 6e18e03e 2004-04-11 devnull are printed according to the format
366 6e18e03e 2004-04-11 devnull .IR f .
367 6e18e03e 2004-04-11 devnull .TP
368 6e18e03e 2004-04-11 devnull .BI = f
369 6e18e03e 2004-04-11 devnull The value of
370 6e18e03e 2004-04-11 devnull .I address
371 6e18e03e 2004-04-11 devnull itself is printed according to the format
372 6e18e03e 2004-04-11 devnull .IR f .
373 6e18e03e 2004-04-11 devnull .PP
374 6e18e03e 2004-04-11 devnull A
375 6e18e03e 2004-04-11 devnull .I format
376 6e18e03e 2004-04-11 devnull consists of one or more characters that specify a style
377 6e18e03e 2004-04-11 devnull of printing.
378 6e18e03e 2004-04-11 devnull Each format character may be preceded by a decimal integer
379 6e18e03e 2004-04-11 devnull that is a repeat count for the format character.
380 6e18e03e 2004-04-11 devnull If no format is given then the last format is used.
381 6e18e03e 2004-04-11 devnull .PP
382 6e18e03e 2004-04-11 devnull Most format letters fetch some data,
383 6e18e03e 2004-04-11 devnull print it,
384 6e18e03e 2004-04-11 devnull and advance (a local copy of) dot
385 6e18e03e 2004-04-11 devnull by the number of bytes fetched.
386 6e18e03e 2004-04-11 devnull The total number of bytes in a format becomes the
387 6e18e03e 2004-04-11 devnull .IR current increment .
388 6e18e03e 2004-04-11 devnull .ta 2.5n .5i
389 6e18e03e 2004-04-11 devnull .RS
390 6e18e03e 2004-04-11 devnull .TP
391 6e18e03e 2004-04-11 devnull .PD 0
392 6e18e03e 2004-04-11 devnull .B o
393 6e18e03e 2004-04-11 devnull Print two-byte integer in octal.
394 6e18e03e 2004-04-11 devnull .TP
395 6e18e03e 2004-04-11 devnull .B O
396 6e18e03e 2004-04-11 devnull Print four-byte integer in octal.
397 6e18e03e 2004-04-11 devnull .TP
398 6e18e03e 2004-04-11 devnull .B q
399 6e18e03e 2004-04-11 devnull Print two-byte integer in signed octal.
400 6e18e03e 2004-04-11 devnull .TP
401 6e18e03e 2004-04-11 devnull .B Q
402 6e18e03e 2004-04-11 devnull Print four-byte integer in signed octal.
403 6e18e03e 2004-04-11 devnull .TP
404 6e18e03e 2004-04-11 devnull .B d
405 6e18e03e 2004-04-11 devnull Print two-byte integer in decimal.
406 6e18e03e 2004-04-11 devnull .TP
407 6e18e03e 2004-04-11 devnull .B D
408 6e18e03e 2004-04-11 devnull Print four-byte integer in decimal.
409 6e18e03e 2004-04-11 devnull .TP
410 6e18e03e 2004-04-11 devnull .B V
411 6e18e03e 2004-04-11 devnull Print eight-byte integer in decimal.
412 6e18e03e 2004-04-11 devnull .TP
413 6e18e03e 2004-04-11 devnull .B Z
414 6e18e03e 2004-04-11 devnull Print eight-byte integer in unsigned decimal.
415 6e18e03e 2004-04-11 devnull .TP
416 6e18e03e 2004-04-11 devnull .B x
417 6e18e03e 2004-04-11 devnull Print two-byte integer in hexadecimal.
418 6e18e03e 2004-04-11 devnull .TP
419 6e18e03e 2004-04-11 devnull .B X
420 6e18e03e 2004-04-11 devnull Print four-byte integer in hexadecimal.
421 6e18e03e 2004-04-11 devnull .TP
422 6e18e03e 2004-04-11 devnull .B Y
423 6e18e03e 2004-04-11 devnull Print eight-byte integer in hexadecimal.
424 6e18e03e 2004-04-11 devnull .TP
425 6e18e03e 2004-04-11 devnull .B u
426 6e18e03e 2004-04-11 devnull Print two-byte integer in unsigned decimal.
427 6e18e03e 2004-04-11 devnull .TP
428 6e18e03e 2004-04-11 devnull .B U
429 6e18e03e 2004-04-11 devnull Print four-byte integer in unsigned decimal.
430 6e18e03e 2004-04-11 devnull .TP
431 6e18e03e 2004-04-11 devnull .B f
432 6e18e03e 2004-04-11 devnull Print
433 6e18e03e 2004-04-11 devnull as a single-precision floating point number.
434 6e18e03e 2004-04-11 devnull .TP
435 6e18e03e 2004-04-11 devnull .B F
436 6e18e03e 2004-04-11 devnull Print double-precision floating point.
437 6e18e03e 2004-04-11 devnull .TP
438 6e18e03e 2004-04-11 devnull .B b
439 6e18e03e 2004-04-11 devnull Print the addressed byte in hexadecimal.
440 6e18e03e 2004-04-11 devnull .TP
441 6e18e03e 2004-04-11 devnull .B c
442 6e18e03e 2004-04-11 devnull Print the addressed byte as an
443 6e18e03e 2004-04-11 devnull .SM ASCII
444 6e18e03e 2004-04-11 devnull character.
445 6e18e03e 2004-04-11 devnull .TP
446 6e18e03e 2004-04-11 devnull .B C
447 6e18e03e 2004-04-11 devnull Print the addressed byte as a character.
448 6e18e03e 2004-04-11 devnull Printable
449 6e18e03e 2004-04-11 devnull .SM ASCII
450 6e18e03e 2004-04-11 devnull characters
451 6e18e03e 2004-04-11 devnull are represented normally; others
452 6e18e03e 2004-04-11 devnull are printed in the form
453 6e18e03e 2004-04-11 devnull .BR \exnn .
454 6e18e03e 2004-04-11 devnull .TP
455 6e18e03e 2004-04-11 devnull .B s
456 6e18e03e 2004-04-11 devnull Print the addressed characters, as a
457 6e18e03e 2004-04-11 devnull .SM UTF
458 6e18e03e 2004-04-11 devnull string, until a zero byte
459 6e18e03e 2004-04-11 devnull is reached.
460 6e18e03e 2004-04-11 devnull Advance dot
461 6e18e03e 2004-04-11 devnull by the length of the string,
462 6e18e03e 2004-04-11 devnull including the zero terminator.
463 6e18e03e 2004-04-11 devnull .TP
464 6e18e03e 2004-04-11 devnull .B S
465 6e18e03e 2004-04-11 devnull Print a string using 
466 6e18e03e 2004-04-11 devnull the escape convention (see
467 6e18e03e 2004-04-11 devnull .B C
468 6e18e03e 2004-04-11 devnull above).
469 6e18e03e 2004-04-11 devnull .TP
470 6e18e03e 2004-04-11 devnull .B r
471 6e18e03e 2004-04-11 devnull Print as
472 6e18e03e 2004-04-11 devnull .SM UTF
473 6e18e03e 2004-04-11 devnull the addressed two-byte integer (rune).
474 6e18e03e 2004-04-11 devnull .TP
475 6e18e03e 2004-04-11 devnull .B R
476 6e18e03e 2004-04-11 devnull Print as
477 6e18e03e 2004-04-11 devnull .SM UTF
478 6e18e03e 2004-04-11 devnull the addressed two-byte integers as runes
479 6e18e03e 2004-04-11 devnull until a zero rune is reached.
480 6e18e03e 2004-04-11 devnull Advance dot
481 6e18e03e 2004-04-11 devnull by the length of the string,
482 6e18e03e 2004-04-11 devnull including the zero terminator.
483 6e18e03e 2004-04-11 devnull .TP
484 6e18e03e 2004-04-11 devnull .B i
485 6e18e03e 2004-04-11 devnull Print as machine instructions.  Dot is
486 6e18e03e 2004-04-11 devnull incremented by the size of the instruction.
487 6e18e03e 2004-04-11 devnull .TP
488 6e18e03e 2004-04-11 devnull .B I
489 6e18e03e 2004-04-11 devnull As
490 6e18e03e 2004-04-11 devnull .B i
491 6e18e03e 2004-04-11 devnull above, but print the machine instructions in
492 6e18e03e 2004-04-11 devnull an alternate form if possible.
493 6e18e03e 2004-04-11 devnull .TP
494 6e18e03e 2004-04-11 devnull .B M
495 6e18e03e 2004-04-11 devnull Print the addressed machine instruction in a
496 6e18e03e 2004-04-11 devnull machine-dependent hexadecimal form.
497 6e18e03e 2004-04-11 devnull .TP
498 6e18e03e 2004-04-11 devnull .B a
499 6e18e03e 2004-04-11 devnull Print the value of dot
500 6e18e03e 2004-04-11 devnull in symbolic form.
501 6e18e03e 2004-04-11 devnull Dot is unaffected.
502 6e18e03e 2004-04-11 devnull .TP
503 6e18e03e 2004-04-11 devnull .B A
504 6e18e03e 2004-04-11 devnull Print the value of dot
505 6e18e03e 2004-04-11 devnull in hexadecimal.
506 6e18e03e 2004-04-11 devnull Dot is unaffected.
507 6e18e03e 2004-04-11 devnull .TP
508 6e18e03e 2004-04-11 devnull .B z
509 6e18e03e 2004-04-11 devnull Print the function name, source file, and line number
510 6e18e03e 2004-04-11 devnull corresponding to dot (textfile only). Dot is unaffected.
511 6e18e03e 2004-04-11 devnull .TP
512 6e18e03e 2004-04-11 devnull .B p
513 6e18e03e 2004-04-11 devnull Print the addressed value in symbolic form.
514 6e18e03e 2004-04-11 devnull Dot is advanced by the size of a machine address.
515 6e18e03e 2004-04-11 devnull .TP
516 6e18e03e 2004-04-11 devnull .B t
517 6e18e03e 2004-04-11 devnull When preceded by an integer, tabs to the next
518 6e18e03e 2004-04-11 devnull appropriate tab stop.
519 6e18e03e 2004-04-11 devnull For example,
520 6e18e03e 2004-04-11 devnull .B 8t 
521 6e18e03e 2004-04-11 devnull moves to the next 8-space tab stop.
522 6e18e03e 2004-04-11 devnull Dot is unaffected.
523 6e18e03e 2004-04-11 devnull .TP
524 6e18e03e 2004-04-11 devnull .B n
525 6e18e03e 2004-04-11 devnull Print a newline.
526 6e18e03e 2004-04-11 devnull Dot is unaffected.
527 6e18e03e 2004-04-11 devnull .tr '"
528 6e18e03e 2004-04-11 devnull .TP
529 6e18e03e 2004-04-11 devnull .BR ' ... '
530 6e18e03e 2004-04-11 devnull Print the enclosed string.
531 6e18e03e 2004-04-11 devnull Dot is unaffected.
532 6e18e03e 2004-04-11 devnull .br
533 6e18e03e 2004-04-11 devnull .tr ''
534 6e18e03e 2004-04-11 devnull .TP
535 6e18e03e 2004-04-11 devnull .B ^
536 6e18e03e 2004-04-11 devnull Dot is decremented by the current increment.
537 6e18e03e 2004-04-11 devnull Nothing is printed.
538 6e18e03e 2004-04-11 devnull .TP
539 6e18e03e 2004-04-11 devnull .B +
540 6e18e03e 2004-04-11 devnull Dot is incremented by 1.
541 6e18e03e 2004-04-11 devnull Nothing is printed.
542 6e18e03e 2004-04-11 devnull .TP
543 6e18e03e 2004-04-11 devnull .B -
544 6e18e03e 2004-04-11 devnull Dot is decremented by 1.
545 6e18e03e 2004-04-11 devnull Nothing is printed.
546 6e18e03e 2004-04-11 devnull .RE
547 6e18e03e 2004-04-11 devnull .PD
548 6e18e03e 2004-04-11 devnull .LP
549 6e18e03e 2004-04-11 devnull Other commands include:
550 6e18e03e 2004-04-11 devnull .TP
551 6e18e03e 2004-04-11 devnull newline
552 6e18e03e 2004-04-11 devnull Update dot by the current increment.
553 6e18e03e 2004-04-11 devnull Repeat the previous command with a
554 6e18e03e 2004-04-11 devnull .I count
555 6e18e03e 2004-04-11 devnull of 1.
556 6e18e03e 2004-04-11 devnull .TP
557 6e18e03e 2004-04-11 devnull .RB [ ?/ ] l "\fI value mask\fR"
558 6e18e03e 2004-04-11 devnull Words starting at dot
559 6e18e03e 2004-04-11 devnull are masked with
560 6e18e03e 2004-04-11 devnull .I mask
561 6e18e03e 2004-04-11 devnull and compared with
562 6e18e03e 2004-04-11 devnull .I value
563 6e18e03e 2004-04-11 devnull until
564 6e18e03e 2004-04-11 devnull a match is found.
565 6e18e03e 2004-04-11 devnull If
566 6e18e03e 2004-04-11 devnull .B l
567 6e18e03e 2004-04-11 devnull is used,
568 6e18e03e 2004-04-11 devnull the match is for a two-byte integer;
569 6e18e03e 2004-04-11 devnull .B L
570 6e18e03e 2004-04-11 devnull matches four bytes.
571 6e18e03e 2004-04-11 devnull If no match is found then dot
572 6e18e03e 2004-04-11 devnull is unchanged; otherwise dot
573 6e18e03e 2004-04-11 devnull is set to the matched location.
574 6e18e03e 2004-04-11 devnull If
575 6e18e03e 2004-04-11 devnull .I mask
576 6e18e03e 2004-04-11 devnull is omitted then ~0 is used.
577 6e18e03e 2004-04-11 devnull .TP
578 6e18e03e 2004-04-11 devnull .RB [ ?/ ] w "\fI value ...\fR"
579 6e18e03e 2004-04-11 devnull Write the two-byte
580 6e18e03e 2004-04-11 devnull .I value
581 6e18e03e 2004-04-11 devnull into the addressed
582 6e18e03e 2004-04-11 devnull location.
583 6e18e03e 2004-04-11 devnull If the command is
584 6e18e03e 2004-04-11 devnull .BR W ,
585 6e18e03e 2004-04-11 devnull write four bytes.
586 6e18e03e 2004-04-11 devnull .TP
587 6e18e03e 2004-04-11 devnull .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
588 6e18e03e 2004-04-11 devnull .br
589 6e18e03e 2004-04-11 devnull New values for
590 6e18e03e 2004-04-11 devnull .RI ( b,\ e,\ f )
591 6e18e03e 2004-04-11 devnull in the segment named
592 6e18e03e 2004-04-11 devnull .I s
593 6e18e03e 2004-04-11 devnull are recorded.  Valid segment names are
594 6e18e03e 2004-04-11 devnull .IR text ,
595 6e18e03e 2004-04-11 devnull .IR data ,
596 6e18e03e 2004-04-11 devnull or 
597 6e18e03e 2004-04-11 devnull .IR ublock .
598 6e18e03e 2004-04-11 devnull If less than three address expressions are given,
599 6e18e03e 2004-04-11 devnull the remaining parameters are left unchanged.
600 6e18e03e 2004-04-11 devnull If the list is terminated by
601 6e18e03e 2004-04-11 devnull .L ?
602 6e18e03e 2004-04-11 devnull or
603 6e18e03e 2004-04-11 devnull .L /
604 6e18e03e 2004-04-11 devnull then the file
605 6e18e03e 2004-04-11 devnull .RI ( textfile
606 6e18e03e 2004-04-11 devnull or
607 6e18e03e 2004-04-11 devnull .I memfile
608 6e18e03e 2004-04-11 devnull respectively) is used
609 6e18e03e 2004-04-11 devnull for subsequent requests.
610 6e18e03e 2004-04-11 devnull For example,
611 6e18e03e 2004-04-11 devnull .L /m?
612 6e18e03e 2004-04-11 devnull causes
613 6e18e03e 2004-04-11 devnull .L /
614 6e18e03e 2004-04-11 devnull to refer to
615 6e18e03e 2004-04-11 devnull .IR textfile .
616 6e18e03e 2004-04-11 devnull .TP
617 6e18e03e 2004-04-11 devnull .BI > name
618 6e18e03e 2004-04-11 devnull Dot is assigned to the variable or register named.
619 6e18e03e 2004-04-11 devnull .TP
620 6e18e03e 2004-04-11 devnull .B !
621 6e18e03e 2004-04-11 devnull The rest of the line is passed to
622 6e18e03e 2004-04-11 devnull .IR rc (1)
623 6e18e03e 2004-04-11 devnull for execution.
624 6e18e03e 2004-04-11 devnull .TP
625 6e18e03e 2004-04-11 devnull .BI $ modifier
626 6e18e03e 2004-04-11 devnull Miscellaneous commands.
627 6e18e03e 2004-04-11 devnull The available 
628 6e18e03e 2004-04-11 devnull .I modifiers 
629 6e18e03e 2004-04-11 devnull are:
630 6e18e03e 2004-04-11 devnull .RS
631 6e18e03e 2004-04-11 devnull .TP
632 6e18e03e 2004-04-11 devnull .PD 0
633 6e18e03e 2004-04-11 devnull .BI < f
634 6e18e03e 2004-04-11 devnull Read commands from the file
635 6e18e03e 2004-04-11 devnull .IR f .
636 6e18e03e 2004-04-11 devnull If this command is executed in a file, further commands
637 6e18e03e 2004-04-11 devnull in the file are not seen.
638 6e18e03e 2004-04-11 devnull If
639 6e18e03e 2004-04-11 devnull .I f
640 6e18e03e 2004-04-11 devnull is omitted, the current input stream is terminated.
641 6e18e03e 2004-04-11 devnull If a
642 6e18e03e 2004-04-11 devnull .I count
643 6e18e03e 2004-04-11 devnull is given, and is zero, the command is ignored.
644 6e18e03e 2004-04-11 devnull .TP
645 6e18e03e 2004-04-11 devnull .BI << f
646 6e18e03e 2004-04-11 devnull Similar to
647 6e18e03e 2004-04-11 devnull .B <
648 6e18e03e 2004-04-11 devnull except it can be used in a file of commands without
649 6e18e03e 2004-04-11 devnull causing the file to be closed.
650 6e18e03e 2004-04-11 devnull There is a (small) limit to the number of
651 6e18e03e 2004-04-11 devnull .B <<
652 6e18e03e 2004-04-11 devnull files that can be open at once.
653 6e18e03e 2004-04-11 devnull .br
654 6e18e03e 2004-04-11 devnull .ns
655 6e18e03e 2004-04-11 devnull .TP
656 6e18e03e 2004-04-11 devnull .BI > f
657 6e18e03e 2004-04-11 devnull Append output to the file
658 6e18e03e 2004-04-11 devnull .IR f ,
659 6e18e03e 2004-04-11 devnull which is created if it does not exist.
660 6e18e03e 2004-04-11 devnull If
661 6e18e03e 2004-04-11 devnull .I f
662 6e18e03e 2004-04-11 devnull is omitted, output is returned to the terminal.
663 6e18e03e 2004-04-11 devnull .TP
664 6e18e03e 2004-04-11 devnull .B ?
665 6e18e03e 2004-04-11 devnull Print process id, the condition which caused stopping or termination,
666 6e18e03e 2004-04-11 devnull the registers and the instruction addressed by
667 6e18e03e 2004-04-11 devnull .BR pc .
668 6e18e03e 2004-04-11 devnull This is the default if
669 6e18e03e 2004-04-11 devnull .I modifier
670 6e18e03e 2004-04-11 devnull is omitted.
671 6e18e03e 2004-04-11 devnull .TP
672 6e18e03e 2004-04-11 devnull .B r
673 6e18e03e 2004-04-11 devnull Print the general registers and
674 6e18e03e 2004-04-11 devnull the instruction addressed by
675 6e18e03e 2004-04-11 devnull .BR pc .
676 6e18e03e 2004-04-11 devnull Dot is set to
677 6e18e03e 2004-04-11 devnull .BR pc .
678 6e18e03e 2004-04-11 devnull .TP
679 6e18e03e 2004-04-11 devnull .B R
680 6e18e03e 2004-04-11 devnull Like
681 6e18e03e 2004-04-11 devnull .BR $r ,
682 6e18e03e 2004-04-11 devnull but include miscellaneous processor control registers
683 6e18e03e 2004-04-11 devnull and floating point registers.
684 6e18e03e 2004-04-11 devnull .TP
685 6e18e03e 2004-04-11 devnull .B f
686 6e18e03e 2004-04-11 devnull Print floating-point register values as
687 6e18e03e 2004-04-11 devnull single-precision floating point numbers.
688 6e18e03e 2004-04-11 devnull .TP
689 6e18e03e 2004-04-11 devnull .B F
690 6e18e03e 2004-04-11 devnull Print floating-point register values as
691 6e18e03e 2004-04-11 devnull double-precision floating point numbers.
692 6e18e03e 2004-04-11 devnull .TP
693 6e18e03e 2004-04-11 devnull .B b
694 6e18e03e 2004-04-11 devnull Print all breakpoints
695 6e18e03e 2004-04-11 devnull and their associated counts and commands.  `B' produces the same results.
696 6e18e03e 2004-04-11 devnull .TP
697 6e18e03e 2004-04-11 devnull .B c
698 6e18e03e 2004-04-11 devnull Stack backtrace.
699 6e18e03e 2004-04-11 devnull If
700 6e18e03e 2004-04-11 devnull .I address
701 6e18e03e 2004-04-11 devnull is given, it specifies the address of a pair of 32-bit
702 6e18e03e 2004-04-11 devnull values containing the
703 6e18e03e 2004-04-11 devnull .B sp
704 6e18e03e 2004-04-11 devnull and
705 6e18e03e 2004-04-11 devnull .B pc
706 6e18e03e 2004-04-11 devnull of an active process.  This allows selecting
707 6e18e03e 2004-04-11 devnull among various contexts of a multi-threaded
708 6e18e03e 2004-04-11 devnull process.
709 6e18e03e 2004-04-11 devnull If
710 6e18e03e 2004-04-11 devnull .B C
711 6e18e03e 2004-04-11 devnull is used, the names and (long) values of all
712 6e18e03e 2004-04-11 devnull parameters,
713 6e18e03e 2004-04-11 devnull automatic
714 6e18e03e 2004-04-11 devnull and static variables are printed for each active function.
715 6e18e03e 2004-04-11 devnull If
716 6e18e03e 2004-04-11 devnull .I count
717 6e18e03e 2004-04-11 devnull is given, only the first
718 6e18e03e 2004-04-11 devnull .I count
719 6e18e03e 2004-04-11 devnull frames are printed.
720 6e18e03e 2004-04-11 devnull .TP
721 6e18e03e 2004-04-11 devnull .B a
722 6e18e03e 2004-04-11 devnull Attach to the running process whose pid
723 6e18e03e 2004-04-11 devnull is contained in
724 6e18e03e 2004-04-11 devnull .IR address .
725 6e18e03e 2004-04-11 devnull .TP
726 6e18e03e 2004-04-11 devnull .B e
727 6e18e03e 2004-04-11 devnull The names and values of all
728 6e18e03e 2004-04-11 devnull external variables are printed.
729 6e18e03e 2004-04-11 devnull .TP
730 6e18e03e 2004-04-11 devnull .B w
731 6e18e03e 2004-04-11 devnull Set the page width for output to
732 6e18e03e 2004-04-11 devnull .I address
733 6e18e03e 2004-04-11 devnull (default 80).
734 6e18e03e 2004-04-11 devnull .TP
735 6e18e03e 2004-04-11 devnull .B q
736 6e18e03e 2004-04-11 devnull Exit from
737 6e18e03e 2004-04-11 devnull .IR db .
738 6e18e03e 2004-04-11 devnull .TP
739 6e18e03e 2004-04-11 devnull .B m
740 6e18e03e 2004-04-11 devnull Print the address maps.
741 6e18e03e 2004-04-11 devnull .TP
742 6e18e03e 2004-04-11 devnull .B k
743 6e18e03e 2004-04-11 devnull Simulate kernel memory management.
744 6e18e03e 2004-04-11 devnull .TP
745 6e18e03e 2004-04-11 devnull .BI M machine
746 6e18e03e 2004-04-11 devnull Set the
747 6e18e03e 2004-04-11 devnull .I machine
748 6e18e03e 2004-04-11 devnull type used for disassembling instructions.
749 6e18e03e 2004-04-11 devnull .PD
750 6e18e03e 2004-04-11 devnull .RE
751 6e18e03e 2004-04-11 devnull .TP
752 6e18e03e 2004-04-11 devnull .BI : modifier
753 6e18e03e 2004-04-11 devnull Manage a subprocess.
754 6e18e03e 2004-04-11 devnull Available modifiers are:
755 6e18e03e 2004-04-11 devnull .RS
756 6e18e03e 2004-04-11 devnull .TP
757 6e18e03e 2004-04-11 devnull .PD 0
758 6e18e03e 2004-04-11 devnull .BI h
759 6e18e03e 2004-04-11 devnull Halt
760 6e18e03e 2004-04-11 devnull an asynchronously running process to allow breakpointing.
761 6e18e03e 2004-04-11 devnull Unnecessary for processes created under
762 6e18e03e 2004-04-11 devnull .IR db ,
763 6e18e03e 2004-04-11 devnull e.g. by
764 6e18e03e 2004-04-11 devnull .BR :r .
765 6e18e03e 2004-04-11 devnull .TP
766 6e18e03e 2004-04-11 devnull .BI b c
767 6e18e03e 2004-04-11 devnull Set breakpoint at
768 6e18e03e 2004-04-11 devnull .IR address .
769 6e18e03e 2004-04-11 devnull The breakpoint is executed
770 6e18e03e 2004-04-11 devnull .IR count \-1
771 6e18e03e 2004-04-11 devnull times before
772 6e18e03e 2004-04-11 devnull causing a stop.
773 6e18e03e 2004-04-11 devnull Also, if a command
774 6e18e03e 2004-04-11 devnull .I c
775 6e18e03e 2004-04-11 devnull is given it is executed at each
776 6e18e03e 2004-04-11 devnull breakpoint and if it sets dot to zero
777 6e18e03e 2004-04-11 devnull the breakpoint causes a stop.
778 6e18e03e 2004-04-11 devnull .TP
779 6e18e03e 2004-04-11 devnull .B d
780 6e18e03e 2004-04-11 devnull Delete breakpoint at
781 6e18e03e 2004-04-11 devnull .IR address .
782 6e18e03e 2004-04-11 devnull .TP
783 6e18e03e 2004-04-11 devnull .B r
784 6e18e03e 2004-04-11 devnull Run
785 6e18e03e 2004-04-11 devnull .I textfile
786 6e18e03e 2004-04-11 devnull as a subprocess.
787 6e18e03e 2004-04-11 devnull If
788 6e18e03e 2004-04-11 devnull .I address
789 6e18e03e 2004-04-11 devnull is given the
790 6e18e03e 2004-04-11 devnull program is entered at that point; otherwise
791 6e18e03e 2004-04-11 devnull the standard entry point is used.
792 6e18e03e 2004-04-11 devnull .I Count
793 6e18e03e 2004-04-11 devnull specifies how many breakpoints are to be
794 6e18e03e 2004-04-11 devnull ignored before stopping.
795 6e18e03e 2004-04-11 devnull Arguments to the subprocess may be supplied on the
796 6e18e03e 2004-04-11 devnull same line as the command.
797 6e18e03e 2004-04-11 devnull An argument starting with < or > causes the standard
798 6e18e03e 2004-04-11 devnull input or output to be established for the command.
799 6e18e03e 2004-04-11 devnull .TP
800 6e18e03e 2004-04-11 devnull .BI c s
801 6e18e03e 2004-04-11 devnull The subprocess is continued.
802 6e18e03e 2004-04-11 devnull If
803 6e18e03e 2004-04-11 devnull .I s
804 6e18e03e 2004-04-11 devnull is omitted
805 6e18e03e 2004-04-11 devnull or nonzero,
806 6e18e03e 2004-04-11 devnull the subprocess
807 6e18e03e 2004-04-11 devnull is sent the note that caused it to stop.
808 6e18e03e 2004-04-11 devnull If 0
809 6e18e03e 2004-04-11 devnull is specified,
810 6e18e03e 2004-04-11 devnull no note is sent.
811 6e18e03e 2004-04-11 devnull (If the stop was due to a breakpoint or single-step,
812 6e18e03e 2004-04-11 devnull the corresponding note is elided before continuing.)
813 6e18e03e 2004-04-11 devnull Breakpoint skipping is the same
814 6e18e03e 2004-04-11 devnull as for
815 6e18e03e 2004-04-11 devnull .BR r .
816 6e18e03e 2004-04-11 devnull .TP
817 6e18e03e 2004-04-11 devnull .BI s s
818 6e18e03e 2004-04-11 devnull As for
819 6e18e03e 2004-04-11 devnull .B c
820 6e18e03e 2004-04-11 devnull except that
821 6e18e03e 2004-04-11 devnull the subprocess is single stepped for
822 6e18e03e 2004-04-11 devnull .I count
823 6e18e03e 2004-04-11 devnull machine instructions.
824 6e18e03e 2004-04-11 devnull If a note is pending,
825 6e18e03e 2004-04-11 devnull it is received
826 6e18e03e 2004-04-11 devnull before the first instruction is executed.
827 6e18e03e 2004-04-11 devnull If there is no current subprocess then
828 6e18e03e 2004-04-11 devnull .I textfile
829 6e18e03e 2004-04-11 devnull is run
830 6e18e03e 2004-04-11 devnull as a subprocess as for
831 6e18e03e 2004-04-11 devnull .BR r .
832 6e18e03e 2004-04-11 devnull In this case no note can be sent; the remainder of the line
833 6e18e03e 2004-04-11 devnull is treated as arguments to the subprocess.
834 6e18e03e 2004-04-11 devnull .TP
835 6e18e03e 2004-04-11 devnull .BI S s
836 6e18e03e 2004-04-11 devnull Identical to
837 6e18e03e 2004-04-11 devnull .B s
838 6e18e03e 2004-04-11 devnull except the subprocess is single stepped for
839 6e18e03e 2004-04-11 devnull .I count
840 6e18e03e 2004-04-11 devnull lines of C source.  In optimized code, the correspondence
841 6e18e03e 2004-04-11 devnull between C source and the machine instructions is
842 6e18e03e 2004-04-11 devnull approximate at best.
843 6e18e03e 2004-04-11 devnull .TP
844 6e18e03e 2004-04-11 devnull .BI x
845 6e18e03e 2004-04-11 devnull The current subprocess, if any, is released by
846 6e18e03e 2004-04-11 devnull .I db
847 6e18e03e 2004-04-11 devnull and allowed to continue executing normally.
848 6e18e03e 2004-04-11 devnull .TP
849 6e18e03e 2004-04-11 devnull .B k
850 6e18e03e 2004-04-11 devnull The current subprocess, if any, is terminated.
851 6e18e03e 2004-04-11 devnull .TP
852 6e18e03e 2004-04-11 devnull .BI n c
853 6e18e03e 2004-04-11 devnull Display the pending notes for the process.
854 6e18e03e 2004-04-11 devnull If
855 6e18e03e 2004-04-11 devnull .I c
856 6e18e03e 2004-04-11 devnull is specified, first delete
857 6e18e03e 2004-04-11 devnull .I c'th
858 6e18e03e 2004-04-11 devnull pending note.
859 6e18e03e 2004-04-11 devnull .PD
860 6e18e03e 2004-04-11 devnull .RE
861 6e18e03e 2004-04-11 devnull .SS Addresses
862 6e18e03e 2004-04-11 devnull The location in a file or memory image associated with
863 6e18e03e 2004-04-11 devnull an address is calculated from a map
864 6e18e03e 2004-04-11 devnull associated with the file.
865 6e18e03e 2004-04-11 devnull Each map contains one or more quadruples
866 6e18e03e 2004-04-11 devnull .RI ( "t, f, b, e, o" ),
867 6e18e03e 2004-04-11 devnull defining a segment named
868 6e18e03e 2004-04-11 devnull .I t
869 6e18e03e 2004-04-11 devnull (usually, 
870 6e18e03e 2004-04-11 devnull .IR text ,
871 6e18e03e 2004-04-11 devnull .IR data ,
872 6e18e03e 2004-04-11 devnull or
873 6e18e03e 2004-04-11 devnull .IR core )
874 6e18e03e 2004-04-11 devnull in file
875 6e18e03e 2004-04-11 devnull .I f
876 6e18e03e 2004-04-11 devnull mapping addresses in the range
877 6e18e03e 2004-04-11 devnull .I b
878 6e18e03e 2004-04-11 devnull through
879 6e18e03e 2004-04-11 devnull .IR e
880 6e18e03e 2004-04-11 devnull to the part of the file
881 6e18e03e 2004-04-11 devnull beginning at
882 6e18e03e 2004-04-11 devnull offset
883 6e18e03e 2004-04-11 devnull .IR o .
884 6e18e03e 2004-04-11 devnull If segments overlap, later segments obscure earlier ones.
885 6e18e03e 2004-04-11 devnull An address
886 6e18e03e 2004-04-11 devnull .I a
887 6e18e03e 2004-04-11 devnull is translated
888 6e18e03e 2004-04-11 devnull to a file address
889 6e18e03e 2004-04-11 devnull by finding the last segment in the list
890 6e18e03e 2004-04-11 devnull for which
891 6e18e03e 2004-04-11 devnull .IR b ≤ a < e ;
892 6e18e03e 2004-04-11 devnull the location in the file
893 6e18e03e 2004-04-11 devnull is then
894 6e18e03e 2004-04-11 devnull .IR address + f \- b .
895 6e18e03e 2004-04-11 devnull .PP
896 6e18e03e 2004-04-11 devnull Usually,
897 6e18e03e 2004-04-11 devnull the text and initialized data of a program
898 6e18e03e 2004-04-11 devnull are mapped by segments called 
899 6e18e03e 2004-04-11 devnull .IR text ,
900 6e18e03e 2004-04-11 devnull .IR data ,
901 6e18e03e 2004-04-11 devnull and
902 6e18e03e 2004-04-11 devnull .IR bss .
903 6e18e03e 2004-04-11 devnull Since a program file does not contain stack data,
904 6e18e03e 2004-04-11 devnull this data is
905 6e18e03e 2004-04-11 devnull not mapped.
906 6e18e03e 2004-04-11 devnull The text segment is mapped similarly in
907 6e18e03e 2004-04-11 devnull a normal (i.e., non-kernel)
908 6e18e03e 2004-04-11 devnull .IR memfile .
909 6e18e03e 2004-04-11 devnull However, one or more segments called 
910 6e18e03e 2004-04-11 devnull .I data
911 6e18e03e 2004-04-11 devnull provide access to process memory.
912 6e18e03e 2004-04-11 devnull This region contains the program's static data, the bss, the
913 6e18e03e 2004-04-11 devnull heap and the stack.
914 6e18e03e 2004-04-11 devnull .PP
915 6e18e03e 2004-04-11 devnull Sometimes it is useful to define a map with a single segment
916 6e18e03e 2004-04-11 devnull mapping the region from 0 to 0xFFFFFFFF; a map of this type
917 6e18e03e 2004-04-11 devnull allows an entire file to be examined
918 6e18e03e 2004-04-11 devnull without address translation.
919 6e18e03e 2004-04-11 devnull .PP
920 6e18e03e 2004-04-11 devnull The
921 6e18e03e 2004-04-11 devnull .B $m
922 6e18e03e 2004-04-11 devnull command dumps the currently active maps.  The
923 6e18e03e 2004-04-11 devnull .B ?m
924 6e18e03e 2004-04-11 devnull and
925 6e18e03e 2004-04-11 devnull .B /m
926 6e18e03e 2004-04-11 devnull commands modify the segment parameters in the
927 6e18e03e 2004-04-11 devnull .I textfile
928 6e18e03e 2004-04-11 devnull and
929 6e18e03e 2004-04-11 devnull .I memfile
930 6e18e03e 2004-04-11 devnull maps, respectively.
931 6e18e03e 2004-04-11 devnull .SH EXAMPLES
932 6e18e03e 2004-04-11 devnull To set a breakpoint at the beginning of
933 6e18e03e 2004-04-11 devnull .B write()
934 6e18e03e 2004-04-11 devnull in extant process 27:
935 6e18e03e 2004-04-11 devnull .IP
936 6e18e03e 2004-04-11 devnull .EX
937 6e18e03e 2004-04-11 devnull % db 27
938 6e18e03e 2004-04-11 devnull :h
939 6e18e03e 2004-04-11 devnull write:b
940 6e18e03e 2004-04-11 devnull :c
941 6e18e03e 2004-04-11 devnull .EE
942 6e18e03e 2004-04-11 devnull .PP
943 6e18e03e 2004-04-11 devnull To set a breakpoint at the entry of function
944 6e18e03e 2004-04-11 devnull .B parse
945 6e18e03e 2004-04-11 devnull when the local variable
946 6e18e03e 2004-04-11 devnull .B argc
947 6e18e03e 2004-04-11 devnull in
948 6e18e03e 2004-04-11 devnull .B main
949 6e18e03e 2004-04-11 devnull is equal to 1:
950 6e18e03e 2004-04-11 devnull .IP
951 6e18e03e 2004-04-11 devnull .EX
952 6e18e03e 2004-04-11 devnull parse:b *main.argc-1=X
953 6e18e03e 2004-04-11 devnull .EE
954 6e18e03e 2004-04-11 devnull .PP
955 6e18e03e 2004-04-11 devnull This prints the value of
956 6e18e03e 2004-04-11 devnull .B argc-1
957 6e18e03e 2004-04-11 devnull which as a side effect sets dot; when
958 6e18e03e 2004-04-11 devnull .B argc
959 6e18e03e 2004-04-11 devnull is one the breakpoint will fire.
960 6e18e03e 2004-04-11 devnull Beware that local variables may be stored in registers; see the
961 6e18e03e 2004-04-11 devnull BUGS section.
962 6e18e03e 2004-04-11 devnull .SH "SEE ALSO"
963 3264d2e2 2005-01-23 devnull .IR acid (1),
964 3264d2e2 2005-01-23 devnull .IR core (1)
965 6e18e03e 2004-04-11 devnull .SH SOURCE
966 c3674de4 2005-01-11 devnull .B \*9/src/cmd/db
967 6e18e03e 2004-04-11 devnull .SH DIAGNOSTICS
968 6e18e03e 2004-04-11 devnull Exit status is 0, unless the last command failed or
969 6e18e03e 2004-04-11 devnull returned non-zero status.
970 6e18e03e 2004-04-11 devnull .SH BUGS
971 6e18e03e 2004-04-11 devnull Examining a local variable with
972 6e18e03e 2004-04-11 devnull .I routine.name
973 6e18e03e 2004-04-11 devnull returns the contents of the memory allocated for the variable, but
974 6e18e03e 2004-04-11 devnull with optimization, variables often reside in registers.
975 6e18e03e 2004-04-11 devnull Also, on some architectures, the first argument is always
976 6e18e03e 2004-04-11 devnull passed in a register.
977 6e18e03e 2004-04-11 devnull .PP
978 6e18e03e 2004-04-11 devnull Variables and parameters that have been
979 6e18e03e 2004-04-11 devnull optimized away do not appear in the
980 6e18e03e 2004-04-11 devnull symbol table, returning the error 
981 6e18e03e 2004-04-11 devnull .IR "bad local variable"
982 6e18e03e 2004-04-11 devnull when accessed by
983 6e18e03e 2004-04-11 devnull .IR db .
984 6e18e03e 2004-04-11 devnull .PP
985 6e18e03e 2004-04-11 devnull Breakpoints should not be set on instructions scheduled
986 6e18e03e 2004-04-11 devnull in delay slots.  When a program stops on such a breakpoint,
987 6e18e03e 2004-04-11 devnull it is usually impossible to continue its execution.