SDB(1) INTERACTIVE UNIX System SDB(1)
NAME
sdb - symbolic debugger
SYNOPSIS
sdb [-w] [-W] [objfil [corfil [directory-list]]]
DESCRIPTION
The sdb command calls a symbolic debugger that can be used
with C programs. It may be used to examine their object
files and core files and to provide a controlled environment
for their execution.
Objfil is an executable program file which has been compiled
with the -g (debug) option. If it has not been compiled
with the -g option, the symbolic capabilities of sdb will be
limited, but the file can still be examined and the program
debugged. The default for objfil is a.out. Corfil is
assumed to be a core image file produced after executing
objfil; the default for corfil is core. The core file need
not be present. A - in place of corfil will force sdb to
ignore any core image file. The colon-separated list of
directories (directory-list) is used to locate the source
files used to build objfil.
It is useful to know that at any time there is a current
line and current file. If corfil exists, then they are ini-
tially set to the line and file containing the source state-
ment at which the process terminated. Otherwise, they are
set to the first line in main(). The current line and file
may be changed with the source file examination commands.
By default, warnings are provided if the source files used
in producing objfil cannot be found, or are newer than
objfil. This checking feature and the accompanying warnings
may be disabled by the use of the -W flag.
Names of variables are written just as they are in C. sdb
does not truncate names. Variables local to a procedure may
be accessed using the form procedure:variable. If no pro-
cedure name is given, the procedure containing the current
line is used by default.
It is also possible to refer to structure members as
variable.member, pointers to structure members as
variable->member, and array elements as variable[number].
Pointers may be dereferenced by using the form pointer[0].
Combinations of these forms may also be used. A number may
be used in place of a structure variable name, in which case
the number is viewed as the address of the structure, and
the template used for the structure is that of the last
structure referenced by sdb. An unqualified structure vari-
able may also be used with various commands. Generally, sdb
will interpret a structure as a set of variables. Thus, sdb
Rev. C Software Development Set Page 1
SDB(1) INTERACTIVE UNIX System SDB(1)
will display the values of all the elements of a structure
when it is requested to display a structure. An exception
to this interpretation occurs when displaying variable
addresses. An entire structure does have an address, and it
is this value sdb displays, not the addresses of individual
elements.
Elements of a multidimensional array may be referenced as
variable [number][number]..., or as variable
[number,number,...]. In place of number, the form
number;number may be used to indicate a range of values, *
may be used to indicate all legitimate values for that sub-
script, or subscripts may be omitted entirely if they are
the last subscripts and the full range of values is desired.
As with structures, sdb displays all the values of an array
or of the section of an array if trailing subscripts are
omitted. It displays only the address of the array itself
or of the section specified by the user if subscripts are
omitted.
A particular instance of a variable on the stack may be
referenced by using the form procedure:variable,number. All
the variations mentioned in naming variables may be used.
Number is the occurrence of the specified procedure on the
stack, counting the top, or most current, as the first. If
no procedure is specified, the procedure currently executing
is used by default.
It is also possible to specify a variable by its address.
All forms of integer constants which are valid in C may be
used, so that addresses may be input in decimal, octal, or
hexadecimal.
Line numbers in the source program are referred to as file-
name: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.
While a process is running under sdb, all addresses refer to
the executing program; otherwise they refer to objfil or
corfil. An initial argument of -w permits overwriting loca-
tions in objfil.
Addresses
The address in a file associated with a written address is
determined by a mapping associated with that file. Each
mapping is represented by two triples (b1, e1, f1) and (b2,
e2, f2) and the file address corresponding to a written
address is calculated as follows:
b1<address<e1
Rev. C Software Development Set Page 2
SDB(1) INTERACTIVE UNIX System SDB(1)
then
file address=address+f1-b1
otherwise
b2<address<e2
then
file address=address+f2-b2
otherwise, the requested address is not legal. In some
cases (e.g., for programs with separated I and D space) the
two segments for a file may overlap.
The initial setting of both mappings is suitable for normal
a.out and core files. If either file is not of the kind
expected, then, for that file, b1 is set to 0, e1 is set to
the maximum file size, and f1 is set to 0; in this way the
whole file can be examined with no address translation.
In order for sdb to be used on large files, all appropriate
values are kept as signed 32-bit integers.
Rev. C Software Development Set Page 3
SDB(1) INTERACTIVE UNIX System SDB(1)
Commands
The commands for examining data in the program are:
t Print a stack trace of the terminated or halted pro-
gram.
T Print the top line of the stack trace.
variable/clm
Print the value of variable according to length l and
format m. A numeric count c indicates that a region of
memory, beginning at the address implied by variable,
is to be displayed. The length specifiers are:
b one byte
h two bytes (half word)
l four bytes (long word)
Legal values for m are:
c character
d decimal
u decimal, unsigned
o octal
x hexadecimal
f 32-bit single precision floating point
g 64-bit double precision floating point
s Assume variable is a string pointer and print
characters starting at the address pointed to by
the variable.
a Print characters starting at the variable's
address. This format may not be used with
register variables.
p pointer to procedure
i disassemble machine-language instruction with
addresses printed numerically and symbolically.
I disassemble machine-language instruction with
addresses just printed numerically.
Length specifiers are only effective with the c, d, u,
o, and x formats. Any of the specifiers, c, l, and m,
may be omitted. If all are omitted, sdb chooses a
length and a format suitable for the variable's type as
declared in the program. If m is specified, then this
format is used for displaying the variable. A length
specifier determines the output length of the value to
be displayed, sometimes resulting in truncation. A
count specifier c tells sdb to display that many units
of memory, beginning at the address of variable. The
number of bytes in one such unit of memory is deter-
mined by the length specifier l, or if no length is
given, by the size associated with the variable. If a
count specifier is used for the s or a command, then
that many characters are printed. Otherwise successive
characters are printed until either a null byte is
reached or 128 characters are printed. The last
Rev. C Software Development Set Page 4
SDB(1) INTERACTIVE UNIX System SDB(1)
variable may be redisplayed with the command ./.
The sh(1) metacharacters * and ? may be used within
procedure and variable names, providing a limited form
of pattern matching. If no procedure name is given,
variables local to the current procedure and global
variables are matched; if a procedure name is speci-
fied, then only variables local to that procedure are
matched. To match only global variables, the form
:pattern is used.
linenumber?lm
variable:?lm
Print the value at the address from a.out or I space
given by linenumber or variable (procedure name),
according to the format lm. The default format is `i'.
variable=lm
linenumber=lm
number=lm
Print the address of variable or linenumber, or the
value of number, in the format specified by lm. 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.
variable!value
Set variable to the given value. The value may be a
number, a character constant, or a variable. The value
must be well defined; expressions which produce more
than one value, such as structures, are not allowed.
Character constants are denoted 'character. Numbers
are viewed as integers unless a decimal point or
exponent is used. In this case, they are treated as
having the type double. Registers are viewed as
integers. The variable may be an expression which
indicates more than one variable, such as an array or
structure name. If the address of a variable is given,
it is regarded as the address of a variable of type
int. C conventions are used in any type conversions
necessary to perform the indicated assignment.
x Print the machine registers and the current machine-
language instruction.
X Print the current machine-language instruction.
The commands for examining source files are:
e procedure
e file-name
e directory/
e directory file-name
The first two forms set the current file to the file
Rev. C Software Development Set Page 5
SDB(1) INTERACTIVE UNIX System SDB(1)
containing procedure or to file-name. The current line
is set to the first line in the named procedure or
file. Source files are assumed to be in directory.
The default is the current working directory. The
latter two forms change the value of directory. If no
procedure, file name, or directory is given, the
current procedure name and file name are reported.
/regular expression/
Search forward from the current line for a line con-
taining a string matching regular expression as in
ed(1). The trailing / may be deleted.
?regular expression?
Search backward from the current line for a line con-
taining a string matching regular expression as in
ed(1). The trailing ? may be deleted.
p Print the current line.
z Print the current line followed by the next 9 lines.
Set the current line to the last line printed.
w Window. Print the 10 lines around the current line.
number
Set the current line to the given line number. Print
the new current line.
count+
Advance the current line by count lines. Print the new
current line.
count-
Retreat the current line by count lines. Print the new
current line.
The commands for controlling the execution of the source
program are:
count r args
count R
Run the program with the given arguments. The r com-
mand with no arguments reuses the previous arguments to
the program while the R command runs the program with
no arguments. An argument beginning with < or > causes
redirection for the standard input or output, respec-
tively. If count is given, it specifies the number of
breakpoints to be ignored.
linenumber c count
linenumber C count
Continue after a breakpoint or interrupt. If count is
Rev. C Software Development Set Page 6
SDB(1) INTERACTIVE UNIX System SDB(1)
given, the program will stop when count breakpoints
have been encountered. The signal which caused the
program to stop is reactivated with the C command and
ignored with the c command. If a line number is speci-
fied, then a temporary breakpoint is placed at the line
and execution is continued. The breakpoint is deleted
when the command finishes.
linenumber g count
Continue after a breakpoint with execution resumed at
the given line. If count is given, it specifies the
number of breakpoints to be ignored.
s count
S count
Single-step the program through count lines. If no
count is given, then the program is run for one line.
S is equivalent to s except it steps through procedure
calls.
i
I Single-step by one machine-language instruction. The
signal which caused the program to stop is reactivated
with the I command and ignored with the i command.
variable$m count
address:m count
Single-step (as with s) until the specified location is
modified with a new value. If count is omitted, it is
effectively infinity. Variable must be accessible from
the current procedure. Since this command is done by
software, it can be very slow.
level v
Toggle verbose mode, for use when single-stepping with
S, s, or m. If level is omitted, then just the current
source file and/or subroutine name is printed when
either changes. If level is 1 or greater, each C
source line is printed before it is executed; if level
is 2 or greater, each assembler statement is also
printed. A v turns verbose mode off if it is on for
any level.
k Kill the program being debugged.
procedure(arg1,arg2,...)
procedure(arg1,arg2,...)/m
Execute the named procedure with the given arguments.
Arguments can be integer, character, or string con-
stants 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 m. If no format is given, it defaults to d.
Rev. C Software Development Set Page 7
SDB(1) INTERACTIVE UNIX System SDB(1)
This facility is only available if the program was
loaded with the -g option.
linenumber b commands
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 pro-
cedure even if it was not compiled with the -g option.
If no linenumber is given, a breakpoint is placed at
the current line. If no commands are given, execution
stops just before the breakpoint and control is
returned to sdb. Otherwise the commands are executed
when the breakpoint is encountered and execution con-
tinues. Multiple commands are specified by separating
them with semicolons. If k is used as a command to
execute at a breakpoint, control returns to sdb,
instead of continuing execution.
B Print a list of the currently active breakpoints.
linenumber d
Delete a breakpoint at the given line. If no
linenumber is given, then the breakpoints are deleted
interactively. 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.
D Delete all breakpoints.
l Print the last executed line.
linenumber a
Announce. If linenumber is of the form proc:number,
the command effectively does a linenumber b l. If
linenumber is of the form proc:, the command effec-
tively does a proc: b T.
Miscellaneous commands:
!command
The command is interpreted by sh(1).
new-line
If the previous command printed a source line, then
advance the current line by one line and print the new
current line. If the previous command displayed a
memory location, then display the next memory location.
end-of-file character
Scroll. Print the next 10 lines of instructions,
source or data depending on which was printed last.
The end-of-file character is usually control-D.
Rev. C Software Development Set Page 8
SDB(1) INTERACTIVE UNIX System SDB(1)
< filename
Read commands from filename until the end of file is
reached, and then continue to accept commands from
standard input. When sdb is told to display a variable
by a command in such a file, the variable name is
displayed along with the value. This command may not
be nested; < may not appear as a command in a file.
M Print the address maps.
M [?/] [*] b e f
Record new values for the address map. The arguments ?
and / specify the text and data maps, respectively.
The first segment (b1, e1, f1) is changed unless * is
specified; in which case, the second segment (b2, e2,
f2) of the mapping is changed. If fewer than three
values are given, the remaining map parameters are left
unchanged.
" string
Print the given string. The C escape sequences of the
form \character are recognized, where character is a
nonnumeric character.
q Exit the debugger.
The following commands also exist and are intended only for
debugging the debugger:
V Print the version number.
Q Print a list of procedures and files being debugged.
Y Toggle debug output.
FILES
a.out
core
SEE ALSO
cc(1), a.out(4), core(4), syms(4).
sh(1) in the INTERACTIVE UNIX System User's/System
Administrator's Reference Manual.
WARNINGS
When sdb prints the value of an external variable for which
there is no debugging information, a warning is printed
before the value. The size is assumed to be int (integer).
Data which are stored in text sections are indistinguishable
from functions.
Line number information in optimized functions is unreli-
able, and some information may be missing.
Rev. C Software Development Set Page 9
SDB(1) INTERACTIVE UNIX System SDB(1)
BUGS
If a procedure is called when the program is 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 which
formats data from a core image.
Rev. C Software Development Set Page 10