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