Commit | Line | Data |
---|---|---|
2839532b KB |
1 | .\" Copyright (c) 1983, 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
ed68ddb1 | 3 | .\" |
3441b3a6 | 4 | .\" %sccs.include.redist.roff% |
ed68ddb1 | 5 | .\" |
2839532b | 6 | .\" @(#)pdx.1 8.1 (Berkeley) %G% |
b5dc1377 CL |
7 | .\" |
8 | .Dd | |
9 | .Dt PDX 1 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm pdx | |
13 | .Nd pascal debugger | |
14 | .Sh SYNOPSIS | |
15 | .Nm pdx | |
16 | .Op Fl r | |
17 | .Op Ar objfile | |
18 | .Sh DESCRIPTION | |
19 | .Nm Pdx | |
20 | is a tool for source level debugging and execution of | |
ed68ddb1 | 21 | Pascal programs. |
b5dc1377 CL |
22 | The |
23 | .Ar objfile | |
24 | is an object file produced by the Pascal translator | |
25 | .Xr pi 1 . | |
26 | If no | |
27 | .Ar objfile | |
28 | is specified, | |
29 | .Nm pdx | |
30 | looks | |
ed68ddb1 KM |
31 | for a file named ``obj'' in the current directory. |
32 | The object file contains a symbol table which includes the name of the | |
b5dc1377 CL |
33 | all the source files translated by |
34 | .Xr pi 1 | |
35 | to create it. | |
ed68ddb1 | 36 | These files are available for perusal while using the debugger. |
b5dc1377 CL |
37 | .Pp |
38 | If the file | |
39 | .Dq Pa .pdxinit | |
40 | exists in the current directory, then the | |
ed68ddb1 | 41 | debugger commands in it are executed. |
b5dc1377 | 42 | .Pp |
3441b3a6 CL |
43 | .Bl -tag -width flag r |
44 | .It Fl r | |
b5dc1377 CL |
45 | The |
46 | .Fl r | |
47 | option causes the | |
48 | .Ar objfile | |
49 | to be executed immediately; | |
50 | if it terminates successfully | |
51 | .Nm pdx | |
52 | exits. | |
ed68ddb1 KM |
53 | Otherwise it reports the reason for termination |
54 | and offers the user the option of entering the debugger | |
b5dc1377 CL |
55 | or simply letting |
56 | .Xr px | |
57 | continue with a traceback. | |
58 | If | |
59 | .Fl r | |
60 | is not specified, | |
61 | .Nm pdx | |
62 | just prompts and waits for a command. | |
3441b3a6 | 63 | .El |
b5dc1377 | 64 | .Pp |
ed68ddb1 | 65 | The commands are: |
3441b3a6 CL |
66 | .Pp |
67 | .Bl -tag -width flag -compact | |
68 | .It Xo | |
69 | .Ic run | |
b5dc1377 | 70 | .Op Ar args |
b5dc1377 | 71 | .Op Ic \&< Ar filename |
b5dc1377 | 72 | .Op Ic \&> Ar filename |
3441b3a6 | 73 | .Xc |
b5dc1377 CL |
74 | Start executing |
75 | .Ar objfile , | |
76 | passing | |
77 | .Ar args | |
78 | as command line arguments; | |
79 | .Ic \&< | |
80 | or | |
81 | .Ic \&> | |
82 | can be used to redirect input or output in the usual manner. | |
83 | .Pp | |
3441b3a6 CL |
84 | .It Xo |
85 | .Ic trace | |
b5dc1377 | 86 | .Op Ic in Ar procedure/function |
3441b3a6 CL |
87 | .Op Ic if Ar condition |
88 | .Xc | |
89 | .It Xo | |
90 | .Ic trace | |
b5dc1377 CL |
91 | .Ar source-line-number |
92 | .Op Ic if Ar condition | |
3441b3a6 CL |
93 | .Xc |
94 | .It Xo | |
95 | .Ic trace | |
b5dc1377 | 96 | .Ar procedure/function |
b5dc1377 | 97 | .Op Ic in Ar procedure/function |
3441b3a6 CL |
98 | .Op Ic if Ar condition |
99 | .Xc | |
100 | .It Xo | |
101 | .Ic trace | |
102 | .Ar expression Ic at Ar source-line-number | |
103 | .Op Ic if Ar condition | |
104 | .Xc | |
105 | .It Xo | |
106 | .Ic trace | |
b5dc1377 | 107 | .Ar variable |
b5dc1377 | 108 | .Op Ic in Ar procedure/function |
3441b3a6 CL |
109 | .Op Ic if Ar condition |
110 | .Xc | |
ed68ddb1 KM |
111 | Have tracing information printed when the program is executed. |
112 | A number is associated with the command that is used | |
b5dc1377 CL |
113 | to turn the tracing off (see the |
114 | .Ic delete | |
115 | command). | |
116 | .Pp | |
ed68ddb1 | 117 | The first argument describes what is to be traced. |
b5dc1377 CL |
118 | If it is a |
119 | .Ar source-line-number , | |
120 | then the line is printed | |
ed68ddb1 KM |
121 | immediately prior to being executed. |
122 | Source line numbers in a file other than the current one | |
123 | must be preceded by the name of the file and a colon, e.g. | |
124 | ``mumble.p:17''. | |
b5dc1377 | 125 | .Pp |
ed68ddb1 KM |
126 | If the argument is a procedure or function name then |
127 | every time it is called, information is printed telling | |
128 | what routine called it, from what source line it was called, | |
129 | and what parameters were passed to it. | |
130 | In addition, its return is noted, and if it's a function | |
131 | then the value it is returning is also printed. | |
b5dc1377 CL |
132 | .Pp |
133 | If the argument is an | |
134 | .Ar expression | |
135 | with an | |
136 | .Ic at | |
137 | clause | |
ed68ddb1 KM |
138 | then the value of the expression is printed whenever the |
139 | identified source line is reached. | |
b5dc1377 | 140 | .Pp |
ed68ddb1 KM |
141 | If the argument is a variable then the name and value of the variable |
142 | is printed whenever it changes. | |
143 | Execution is substantially slower during this form of tracing. | |
b5dc1377 | 144 | .Pp |
ed68ddb1 KM |
145 | If no argument is specified then all source lines are printed |
146 | before they are executed. | |
147 | Execution is substantially slower during this form of tracing. | |
b5dc1377 CL |
148 | .Pp |
149 | The clause | |
3441b3a6 | 150 | .Dq Ic in Ar procedure/function |
b5dc1377 | 151 | restricts tracing information |
ed68ddb1 KM |
152 | to be printed only while executing inside the given procedure |
153 | or function. | |
b5dc1377 CL |
154 | .Pp |
155 | .Ar Condition | |
156 | is a Pascal boolean expression and is | |
ed68ddb1 KM |
157 | evaluated prior to printing the tracing information; |
158 | if it is false then the information is not printed. | |
b5dc1377 | 159 | .Pp |
ed68ddb1 KM |
160 | There is no restriction on the amount of information |
161 | that can be traced. | |
b5dc1377 | 162 | .Pp |
ed68ddb1 | 163 | .ne 10 |
3441b3a6 CL |
164 | .It Ic stop if Ar condition |
165 | .It Xo | |
166 | .Ic stop at Ar source-line-number | |
167 | .Op Ic if Ar condition | |
168 | .Xc | |
169 | .It Xo | |
170 | .Ic stop in Ar procedure/function | |
171 | .Op Ic if Ar condition | |
172 | .Xc | |
173 | .It Xo | |
174 | .Ic stop Ar variable | |
175 | .Op Ic if Ar condition | |
176 | .Xc | |
ed68ddb1 KM |
177 | Stop execution when the given line is reached, procedure or function |
178 | called, variable changed, or condition true. | |
b5dc1377 | 179 | .Pp |
3441b3a6 | 180 | .It Ic delete Ar command-number |
ed68ddb1 KM |
181 | The trace or stop corresponding to the given number is removed. |
182 | The numbers associated with traces and stops are printed by | |
b5dc1377 CL |
183 | the |
184 | .Ic status | |
185 | command. | |
186 | .Pp | |
3441b3a6 | 187 | .It Ic status Op Ic \&> Ar filename |
ed68ddb1 | 188 | Print out |
b5dc1377 CL |
189 | the currently active |
190 | .Ic trace | |
191 | and | |
192 | .Ic stop | |
193 | commands. | |
194 | .Pp | |
3441b3a6 | 195 | .It Ic cont |
ed68ddb1 KM |
196 | Continue execution from where it stopped. |
197 | This can only be | |
198 | done when the program was stopped by an interrupt | |
b5dc1377 CL |
199 | or through use of the |
200 | .Ic stop | |
201 | command. | |
202 | .Pp | |
3441b3a6 | 203 | .It Ic step |
ed68ddb1 | 204 | Execute one source line. |
b5dc1377 | 205 | .Pp |
3441b3a6 | 206 | .It Ic next |
ed68ddb1 | 207 | Execute up to the next source line. |
b5dc1377 CL |
208 | The difference between this and |
209 | .Ic step | |
210 | is that | |
ed68ddb1 | 211 | if the line contains a call to a procedure or function |
b5dc1377 CL |
212 | the |
213 | .Ic step | |
214 | command will stop at the beginning of that | |
215 | block, while the | |
216 | .Ic next | |
217 | command will not. | |
218 | .Pp | |
3441b3a6 CL |
219 | .It Xo |
220 | .Ic print Ar expression | |
221 | .Op Ic \&, Ar expression ... | |
222 | .Xc | |
ed68ddb1 KM |
223 | Print out the values of the Pascal expressions. |
224 | Variables declared in an outer block but having | |
225 | the same identifier as one in the current block may be | |
b5dc1377 CL |
226 | referenced as |
227 | .Dq Ar block-name \&. variable | |
228 | .Pp | |
3441b3a6 | 229 | .It Ic whatis Ar identifier |
ed68ddb1 | 230 | Print the declaration of the given identifier. |
b5dc1377 | 231 | .Pp |
3441b3a6 | 232 | .It Ic which Ar identifier |
ed68ddb1 KM |
233 | Print the full qualification of the given identifer, i.e. |
234 | the outer blocks that the identifier is associated with. | |
b5dc1377 | 235 | .Pp |
3441b3a6 | 236 | .It Ic assign Ar variable Ar expression |
ed68ddb1 | 237 | Assign the value of the expression to the variable. |
b5dc1377 | 238 | .Pp |
3441b3a6 | 239 | .It Ic call Ar procedure Ns (parameters) |
ed68ddb1 | 240 | Execute the object code associated with the named procedure or function. |
b5dc1377 | 241 | .Pp |
3441b3a6 | 242 | .It Ic help |
b5dc1377 CL |
243 | Print out a synopsis of |
244 | .Nm pdx | |
245 | commands. | |
246 | .Pp | |
3441b3a6 | 247 | .It Ic gripe |
b5dc1377 CL |
248 | Invokes a mail program to send a message to the person in charge of |
249 | .Nm pdx . | |
250 | .Pp | |
3441b3a6 | 251 | .It Ic where |
ed68ddb1 KM |
252 | Print out |
253 | a list of the active procedures and functions and the respective source | |
254 | line where they are called. | |
b5dc1377 | 255 | .Pp |
3441b3a6 | 256 | .It Ic source Ar filename |
b5dc1377 CL |
257 | Read |
258 | .Nm pdx | |
259 | commands from the given | |
260 | .Ar filename . | |
261 | Especially useful when the | |
262 | .Ar filename | |
263 | has been created by redirecting | |
264 | a | |
265 | .Ic status | |
266 | command from an earlier debugging session. | |
267 | .Pp | |
3441b3a6 | 268 | .It Ic dump Op Ic \&> Ar filename |
ed68ddb1 KM |
269 | Print the names and values of all active |
270 | data. | |
b5dc1377 | 271 | .Pp |
3441b3a6 CL |
272 | .It Xo |
273 | .Ic list | |
274 | .Oo Ar source-line-number | |
275 | .Op \&, Ar source-line-number Oc | |
276 | .Xc | |
277 | .It Ic list Ar procedure/function | |
ed68ddb1 KM |
278 | List the lines in the current source file from the first line number to |
279 | the second inclusive. | |
280 | As in the editor | |
281 | ``$'' can be used to refer to the last line. | |
282 | If no lines are specified, the entire file is listed. | |
283 | If the name of a procedure or function is given | |
b5dc1377 CL |
284 | lines |
285 | .Ar n-k | |
286 | to | |
287 | .Ar n+k | |
288 | are listed where | |
289 | .Ar n | |
290 | is the first statement | |
291 | in the procedure or function and | |
292 | .Ar k | |
293 | is small. | |
294 | .Pp | |
3441b3a6 | 295 | .It Ic file Op Ar filename |
b5dc1377 CL |
296 | Change the current source file name to |
297 | .Ar filename . | |
ed68ddb1 | 298 | If none is specified then the current source file name is printed. |
b5dc1377 | 299 | .Pp |
3441b3a6 CL |
300 | .It Ic edit Op Ar filename |
301 | .It Ic edit Ar procedure Ns / Ns Ar function-name | |
b5dc1377 CL |
302 | Invoke an editor on |
303 | .Ar filename | |
304 | or the current source file if none | |
ed68ddb1 | 305 | is specified. |
b5dc1377 CL |
306 | If a |
307 | .Ar procedure | |
308 | or | |
309 | .Ar function | |
310 | name is specified, | |
ed68ddb1 KM |
311 | the editor is invoked on the file that contains it. |
312 | Which editor is invoked by default depends on the installation. | |
313 | The default can be overridden by setting the environment variable | |
3441b3a6 CL |
314 | .Ev EDITOR |
315 | to the name of the desired editor. | |
b5dc1377 | 316 | .Pp |
3441b3a6 | 317 | .It Ic pi |
ed68ddb1 | 318 | Recompile the program and read in the new symbol table information. |
b5dc1377 | 319 | .Pp |
3441b3a6 | 320 | .It Ic sh Ar command-line |
ed68ddb1 KM |
321 | Pass the command line to the shell for execution. |
322 | The SHELL environment variable determines which shell is used. | |
b5dc1377 | 323 | .Pp |
3441b3a6 | 324 | .It Ic alias Ar new-command-name Ar old-command-name |
b5dc1377 CL |
325 | This command makes |
326 | .Nm pdx | |
327 | respond to | |
328 | .Ar new-command-name | |
329 | the way it used to respond to | |
330 | .Ar old-command-name . | |
331 | .Pp | |
3441b3a6 | 332 | .It Ic quit |
b5dc1377 CL |
333 | Exit |
334 | .Nm pdx . | |
3441b3a6 | 335 | .El |
b5dc1377 CL |
336 | .Pp |
337 | The following commands deal with the program at the | |
338 | .Ar px | |
339 | instruction | |
ed68ddb1 KM |
340 | level rather than source level. |
341 | They are not intended for general use. | |
3441b3a6 CL |
342 | .Pp |
343 | .Bl -tag -width Fl -compact | |
344 | .It Xo | |
345 | .Ic tracei | |
b5dc1377 | 346 | .Op Ar address |
3441b3a6 CL |
347 | .Op Ic if Ar cond |
348 | .Xc | |
349 | .It Xo | |
350 | .Ic tracei | |
b5dc1377 | 351 | .Op Ar variable |
b5dc1377 | 352 | .Op Ic at Ar address |
3441b3a6 CL |
353 | .Op Ic if Ar cond |
354 | .Xc | |
355 | .It Xo | |
356 | .Ic stopi | |
b5dc1377 | 357 | .Op Ar address |
3441b3a6 CL |
358 | .Op Ic if Ar cond |
359 | .Xc | |
360 | .It Xo | |
361 | .Ic stopi | |
b5dc1377 | 362 | .Op Ic at |
b5dc1377 | 363 | .Op Ar address |
3441b3a6 CL |
364 | .Op Ic if Ar cond |
365 | .Xc | |
b5dc1377 CL |
366 | Turn on tracing or set a stop using a |
367 | .Ic px | |
368 | machine | |
ed68ddb1 | 369 | instruction addresses. |
b5dc1377 | 370 | .Pp |
3441b3a6 CL |
371 | .It Xo |
372 | .Ic xi Ar address | |
373 | .Op Ic \&, Ar address | |
374 | .Xc | |
b5dc1377 CL |
375 | Print the instructions starting at the first |
376 | .Ar address . | |
ed68ddb1 | 377 | Instructions up to |
b5dc1377 CL |
378 | the second |
379 | .Ar address | |
380 | are printed. | |
381 | .Pp | |
3441b3a6 CL |
382 | .It Xo |
383 | .Ic xd Ar address | |
384 | .Op Ic \&, Ar address | |
385 | .Xc | |
ed68ddb1 | 386 | Print in octal the specified data location(s). |
3441b3a6 | 387 | .El |
b5dc1377 | 388 | .Sh ENVIRONMENT |
3441b3a6 CL |
389 | .Bl -tag -width Ar |
390 | .It Ev EDITOR | |
b5dc1377 CL |
391 | The |
392 | .Ic edit | |
393 | function uses the | |
394 | .Ev EDITOR | |
395 | environment variable to see what editor to use. | |
3441b3a6 | 396 | .It Ev SHELL |
b5dc1377 CL |
397 | The function |
398 | .Ic sh | |
399 | checks the | |
400 | .Ev SHELL | |
401 | variable to see which shell to | |
402 | execute. | |
3441b3a6 | 403 | .El |
b5dc1377 | 404 | .Sh FILES |
3441b3a6 CL |
405 | .Bl -tag -width .pdxinit -compact |
406 | .It Pa obj | |
ed68ddb1 | 407 | Pascal object file |
3441b3a6 | 408 | .It Pa .pdxinit |
b5dc1377 CL |
409 | .Nm Pdx |
410 | initialization file | |
3441b3a6 | 411 | .El |
b5dc1377 CL |
412 | .Sh SEE ALSO |
413 | .Xr pi 1 , | |
414 | .Xr px 1 | |
3441b3a6 CL |
415 | .Rs |
416 | .%T "An Introduction to Pdx" | |
417 | .Re | |
b5dc1377 CL |
418 | .Sh HISTORY |
419 | .Nm Pdx | |
3441b3a6 CL |
420 | appeared in |
421 | .Bx 4.2 . | |
b5dc1377 CL |
422 | .Sh BUGS |
423 | .Nm Pdx | |
424 | does not understand sets, | |
ed68ddb1 | 425 | and provides no information about files. |
b5dc1377 CL |
426 | .Pp |
427 | The | |
428 | .Ic whatis | |
429 | command doesn't quite work for variant records. | |
430 | .Pp | |
ed68ddb1 | 431 | Bad things will happen if a procedure invoked with |
b5dc1377 CL |
432 | the |
433 | .Ic call | |
434 | command does a non-local goto. | |
435 | .Pp | |
436 | The commands | |
437 | .Ic step | |
438 | and | |
439 | .Ic next | |
440 | should be able to take a | |
441 | .Ar count | |
ed68ddb1 | 442 | that specifies how many lines to execute. |
b5dc1377 CL |
443 | .Pp |
444 | There should be commands | |
445 | .Ic stepi | |
446 | and | |
447 | .Ic nexti | |
448 | that correspond | |
449 | to | |
450 | .Ic step | |
451 | and | |
452 | .Ic next | |
453 | but work at the instruction level. | |
454 | .Pp | |
ed68ddb1 KM |
455 | There should be a way to get an address associated with |
456 | a line number, procedure or function, and variable. | |
b5dc1377 | 457 | .Pp |
ed68ddb1 | 458 | Most of the command names are too long. |
b5dc1377 | 459 | .Pp |
ed68ddb1 | 460 | The alias facility is quite weak. |
b5dc1377 CL |
461 | .Pp |
462 | A | |
3441b3a6 CL |
463 | .Xr csh 1 Ns \-like |
464 | history capability would improve the situation. |