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