Commit | Line | Data |
---|---|---|
b5dc1377 | 1 | .\" Copyright (c) 1983, 1990 The Regents of the University of California. |
8a90f3aa | 2 | .\" All rights reserved. |
0b6ba29a | 3 | .\" |
b5dc1377 | 4 | .\" %sccs.include.redist.man% |
8a90f3aa | 5 | .\" |
b5dc1377 | 6 | .\" @(#)dbx.1 6.4 (Berkeley) %G% |
0b6ba29a | 7 | .\" |
b5dc1377 CL |
8 | .Dd |
9 | .Dt DBX 1 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm dbx | |
13 | .Nd debugger | |
14 | .Sh SYNOPSIS | |
15 | .Nm Dbx | |
16 | .Op Fl r | |
17 | .Op Fl i | |
18 | .Op Fl k | |
19 | .Op Fl I Ar dir | |
20 | .Op Fl c Ar file | |
21 | .Op Ar objfile Op Ar coredump | |
22 | .Sh DESCRIPTION | |
23 | .Nm dbx | |
24 | is a tool for source level debugging and execution of | |
0b6ba29a | 25 | programs under UNIX. |
b5dc1377 CL |
26 | The |
27 | .Ar objfile | |
28 | is an object file produced by a compiler | |
29 | with the appropriate flag (usually | |
30 | .Fl g ) | |
0b6ba29a | 31 | specified to produce symbol information in the object file. |
b5dc1377 CL |
32 | Currently, |
33 | .Xr cc 1 , | |
34 | .Xr f77 1 , | |
35 | .Xr pc 1 , | |
36 | and the DEC Western | |
37 | Research Laboratory Modula-2 compiler, | |
38 | .Xr mod l , | |
81ddc115 | 39 | produce the appropriate source information. |
b5dc1377 CL |
40 | The machine level facilities of |
41 | .Nm dbx | |
0b6ba29a | 42 | can be used on any program. |
b5dc1377 | 43 | .Pp |
81ddc115 | 44 | The object file contains a symbol table that includes the name of the |
0b6ba29a KM |
45 | all the source files translated by the compiler to create it. |
46 | These files are available for perusal while using the debugger. | |
b5dc1377 CL |
47 | .Pp |
48 | If a file named ``core'' | |
49 | exists in the current directory | |
50 | or a | |
51 | .Ar coredump | |
52 | file is specified, | |
53 | .Nm dbx | |
54 | can be used | |
0b6ba29a | 55 | to examine the state of the program when it faulted. |
b5dc1377 CL |
56 | .Pp |
57 | If the file ``.dbxinit'' exists in the current directory then the | |
0b6ba29a | 58 | debugger commands in it are executed. |
b5dc1377 CL |
59 | .Nm Dbx |
60 | also checks for a ``.dbxinit'' in the user's home directory | |
0b6ba29a | 61 | if there isn't one in the current directory. |
b5dc1377 | 62 | .Pp |
0b6ba29a | 63 | The command line options and their meanings are: |
b5dc1377 CL |
64 | .Tw Fl |
65 | .Tp Fl r | |
66 | Execute | |
67 | .Ar objfile | |
68 | immediately. | |
69 | If it terminates successfully | |
70 | .Nm dbx | |
71 | exits. | |
0b6ba29a KM |
72 | Otherwise the reason for termination will be reported |
73 | and the user offered the option of entering the debugger | |
74 | or letting the program fault. | |
b5dc1377 CL |
75 | .Nm Dbx |
76 | will read from ``/dev/tty'' when | |
77 | .Fl r | |
78 | is specified | |
0b6ba29a | 79 | and standard input is not a terminal. |
b5dc1377 CL |
80 | .Tp Fl i |
81 | Force | |
82 | .Nm dbx | |
83 | to act as though standard input is a terminal. | |
84 | .Tp Fl k | |
81ddc115 | 85 | Map memory addresses, useful for kernel debugging. |
b5dc1377 CL |
86 | .Tp Cx Fl I |
87 | .Cx \&\ \& | |
88 | .Ar dir | |
89 | .Cx | |
90 | Add | |
91 | .Ar dir | |
92 | to the list of directories | |
0b6ba29a | 93 | that are searched when looking for a source file. |
b5dc1377 CL |
94 | Normally |
95 | .Nm dbx | |
96 | looks for source files in the current directory | |
97 | and in the directory where | |
98 | .Ar objfile | |
99 | is located. | |
100 | The directory search path can also be set with the | |
101 | .Ar use | |
102 | command. | |
103 | .Tp Cx Fl c | |
104 | .Cx \&\ \& | |
105 | .Ar file | |
106 | .Cx | |
107 | Execute the | |
108 | .Nm dbx | |
109 | commands in the | |
110 | .Ar file | |
111 | before | |
81ddc115 | 112 | reading from standard input. |
b5dc1377 CL |
113 | .Tp |
114 | .Pp | |
115 | Unless | |
116 | .Fl r | |
117 | is specified, | |
118 | .Nm dbx | |
119 | just prompts and waits for a command. | |
120 | .Ss Execution and Tracing Commands | |
121 | .Dw Fl | |
122 | .Di L | |
123 | .Dp Cx Ic run | |
124 | .Cx \&\ \& | |
125 | .Op Ar args | |
126 | .Cx \&\ \& | |
127 | .Op Sy < Ar filename | |
128 | .Cx \&\ \& | |
129 | .Op Sy > Ar filename | |
130 | .Cx | |
131 | .Dp Cx Ic rerun | |
132 | .Cx \&\ \& | |
133 | .Op Ar args | |
134 | .Cx \&\ \& | |
135 | .Op Sy < Ar filename | |
136 | .Cx \&\ \& | |
137 | .Op Sy > Ar filename | |
138 | .Cx | |
139 | Start executing | |
140 | .Ar objfile , | |
141 | passing | |
142 | .Ar args | |
143 | as command line arguments; | |
144 | .Sy < | |
145 | or | |
146 | .Sy > | |
147 | can be used to redirect input or output in the usual manner. | |
148 | When | |
149 | .Ic rerun | |
150 | is used without any arguments the previous | |
81ddc115 | 151 | argument list is passed to the program; |
b5dc1377 CL |
152 | otherwise it is identical to |
153 | .Ic run . | |
154 | If | |
155 | .Ar objfile | |
156 | has been written since the last time the symbolic information | |
157 | was read in, | |
158 | .Nm dbx | |
159 | will read in the new information. | |
160 | .Dp Cx Ic trace | |
161 | .Cx \&\ \& | |
162 | .Op Ic in Ar procedure/function | |
163 | .Cx \&\ \& | |
164 | .Op Ic if Ar condition | |
165 | .Cx | |
166 | .Dp Cx Ic trace | |
167 | .Cx \&\ \& | |
168 | .Ar source-line-number | |
169 | .Cx \&\ \& | |
170 | .Op Ic if Ar condition | |
171 | .Cx | |
172 | .Dp Cx Ic trace | |
173 | .Cx \&\ \& | |
174 | .Ar procedure/function | |
175 | .Cx \&\ \& | |
176 | .Op Ic in Ar procedure/function | |
177 | .Cx \&\ \& | |
178 | .Op Ic if Ar condition | |
179 | .Cx | |
180 | .Dp Cx Ic trace | |
181 | .Cx \&\ \& | |
182 | .Ar expression | |
183 | .Cx \&\ \& | |
184 | .Ic at | |
185 | .Cx \&\ \& | |
186 | .Ar source-line-number | |
187 | .Cx \&\ \& | |
188 | .Op Ic if Ar condition | |
189 | .Cx | |
190 | .Dp Cx Ic trace | |
191 | .Cx \&\ \& | |
192 | .Ar variable | |
193 | .Cx \&\ \& | |
194 | .Op Ic in Ar procedure/function | |
195 | .Cx \&\ \& | |
196 | .Op Ic if Ar condition | |
197 | .Cx | |
0b6ba29a KM |
198 | Have tracing information printed when the program is executed. |
199 | A number is associated with the command that is used | |
b5dc1377 CL |
200 | to turn the tracing off (see the |
201 | .Ic delete | |
202 | command). | |
203 | .Pp | |
0b6ba29a | 204 | The first argument describes what is to be traced. |
b5dc1377 CL |
205 | If it is a |
206 | .Ar source-line-number , | |
207 | then the line is printed | |
0b6ba29a KM |
208 | immediately prior to being executed. |
209 | Source line numbers in a file other than the current one | |
210 | must be preceded by the name of the file in quotes and a colon, e.g. | |
211 | "mumble.p":17. | |
b5dc1377 | 212 | .Pp |
0b6ba29a KM |
213 | If the argument is a procedure or function name then |
214 | every time it is called, information is printed telling | |
215 | what routine called it, from what source line it was called, | |
216 | and what parameters were passed to it. | |
217 | In addition, its return is noted, and if it's a function | |
218 | then the value it is returning is also printed. | |
b5dc1377 CL |
219 | .Pp |
220 | If the argument is an | |
221 | .Ar expression | |
222 | with an | |
223 | .Ic at | |
224 | clause | |
0b6ba29a KM |
225 | then the value of the expression is printed whenever the |
226 | identified source line is reached. | |
b5dc1377 | 227 | .Pp |
0b6ba29a KM |
228 | If the argument is a variable then the name and value of the variable |
229 | is printed whenever it changes. | |
230 | Execution is substantially slower during this form of tracing. | |
b5dc1377 | 231 | .Pp |
0b6ba29a KM |
232 | If no argument is specified then all source lines are printed |
233 | before they are executed. | |
234 | Execution is substantially slower during this form of tracing. | |
b5dc1377 CL |
235 | .Pp |
236 | The clause | |
237 | .Ic in | |
238 | .Ar procedure/function | |
239 | restricts tracing information | |
0b6ba29a KM |
240 | to be printed only while executing inside the given procedure |
241 | or function. | |
b5dc1377 CL |
242 | .Pp |
243 | .Ar Condition | |
244 | is a boolean expression and is | |
0b6ba29a KM |
245 | evaluated prior to printing the tracing information; |
246 | if it is false then the information is not printed. | |
b5dc1377 CL |
247 | .Dp Cx Ic stop if |
248 | .Cx \&\ \& | |
249 | .Ar condition | |
250 | .Cx | |
251 | .Dp Cx Ic stop at | |
252 | .Cx \&\ \& | |
253 | .Ar source-line-number | |
254 | .Cx \&\ \& | |
255 | .Op Ic if Ar condition | |
256 | .Cx | |
257 | .Dp Cx Ic stop in | |
258 | .Cx \&\ \& | |
259 | .Ar source-line-number | |
260 | .Cx \&\ \& | |
261 | .Op Ic if Ar condition | |
262 | .Cx | |
263 | .Dp Cx Ic stop | |
264 | .Cx \&\ \& | |
265 | .Ar variable | |
266 | .Cx \&\ \& | |
267 | .Op Ic if Ar condition | |
268 | .Cx | |
0b6ba29a KM |
269 | Stop execution when the given line is reached, procedure or function |
270 | called, variable changed, or condition true. | |
b5dc1377 CL |
271 | .Dp Cx Ic status |
272 | .Cx \&\ \& | |
273 | .Op Ic \&> Ar filename | |
274 | .Cx | |
275 | Print out the currently active | |
276 | .Ic trace | |
277 | and | |
278 | .Ic stop | |
279 | commands. | |
280 | .Dp Cx Ic delete | |
281 | .Cx \&\ \& | |
282 | .Ar command-number ... | |
283 | .Cx | |
81ddc115 | 284 | The traces or stops corresponding to the given numbers are removed. |
0b6ba29a | 285 | The numbers associated with traces and stops are printed by |
b5dc1377 CL |
286 | the |
287 | .Ic status | |
288 | command. | |
289 | .Dp Cx Ic catch | |
290 | .Cx \&\ \& | |
291 | .Ar number | |
292 | .Cx | |
293 | .Dp Cx Ic catch | |
294 | .Cx \&\ \& | |
295 | .Ar signal-name | |
296 | .Cx | |
297 | .Dp Cx Ic ignore | |
298 | .Cx \&\ \& | |
299 | .Ar number | |
300 | .Cx | |
301 | .Dp Cx Ic ignore | |
302 | .Cx \&\ \& | |
303 | .Ar signal-name | |
304 | .Cx | |
81ddc115 | 305 | Start or stop trapping a signal before it is sent |
0b6ba29a KM |
306 | to the program. |
307 | This is useful when a program being debugged | |
308 | handles signals such as interrupts. | |
81ddc115 KM |
309 | A signal may be specified by number or by a name |
310 | (e.g., SIGINT). | |
311 | Signal names are case insensitive and the ``SIG'' prefix is optional. | |
312 | By default all signals are trapped except SIGCONT, SIGCHILD, | |
0b6ba29a | 313 | SIGALRM and SIGKILL. |
b5dc1377 CL |
314 | .Dp Cx Ic cont |
315 | .Cx \&\ \& | |
316 | .Ar integer | |
317 | .Cx | |
318 | .Dp Cx Ic cont | |
319 | .Cx \&\ \& | |
320 | .Ar signal-name | |
321 | .Cx | |
0b6ba29a | 322 | Continue execution from where it stopped. |
81ddc115 KM |
323 | If a signal is specified, the process continues as though |
324 | it received the signal. | |
325 | Otherwise, the process is continued as though it had not been stopped. | |
b5dc1377 | 326 | .Pp |
0b6ba29a KM |
327 | Execution cannot be continued if the process has ``finished'', |
328 | that is, called the standard procedure ``exit''. | |
b5dc1377 CL |
329 | .Nm Dbx |
330 | does not allow the process to exit, thereby | |
0b6ba29a | 331 | letting the user to examine the program state. |
b5dc1377 | 332 | .Dp Ic step |
0b6ba29a | 333 | Execute one source line. |
b5dc1377 | 334 | .Dp Ic next |
0b6ba29a | 335 | Execute up to the next source line. |
b5dc1377 CL |
336 | The difference between this and |
337 | .Ic step | |
338 | is that | |
0b6ba29a | 339 | if the line contains a call to a procedure or function |
b5dc1377 CL |
340 | the |
341 | .Ic step | |
342 | command will stop at the beginning of that | |
343 | block, while the | |
344 | .Ic next | |
345 | command will not. | |
346 | .Dp Cx Ic return | |
347 | .Cx \&\ \& | |
348 | .Op Ar procedure | |
349 | .Cx | |
350 | Continue until a return to | |
351 | .Ar procedure | |
352 | is executed, or | |
81ddc115 | 353 | until the current procedure returns if none is specified. |
b5dc1377 CL |
354 | .Dp Cx Ic call |
355 | .Cx \&\ \& | |
356 | .Ar procedure (parameters ) | |
357 | .Cx | |
81ddc115 | 358 | Execute the object code associated with the named procedure or function. |
b5dc1377 CL |
359 | .Dp |
360 | .Ss Printing Variables and Expressions | |
81ddc115 KM |
361 | Names are resolved first using the static scope of the current function, |
362 | then using the dynamic scope if the name is not defined | |
363 | in the static scope. | |
364 | If static and dynamic searches do not yield a result, | |
365 | an arbitrary symbol is chosen and | |
b5dc1377 CL |
366 | the message |
367 | .Cx `` | |
368 | .Op using Ar qualified name | |
369 | .Cx \'\' | |
370 | .Cx | |
371 | is printed. | |
81ddc115 | 372 | The name resolution procedure may be overridden by qualifying an identifier |
b5dc1377 CL |
373 | with a block name, e.g., |
374 | .Cx `` | |
375 | Ar module.variable | |
376 | .Cx \'\'. | |
377 | .Cx | |
81ddc115 KM |
378 | For C, source files are treated as modules named |
379 | by the file name without ``.c''. | |
b5dc1377 | 380 | .Pp |
81ddc115 KM |
381 | Expressions are specified with an approximately |
382 | common subset of C and Pascal (or equivalently Modula-2) syntax. | |
383 | Indirection can be denoted using either a prefix ``*'' or | |
384 | a postfix ``^'' and | |
b5dc1377 CL |
385 | array expressions are subscripted by brackets |
386 | .Cx (`` | |
387 | .Op | |
388 | .Cx \'\'). | |
389 | .Cx | |
0b6ba29a | 390 | The field reference operator (``.'') can be used with pointers |
b5dc1377 | 391 | as well as records, making the C operator ``\->'' unnecessary |
0b6ba29a | 392 | (although it is supported). |
b5dc1377 | 393 | .Pp |
81ddc115 KM |
394 | Types of expressions are checked; |
395 | the type of an expression may be overridden | |
b5dc1377 CL |
396 | by using |
397 | .Cx `` | |
398 | .Ar type-name (expression) | |
399 | .Cx \'\'. | |
400 | .Cx | |
81ddc115 | 401 | When there is no corresponding named type |
b5dc1377 CL |
402 | the special constructs |
403 | .Cx ``& | |
404 | .Ar type-name | |
405 | .Cx \'\' | |
406 | .Cx | |
407 | and | |
408 | .Cx ``$$ | |
409 | .Ar tag-name | |
410 | .Cx \'\' | |
411 | .Cx | |
81ddc115 | 412 | can be used to represent a pointer to a named type or C structure tag. |
b5dc1377 CL |
413 | .Dw Fl |
414 | .Di L | |
415 | .Dp Cx Ic assign | |
416 | .Cx \&\ \& | |
417 | .Ar variable | |
418 | .Ic = | |
419 | .Ar expression | |
420 | .Cx | |
81ddc115 | 421 | Assign the value of the expression to the variable. |
b5dc1377 CL |
422 | .Dp Cx Ic dump |
423 | .Cx \&\ \& | |
424 | .Op Ar procedure | |
425 | .Cx \&\ \& | |
426 | .Op Ic > Ar filename | |
427 | .Cx | |
81ddc115 KM |
428 | Print the names and values of variables in the given procedure, |
429 | or the current one if none is specified. | |
430 | If the procedure given is ``.'', then the all active variables | |
431 | are dumped. | |
b5dc1377 CL |
432 | .Dp Cx Ic print |
433 | .Cx \&\ \& | |
434 | .Ar expression | |
435 | .Cx \&\ \& | |
436 | .Op Ic \&, Ar expression ... | |
437 | .Cx | |
81ddc115 | 438 | Print out the values of the expressions. |
b5dc1377 CL |
439 | .Dp Cx Ic whatis |
440 | .Cx \&\ \& | |
441 | .Ar name | |
442 | .Cx | |
0b6ba29a KM |
443 | Print the declaration of the given name, which may be qualified |
444 | with block names as above. | |
b5dc1377 CL |
445 | .Dp Cx Ic which |
446 | .Cx \&\ \& | |
447 | .Ar identifier | |
448 | .Cx | |
0b6ba29a KM |
449 | Print the full qualification of the given identifer, i.e. |
450 | the outer blocks that the identifier is associated with. | |
b5dc1377 CL |
451 | .Dp Cx Ic up |
452 | .Cx \&\ \& | |
453 | .Op Ar count | |
454 | .Cx | |
455 | .Dp Cx Ic down | |
456 | .Cx \&\ \& | |
457 | .Op Ar count | |
458 | .Cx | |
81ddc115 | 459 | Move the current function, which is used for resolving names, |
b5dc1377 CL |
460 | up or down the stack |
461 | .Ar count | |
462 | levels. | |
463 | The default | |
464 | .Ar count | |
465 | is 1. | |
466 | .Dp Ic where | |
81ddc115 | 467 | Print out a list of the active procedures and function. |
b5dc1377 CL |
468 | .Dp Cx Ic whereis |
469 | .Cx \&\ \& | |
470 | .Ar identifier | |
471 | .Cx | |
0b6ba29a KM |
472 | Print the full qualification of all the symbols whose |
473 | name matches the given identifier. | |
474 | The order in which the symbols are printed is not meaningful. | |
b5dc1377 CL |
475 | .Ss Accessing Source Files |
476 | .Pp | |
477 | .Dp Cx Ar /regular expression | |
478 | .Op / | |
479 | .Cx | |
480 | .Dp Cx Ar ?regular expression | |
481 | .Op ? | |
482 | .Cx | |
81ddc115 KM |
483 | Search forward or backward in the current source file |
484 | for the given pattern. | |
b5dc1377 CL |
485 | .Dp Cx Ic edit |
486 | .Cx \&\ \& | |
487 | .Op Ar filename | |
488 | .Cx | |
489 | .Dp Cx Ic edit | |
490 | .Cx \&\ \& | |
491 | .Ar procedure/function-name | |
492 | .Cx | |
493 | Invoke an editor on | |
494 | .Ar filename | |
495 | or the current source file if none | |
0b6ba29a | 496 | is specified. |
b5dc1377 CL |
497 | If a |
498 | .Ar procedure | |
499 | or | |
500 | .Ar function | |
501 | name is specified, | |
0b6ba29a KM |
502 | the editor is invoked on the file that contains it. |
503 | Which editor is invoked by default depends on the installation. | |
504 | The default can be overridden by setting the environment variable | |
b5dc1377 CL |
505 | .Ev EDITOR |
506 | to the name of the desired editor. | |
507 | .Dp Cx Ic file | |
508 | .Cx \&\ \& | |
509 | .Op Ar filename | |
510 | .Cx | |
511 | Change the current source file name to | |
512 | .Ar filename . | |
0b6ba29a | 513 | If none is specified then the current source file name is printed. |
b5dc1377 CL |
514 | .Dp Cx Ic func |
515 | .Cx \&\ \& | |
516 | .Op Ar procedure/function | |
517 | .Cx | |
0b6ba29a KM |
518 | Change the current function. |
519 | If none is specified then print the current function. | |
520 | Changing the current function implicitly changes the current source file | |
521 | to the one that contains the function; it also changes the current scope | |
522 | used for name resolution. | |
b5dc1377 CL |
523 | .Dp Cx Ic list |
524 | .Cx \&\ \& | |
525 | .Op Ar source-line-number Op Ic \&, Ar source-line-number | |
526 | .Cx | |
527 | .Dp Cx Ic list | |
528 | .Cx \&\ \& | |
529 | .Ar procedure/function | |
530 | .Cx | |
0b6ba29a KM |
531 | List the lines in the current source file from the first line number to |
532 | the second inclusive. | |
533 | If no lines are specified, the next 10 lines are listed. | |
534 | If the name of a procedure or function is given | |
b5dc1377 CL |
535 | lines |
536 | .Ar n-k | |
537 | to | |
538 | .Ar n +k | |
539 | are listed where | |
540 | .Ar n | |
541 | is the first statement | |
542 | in the procedure or function and | |
543 | .Ar k | |
544 | is small. | |
545 | .Dp Cx Ic use | |
546 | .Cx \&\ \& | |
547 | .Ar directory-list | |
548 | .Cx | |
0b6ba29a KM |
549 | Set the list of directories to be searched |
550 | when looking for source files. | |
b5dc1377 CL |
551 | .Dp |
552 | .Ss Command Aliases and Variables | |
553 | .Dw Fl | |
554 | .Di L | |
555 | .Dp Cx Ic alias | |
556 | .Cx \&\ \& | |
557 | .Ar name | |
558 | .Cx \&\ \& | |
559 | .Ar name | |
560 | .Cx | |
561 | .Dp Cx Ic alias | |
562 | .Cx \&\ \& | |
563 | .Ar name | |
564 | .Cx \&\ \& | |
565 | .Ar string | |
566 | .Cx | |
567 | .Dp Cx Ic alias | |
568 | .Cx \&\ \& | |
569 | .Ar name (parameters) | |
570 | .Cx \&\ \& | |
571 | .Cx `` | |
572 | .Ar string | |
573 | .Cx \'\' | |
574 | .Cx | |
81ddc115 | 575 | When commands are processed, |
b5dc1377 | 576 | dbx first checks to see if the word |
81ddc115 | 577 | is an alias for either a command or a string. |
b5dc1377 | 578 | If it is an alias, then dbx treats the input as though |
81ddc115 KM |
579 | the corresponding string (with values substituted for any parameters) |
580 | had been entered. | |
581 | For example, | |
582 | to define an alias ``rr'' for the command ``rerun'', | |
583 | one can say | |
b5dc1377 CL |
584 | .Pp |
585 | .Dl alias rr rerun | |
586 | .Pp | |
81ddc115 KM |
587 | To define an alias called ``b'' that sets a stop at a particular line |
588 | one can say | |
b5dc1377 CL |
589 | .Pp |
590 | .Dl alias b(x) ``stop at x'' | |
591 | .Pp | |
81ddc115 | 592 | Subsequently, the command ``b(12)'' will expand to ``stop at 12''. |
b5dc1377 CL |
593 | .Pp |
594 | .Dp Cx Ic set | |
595 | .Ar name | |
596 | .Op \&= Ar expression | |
597 | .Cx | |
598 | The | |
599 | .Ic set | |
600 | command defines values for debugger variables. | |
81ddc115 KM |
601 | The names of these variables cannot conflict with names in the program |
602 | being debugged, and are expanded to the corresponding expression | |
603 | within other commands. | |
604 | The following variables have a special meaning: | |
b5dc1377 CL |
605 | .Dw Ds |
606 | .Di L | |
607 | .Dp Li $frame | |
608 | Setting this variable to an address causes dbx to use the stack frame | |
81ddc115 KM |
609 | pointed to by the address for |
610 | doing stack traces and accessing local variables. | |
611 | This facility is of particular use for kernel debugging. | |
b5dc1377 CL |
612 | .Dp Li $hexchars |
613 | .Dp Li $hexints | |
614 | .Dp Li $hexoffsets | |
615 | .Dp Li $hexstrings | |
616 | When set, dbx prints out | |
81ddc115 KM |
617 | out characters, integers, offsets from registers, or character pointers |
618 | respectively in hexadecimal. | |
b5dc1377 | 619 | .Dp Li $listwindow |
81ddc115 | 620 | The value of this variable specifies the number |
b5dc1377 CL |
621 | of lines to list around a function or when the |
622 | .Ic list | |
623 | command | |
81ddc115 KM |
624 | is given without any parameters. |
625 | Its default value is 10. | |
b5dc1377 CL |
626 | .Dp Li $mapaddrs |
627 | Setting (unsetting) this variable causes dbx to start (stop) | |
81ddc115 KM |
628 | mapping addresses. |
629 | As with ``$frame'', this is useful for kernel debugging. | |
b5dc1377 CL |
630 | .Dp Li $unsafecall |
631 | .Dp Li $unsafeassign | |
3e8dcebc DS |
632 | When ``$unsafecall'' is set, |
633 | strict type checking is turned off for arguments to | |
b5dc1377 CL |
634 | subroutine or function calls ( |
635 | .Ar e .g . | |
636 | in the | |
637 | .Ic call | |
638 | statement). | |
3e8dcebc DS |
639 | When ``$unsafeassign'' is set, |
640 | strict type checking between the two sides | |
b5dc1377 CL |
641 | of an |
642 | .Ic assign | |
643 | statement is turned off. | |
3e8dcebc | 644 | These variables should be used only with great care, |
b5dc1377 | 645 | because they severely limit dbx's usefulness |
3e8dcebc | 646 | for detecting errors. |
b5dc1377 CL |
647 | .Dp |
648 | .Dp Cx Ic unalias | |
649 | .Cx \&\ \& | |
650 | .Ar name | |
651 | .Cx | |
81ddc115 | 652 | Remove the alias with the given name. |
b5dc1377 CL |
653 | .Dp Cx Ic unset |
654 | .Cx \&\ \& | |
655 | .Ar name | |
656 | .Cx | |
657 | Delete the debugger variable associated with | |
658 | .Ar name . | |
659 | .Dp | |
660 | .Ss Machine Level Commands | |
661 | .Dw Fl | |
662 | .Di L | |
663 | .Dp Cx Ic tracei | |
664 | .Cx \&\ \& | |
665 | .Op Ar address | |
666 | .Cx \&\ \& | |
667 | .Op .Ic if Ar cond | |
668 | .Cx | |
669 | .Dp Cx Ic tracei | |
670 | .Cx \&\ \& | |
671 | .Op Ar variable | |
672 | .Cx \&\ \& | |
673 | .Op Ic at Ar address | |
674 | .Cx \&\ \& | |
675 | .Op Ic if Ar cond | |
676 | .Cx | |
677 | .Dp Cx Ic stopi | |
678 | .Cx \&\ \& | |
679 | .Op Ar address | |
680 | .Cx \&\ \& | |
681 | .Op Ic if Ar cond | |
682 | .Cx | |
683 | .Dp Cx Ic stopi | |
684 | .Cx \&\ \& | |
685 | .Op Ic at | |
686 | .Cx \&\ \& | |
687 | .Op Ar address | |
688 | .Cx \&\ \& | |
689 | .Op Ic if Ar cond | |
690 | .Cx | |
0b6ba29a | 691 | Turn on tracing or set a stop using a machine instruction address. |
b5dc1377 CL |
692 | .Dp Ic stepi |
693 | .Dp Ic nexti | |
694 | Single step as in | |
695 | .Ic step | |
696 | or | |
697 | .Ic next , | |
698 | but do a single instruction | |
0b6ba29a | 699 | rather than source line. |
b5dc1377 CL |
700 | .Dp Cx Ar address |
701 | .Cx \&, | |
702 | .Ar address | |
703 | .Cx \&/ | |
704 | .Op Ar mode | |
705 | .Cx | |
706 | .Dp Cx Ar address | |
707 | .Cx \&/ | |
708 | .Op Ar count | |
709 | .Op Ar mode | |
710 | .Cx | |
711 | Print the contents of memory starting at the first | |
712 | .Ar address | |
713 | and continuing up to the second | |
714 | .Ar address | |
715 | or until | |
716 | .Ar count | |
717 | items are printed. | |
81ddc115 | 718 | If the address is ``.'', the address following the one |
0b6ba29a | 719 | printed most recently is used. |
b5dc1377 CL |
720 | The |
721 | .Ar mode | |
722 | specifies how memory is to be printed; | |
0b6ba29a KM |
723 | if it is omitted the previous mode specified is used. |
724 | The initial mode is ``X''. | |
725 | The following modes are supported: | |
b5dc1377 CL |
726 | .Dw Cm |
727 | .Dp Cm i | |
0b6ba29a | 728 | print the machine instruction |
b5dc1377 | 729 | .Dp Cm d |
0b6ba29a | 730 | print a short word in decimal |
b5dc1377 | 731 | .Dp Cm D |
0b6ba29a | 732 | print a long word in decimal |
b5dc1377 | 733 | .Dp Cm o |
0b6ba29a | 734 | print a short word in octal |
b5dc1377 | 735 | .Dp Cm O |
0b6ba29a | 736 | print a long word in octal |
b5dc1377 | 737 | .Dp Cm x |
0b6ba29a | 738 | print a short word in hexadecimal |
b5dc1377 | 739 | .Dp Cm X |
0b6ba29a | 740 | print a long word in hexadecimal |
b5dc1377 | 741 | .Dp Cm b |
0b6ba29a | 742 | print a byte in octal |
b5dc1377 | 743 | .Dp Cm c |
0b6ba29a | 744 | print a byte as a character |
b5dc1377 | 745 | .Dp Cm s |
0b6ba29a | 746 | print a string of characters terminated by a null byte |
b5dc1377 | 747 | .Dp Cm f |
0b6ba29a | 748 | print a single precision real number |
b5dc1377 | 749 | .Dp Cm g |
0b6ba29a | 750 | print a double precision real number |
b5dc1377 CL |
751 | .Dp |
752 | .Pp | |
0b6ba29a KM |
753 | Symbolic addresses are specified by preceding the name with an ``&''. |
754 | Registers are denoted by ``$rN'' where N is the number of the register. | |
755 | Addresses may be expressions made up of other addresses and | |
756 | the operators ``+'', ``-'', and indirection (unary ``*''). | |
b5dc1377 CL |
757 | .Dp |
758 | .Ss Miscellaneous Commands | |
759 | .Tw Ic | |
760 | .Tp Ic gripe | |
761 | Invoke a mail program to send a message to the person in charge of | |
762 | .Nm dbx . | |
763 | .Tp Ic help | |
764 | Print out a synopsis of | |
765 | .Nm dbx | |
766 | commands. | |
767 | .Tp Ic quit | |
768 | Exit | |
769 | .Nm dbx . | |
770 | .Tp Cx Ic sh | |
771 | .Cx \&\ \& | |
772 | .Ar command-line | |
773 | .Cx | |
0b6ba29a KM |
774 | Pass the command line to the shell for execution. |
775 | The SHELL environment variable determines which shell is used. | |
b5dc1377 CL |
776 | .Tp Cx Ic source |
777 | .Cx \&\ \& | |
778 | .Ar filename | |
779 | .Cx | |
780 | Read | |
781 | .Nm dbx | |
782 | commands from the given | |
783 | .Ar filename . | |
784 | .Tp | |
785 | .Sh ENVIRONMENT | |
786 | .Nm Dbx | |
787 | checks these environment variables: | |
788 | .Ds I | |
789 | EDITOR | |
790 | HOME | |
791 | PATH | |
792 | SHELL | |
793 | .De | |
794 | .Sh FILES | |
795 | .Dw .dbxinit | |
796 | .Di L | |
797 | .Dp Pa a.out | |
0b6ba29a | 798 | object file |
b5dc1377 | 799 | .Dp Pa .dbxinit |
0b6ba29a | 800 | initial commands |
b5dc1377 CL |
801 | .Dp |
802 | .Sh SEE ALSO | |
803 | .Xr cc 1 , | |
804 | .Xr mod l , | |
805 | .Xr f77 1 , | |
806 | .Xr pc 1 | |
807 | .Sh HISTORY | |
808 | .Nm Dbx | |
809 | appeared in 4.2 BSD. | |
810 | .Sh BUGS | |
811 | .Nm Dbx | |
812 | suffers from the same ``multiple include'' malady as did | |
813 | .Nm sdb . | |
0b6ba29a KM |
814 | If you have a program consisting of a number of object files |
815 | and each is built from source files that include header files, | |
816 | the symbolic information for the header files is replicated in | |
817 | each object file. | |
818 | Since about one debugger start-up is done for each link, | |
b5dc1377 CL |
819 | having the linker |
820 | .Xr ld 1 | |
821 | re-organize the symbol information | |
81ddc115 | 822 | would not save much time, though it would reduce some of the |
0b6ba29a | 823 | disk space used. |
b5dc1377 | 824 | .Pp |
81ddc115 | 825 | This problem is an artifact of the unrestricted semantics |
0b6ba29a KM |
826 | of #include's in C; for example an include file can contain |
827 | static declarations that are separate entities for each file | |
828 | in which they are included. | |
81ddc115 KM |
829 | However, even with Modula-2 there is a substantial amount of duplication |
830 | of symbol information necessary for inter-module type checking. | |
b5dc1377 | 831 | .Pp |
3e8dcebc DS |
832 | Some problems remain with the support for individual languages. |
833 | Fortran problems include: | |
834 | inability to assign to logical, logical*2, complex | |
835 | and double complex variables; | |
836 | inability to represent parameter constants | |
837 | which are not type integer or real; | |
838 | peculiar representation for the values of dummy procedures | |
839 | (the value shown for a dummy procedure is actually | |
840 | the first few bytes of the procedure text; | |
841 | to find the location of the procedure, | |
842 | use ``&'' to take the address of the variable). |