Commit | Line | Data |
---|---|---|
95e5b261 HK |
1 | .RP |
2 | .TL | |
3 | Sdb: A Symbolic Debugger | |
4 | .AU "HO 4F-605" 5337 | |
5 | Howard P. Katseff | |
6 | .AI | |
7 | .HO | |
8 | .OK | |
9 | UNIX | |
10 | C programming | |
11 | Program testing | |
12 | .AB | |
13 | Sdb is a symbolic debugging program currently implemented for the | |
14 | language C on the UNIX/32V\s-2\u\(dg\d\s+2 Operating System. | |
15 | .FS | |
16 | \(dg\dUNIX is a trademark of Bell Laboratories | |
17 | .FE | |
18 | Sdb allows one to interact with a debugged program at the | |
19 | C language level. | |
20 | When debugging a core image from an aborted program, | |
21 | sdb reports which line in the C program caused the error | |
22 | and allows all variables, | |
23 | including array and structure elements, | |
24 | to be accessed symbolically | |
25 | and displayed in the correct format. | |
26 | .PP | |
27 | One may place breakpoints at selected statements | |
28 | or single step on a line by line basis. | |
29 | To facilitate specification of lines in the program without | |
30 | a source listing, | |
31 | a mechanism for examining the source text is also included in sdb. | |
32 | .PP | |
33 | Procedures may be called directly from the debugger. | |
34 | This feature is useful both for testing individual procedures | |
35 | and for calling user-provided routines which provide formatted | |
36 | printout of structured data. | |
37 | .AE | |
38 | .CS 6 4 10 0 0 2 | |
39 | .NH | |
40 | Introduction | |
41 | .PP | |
42 | This document describes a symbolic debugger, sdb, as implemented | |
43 | for C programs on the UNIX/V32\s-2\u\(dg\d\s+2 Operating System. | |
44 | .FS | |
45 | \(dg\dUNIX is a trademark of Bell Laboratories | |
46 | .FE | |
47 | Sdb is useful both for examining core images of aborted programs | |
48 | and for providing an environment in which execution of a program | |
49 | can be monitored and controlled. | |
50 | .NH | |
51 | Examining core images | |
52 | .PP | |
53 | In order to use sdb, | |
54 | it is necessary to compile the C program with the `\(mig' flag. | |
55 | This causes the compiler to generate additional information | |
56 | about the variables and statements of the compiled program. | |
57 | When the debug flag is specified, | |
58 | sdb can be used to obtain a trace of the called procedures | |
59 | at the time of the abort and interactively display the | |
60 | values of variables. | |
61 | .NH 2 | |
62 | Invoking sdb | |
63 | .PP | |
64 | A typical sequence of shell commands for debugging a core image is: | |
65 | .DS | |
66 | % cc \(mig foo.c \(mio foo | |
67 | % foo | |
68 | Bus error \(mi core dumped | |
69 | % sdb foo | |
70 | main:25: x[i] = 0; | |
71 | \v'.25m'*\v'-.25m' | |
72 | .DE | |
73 | .PP | |
74 | The program foo was compiled with the `\(mig' flag and then executed. | |
75 | An error occurred which caused a core dump. | |
76 | Sdb is then invoked to examine the core dump to determine the | |
77 | cause of the error. | |
78 | It reports that the Bus error occurred in procedure main at line 25 | |
79 | (line numbers are always relative to the beginning of the file) | |
80 | and outputs the source text of the offending line. | |
81 | Sdb then prompts the user with a `\v'.25m'*\v'-.25m'' indicating that it awaits | |
82 | a command. | |
83 | .PP | |
84 | It is useful to know that sdb has a notion of current | |
85 | procedure and current line. | |
86 | In this example, they are initially set to `main' and `25' | |
87 | respectively. | |
88 | .PP | |
89 | In the above example sdb was called with one argument, `foo'. | |
90 | In general it takes three arguments on the command line. | |
91 | The first is the name of the executable file which is to be | |
92 | debugged; | |
93 | It defaults to a.out when not specified. | |
94 | The second is the name of the core file, defaulting to core | |
95 | and the third is the name of the directory containing the source | |
96 | of the program being debugged. | |
97 | Sdb currently requires all source to reside in a single directory. | |
98 | The default is the working directory. | |
99 | In the example | |
100 | the second and third arguments defaulted to the correct values, | |
101 | so only the first was specified. | |
102 | .PP | |
103 | It is possible that the error occurred in a procedure which was | |
104 | not compiled with the debug flag. | |
105 | In this case, sdb prints the procedure name and the address at | |
106 | which the error occurred. | |
107 | The current line and procedure are set to the first line in main. | |
108 | Sdb will complain if main was not compiled with `\(mig' | |
109 | but debugging can continue for those routines compiled with the | |
110 | debug flag. | |
111 | .NH 2 | |
112 | Printing a stack trace | |
113 | .PP | |
114 | It is often useful to obtain a listing of the procedure calls | |
115 | which led to the error. | |
116 | This is obtained with the | |
117 | .B t | |
118 | command. | |
119 | For example: | |
120 | .DS | |
121 | \v'.25m'*\v'-.25m't | |
122 | sub(2,3) [foo.c:25] | |
123 | inter(16012) [foo.c:96] | |
124 | main(1,2147483584, 2147483592) [foo.c:15] | |
125 | .DE | |
126 | This indicates that the error occurred within the procedure sub | |
127 | at line 25 in file foo.c. | |
128 | Sub was called with the arguments 2 and 3 for inter at line 96. | |
129 | Inter was called from main at line 16. | |
130 | Main is always called by the shell with three arguments, | |
131 | often referred to as | |
132 | .I argc, | |
133 | .I argp | |
134 | and | |
135 | .I envp. | |
136 | Arguments in the call trace are always printed in decimal. | |
137 | .NH 2 | |
138 | Examining variables | |
139 | .PP | |
140 | Sdb can be used to display variables in the stopped program. | |
141 | Variables are displayed by typing their name followed by a slash, | |
142 | so | |
143 | .DS | |
144 | \v'.25m'*\v'-.25m'errflg/ | |
145 | .DE | |
146 | causes sdb to display the value of variable errflg. | |
147 | Unless otherwise specified, | |
148 | variables are assumed to be either local to or accessible from | |
149 | the current procedure. | |
150 | To specify a different procedure, use the form | |
151 | .DS | |
152 | \v'.25m'*\v'-.25m'sub:i/ | |
153 | .DE | |
154 | to display variable i in procedure sub. | |
155 | Section 3.2 will explain how to change the current procedure. | |
156 | .PP | |
157 | Sdb normally displays the variable in a format determined by | |
158 | its type as declared in the C program. | |
159 | To request a different format, a specifier is placed after | |
160 | the slash. | |
161 | The specifier consists of an optional length specification | |
162 | followed by the format. | |
163 | The length specifiers are | |
164 | .nr PD 0 | |
165 | .DS | |
166 | .IP \fBb\fP | |
167 | one byte | |
168 | .IP \fBh\fP | |
169 | two bytes (half word) | |
170 | .IP \fBl\fP | |
171 | four bytes (long word) | |
172 | .DE | |
173 | .nr PD 0.3v | |
174 | The lengths are only effective with the formats | |
175 | \fBd\fP, \fBo\fP, \fBx\fP and \fBu\fP. | |
176 | If no length is specified, the word length of the host machine, | |
177 | four for the DEC VAX-11/780\s-2\u\(dg\d\s+2, is used. | |
178 | .FS | |
179 | \(dg\dDEC and VAX are trademarks of Digital Equipment Corporation | |
180 | .FE | |
181 | There are a number of format specifiers available: | |
182 | .nr PD 0 | |
183 | .DS | |
184 | .DS | |
185 | .IP \fBc\fR | |
186 | character | |
187 | .IP \fBd\fP | |
188 | decimal | |
189 | .IP \fBu\fP | |
190 | decimal unsigned | |
191 | .IP \fBo\fP | |
192 | octal | |
193 | .IP \fBx\fP | |
194 | hexadecimal | |
195 | .IP \fBf\fP | |
196 | 32 bit single precision floating point | |
197 | .IP \fBg\fP | |
198 | 64 bit double precision floating point | |
199 | .IP \fBs\fP | |
200 | Assume variable is a string pointer and print characters until a null is | |
201 | reached. | |
202 | .IP \fBa\fP | |
203 | Print characters starting at the variable's address until a null | |
204 | is reached. | |
205 | .DE | |
206 | .DE | |
207 | .nr PD 0.3v | |
208 | As an example, | |
209 | variable i can be displayed in hexadecimal with the following command | |
210 | .DS | |
211 | \v'.25m'*\v'-.25m'i/x | |
212 | .DE | |
213 | .PP | |
214 | Sdb also knows about structures, one dimensional arrays and | |
215 | pointers | |
216 | so that all of the following commands work. | |
217 | .DS | |
218 | \v'.25m'*\v'-.25m'array[2]/ | |
219 | \v'.25m'*\v'-.25m'sym.id/ | |
220 | \v'.25m'*\v'-.25m'psym\(mi>usage/ | |
221 | \v'.25m'*\v'-.25m'xsym[20].p\(mi>usage/ | |
222 | .DE | |
223 | The only restriction is that array subscripts must be numbers. | |
224 | Note that, as a special case | |
225 | .DS | |
226 | \v'.25m'*\v'-.25m'psym\(mi>/d | |
227 | .DE | |
228 | displays the location pointed to by psym in decimal. | |
229 | .PP | |
230 | Core locations can also be displayed by specifying their absolute | |
231 | addresses. The command | |
232 | .DS | |
233 | \v'.25m'*\v'-.25m'1024/ | |
234 | .DE | |
235 | displays location 1024 in decimal. | |
236 | As in C, | |
237 | numbers may also be specified in octal or hexadecimal so the above | |
238 | command is equivalent to both of | |
239 | .DS | |
240 | \v'.25m'*\v'-.25m'02000/ | |
241 | \v'.25m'*\v'-.25m'0x400/ | |
242 | .DE | |
243 | It is possible to intermix numbers and variables, so that | |
244 | .DS | |
245 | \v'.25m'*\v'-.25m'1000.x/ | |
246 | .DE | |
247 | refers to an element of a structure starting at address 1000 and | |
248 | .DS | |
249 | \v'.25m'*\v'-.25m'1000\(mi>x/ | |
250 | .DE | |
251 | refers to an element of a structure whose address is at 1000. | |
252 | .PP | |
253 | The address of a variable is printed with the `=' command, so | |
254 | .DS | |
255 | \v'.25m'*\v'-.25m'i= | |
256 | .DE | |
257 | displays the address of i. | |
258 | Another feature whose usefulness will become apparent later is | |
259 | the command | |
260 | .DS | |
261 | \v'.25m'*\v'-.25m'./ | |
262 | .DE | |
263 | which redisplays the last variable typed. | |
264 | .NH | |
265 | Source file display and manipulation | |
266 | .PP | |
267 | Sdb has been designed to make it easy to debug a program without | |
268 | constant reference to a current source listing. | |
269 | Facilities are provided which perform context searches | |
270 | within the source files of the program being debugged | |
271 | and to display selected portions of the source files. | |
272 | The commands are similar to those of the UNIX editor ed and ex [1]. | |
273 | Like these editors, | |
274 | sdb has a notion of current file and line within the file. | |
275 | Sdb also knows how the lines of a file are partitioned into | |
276 | procedures, so that it also has a notion of current procedure. | |
277 | As noted in other parts of this document, | |
278 | the current procedure is used by a number of sdb commands. | |
279 | .NH 2 | |
280 | Displaying the source file | |
281 | .PP | |
282 | Four command exist for displaying lines in the source file. | |
283 | They are useful for perusing through the source program | |
284 | and for determining the context of the current line. | |
285 | The commands are | |
286 | .DS | |
287 | .IP \fBw\fP | |
288 | Window. Print a window of 10 lines around the current line. | |
289 | .IP \fBz\fP | |
290 | Print 10 lines starting at the current line. | |
291 | Advance the current line by 10. | |
292 | .IP | |
293 | .ti 0 | |
294 | \fBcontrol-D\fP | |
295 | .br | |
296 | .sp -1 | |
297 | Scroll. | |
298 | Print the next 10 lines and advance the current line by 10. | |
299 | This command is used to cleanly display longs segments of the program. | |
300 | .DE | |
301 | .PP | |
302 | There is also a | |
303 | .B p | |
304 | command which prints the current line. | |
305 | When a line from a file is printed, it is preceded by its line number. | |
306 | This not only gives an indication of its relative position in the file, | |
307 | but is also used as input by some sdb commands. | |
308 | .NH 2 | |
309 | Changing the current source file or procedure | |
310 | .PP | |
311 | The | |
312 | .B e | |
313 | command is used to change the current source file. | |
314 | Either of the forms | |
315 | .DS | |
316 | \v'.25m'*\v'-.25m'e procedure | |
317 | \v'.25m'*\v'-.25m'e file.c | |
318 | .DE | |
319 | may be used. | |
320 | The first causes the file containing the named procedure | |
321 | to become the current file | |
322 | and the current line becomes the first line of the procedure. | |
323 | The other form causes the named file to become current. | |
324 | In this case the current line is set to the first line of the named file. | |
325 | Finally, | |
326 | an | |
327 | .B e | |
328 | command with no argument causes the current procedure and file named | |
329 | to be printed. | |
330 | .NH 2 | |
331 | Changing the current line in the source file | |
332 | .PP | |
333 | As mentioned in section 3.1, | |
334 | the | |
335 | .B z | |
336 | and | |
337 | .B control-D | |
338 | commands have a side effect of changing the current line in the | |
339 | source file. | |
340 | This section describes other commands which change the current line. | |
341 | .PP | |
342 | There are two commands for searching for regular expressions in | |
343 | source files. | |
344 | They are | |
345 | .DS | |
346 | \v'.25m'*\v'-.25m'/regular expression/ | |
347 | \v'.25m'*\v'-.25m'?regular expression? | |
348 | .DE | |
349 | The first command searches forward through the file for a line containing | |
350 | a string which matches the regular expression and the second searches | |
351 | backwards. | |
352 | The trailing `/' and `?' may be omitted from these commands. | |
353 | Regular expression matching is identical to that of ed. | |
354 | .PP | |
355 | The | |
356 | .B + | |
357 | and | |
358 | .B \(mi | |
359 | commands | |
360 | may be used to move the current line forwards or backwards by a | |
361 | specified number of lines. | |
362 | Typing a newline advances the current line by one | |
363 | and | |
364 | typing a number causes that line to become the current line | |
365 | in the file. | |
366 | These commands may be catenated with the display commands so that | |
367 | .DS | |
368 | \v'.25m'*\v'-.25m'+15z | |
369 | .DE | |
370 | advances the current line by 15 and then prints 10 lines. | |
371 | .NH | |
372 | A controlled environment for program testing | |
373 | .PP | |
374 | One very useful feature of sdb | |
375 | is breakpoint debugging. | |
376 | After entering the debugger, | |
377 | certain lines in the source program may be specified to be | |
378 | .I breakpoints. | |
379 | The program is then started with a sdb command. | |
380 | Execution of the program proceeds as normal until | |
381 | it is about to execute one of the lines at which a breakpoint has | |
382 | been set. | |
383 | The program stops and sdb reports which breakpoint the | |
384 | program is stopped at. | |
385 | Now, sdb commands may be used to display | |
386 | the trace of procedure calls and the values of variables. | |
387 | If the user is satisfied that the program is working correctly | |
388 | to this point, some breakpoints can be deleted and others set, | |
389 | and then program execution may be continued from the point where it stopped. | |
390 | .PP | |
391 | A useful alternative to setting breakpoints is single stepping. | |
392 | Sdb can be requested to execute the next line of the program | |
393 | and them stop. | |
394 | This feature is especially useful for testing new programs, | |
395 | so they can be verified on a statement by statement basis. | |
396 | Note that if an attempt is made to single step through a | |
397 | procedure which has not been compiled with the `\(mig' flag, | |
398 | execution proceeds until a statement in a procedure compiled | |
399 | with the debug flag is reached. | |
400 | .PP | |
401 | The current implementation of single | |
402 | stepping is rather slow. | |
403 | While this is not a problem when stepping through a single statement, | |
404 | it may result in long delays while stepping through procedures not | |
405 | compiled with the debug flag. | |
406 | This problem is partially alleviated with the | |
407 | .B n | |
408 | command which quickly single steps until the | |
409 | positionally next statement is reached. | |
410 | .NH 2 | |
411 | Setting and deleting breakpoints | |
412 | .PP | |
413 | Breakpoints can be set at any line in a procedure which contains | |
414 | executable code. | |
415 | The command format is: | |
416 | .DS | |
417 | \v'.25m'*\v'-.25m'12b | |
418 | \v'.25m'*\v'-.25m'proc:12b | |
419 | \v'.25m'*\v'-.25m'proc:b | |
420 | .DE | |
421 | The first form sets a breakpoint at line 12 in the current procedure. | |
422 | The line numbers are relative to the beginning of the file, | |
423 | as printed by the source file display commands. | |
424 | The second form sets a breakpoint at line 12 of procedure proc and the third | |
425 | sets a breakpoint at the first line of proc. | |
426 | .PP | |
427 | Breakpoints are deleted similarly with the commands: | |
428 | .DS | |
429 | \v'.25m'*\v'-.25m'12d | |
430 | \v'.25m'*\v'-.25m'proc:12d | |
431 | \v'.25m'*\v'-.25m'proc:d | |
432 | .DE | |
433 | In addition, | |
434 | if the command | |
435 | .B d | |
436 | is given alone, | |
437 | the breakpoints are deleted interactively. | |
438 | Each breakpoint location is printed and a line is read from the | |
439 | user. | |
440 | If the line begins with a `y' or `d', the breakpoint is deleted. | |
441 | .PP | |
442 | A list of the current breakpoints is printed in response to | |
443 | a | |
444 | .B b | |
445 | command. | |
446 | Beware that breakpoints do strange things if the debugged program | |
447 | is being run elsewhere at the same time. | |
448 | .NH 2 | |
449 | Running the program | |
450 | .PP | |
451 | The | |
452 | .B r | |
453 | command is used to begin program execution. | |
454 | It restarts the program as if it were invoked from the shell. | |
455 | The command | |
456 | .DS | |
457 | \v'.25m'*\v'-.25m'r args | |
458 | .DE | |
459 | runs the program with the given arguments, | |
460 | as if they had been typed on the shell command line. | |
461 | .PP | |
462 | Execution is continued after a breakpoint with the | |
463 | .B c | |
464 | command | |
465 | and single stepping is accomplished with \fBs\fP. | |
466 | The | |
467 | .B n | |
468 | command is used to run the program until it reaches the positionally | |
469 | next statement. | |
470 | .PP | |
471 | Program execution can also be stopped with the RUBOUT key. | |
472 | The debugger is entered as if a breakpoint was encountered | |
473 | so that execution may be continued with | |
474 | \fBc\fP, \fBs\fP or \fBn\fP. | |
475 | .NH 2 | |
476 | Calling procedures | |
477 | .PP | |
478 | It is possible to call any of the procedures of the program from | |
479 | the debugger. | |
480 | This feature is useful both for testing individual procedures | |
481 | with different arguments and for calling a procedure which | |
482 | prints structured data in a nice way. | |
483 | There are two ways to call a procedure: | |
484 | .DS | |
485 | \v'.25m'*\v'-.25m'proc(arg1, arg2, ...) | |
486 | \v'.25m'*\v'-.25m'proc(arg1, arg2, ...)/ | |
487 | .DE | |
488 | The first simply executes the procedure. | |
489 | The second is intended for calling functions: | |
490 | It executes the procedure and prints the value that it returns. | |
491 | The value is printed in decimal unless some other | |
492 | format is specified. | |
493 | Arguments to procedures may be integer, character or string constants, | |
494 | or values of variables which are accessible from the current | |
495 | procedure. | |
496 | .PP | |
497 | An unfortunate bug in the current implementation is that | |
498 | if a procedure is called when the program is | |
499 | .I not | |
500 | stopped at a breakpoint | |
501 | (such as when a core image is being debugged), | |
502 | static variables are reinitialized before the procedure is | |
503 | restarted. | |
504 | This makes it impossible to use a procedure which | |
505 | formats data from a dump. | |
506 | .NH | |
507 | Other commands | |
508 | .PP | |
509 | To exit the debugger, use the | |
510 | .B q | |
511 | command. | |
512 | .PP | |
513 | The | |
514 | .B ! | |
515 | command is identical to that in ed and is used to have the shell | |
516 | execute a command. | |
517 | .PP | |
518 | It is possible to change the values of variables when the program | |
519 | is stopped at a breakpoint. This is done with the command | |
520 | .DS | |
521 | \v'.25m'*\v'-.25m'variable!value | |
522 | .DE | |
523 | which sets the variable to the given value. | |
524 | The value may be a number, character constant or the name of | |
525 | another variable. | |
526 | .SH | |
527 | Acknowledgments | |
528 | .PP | |
529 | I would like to thank Bill Joy and Chuck Haley | |
530 | for their comments and constructive criticisms. | |
531 | .SH | |
532 | Reference | |
533 | .IP [1] | |
534 | William N. Joy, Ex Reference Manual, Computer Science Division, | |
535 | University of California, Berkeley, November 1977. | |
536 | .LP | |
537 | .SG HO-1353-hpk-sdb | |
538 | .bp | |
539 | .SH | |
540 | Appendix 1. Example of usage. | |
541 | .bp | |
542 | .SH | |
543 | Appendix 2. Manual pages. |