.th CDB I 2/8/75
.sh NAME
cdb \*- C debugger
.sh SYNOPSIS
.bd cdb
[ a.out [ core ] ]
.sh DESCRIPTION
.it Cdb
is a debugger for use with C programs.
It is useful for both post-mortem and interactive debugging.
An important feature of
.it cdb
is that even in the interactive case no
advance planning is necessary to use it;
in particular it is not necessary to compile or load the program
in any special way nor to include any special
routines in the object file.
.s3
The first argument to
.it cdb
is an object
program, preferably containing a symbol table;
if not given ``a.out'' is used.
The second argument is the name of a core-image file;
if it is not given, ``core'' is used.
The core file need not be present.
.s3
Commands to
.it cdb
consist of an address,
followed by a single command character,
possibly followed by a command modifier.
Usually if no address is given the last-printed
address is used.
An address may be followed by a comma and
a number,
in which case the command applies
to the appropriate number of successive addresses.
.s3
Addresses are expressions composed of names,
decimal numbers, and octal numbers
(which begin with ``0'') and separated by
``+'' and ``\*-''.
Evaluation proceeds left-to-right.
.s3
Names of external variables are written just as they are in C.
For various reasons the external names generated by C
all begin with an underscore, which is automatically tacked on by
.it cdb.
Currently it is not possible to suppress this feature, so
symbols (defined in assembly-language programs) which do not begin with
underscore are inaccessible.
.s3
Variables
local to a function
(automatic, static, and arguments)
are accessible by writing the name of the function, a colon ``:'',
and the name of the local variable
(e.g. ``main:argc'').
There is no notion of the ``current'' function;
its name must always be written explicitly.
.s3
A number which begins with ``0'' is taken to be octal; otherwise
numbers are decimal, just as in C.
There is no provision for input of floating numbers.
.s3
The construction ``name[expression]''
assumes that
.it name
is a pointer to an integer
and is equivalent
to the contents of the named cell plus twice the expression.
Notice that
.it name
has to be a genuine pointer and that arrays
are not accessible in this way.
This is a consequence of the fact that types of variables are
not currently saved in the symbol table.
.s3
The command characters are:
.s3
.lp +4 4
/\fIm\fR	print the addressed words.
.it m
indicates the mode of printout;
specifying a mode sets the mode until it is explicitly changed again:
.lp +8 4
\fBo\fR	octal (default)
.lp +8 4
\fBi\fR	decimal
.lp +8 4
\fBf\fR	single-precision floating-point
.lp +8 4
\fBd\fR	double-precision floating-point
.s3
.i0
.lp +4 4
\\	Print the specified bytes in octal.
.s3
.lp +4 4
=	print the value of the addressed expression in octal.
.c2 @
.s3
.lp +4 4
\*a	print the addressed bytes as characters.
Control and non-ASCII characters are escaped in octal.
.c2 '
.s3
.lp +4 4
"	take the contents of the address as a pointer to a sequence
of characters, and print the characters up to a null byte.
Control and non-ASCII characters are escaped as octal.
.s3
.lp +4 4
&	Try to interpret the contents
of the address as a pointer,
and print symbolically where the pointer points.
The typeout contains the name of an external symbol
and, if required,
the smallest possible positive offset.
Only external symbols are considered.
.s3
.lp +4 4
?	Interpret the addressed location as a PDP-11 instruction.
.s3
.lp +4 4
$\fIm\fR	If no
.it m
is given,
print a stack trace of the terminated or stopped program.
The last call made is listed first;
the actual arguments to each routine are
given in octal.
(If this is inappropriate, the arguments may be examined by
name in the desired format using ``/''.)
If
.it m
is ``r'', the contents of the PDP-11 general registers are
listed.
If
.it m
is ``f'', the contents of the floating-point registers are listed.
In all cases, the reason why the program stopped or terminated
is indicated.
.s3
.lp +4 4
%\fIm\fR	According to
.it m,
set or delete a breakpoint,
or run or continue the program:
.s3
.lp +8 4
\fBb\fR	An address within the program must
be given;
a breakpoint is set there.
Ordinarily, breakpoints will be set on the entry points of functions,
but any location is possible as long as it is the first word of an instruction.
(Labels don't appear in the symbol table yet.)
Stopping at the actual first instruction of a function is undesirable
because to make symbolic printouts work,
the function's save sequence has to be completed;
therefore
.it cdb
automatically moves breakpoints at the start of functions
down to the first real code.
.s3
It is impossible to set breakpoints on pure-procedure programs
(\-n flag on cc or ld) because the program text is write-protected.
.s3
.lp +8 4
\fBd\fR	An address must be given;
the breakpoint at that address is removed.
.s3
.lp +8 4
\fBr\fR	Run the program being debugged.
Following the ``%r'', arguments may be given;
they cannot specify I/O redirection
(``>'', ``<'')
or filters.
No address is permissible, and the program is restarted from scratch,
not continued.
Breakpoints should have been set if any were desired.
The program will stop
if any signal is generated,
such as illegal instruction (including simulated floating point),
bus error, or interrupt (see signal(II));
it will also stop when a breakpoint occurs
and in any case announce the reason.
Then a stack trace can be printed, named locations examined, etc.
.s3
.lp +8 4
\fBc\fR	Continue after
a breakpoint.
It is possible but probably useless to continue after
an error since there is no way to repair the cause of the error.
.s3
.i0
.sh "SEE ALSO"
cc (I), db (I), C Reference Manual
.sh BUGS
Use caution in believing
values of register variables at the lowest levels
of the call stack;
the value of a register is found by looking at the place where it was
supposed to have been saved by the callee.
.s3
Some things are still needed to make
.it cdb
uniformly better than
.it db:
non-C symbols, patching files, patching core images of programs
being run.
It would be desirable to have the types of variables around
to make the correct style printout more automatic.
Structure members should be available.
.s3
Naturally, there are all sorts of neat features
not handled, like conditional breakpoints, optional stopping on certain signals
(like illegal instructions, to allow breakpointing
of simulated floating-point programs).