Sdb is a symbolic debugging program currently implemented for the
language C on the UNIX/32V\s-2\u\(dg\d\s+2 Operating System.
\(dg\dUNIX is a trademark of Bell Laboratories
Sdb allows one to interact with a debugged program at the
When debugging a core image from an aborted program,
sdb reports which line in the C program caused the error
and allows all variables,
including array and structure elements,
to be accessed symbolically
and displayed in the correct format.
One may place breakpoints at selected statements
or single step on a line by line basis.
To facilitate specification of lines in the program without
a mechanism for examining the source text is also included in sdb.
Procedures may be called directly from the debugger.
This feature is useful both for testing individual procedures
and for calling user-provided routines which provide formatted
printout of structured data.
This document describes a symbolic debugger, sdb, as implemented
for C programs on the UNIX/V32\s-2\u\(dg\d\s+2 Operating System.
\(dg\dUNIX is a trademark of Bell Laboratories
Sdb is useful both for examining core images of aborted programs
and for providing an environment in which execution of a program
can be monitored and controlled.
it is necessary to compile the C program with the `\(mig' flag.
This causes the compiler to generate additional information
about the variables and statements of the compiled program.
When the debug flag is specified,
sdb can be used to obtain a trace of the called procedures
at the time of the abort and interactively display the
A typical sequence of shell commands for debugging a core image is:
% cc \(mig foo.c \(mio foo
Bus error \(mi core dumped
The program foo was compiled with the `\(mig' flag and then executed.
An error occurred which caused a core dump.
Sdb is then invoked to examine the core dump to determine the
It reports that the Bus error occurred in procedure main at line 25
(line numbers are always relative to the beginning of the file)
and outputs the source text of the offending line.
Sdb then prompts the user with a `\v'.25m'*\v'-.25m'' indicating that it awaits
It is useful to know that sdb has a notion of current
procedure and current line.
In this example, they are initially set to `main' and `25'
In the above example sdb was called with one argument, `foo'.
In general it takes three arguments on the command line.
The first is the name of the executable file which is to be
It defaults to a.out when not specified.
The second is the name of the core file, defaulting to core
and the third is the name of the directory containing the source
of the program being debugged.
Sdb currently requires all source to reside in a single directory.
The default is the working directory.
the second and third arguments defaulted to the correct values,
so only the first was specified.
It is possible that the error occurred in a procedure which was
not compiled with the debug flag.
In this case, sdb prints the procedure name and the address at
which the error occurred.
The current line and procedure are set to the first line in main.
Sdb will complain if main was not compiled with `\(mig'
but debugging can continue for those routines compiled with the
It is often useful to obtain a listing of the procedure calls
This is obtained with the
main(1,2147483584, 2147483592) [foo.c:15]
This indicates that the error occurred within the procedure sub
at line 25 in file foo.c.
Sub was called with the arguments 2 and 3 for inter at line 96.
Inter was called from main at line 16.
Main is always called by the shell with three arguments,
Arguments in the call trace are always printed in decimal.
Sdb can be used to display variables in the stopped program.
Variables are displayed by typing their name followed by a slash,
\v'.25m'*\v'-.25m'errflg/
causes sdb to display the value of variable errflg.
Unless otherwise specified,
variables are assumed to be either local to or accessible from
To specify a different procedure, use the form
to display variable i in procedure sub.
Section 3.2 will explain how to change the current procedure.
Sdb normally displays the variable in a format determined by
its type as declared in the C program.
To request a different format, a specifier is placed after
The specifier consists of an optional length specification
The length specifiers are
The lengths are only effective with the formats
\fBd\fP, \fBo\fP, \fBx\fP and \fBu\fP.
If no length is specified, the word length of the host machine,
four for the DEC VAX-11/780\s-2\u\(dg\d\s+2, is used.
\(dg\dDEC and VAX are trademarks of Digital Equipment Corporation
There are a number of format specifiers available:
32 bit single precision floating point
64 bit double precision floating point
Assume variable is a string pointer and print characters until a null is
Print characters starting at the variable's address until a null
variable i can be displayed in hexadecimal with the following command
Sdb also knows about structures, one dimensional arrays and
so that all of the following commands work.
\v'.25m'*\v'-.25m'array[2]/
\v'.25m'*\v'-.25m'sym.id/
\v'.25m'*\v'-.25m'psym\(mi>usage/
\v'.25m'*\v'-.25m'xsym[20].p\(mi>usage/
The only restriction is that array subscripts must be numbers.
Note that, as a special case
\v'.25m'*\v'-.25m'psym\(mi>/d
displays the location pointed to by psym in decimal.
Core locations can also be displayed by specifying their absolute
displays location 1024 in decimal.
numbers may also be specified in octal or hexadecimal so the above
command is equivalent to both of
It is possible to intermix numbers and variables, so that
\v'.25m'*\v'-.25m'1000.x/
refers to an element of a structure starting at address 1000 and
\v'.25m'*\v'-.25m'1000\(mi>x/
refers to an element of a structure whose address is at 1000.
The address of a variable is printed with the `=' command, so
displays the address of i.
Another feature whose usefulness will become apparent later is
which redisplays the last variable typed.
Source file display and manipulation
Sdb has been designed to make it easy to debug a program without
constant reference to a current source listing.
Facilities are provided which perform context searches
within the source files of the program being debugged
and to display selected portions of the source files.
The commands are similar to those of the UNIX editor ed and ex [1].
sdb has a notion of current file and line within the file.
Sdb also knows how the lines of a file are partitioned into
procedures, so that it also has a notion of current procedure.
As noted in other parts of this document,
the current procedure is used by a number of sdb commands.
Displaying the source file
Four command exist for displaying lines in the source file.
They are useful for perusing through the source program
and for determining the context of the current line.
Window. Print a window of 10 lines around the current line.
Print 10 lines starting at the current line.
Advance the current line by 10.
Print the next 10 lines and advance the current line by 10.
This command is used to cleanly display longs segments of the program.
command which prints the current line.
When a line from a file is printed, it is preceded by its line number.
This not only gives an indication of its relative position in the file,
but is also used as input by some sdb commands.
Changing the current source file or procedure
command is used to change the current source file.
\v'.25m'*\v'-.25m'e procedure
\v'.25m'*\v'-.25m'e file.c
The first causes the file containing the named procedure
to become the current file
and the current line becomes the first line of the procedure.
The other form causes the named file to become current.
In this case the current line is set to the first line of the named file.
command with no argument causes the current procedure and file named
Changing the current line in the source file
As mentioned in section 3.1,
commands have a side effect of changing the current line in the
This section describes other commands which change the current line.
There are two commands for searching for regular expressions in
\v'.25m'*\v'-.25m'/regular expression/
\v'.25m'*\v'-.25m'?regular expression?
The first command searches forward through the file for a line containing
a string which matches the regular expression and the second searches
The trailing `/' and `?' may be omitted from these commands.
Regular expression matching is identical to that of ed.
may be used to move the current line forwards or backwards by a
specified number of lines.
Typing a newline advances the current line by one
typing a number causes that line to become the current line
These commands may be catenated with the display commands so that
advances the current line by 15 and then prints 10 lines.
A controlled environment for program testing
One very useful feature of sdb
After entering the debugger,
certain lines in the source program may be specified to be
The program is then started with a sdb command.
Execution of the program proceeds as normal until
it is about to execute one of the lines at which a breakpoint has
The program stops and sdb reports which breakpoint the
Now, sdb commands may be used to display
the trace of procedure calls and the values of variables.
If the user is satisfied that the program is working correctly
to this point, some breakpoints can be deleted and others set,
and then program execution may be continued from the point where it stopped.
A useful alternative to setting breakpoints is single stepping.
Sdb can be requested to execute the next line of the program
This feature is especially useful for testing new programs,
so they can be verified on a statement by statement basis.
Note that if an attempt is made to single step through a
procedure which has not been compiled with the `\(mig' flag,
execution proceeds until a statement in a procedure compiled
with the debug flag is reached.
The current implementation of single
While this is not a problem when stepping through a single statement,
it may result in long delays while stepping through procedures not
compiled with the debug flag.
This problem is partially alleviated with the
command which quickly single steps until the
positionally next statement is reached.
Setting and deleting breakpoints
Breakpoints can be set at any line in a procedure which contains
\v'.25m'*\v'-.25m'proc:12b
The first form sets a breakpoint at line 12 in the current procedure.
The line numbers are relative to the beginning of the file,
as printed by the source file display commands.
The second form sets a breakpoint at line 12 of procedure proc and the third
sets a breakpoint at the first line of proc.
Breakpoints are deleted similarly with the commands:
\v'.25m'*\v'-.25m'proc:12d
the breakpoints are deleted interactively.
Each breakpoint location is printed and a line is read from the
If the line begins with a `y' or `d', the breakpoint is deleted.
A list of the current breakpoints is printed in response to
Beware that breakpoints do strange things if the debugged program
is being run elsewhere at the same time.
command is used to begin program execution.
It restarts the program as if it were invoked from the shell.
runs the program with the given arguments,
as if they had been typed on the shell command line.
Execution is continued after a breakpoint with the
and single stepping is accomplished with \fBs\fP.
command is used to run the program until it reaches the positionally
Program execution can also be stopped with the RUBOUT key.
The debugger is entered as if a breakpoint was encountered
so that execution may be continued with
\fBc\fP, \fBs\fP or \fBn\fP.
It is possible to call any of the procedures of the program from
This feature is useful both for testing individual procedures
with different arguments and for calling a procedure which
prints structured data in a nice way.
There are two ways to call a procedure:
\v'.25m'*\v'-.25m'proc(arg1, arg2, ...)
\v'.25m'*\v'-.25m'proc(arg1, arg2, ...)/
The first simply executes the procedure.
The second is intended for calling functions:
It executes the procedure and prints the value that it returns.
The value is printed in decimal unless some other
Arguments to procedures may be integer, character or string constants,
or values of variables which are accessible from the current
An unfortunate bug in the current implementation is that
if a procedure is called when the program is
(such as when a core image is being debugged),
static variables are reinitialized before the procedure is
This makes it impossible to use a procedure which
formats data from a dump.
To exit the debugger, use the
command is identical to that in ed and is used to have the shell
It is possible to change the values of variables when the program
is stopped at a breakpoint. This is done with the command
\v'.25m'*\v'-.25m'variable!value
which sets the variable to the given value.
The value may be a number, character constant or the name of
I would like to thank Bill Joy and Chuck Haley
for their comments and constructive criticisms.
William N. Joy, Ex Reference Manual, Computer Science Division,
University of California, Berkeley, November 1977.
Appendix 1. Example of usage.
Appendix 2. Manual pages.