Commit | Line | Data |
---|---|---|
ed68ddb1 KM |
1 | .\" Copyright (c) 1983 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
95f51977 | 5 | .\" @(#)pdx.1 6.1 (Berkeley) 4/29/85 |
ed68ddb1 | 6 | .\" |
95f51977 | 7 | .TH PDX 1 "April 29, 1985" |
ed68ddb1 KM |
8 | .UC 5 |
9 | .SH NAME | |
10 | pdx \- pascal debugger | |
11 | .SH SYNOPSIS | |
12 | pdx [\fB\-r\fP] [\fIobjfile\fP] | |
13 | .SH DESCRIPTION | |
14 | \fIPdx\fP is a tool for source level debugging and execution of | |
15 | Pascal programs. | |
16 | The \fIobjfile\fP is an object file produced by the Pascal translator | |
17 | \fIpi\fP(1). If no \fIobjfile\fP is specified, \fIpdx\fP looks | |
18 | for a file named ``obj'' in the current directory. | |
19 | The object file contains a symbol table which includes the name of the | |
20 | all the source files translated by \fIpi\fP to create it. | |
21 | These files are available for perusal while using the debugger. | |
22 | .PP | |
23 | If the file ``.pdxinit'' exists in the current directory, then the | |
24 | debugger commands in it are executed. | |
25 | .PP | |
26 | The \fB\-r\fP option causes the \fIobjfile\fP to be executed immediately; | |
27 | if it terminates successfully \fIpdx\fP exits. | |
28 | Otherwise it reports the reason for termination | |
29 | and offers the user the option of entering the debugger | |
30 | or simply letting \fIpx\fP continue with a traceback. | |
31 | If \fB\-r\fP is not specified, \fIpdx\fP just prompts and waits for a command. | |
32 | .PP | |
33 | The commands are: | |
34 | .TP | |
35 | \fBrun\fP [\fIargs\fP] [\fB<\fP \fIfilename\fP] [\fB>\fP \fIfilename\fP] | |
36 | Start executing \fIobjfile\fP, passing \fIargs\fP as command line arguments; | |
37 | \fB<\fP or \fB>\fP can be used to redirect input or output in the usual manner. | |
38 | .TP | |
39 | \fBtrace\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] | |
40 | .ns | |
41 | .TP | |
42 | \fBtrace\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP] | |
43 | .ns | |
44 | .TP | |
45 | \fBtrace\fP \fIprocedure/function\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] | |
46 | .ns | |
47 | .TP | |
48 | \fBtrace\fP \fIexpression\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP] | |
49 | .ns | |
50 | .TP | |
51 | \fBtrace\fP \fIvariable\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] | |
52 | Have tracing information printed when the program is executed. | |
53 | A number is associated with the command that is used | |
54 | to turn the tracing off (see the \fBdelete\fP command). | |
55 | .sp 1 | |
56 | The first argument describes what is to be traced. | |
57 | If it is a \fIsource-line-number\fP, then the line is printed | |
58 | immediately prior to being executed. | |
59 | Source line numbers in a file other than the current one | |
60 | must be preceded by the name of the file and a colon, e.g. | |
61 | ``mumble.p:17''. | |
62 | .sp 1 | |
63 | If the argument is a procedure or function name then | |
64 | every time it is called, information is printed telling | |
65 | what routine called it, from what source line it was called, | |
66 | and what parameters were passed to it. | |
67 | In addition, its return is noted, and if it's a function | |
68 | then the value it is returning is also printed. | |
69 | .sp 1 | |
70 | If the argument is an \fIexpression\fP with an \fBat\fP clause | |
71 | then the value of the expression is printed whenever the | |
72 | identified source line is reached. | |
73 | .sp 1 | |
74 | If the argument is a variable then the name and value of the variable | |
75 | is printed whenever it changes. | |
76 | Execution is substantially slower during this form of tracing. | |
77 | .sp 1 | |
78 | If no argument is specified then all source lines are printed | |
79 | before they are executed. | |
80 | Execution is substantially slower during this form of tracing. | |
81 | .sp 1 | |
82 | The clause ``\fBin\fP \fIprocedure/function\fP'' restricts tracing information | |
83 | to be printed only while executing inside the given procedure | |
84 | or function. | |
85 | .sp 1 | |
86 | \fICondition\fP is a Pascal boolean expression and is | |
87 | evaluated prior to printing the tracing information; | |
88 | if it is false then the information is not printed. | |
89 | .sp 1 | |
90 | There is no restriction on the amount of information | |
91 | that can be traced. | |
92 | .br | |
93 | .ne 10 | |
94 | .IP "\fBstop\fP \fBif\fP \fIcondition\fP" | |
95 | .ns | |
96 | .IP "\fBstop\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]" | |
97 | .ns | |
98 | .IP "\fBstop\fP \fBin\fP \fIprocedure/function\fP [\fBif\fP \fIcondition\fP]" | |
99 | .ns | |
100 | .IP "\fBstop\fP \fIvariable\fP [\fBif\fP \fIcondition\fP]" | |
101 | Stop execution when the given line is reached, procedure or function | |
102 | called, variable changed, or condition true. | |
103 | .IP "\fBdelete\fP \fIcommand-number\fP" | |
104 | The trace or stop corresponding to the given number is removed. | |
105 | The numbers associated with traces and stops are printed by | |
106 | the \fBstatus\fP command. | |
107 | .IP "\fBstatus\fP [\fB>\fP \fIfilename\fP]" | |
108 | Print out | |
109 | the currently active \fBtrace\fP and \fBstop\fP commands. | |
110 | .IP \fBcont\fP | |
111 | Continue execution from where it stopped. | |
112 | This can only be | |
113 | done when the program was stopped by an interrupt | |
114 | or through use of the \fBstop\fP command. | |
115 | .IP \fBstep\fP | |
116 | Execute one source line. | |
117 | .IP \fBnext\fP | |
118 | Execute up to the next source line. | |
119 | The difference between this and \fBstep\fP is that | |
120 | if the line contains a call to a procedure or function | |
121 | the \fBstep\fP command will stop at the beginning of that | |
122 | block, while the \fBnext\fP command will not. | |
123 | .IP "\fBprint\fP \fIexpression\fP [\fB,\fP \fIexpression\fP ...]" | |
124 | Print out the values of the Pascal expressions. | |
125 | Variables declared in an outer block but having | |
126 | the same identifier as one in the current block may be | |
127 | referenced as ``\fIblock-name\fP\ \fB.\fP\ \fIvariable\fP''. | |
128 | .IP "\fBwhatis\fP \fIidentifier\fP" | |
129 | Print the declaration of the given identifier. | |
130 | .IP "\fBwhich\fP \fIidentifier\fP" | |
131 | Print the full qualification of the given identifer, i.e. | |
132 | the outer blocks that the identifier is associated with. | |
133 | .IP "\fBassign\fP \fIvariable\fP \fIexpression\fP" | |
134 | Assign the value of the expression to the variable. | |
135 | .IP "\fBcall\fP \fIprocedure(parameters)\fP" | |
136 | Execute the object code associated with the named procedure or function. | |
137 | .IP \fBhelp\fP | |
138 | Print out a synopsis of \fIpdx\fP commands. | |
139 | .IP \fBgripe\fP | |
140 | Invokes a mail program to send a message to the person in charge of \fIpdx\fP. | |
141 | .IP \fBwhere\fP | |
142 | Print out | |
143 | a list of the active procedures and functions and the respective source | |
144 | line where they are called. | |
145 | .TP | |
146 | \fBsource\fP \fIfilename\fP | |
147 | Read \fIpdx\fP commands from the given \fIfilename\fP. | |
148 | Especially useful when the \fIfilename\fP has been created by redirecting | |
149 | a \fBstatus\fP command from an earlier debugging session. | |
150 | .IP "\fBdump\fP [\fB>\fP \fIfilename\fP]" | |
151 | Print the names and values of all active | |
152 | data. | |
153 | .IP "\fBlist\fP [\fIsource-line-number\fP [\fB,\fP \fIsource-line-number\fP]]" | |
154 | .ns | |
155 | .IP "\fBlist\fP \fIprocedure/function\fP" | |
156 | List the lines in the current source file from the first line number to | |
157 | the second inclusive. | |
158 | As in the editor | |
159 | ``$'' can be used to refer to the last line. | |
160 | If no lines are specified, the entire file is listed. | |
161 | If the name of a procedure or function is given | |
162 | lines \fIn-k\fP to \fIn+k\fP are listed where \fIn\fP is the first statement | |
163 | in the procedure or function and \fIk\fP is small. | |
164 | .IP "\fBfile\fP [\fIfilename\fP]" | |
165 | Change the current source file name to \fIfilename\fP. | |
166 | If none is specified then the current source file name is printed. | |
167 | .IP "\fBedit\fP [\fIfilename\fP]" | |
168 | .ns | |
169 | .IP "\fBedit\fP \fIprocedure/function-name\fP" | |
170 | Invoke an editor on \fIfilename\fP or the current source file if none | |
171 | is specified. | |
172 | If a \fIprocedure\fP or \fIfunction\fP name is specified, | |
173 | the editor is invoked on the file that contains it. | |
174 | Which editor is invoked by default depends on the installation. | |
175 | The default can be overridden by setting the environment variable | |
176 | EDITOR to the name of the desired editor. | |
177 | .IP \fBpi\fP | |
178 | Recompile the program and read in the new symbol table information. | |
179 | .IP "\fBsh\fP \fIcommand-line\fP" | |
180 | Pass the command line to the shell for execution. | |
181 | The SHELL environment variable determines which shell is used. | |
182 | .IP "\fBalias\fP \fInew-command-name\fP \fIold-command-name\fP" | |
183 | This command makes \fIpdx\fP respond to \fInew-command-name\fP | |
184 | the way it used to respond to \fIold-command-name\fP. | |
185 | .IP "\fBquit\fP" | |
186 | Exit \fIpdx\fP. | |
187 | .sp 4 | |
188 | .PP | |
189 | The following commands deal with the program at the \fIpx\fP instruction | |
190 | level rather than source level. | |
191 | They are not intended for general use. | |
192 | .TP | |
193 | \fBtracei\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP] | |
194 | .ns | |
195 | .TP | |
196 | \fBtracei\fP [\fIvariable\fP] [\fBat\fP \fIaddress\fP] [\fBif\fP \fIcond\fP] | |
197 | .ns | |
198 | .TP | |
199 | \fBstopi\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP] | |
200 | .ns | |
201 | .TP | |
202 | \fBstopi\fP [\fBat\fP] [\fIaddress\fP] [\fBif\fP \fIcond\fP] | |
203 | Turn on tracing or set a stop using a \fIpx\fP machine | |
204 | instruction addresses. | |
205 | .TP | |
206 | \fBxi\fP \fIaddress\fP [\fB,\fP \fIaddress\fP] | |
207 | Print the instructions starting at the first \fIaddress\fP. | |
208 | Instructions up to | |
209 | the second \fIaddress\fP are printed. | |
210 | .TP | |
211 | \fBxd\fP \fIaddress\fP [\fB,\fP \fIaddress\fP] | |
212 | Print in octal the specified data location(s). | |
213 | .SH FILES | |
214 | .nr In 25 | |
215 | .in +\n(Inn | |
216 | .ta \n(Inn | |
217 | .br | |
218 | .nr wg 1v | |
219 | .ie \n(.h=\n(vk .nr wg -\n(vhu | |
220 | .el .nr vh 0 | |
221 | .if \n(wg>0 \{\ | |
222 | .sp \n(wgu | |
223 | .nr vh +\n(wgu \} | |
224 | .nr vk \n(.h | |
225 | .ti -\n(Inn | |
226 | \&obj \c | |
227 | Pascal object file | |
228 | .br | |
229 | .nr wg 0v | |
230 | .ie \n(.h=\n(vk .nr wg -\n(vhu | |
231 | .el .nr vh 0 | |
232 | .if \n(wg>0 \{\ | |
233 | .sp \n(wgu | |
234 | .nr vh +\n(wgu \} | |
235 | .nr vk \n(.h | |
236 | .ti -\n(Inn | |
237 | \&\&.pdxinit \c | |
238 | \fIPdx\fP initialization file | |
239 | .in -\n(Inn | |
240 | .br | |
241 | .nr wg 1v | |
242 | .ie \n(.h=\n(vk .nr wg -\n(vhu | |
243 | .el .nr vh 0 | |
244 | .if \n(wg>0 \{\ | |
245 | .sp \n(wgu | |
246 | .nr vh +\n(wgu \} | |
247 | .nr vk \n(.h | |
248 | .SH SEE ALSO | |
249 | pi(1), px(1) | |
250 | .br | |
251 | \fIAn Introduction to Pdx\fP | |
252 | .SH BUGS | |
253 | \fIPdx\fP does not understand sets, | |
254 | and provides no information about files. | |
255 | .sp 1 | |
256 | The \fIwhatis\fP command doesn't quite work for variant records. | |
257 | .sp 1 | |
258 | Bad things will happen if a procedure invoked with | |
259 | the \fBcall\fP command does a non-local goto. | |
260 | .sp 1 | |
261 | The commands \fBstep\fP and \fBnext\fP should be able to take a \fIcount\fP | |
262 | that specifies how many lines to execute. | |
263 | .sp 1 | |
264 | There should be commands \fBstepi\fP and \fBnexti\fP that correspond | |
265 | to \fBstep\fP and \fBnext\fP but work at the instruction level. | |
266 | .sp 1 | |
267 | There should be a way to get an address associated with | |
268 | a line number, procedure or function, and variable. | |
269 | .sp 1 | |
270 | Most of the command names are too long. | |
271 | .sp 1 | |
272 | The alias facility is quite weak. | |
273 | .sp 1 | |
274 | A \fIcsh\fP-like history capability would improve the situation. |