Commit | Line | Data |
---|---|---|
9023b93d KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
7e5e5e65 | 5 | .\" @(#)sdb.1 6.1 (Berkeley) %G% |
9023b93d | 6 | .\" |
7e5e5e65 | 7 | .TH SDB 1 "%G%" |
9023b93d KM |
8 | .UC 4 |
9 | .SH NAME | |
10 | sdb \- symbolic debugger | |
11 | .SH SYNOPSIS | |
12 | .B sdb | |
13 | [ objfil [ corfil [ directory ] ] ] | |
14 | .SH DESCRIPTION | |
15 | .I Sdb | |
16 | is a symbolic debugger which can be used with C, PASCAL, and F77 programs. | |
17 | It may be used to examine their files and to provide | |
18 | a controlled environment for their execution. | |
19 | .PP | |
20 | .I Objfil | |
21 | is an executable program file | |
22 | which has been compiled with the \-g (debug) option. | |
23 | The default for | |
24 | .I objfil | |
25 | is | |
26 | .B a.out. | |
27 | .I Corfil | |
28 | is assumed to be a core image file produced after | |
29 | executing | |
30 | .IR objfil ; | |
31 | the default for | |
32 | .I corfil | |
33 | is | |
34 | .B core. | |
35 | The core file need not be present. | |
36 | .PP | |
37 | It is useful to know that at any time there is a | |
38 | .I "current line" | |
39 | and | |
40 | .I "current file." | |
41 | If | |
42 | .I corfil | |
43 | exists then they are initially set to the line and file | |
44 | containing the source statement at which the process terminated or stopped. | |
45 | Otherwise, they are set to the first line in main. | |
46 | The current line and file may be changed with the source file | |
47 | examination commands. | |
48 | .PP | |
49 | Names of variables are written just as they are in C, PASCAL, or F77. | |
50 | Variables local to a procedure may be accessed using the form | |
51 | `procedure:variable'. | |
52 | If no procedure name is given, the procedure containing the | |
53 | current line is used by default. | |
54 | It is also possible to refer to structure members as `variable.member', | |
55 | pointers to structure members as `variable\(mi>member' and array elements | |
56 | as `variable[number]'. | |
57 | Combinations of these forms may also be used. | |
58 | .PP | |
59 | It is also possible to specify a variable by its address. | |
60 | All forms of integer constants which are valid in C may be used, so that | |
61 | addresses may be input in decimal, octal or hexadecimal. | |
62 | .PP | |
63 | Line numbers in the source program are referred to as `filename:number' | |
64 | or `procedure:number'. | |
65 | In either case the number is relative to the beginning of the file. | |
66 | If no procedure or file name is given, | |
67 | the current file is used by default. | |
68 | If no number is given, | |
69 | the first line of the named procedure or file is used. | |
70 | .sp 1 | |
71 | .PP | |
72 | The commands for examining data in the program are: | |
73 | .TP 5 | |
74 | .B t | |
75 | Print a stack trace of the terminated or stopped program. | |
76 | .TP 5 | |
77 | .B T | |
78 | Print the top line of the stack trace. | |
79 | .TP 5 | |
80 | variable/\fIlm\fP | |
81 | Print the value of variable according to | |
82 | length | |
83 | .I l | |
84 | and format | |
85 | .I m. | |
86 | If | |
87 | .I l | |
88 | and | |
89 | .I m | |
90 | are omitted, | |
91 | sdb chooses a length and format suitable for the variable's type | |
92 | as declared in the program. | |
93 | The length specifiers are: | |
94 | .RS | |
95 | .TP | |
96 | .BI b | |
97 | one byte | |
98 | .br | |
99 | .ns | |
100 | .TP | |
101 | .BI h | |
102 | two bytes (half word) | |
103 | .br | |
104 | .ns | |
105 | .TP | |
106 | .BI l | |
107 | four bytes (long word) | |
108 | .br | |
109 | .ns | |
110 | .TP | |
111 | number | |
112 | string length for formats | |
113 | .B s | |
114 | and | |
115 | .B a | |
116 | .RE | |
117 | .TP 5 | |
118 | \ | |
119 | Legal values for | |
120 | .I m | |
121 | are: | |
122 | .RS | |
123 | .TP | |
124 | .BI c | |
125 | character | |
126 | .br | |
127 | .ns | |
128 | .TP | |
129 | .BI d | |
130 | decimal | |
131 | .br | |
132 | .ns | |
133 | .TP | |
134 | .BI u | |
135 | decimal, unsigned | |
136 | .br | |
137 | .ns | |
138 | .TP | |
139 | .BI o | |
140 | octal | |
141 | .br | |
142 | .ns | |
143 | .TP | |
144 | .BI x | |
145 | hexadecimal | |
146 | .br | |
147 | .ns | |
148 | .TP | |
149 | .BI f | |
150 | 32 bit single precision floating point | |
151 | .br | |
152 | .ns | |
153 | .TP | |
154 | .BI g | |
155 | 64 bit double precision floating point | |
156 | .br | |
157 | .ns | |
158 | .TP | |
159 | .BI s | |
160 | Assume variable is a string pointer and print characters until a null is | |
161 | reached. | |
162 | .br | |
163 | .ns | |
164 | .TP | |
165 | .BI a | |
166 | Print characters starting at the variable's address until a null | |
167 | is reached. | |
168 | .br | |
169 | .ns | |
170 | .TP | |
171 | .BI p | |
172 | pointer to procedure | |
173 | .RE | |
174 | .TP 5 | |
175 | \ | |
176 | The length specifiers are only effective with the formats | |
177 | \fBd\fP, \fBu\fP, \fBo\fP and \fBx\fP. | |
178 | If | |
179 | one of these formats | |
180 | is specified and | |
181 | .I l | |
182 | is omitted, | |
183 | the length | |
184 | defaults to the word length of the host machine; | |
185 | 4 for the DEC VAX/11-780. | |
186 | The last variable may be redisplayed with the command `./'. | |
187 | .sp | |
188 | The sh(1) metacharacters | |
189 | .B * | |
190 | and | |
191 | .B ? | |
192 | may be used within procedure and variable names, | |
193 | providing a limited form of pattern matching. | |
194 | If no procedure name is given, both variables local to the current | |
195 | procedure and global (common for F77) variables are matched, | |
196 | while if a procedure name is specified then | |
197 | only variables local to that procedure and matched. | |
198 | To match only global variables (or blank common for F77), | |
199 | the form `:pattern' is used. | |
200 | The name of a common block may be specified instead of a procedure name | |
201 | for F77 programs. | |
202 | .RE | |
203 | .TP 5 | |
204 | variable\fB=\fP\fIlm\fP | |
205 | .br | |
206 | .ns | |
207 | .TP 5 | |
208 | linenumber\fB=\fP\fIlm\fP | |
209 | .br | |
210 | .ns | |
211 | .TP 5 | |
212 | number\fB=\fP\fIlm\fP | |
213 | Print the address of the variable or line number or the value of the number | |
214 | in the specified format. | |
215 | If no format is given, then `lx' is used. | |
216 | The last variant of this command provides a convenient way to convert | |
217 | between decimal, octal and hexadecimal. | |
218 | .TP 5 | |
219 | variable\fB!\fPvalue | |
220 | Set the variable to the given value. | |
221 | The value may be a number, character constant or a variable. | |
222 | If the variable is of type float or double, | |
223 | the value may also be a floating constant. | |
224 | .sp 1 | |
225 | .PP | |
226 | The commands for examining source files are | |
227 | .TP 5 | |
228 | \fBe\fP procedure | |
229 | .br | |
230 | .ns | |
231 | .TP 5 | |
232 | \fBe\fP filename.c | |
233 | Set the current file to | |
234 | the file containing the named procedure | |
235 | or the named filename. | |
236 | Set the current line to the first line in the named | |
237 | procedure or file. | |
238 | All source files are assumed to be in | |
239 | .I directory. | |
240 | The default for | |
241 | .I directory | |
242 | is the working directory. | |
243 | If no procedure or file name is given, the current procedure and file names | |
244 | are reported. | |
245 | .TP 5 | |
246 | \fB/\fPregular expression\fB/\fP | |
247 | Search forward from the current line for a line containing | |
248 | a string matching the regular expression as in ed(1). | |
249 | The trailing `/' may be elided. | |
250 | .TP 5 | |
251 | \fB?\fPregular expression\fB?\fP | |
252 | Search backward from the current line for a line containing | |
253 | a string matching the regular expression as in ed(1). | |
254 | The trailing `?' may be elided. | |
255 | .TP 5 | |
256 | .B p | |
257 | Print the current line. | |
258 | .TP 5 | |
259 | .B z | |
260 | Print the current line followed by the next 9 lines. | |
261 | Set the current line to the last line printed. | |
262 | .TP 5 | |
263 | .B control-D | |
264 | Scroll. | |
265 | Print the next 10 lines. | |
266 | Set the current line to the last line printed. | |
267 | .TP 5 | |
268 | .B w | |
269 | Window. | |
270 | Print the 10 lines around the current line. | |
271 | .TP 5 | |
272 | number | |
273 | Set the current line to the given line number. | |
274 | Print the new current line. | |
275 | .TP 5 | |
276 | \fIcount\fB +\fR | |
277 | Advance the current line by \fIcount\fP lines. | |
278 | Print the new current line. | |
279 | .TP 5 | |
280 | \fIcount\fB \(mi\fR | |
281 | Retreat the current line by \fIcount\fP lines. | |
282 | Print the new current line. | |
283 | .sp 1 | |
284 | .PP | |
285 | The commands for controlling the execution of the source program are: | |
286 | .TP 5 | |
287 | \fIcount\fB r \fIargs\fR | |
288 | .br | |
289 | .ns | |
290 | .TP 5 | |
291 | \fIcount\fB R | |
292 | Run the program with the given arguments. | |
293 | The \fBr\fP command with no arguments reuses the previous arguments | |
294 | to the program while the \fBR\fP command | |
295 | runs the program with no arguments. | |
296 | An argument beginning with `<' or `>' causes redirection for the | |
297 | standard input or output respectively. | |
298 | If \fIcount\fP is given, | |
299 | it specifies the number of breakpoints to be ignored. | |
300 | .TP 5 | |
301 | \fIlinenumber\fB c\fI count\fR | |
302 | .br | |
303 | .ns | |
304 | .TP 5 | |
305 | \fIlinenumber\fB C\fI count\fR | |
306 | Continue after a breakpoint or interrupt. | |
307 | If \fIcount\fP is given, | |
308 | it specifies the number of breakpoints to be ignored. | |
309 | \fBC\fP continues with the signal which caused the program to stop and | |
310 | \fBc\fP ignores it. | |
311 | .sp 0.5 | |
312 | If a linenumber is specified | |
313 | then a temporary breakpoint is placed at the line | |
314 | and execution is continued. | |
315 | The breakpoint is deleted when the command finishes. | |
316 | .TP 5 | |
317 | \fIcount\fB s\fR | |
318 | Single step. | |
319 | Run the program through \fIcount\fP lines. | |
320 | If no count is given then the program is run for one line. | |
321 | .TP 5 | |
322 | \fIcount\fB S\fR | |
323 | Single step, but step through subroutine calls. | |
324 | .TP 5 | |
325 | .B k | |
326 | Kill the debugged program. | |
327 | .TP 5 | |
328 | procedure\fB(\fParg1,arg2,...\fB)\fP | |
329 | .br | |
330 | .ns | |
331 | .TP 5 | |
332 | procedure\fB(\fParg1,arg2,...\fB)/\fP\fIm\fP | |
333 | Execute the named procedure with the given arguments. | |
334 | Arguments can be integer, character or string constants | |
335 | or names of variables accessible from the current procedure. | |
336 | The second form causes the value returned by the procedure to be | |
337 | printed according to format \fIm\fP. | |
338 | If no format is given, it defaults to `d'. | |
339 | .TP 5 | |
340 | \fIlinenumber\fB b\fR \fIcommands\fR | |
341 | Set a breakpoint at the given line. | |
342 | If a procedure name without a line number is given (e.g. `proc:'), | |
343 | a breakpoint is placed at the first line in the procedure | |
344 | even if it was not compiled with the debug flag. | |
345 | If no \fIlinenumber\fP is given, | |
346 | a breakpoint is placed at the current line. | |
347 | .sp 0.5 | |
348 | If no | |
349 | .I commands | |
350 | are given then execution stops just before the breakpoint | |
351 | and control is returned to sdb. | |
352 | Otherwise | |
353 | the | |
354 | .I commands | |
355 | are executed when the breakpoint is | |
356 | encountered and execution continues. | |
357 | Multiple commands are specified by separating them with semicolons. | |
358 | .TP 5 | |
359 | \fIlinenumber\fB d\fR | |
360 | Delete a breakpoint at the given line. | |
361 | If no \fIlinenumber\fP is given then the breakpoints are deleted interactively: | |
362 | Each breakpoint location is printed and a line is read from the standard input. | |
363 | If the line begins with a `y' or `d' then the breakpoint is deleted. | |
364 | .TP 5 | |
365 | .B B | |
366 | Print a list of the currently active breakpoints. | |
367 | .TP 5 | |
368 | .B D | |
369 | Delete all breakpoints. | |
370 | .TP 5 | |
371 | l | |
372 | Print the last executed line. | |
373 | .TP 5 | |
374 | \fIlinenumber\fB a\fR | |
375 | Announce. | |
376 | If \fIlinenumber\fR is of the form `proc:number', the command | |
377 | effectively does a `linenumber b l'. | |
378 | If \fIlinenumber\fR is of the form `proc:', the command | |
379 | effectively does a `proc: b T'. | |
380 | .sp 1 | |
381 | .PP | |
382 | Miscellaneous commands. | |
383 | .TP 5 | |
384 | \fB! \fIcommand\fR | |
385 | The command is interpreted by sh(1). | |
386 | .TP 5 | |
387 | .B newline | |
388 | If the previous command printed a source line then | |
389 | advance the current line by 1 line and | |
390 | print the new current line. | |
391 | If the previous command displayed a core location then | |
392 | display the next core location. | |
393 | .TP 5 | |
394 | \fB"\fI string\fR | |
395 | Print the given string. | |
396 | .TP 5 | |
397 | .B q | |
398 | Exit the debugger. | |
399 | .sp 1 | |
400 | .PP | |
401 | The following commands also exist and are intended only for | |
402 | debugging the debugger. | |
403 | .TP 5 | |
404 | .B V | |
405 | Print the version number. | |
406 | .TP 5 | |
407 | .B X | |
408 | Print a list of procedures and files being debugged. | |
409 | .TP 5 | |
410 | .B Y | |
411 | Toggle debug output. | |
412 | .SH FILES | |
413 | a.out | |
414 | .br | |
415 | core | |
416 | .SH SEE\ ALSO | |
417 | adb(1) | |
418 | .SH DIAGNOSTICS | |
419 | Error reports are either identical to those of adb(1) or are | |
420 | self-explanatory. | |
421 | .SH BUGS | |
422 | If a procedure is called when the program is | |
423 | .I not | |
424 | stopped at a breakpoint | |
425 | (such as when a core image is being debugged), | |
426 | all variables are initialized before the procedure is started. | |
427 | This makes it impossible to use a procedure which formats | |
428 | data from a core image. | |
429 | .PP | |
430 | Arrays must be of one dimension and of zero origin to be correctly | |
431 | addressed by sdb. | |
432 | .PP | |
433 | The default type for printing F77 parameters is incorrect. | |
434 | Their address is printed instead of their value. | |
435 | .PP | |
436 | Tracebacks containing F77 subprograms with multiple entry points | |
437 | may print too many arguments in the wrong order, but their values | |
438 | are correct. | |
439 | .PP | |
440 | Sdb understands Pascal, but not its types. |