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