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