4.2BSD/usr/man/man1/dbx.1

.ds dB dbx
.ds DB Dbx
.TH DBX 1 "18 July 1983"
.UC 4
.SH NAME
dbx \- debugger
.SH SYNOPSIS
.B dbx
[
.B \-r
] [
.B \-i
] [
.B \-I
.I dir
] [
.I objfile
[
.I coredump
]]
.SH DESCRIPTION
\fI\*(DB\fP is a tool for source level debugging and execution of
programs under UNIX.
The \fIobjfile\fP is an object file produced by a compiler
with the appropriate flag (usually ``\-g'')
specified to produce symbol information in the object file.
Currently, \fIcc\fP(1) and \fIf77\fP(1) produce the appropriate source 
information
and it is expected that in the future the Pascal compiler
will also be able to generate source level information.
The machine level facilities of \fI\*(dB\fP
can be used on any program.
.PP
If no \fIobjfile\fP is specified, \fI\*(dB\fP looks
for a file named ``a.out'' in the current directory.
The object file contains a symbol table which includes the name of the
all the source files translated by the compiler to create it.
These files are available for perusal while using the debugger.
.PP
If a file named ``core'' exists in the current directory
or a \fIcoredump\fP file is specified, \fI\*(dB\fP can be used
to examine the state of the program when it faulted.
.PP
If the file ``.\*(dBinit'' exists in the current directory then the
debugger commands in it are executed.
\fI\*(DB\fP also checks for a ``.\*(dBinit'' in the user's home directory
if there isn't one in the current directory.
.PP
The command line options and their meanings are:
.nr In 7
.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
\&\fB\-r\fP	\c
Execute \fIobjfile\fP immediately.
If it terminates successfully \fI\*(dB\fP exits.
Otherwise the reason for termination will be reported
and the user offered the option of entering the debugger
or letting the program fault.
\fI\*(DB\fP will read from ``/dev/tty'' when \fB\-r\fP is specified
and standard input is not a terminal.
.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
\&\fB\-i\fP	\c
Force \fI\*(dB\fP to act as though standard input is a terminal.
.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
\&\fB\-I\fP \fIdir\fP	\c
Add \fIdir\fP to the list of directories
that are searched when looking for a source file.
Normally \fI\*(dB\fP looks for source files in the current directory
and in the directory where \fIobjfile\fP is located.
The directory search path can also be set with the \fBuse\fP command.
.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
.PP
Unless \fB\-r\fP is specified, \fI\*(dB\fP just prompts and waits for a command.
.sp 1
.ne 8
.B Execution and Tracing Commands
.sp 1
.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.
If \fIobjfile\fP has been written since the last time the symbolic information
was read in, \fI\*(dB\fP will read in the new information.
.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 in quotes 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 boolean expression and is
evaluated prior to printing the tracing information;
if it is false then the information is not printed.
.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 "\fBstatus\fP [\fB>\fP \fIfilename\fP]"
Print out the currently active \fBtrace\fP and \fBstop\fP commands.
.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 "\fBcatch\fP \fInumber\fP"
.ns
.IP "\fBignore\fP \fInumber\fP"
Start or stop trapping signal \fInumber\fP before it is sent
to the program.
This is useful when a program being debugged
handles signals such as interrupts.
Initially all signals are trapped except SIGCONT, SIGCHILD,
SIGALRM and SIGKILL.
.IP \fBcont\fP
Continue execution from where it stopped.
Execution cannot be continued if the process has ``finished'',
that is, called the standard procedure ``exit''.
\fI\*(DB\fP does not allow the process to exit, thereby
letting the user to examine the program state.
.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.
.sp 1
.br
.ne 8v
.PP
.B Displaying and Naming Data
.sp 1
.IP "\fBprint\fP \fIexpression\fP [\fB,\fP \fIexpression\fP ...]"
Print out the values of the expressions.
Array expressions are always subscripted by brackets (``[ ]'').
Variables having the same identifier as one in the current block may be
referenced as ``\fIblock-name\fP\ \fB.\fP\ \fIvariable\fP''.
The field reference operator (``.'') can be used with pointers
as well as records, making the C operator ``->'' unnecessary
(although it is supported).
The construct \fItypename\fP(\fIexpression\fP) can be used to print
the \fIexpression\fP out in the format of the named \fItype\fP.
.IP "\fBwhatis\fP \fIname\fP"
Print the declaration of the given name, which may be qualified
with block names as above.
.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 "\fBwhereis\fP \fIidentifier\fP"
Print the full qualification of all the symbols whose
name matches the given identifier.
The order in which the symbols are printed is not meaningful.
.IP "\fBassign\fP \fIvariable\fP \fB=\fP \fIexpression\fP"
.ns
.IP "\fBset\fP \fIvariable\fP \fB=\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.
Currently, calls to a procedure with a variable number of arguments
are not possible.
Also, string parameters are not passed properly for C.
.IP \fBwhere\fP
Print out a list of the active procedures and function.
.IP "\fBdump\fP [\fB>\fP \fIfilename\fP]"
Print the names and values of all active variables.
.sp 1
.br
.ne 8v
.PP
.B Accessing Source Files
.sp 1
.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 "\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 "\fBfunc\fP [\fIprocedure/function\fP]"
Change the current function.
If none is specified then print the current function.
Changing the current function implicitly changes the current source file
to the one that contains the function; it also changes the current scope
used for name resolution.
.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.
If no lines are specified, the next 10 lines are 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 "\fBuse\fP \fIdirectory-list\fP"
Set the list of directories to be searched
when looking for source files.
.sp 1
.br
.ne 8v
.PP
.B Machine Level Commands
.sp 1
.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 machine instruction address.
.TP
\fBstepi\fP
.ns
.TP
\fBnexti\fP
Single step as in \fBstep\fP or \fBnext\fP, but do a single instruction
rather than source line.
.TP
\fIaddress\fP \fB,\fP\fIaddress\fP\fB/\fP [\fImode\fP]
.ns
.TP
[\fIaddress\fP] \fB/\fP [\fIcount\fP] [\fImode\fP]
Print the contents of memory starting at the first \fIaddress\fP
and continuing up to the second \fIaddress\fP or until \fIcount\fP items are printed.
If no address is specified, the address following the one
printed most recently is used.
The \fImode\fP specifies how memory is to be printed;
if it is omitted the previous mode specified is used.
The initial mode is ``X''.
The following modes are supported:
.nr In 5
.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
\&\fBi\fP	\c
print the machine instruction
.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
\&\fBd\fP	\c
print a short word in decimal
.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
\&\fBD\fP	\c
print a long word in decimal
.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
\&\fBo\fP	\c
print a short word in octal
.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
\&\fBO\fP	\c
print a long word in octal
.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
\&\fBx\fP	\c
print a short word in hexadecimal
.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
\&\fBX\fP	\c
print a long word in hexadecimal
.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
\&\fBb\fP	\c
print a byte in octal
.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
\&\fBc\fP	\c
print a byte as a character
.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
\&\fBs\fP	\c
print a string of characters terminated by a null byte
.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
\&\fBf\fP	\c
print a single precision real number
.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
\&\fBg\fP	\c
print a double precision real number
.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
.PP
Symbolic addresses are specified by preceding the name with an ``&''.
Registers are denoted by ``$rN'' where N is the number of the register.
Addresses may be expressions made up of other addresses and
the operators ``+'', ``-'', and indirection (unary ``*'').
.sp 1
.br
.ne 8v
.PP
.B Miscellaneous Commands
.sp 1
.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"
Respond to \fInew-command-name\fP
as though it were \fIold-command-name\fP.
.IP \fBhelp\fP
Print out a synopsis of \fI\*(dB\fP commands.
.IP \fBgripe\fP
Invoke a mail program to send a message to the person in charge of \fI\*(dB\fP.
.TP
\fBsource\fP \fIfilename\fP
Read \fI\*(dB\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 "\fBquit\fP"
Exit \fI\*(dB\fP.
.SH FILES
.nr In 20
.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
\&a.out	\c
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
\&\&.\*(dBinit	\c
initial commands
.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
.SH SEE ALSO
cc(1), f77(1), pc(1)
.SH COMMENTS
Non-local gotos can cause some trace/stops to be missed.
Most of the command names are too long.
The alias facility helps, but is really quite weak.
A \fIcsh\fP-like history capability would improve the situation.
But then, who wants to duplicate the c-shell in a debugger?
.PP
\fI\*(DB\fP suffers from the same ``multiple include'' malady as does sdb.
If you have a program consisting of a number of object files
and each is built from source files that include header files,
the symbolic information for the header files is replicated in
each object file.
Since about one debugger start-up is done for each link,
having the linker (ld) re-organize the symbol information
won't save much time, though it would reduce some of the
disk space used.
The problem is an artifact of the unrestricted semantics
of #include's in C; for example an include file can contain
static declarations that are separate entities for each file
in which they are included.