.TH SDB 1 
.SH NAME
sdb \- symbolic debugger
.SH SYNOPSIS
.B sdb
[ objfil [ corfil [ directory ] ] ]
.SH DESCRIPTION
.I sdb
is a symbolic debugger.
It may examine source and/or object files and provide
a controlled environment for execution.
.PP
.I objfil
is an executable program file
which has been compiled with the 
.B \-g
(debug) option of 
.I cc, pascal,
or
.IR f77 (1).
The default for
.I objfil
is
.B  a.out.
.I corfil
is assumed to be a core image file produced after
executing
.IR objfil ;
the default for
.I corfil
is
.B  core.
.I directory
names the location of source files, by default the current directory.
.PP
.I sdb
maintains a
.I "current line"
and a
.I "current file."
If
.I corfil
exists then they are initially set to the line and file
containing the source statement at which the process terminated or stopped.
Otherwise, they are set to the first line in function
.I main.
.PP
Names of variables are written just as they are in C, Pascal, or Fortran.
Variables local to a procedure may be accessed using the form
`procedure:variable'.
If no procedure name is given, the procedure containing the
current line is used by default.
A member of a structure may be referred to as `variable.member' or
`variable->member'; an array element as `variable[number]'.
Combinations of these forms may be used.
.PP
It is also possible to specify a variable by address.
All forms of integer constants which are valid in C may be used.
.PP
Line numbers in the source program are referred to as `filename:number'
or `procedure:number'.
In either case the number is relative to the beginning of the file.
If no procedure or file name is given,
the current file is used by default.
If no number is given,
the first line of the named procedure or file is used.
.PP
The commands for examining data are:
.TP 5
.B t
Print a stack trace of the terminated or stopped program.
.TP 5
.B T
Print the top line of the stack trace.
.TP 5
variable/\fIlm\fP
Print the value of variable according to
length
.I l
and format 
.I m.
If 
.I l
and
.I m
are omitted,
sdb chooses a length and format suitable for the variable's type
as declared in the program.
The length specifiers are:
.RS
.TP
.BI b
one byte
.br
.ns
.TP
.BI h
two bytes (half word)
.br
.ns
.TP
.BI l
four bytes (long word)
.br
.ns
.TP
number
string length for formats
.B s
and
.B a
.RE
.TP 5
\ 
Legal values for
.I m
are:
.RS
.TP
.BI c
character
.br
.ns
.TP
.BI d
decimal
.br
.ns
.TP
.BI u
decimal, unsigned
.br
.ns
.TP
.BI o
octal
.br
.ns
.TP
.BI x
hexadecimal
.br
.ns
.TP
.BI f
32 bit single precision floating point
.br
.ns
.TP
.BI g
64 bit double precision floating point
.br
.ns
.TP
.BI s
Assume variable is a string pointer and print characters until a null is 
reached.
.br
.ns
.TP
.BI a
Print characters starting at the variable's address until a null
is reached.
.br
.ns
.TP
.BI p
pointer to procedure
.RE
.TP 5
\ 
The length specifiers are only effective with the formats
\fBd\fP, \fBu\fP, \fBo\fP and \fBx\fP.
If
one of these formats
is specified and
.I l
is omitted,
the length
defaults to the word length of the host machine:
4 for the VAX.
The last variable may be redisplayed with the command `./'.
The
.IR sh (1)
metacharacters
.B *
and
.B ?
may be used within procedure and variable names,
providing a limited form of pattern matching.
If no procedure name is given, both variables local to the current
procedure and global (common for f77) variables are matched.
If a procedure name is specified,
only variables local to that procedure are matched.
The form `:pattern'
matches only global variables (blank common for f77),.
The name of a common block may be specified instead of a procedure name
for f77 programs.
.RE
.TP 5
variable\fB=\fP\fIlm\fP
.br
.ns
.TP 5
linenumber\fB=\fP\fIlm\fP
.br
.ns
.TP 5
number\fB=\fP\fIlm\fP
Print the address of the variable or line number or the value of the number
in the specified format.
If no format is given, then `lx' is used.
The last variant of this command provides a convenient way to convert
between decimal, octal and hexadecimal.
.TP 5
variable\fB!\fPvalue
Set the variable to the given value.
The value may be a number, character constant or a variable.
If the variable is of type float or double,
the value may also be a floating constant.
.PP
The commands for examining source files are
.TP 5
\fBe\fP procedure
.br
.ns
.TP 5
\fBe\fP filename.c
Set the current file to
the file containing the named procedure
or the named filename.
Set the current line to the first line in the named
procedure or file.
If no procedure or file name is given, the current procedure and file names
are reported.
.TP 5
\fB/\fPregular expression\fB/\fP
Search forward from the current line for a line containing
a string matching the regular expression as in ed(1).
The trailing `/' may be elided.
.TP 5
\fB?\fPregular expression\fB?\fP
Search backward from the current line for a line containing
a string matching the regular expression as in ed(1).
The trailing `?' may be elided.
.TP 5
.B p
Print the current line.
.TP 5
.B z
Print the current line followed by the next 9 lines.
Set the current line to the last line printed.
.TP 5
.RB control- D
Scroll.
Print the next 10 lines.
Set the current line to the last line printed.
.TP 5
.B w
Window.
Print the 10 lines around the current line.
.TP 5
number
Set the current line to the given line number.
Print the new current line.
.TP 5
\fIcount\fB +\fR
Advance the current line by \fIcount\fP lines.
Print the new current line.
.TP 5
\fIcount\fB \(mi\fR
Retreat the current line by \fIcount\fP lines.
Print the new current line.
.sp 1
.PP
The commands for controlling the execution of the source program are:
.TP 5
\fIcount\fB r \fIargs\fR
.br
.ns
.TP 5
\fIcount\fB R
Run the program with the given arguments.
The \fBr\fP command with no arguments reuses the previous arguments
to the program while the \fBR\fP command
runs the program with no arguments.
An argument beginning with `<' or `>' causes redirection for the
standard input or output respectively.
If \fIcount\fP is given,
it specifies the number of breakpoints to be ignored.
.TP 5
\fIlinenumber\fB c\fI count\fR
.br
.ns
.TP 5
\fIlinenumber\fB C\fI count\fR
Continue after a breakpoint or interrupt.
If \fIcount\fP is given,
it specifies the number of breakpoints to be ignored.
\fBC\fP continues with the signal which caused the program to stop and
\fBc\fP ignores it.
If a
.I linenumber
is given then a temporary breakpoint is placed at the line
and execution is continued.
The breakpoint is deleted when the command finishes.
.TP 5
\fIcount\fB s\fR
Single step.
Run the program through \fIcount\fP lines.
If no count is given then the program is run for one line.
.TP 5
\fIcount\fB S\fR
Single step, but step through subroutine calls.
.TP 5
.B k
Kill the debugged program.
.TP 5
procedure\fB(\fParg1,arg2,...\fB)\fP
.br
.ns
.TP 5
procedure\fB(\fParg1,arg2,...\fB)/\fP\fIm\fP
Execute the named procedure with the given arguments.
Arguments can be integer, character or string constants
or names of variables accessible from the current procedure.
The second form causes the value returned by the procedure to be
printed according to format \fIm\fP.
If no format is given, it defaults to `d'.
.TP 5
\fIlinenumber\fB b\fR \fIcommands\fR
Set a breakpoint at the given line.
If a procedure name without a line number is given (e.g. `proc:'),
a breakpoint is placed at the first line in the procedure
even if it was not compiled with the debug flag.
If no \fIlinenumber\fP is given,
a breakpoint is placed at the current line.
.sp 0.5
If no
.I commands
are given then execution stops just before the breakpoint
and control is returned to
.I sdb.
Otherwise
the semicolon-separated
.I commands 
are executed when the breakpoint is
encountered and execution continues.
.TP 5
\fIlinenumber\fB d\fR
Delete a breakpoint at the given line.
If no \fIlinenumber\fP is given,
each breakpoint location is printed and a line is read from the standard input.
If the line begins with a `y' or `d' then the breakpoint is deleted.
.TP 5
.B B
Print a list of the currently active breakpoints.
.TP 5
.B D
Delete all breakpoints.
.TP 5
.B l
Print the last executed line.
.TP 5
\fIlinenumber\fB a\fR
Announce.
If \fIlinenumber\fR is of the form `proc:number', the command
does a `linenumber b l'.
If \fIlinenumber\fR is of the form `proc:', the command
does a `proc: b T'.
.sp 1
.PP
Miscellaneous commands.
.TP 5
\fB! \fIcommand\fR
The command is interpreted by sh(1).
.TP 5
.B newline
If the previous command printed a source line then
advance the current line by 1 line and
print the new current line.
If the previous command displayed a core location then
display the next core location.
.TP 5
\fB"\fI string\fR
Print the given string.
.TP 5
.B q
Exit the debugger.
.PP
The following commands are intended for
debugging the debugger.
.TP 5
.B V
Print the version number.
.TP 5
.B X
Print a list of procedures and files being debugged.
.TP 5
.B Y
Toggle debug output.
.SH FILES
a.out
.br
core
.SH DIAGNOSTICS
Error reports are either identical to those of 
.IR adb (1)
or are self-explanatory.
.SH SEE\ ALSO
adb(1), pi(9.1), coreid(1)
.SH BUGS
If a procedure is called when the program is
.I not
stopped at a breakpoint
(such as when a core image is being debugged),
all variables are initialized before the procedure is started.
This makes it impossible to use a procedure to extract
data from a core image.
.PP
Arrays must be of one dimension and of zero origin to be correctly
addressed.
.PP
The default type for printing Fortran parameters is incorrect:
address instead of value.
.PP
Tracebacks containing Fortran subprograms with multiple entry points
may print too many arguments in the wrong order, but their values
are correct.
.PP
.I sdb
understands Pascal, but not its types.
.PP
The meaning of control-D is nonstandard