+.\" Copyright (c) 1983 Regents of the University of California.
+.\" All rights reserved. The Berkeley software License Agreement
+.\" specifies the terms and conditions for redistribution.
+.\"
+.\" @(#)pdx.1 5.1 (Berkeley) %G%
+.\"
+.TH PDX 1 "9 February 1983"
+.UC 5
+.SH NAME
+pdx \- pascal debugger
+.SH SYNOPSIS
+pdx [\fB\-r\fP] [\fIobjfile\fP]
+.SH DESCRIPTION
+\fIPdx\fP is a tool for source level debugging and execution of
+Pascal programs.
+The \fIobjfile\fP is an object file produced by the Pascal translator
+\fIpi\fP(1). If no \fIobjfile\fP is specified, \fIpdx\fP looks
+for a file named ``obj'' in the current directory.
+The object file contains a symbol table which includes the name of the
+all the source files translated by \fIpi\fP to create it.
+These files are available for perusal while using the debugger.
+.PP
+If the file ``.pdxinit'' exists in the current directory, then the
+debugger commands in it are executed.
+.PP
+The \fB\-r\fP option causes the \fIobjfile\fP to be executed immediately;
+if it terminates successfully \fIpdx\fP exits.
+Otherwise it reports the reason for termination
+and offers the user the option of entering the debugger
+or simply letting \fIpx\fP continue with a traceback.
+If \fB\-r\fP is not specified, \fIpdx\fP just prompts and waits for a command.
+.PP
+The commands are:
+.TP
+\fBrun\fP [\fIargs\fP] [\fB<\fP \fIfilename\fP] [\fB>\fP \fIfilename\fP]
+Start executing \fIobjfile\fP, passing \fIargs\fP as command line arguments;
+\fB<\fP or \fB>\fP can be used to redirect input or output in the usual manner.
+.TP
+\fBtrace\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP]
+.ns
+.TP
+\fBtrace\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]
+.ns
+.TP
+\fBtrace\fP \fIprocedure/function\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP]
+.ns
+.TP
+\fBtrace\fP \fIexpression\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]
+.ns
+.TP
+\fBtrace\fP \fIvariable\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP]
+Have tracing information printed when the program is executed.
+A number is associated with the command that is used
+to turn the tracing off (see the \fBdelete\fP command).
+.sp 1
+The first argument describes what is to be traced.
+If it is a \fIsource-line-number\fP, then the line is printed
+immediately prior to being executed.
+Source line numbers in a file other than the current one
+must be preceded by the name of the file and a colon, e.g.
+``mumble.p:17''.
+.sp 1
+If the argument is a procedure or function name then
+every time it is called, information is printed telling
+what routine called it, from what source line it was called,
+and what parameters were passed to it.
+In addition, its return is noted, and if it's a function
+then the value it is returning is also printed.
+.sp 1
+If the argument is an \fIexpression\fP with an \fBat\fP clause
+then the value of the expression is printed whenever the
+identified source line is reached.
+.sp 1
+If the argument is a variable then the name and value of the variable
+is printed whenever it changes.
+Execution is substantially slower during this form of tracing.
+.sp 1
+If no argument is specified then all source lines are printed
+before they are executed.
+Execution is substantially slower during this form of tracing.
+.sp 1
+The clause ``\fBin\fP \fIprocedure/function\fP'' restricts tracing information
+to be printed only while executing inside the given procedure
+or function.
+.sp 1
+\fICondition\fP is a Pascal boolean expression and is
+evaluated prior to printing the tracing information;
+if it is false then the information is not printed.
+.sp 1
+There is no restriction on the amount of information
+that can be traced.
+.br
+.ne 10
+.IP "\fBstop\fP \fBif\fP \fIcondition\fP"
+.ns
+.IP "\fBstop\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]"
+.ns
+.IP "\fBstop\fP \fBin\fP \fIprocedure/function\fP [\fBif\fP \fIcondition\fP]"
+.ns
+.IP "\fBstop\fP \fIvariable\fP [\fBif\fP \fIcondition\fP]"
+Stop execution when the given line is reached, procedure or function
+called, variable changed, or condition true.
+.IP "\fBdelete\fP \fIcommand-number\fP"
+The trace or stop corresponding to the given number is removed.
+The numbers associated with traces and stops are printed by
+the \fBstatus\fP command.
+.IP "\fBstatus\fP [\fB>\fP \fIfilename\fP]"
+Print out
+the currently active \fBtrace\fP and \fBstop\fP commands.
+.IP \fBcont\fP
+Continue execution from where it stopped.
+This can only be
+done when the program was stopped by an interrupt
+or through use of the \fBstop\fP command.
+.IP \fBstep\fP
+Execute one source line.
+.IP \fBnext\fP
+Execute up to the next source line.
+The difference between this and \fBstep\fP is that
+if the line contains a call to a procedure or function
+the \fBstep\fP command will stop at the beginning of that
+block, while the \fBnext\fP command will not.
+.IP "\fBprint\fP \fIexpression\fP [\fB,\fP \fIexpression\fP ...]"
+Print out the values of the Pascal expressions.
+Variables declared in an outer block but having
+the same identifier as one in the current block may be
+referenced as ``\fIblock-name\fP\ \fB.\fP\ \fIvariable\fP''.
+.IP "\fBwhatis\fP \fIidentifier\fP"
+Print the declaration of the given identifier.
+.IP "\fBwhich\fP \fIidentifier\fP"
+Print the full qualification of the given identifer, i.e.
+the outer blocks that the identifier is associated with.
+.IP "\fBassign\fP \fIvariable\fP \fIexpression\fP"
+Assign the value of the expression to the variable.
+.IP "\fBcall\fP \fIprocedure(parameters)\fP"
+Execute the object code associated with the named procedure or function.
+.IP \fBhelp\fP
+Print out a synopsis of \fIpdx\fP commands.
+.IP \fBgripe\fP
+Invokes a mail program to send a message to the person in charge of \fIpdx\fP.
+.IP \fBwhere\fP
+Print out
+a list of the active procedures and functions and the respective source
+line where they are called.
+.TP
+\fBsource\fP \fIfilename\fP
+Read \fIpdx\fP commands from the given \fIfilename\fP.
+Especially useful when the \fIfilename\fP has been created by redirecting
+a \fBstatus\fP command from an earlier debugging session.
+.IP "\fBdump\fP [\fB>\fP \fIfilename\fP]"
+Print the names and values of all active
+data.
+.IP "\fBlist\fP [\fIsource-line-number\fP [\fB,\fP \fIsource-line-number\fP]]"
+.ns
+.IP "\fBlist\fP \fIprocedure/function\fP"
+List the lines in the current source file from the first line number to
+the second inclusive.
+As in the editor
+``$'' can be used to refer to the last line.
+If no lines are specified, the entire file is listed.
+If the name of a procedure or function is given
+lines \fIn-k\fP to \fIn+k\fP are listed where \fIn\fP is the first statement
+in the procedure or function and \fIk\fP is small.
+.IP "\fBfile\fP [\fIfilename\fP]"
+Change the current source file name to \fIfilename\fP.
+If none is specified then the current source file name is printed.
+.IP "\fBedit\fP [\fIfilename\fP]"
+.ns
+.IP "\fBedit\fP \fIprocedure/function-name\fP"
+Invoke an editor on \fIfilename\fP or the current source file if none
+is specified.
+If a \fIprocedure\fP or \fIfunction\fP name is specified,
+the editor is invoked on the file that contains it.
+Which editor is invoked by default depends on the installation.
+The default can be overridden by setting the environment variable
+EDITOR to the name of the desired editor.
+.IP \fBpi\fP
+Recompile the program and read in the new symbol table information.
+.IP "\fBsh\fP \fIcommand-line\fP"
+Pass the command line to the shell for execution.
+The SHELL environment variable determines which shell is used.
+.IP "\fBalias\fP \fInew-command-name\fP \fIold-command-name\fP"
+This command makes \fIpdx\fP respond to \fInew-command-name\fP
+the way it used to respond to \fIold-command-name\fP.
+.IP "\fBquit\fP"
+Exit \fIpdx\fP.
+.sp 4
+.PP
+The following commands deal with the program at the \fIpx\fP instruction
+level rather than source level.
+They are not intended for general use.
+.TP
+\fBtracei\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP]
+.ns
+.TP
+\fBtracei\fP [\fIvariable\fP] [\fBat\fP \fIaddress\fP] [\fBif\fP \fIcond\fP]
+.ns
+.TP
+\fBstopi\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP]
+.ns
+.TP
+\fBstopi\fP [\fBat\fP] [\fIaddress\fP] [\fBif\fP \fIcond\fP]
+Turn on tracing or set a stop using a \fIpx\fP machine
+instruction addresses.
+.TP
+\fBxi\fP \fIaddress\fP [\fB,\fP \fIaddress\fP]
+Print the instructions starting at the first \fIaddress\fP.
+Instructions up to
+the second \fIaddress\fP are printed.
+.TP
+\fBxd\fP \fIaddress\fP [\fB,\fP \fIaddress\fP]
+Print in octal the specified data location(s).
+.SH FILES
+.nr In 25
+.in +\n(Inn
+.ta \n(Inn
+.br
+.nr wg 1v
+.ie \n(.h=\n(vk .nr wg -\n(vhu
+.el .nr vh 0
+.if \n(wg>0 \{\
+.sp \n(wgu
+.nr vh +\n(wgu \}
+.nr vk \n(.h
+.ti -\n(Inn
+\&obj \c
+Pascal object file
+.br
+.nr wg 0v
+.ie \n(.h=\n(vk .nr wg -\n(vhu
+.el .nr vh 0
+.if \n(wg>0 \{\
+.sp \n(wgu
+.nr vh +\n(wgu \}
+.nr vk \n(.h
+.ti -\n(Inn
+\&\&.pdxinit \c
+\fIPdx\fP initialization file
+.in -\n(Inn
+.br
+.nr wg 1v
+.ie \n(.h=\n(vk .nr wg -\n(vhu
+.el .nr vh 0
+.if \n(wg>0 \{\
+.sp \n(wgu
+.nr vh +\n(wgu \}
+.nr vk \n(.h
+.SH SEE ALSO
+pi(1), px(1)
+.br
+\fIAn Introduction to Pdx\fP
+.SH BUGS
+\fIPdx\fP does not understand sets,
+and provides no information about files.
+.sp 1
+The \fIwhatis\fP command doesn't quite work for variant records.
+.sp 1
+Bad things will happen if a procedure invoked with
+the \fBcall\fP command does a non-local goto.
+.sp 1
+The commands \fBstep\fP and \fBnext\fP should be able to take a \fIcount\fP
+that specifies how many lines to execute.
+.sp 1
+There should be commands \fBstepi\fP and \fBnexti\fP that correspond
+to \fBstep\fP and \fBnext\fP but work at the instruction level.
+.sp 1
+There should be a way to get an address associated with
+a line number, procedure or function, and variable.
+.sp 1
+Most of the command names are too long.
+.sp 1
+The alias facility is quite weak.
+.sp 1
+A \fIcsh\fP-like history capability would improve the situation.
projects / unix-history / commitdiff