sdb(1) sdb(1)
NAME
sdb - symbolic debugger
SYNOPSIS
sdb [-w] [-W] [objfil[corfil[directory]]]
DESCRIPTION
sdb is a symbolic debugger which can be used with C and f77
programs. It may be used to examine their object files and
core files and to provide a controlled environment for their
execution.
objfil is normally an executable program file which has been
compiled with the -g (debug) flag option; if it has not been
compiled with the -g flag option, or if it is not an
executable file, the symbolic capabilities of sdb are
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 forces sdb to ignore
any core image file. Source files used in constructing
objfil must be in directory to be located.
It is useful to know that at any time there is a current
line and current file. If corfil exists then they are
initially set to the line and file containing the source
statement 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 or f77.
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.
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. f77 common
variables may be referenced by using the name of the common
block instead of the structure name. Blank common variables
may be named by the form .variable. 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
Page 1 (last mod. 1/16/87)
sdb(1) sdb(1)
used for the structure is that of the last structure
referenced by sdb. An unqualified structure variable may
also be used with various commands. Generally, sdb
interprets a structure as a set of variables; thus, it
displays 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
subscript, 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 multidimensional parameter in an f77 program
cannot be displayed as an array, but it is actually a
pointer, whose value is the location of the array. The
array itself can be accessed symbolically from the calling
function.
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 filename 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
locations in objfil.
Page 2 (last mod. 1/16/87)
sdb(1) sdb(1)
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). The file address corresponding to a written
address is calculated as follows:
b1address<e1
file address=address+f1-b1
otherwise
b2address<e2
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.
Commands.
The commands for examining data in the program are:
t Print a stack trace of the terminated or halted
program.
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
Page 3 (last mod. 1/16/87)
sdb(1) sdb(1)
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 printed numerically only.
The length specifiers are only effective with the
formats c, d, u, o and x. 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 determined 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 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
specified, 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
Page 4 (last mod. 1/16/87)
sdb(1) sdb(1)
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 that 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 that
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
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, filename, or directory is given, the current
procedure name and filename are reported.
/regular expression/
Search forward from the current line for a line
containing a string matching regular expression as in
ed(1). The trailing / may be elided.
?regular expression?
Search backward from the current line for a line
containing a string matching regular expression as in
ed(1). The trailing ? may be elided.
p Print the current line.
Page 5 (last mod. 1/16/87)
sdb(1) sdb(1)
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
command 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
respectively. 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
given, it specifies the number of breakpoints to be
ignored. C continues with the signal that caused the
program to stop reactivated and c ignores it. If a
linenumber is specified 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.
Page 6 (last mod. 1/16/87)
sdb(1) sdb(1)
i
I Single step by one machine-language instruction. I
steps with the signal that caused the program to stop
reactivated and i ignores it.
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 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 m.
If no format is given, it defaults to d.
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 procedure
even if it was not compiled with the -g flag 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
continues. 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
Page 7 (last mod. 1/16/87)
sdb(1) sdb(1)
Delete a breakpoint at the given line. If no
linenumber is given, 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, 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 bl. If
linenumber is of the form proc:, the command
effectively does a proc: b T.
Miscellaneous commands:
!command
The command is interpreted by sh(1).
newline
If the previous command printed a source line, advance
the current line by one line and print the new current
line. If the previous command displayed a memory
location, display the next memory location.
CONTROL-D
Scroll. Print the next 10 lines of instructions,
source, or data, depending on which was printed last.
< filename
Read commands from filename until the end of file is
reached, 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
Page 8 (last mod. 1/16/87)
sdb(1) sdb(1)
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
/usr/bin/sdb
a.out
core
SEE ALSO
cc(1), f77(1), sh(1), a.out(4), core(4).
``sdb Reference'' in Oreo Programming Languages and Tools,
Volume 1.
WARNINGS
Data stored in text sections are indistinguishable from
functions.
Line number information in optimized functions is
unreliable, and some information may be missing.
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.
The default type for printing f77 parameters is incorrect.
Their address is printed instead of their value.
Tracebacks containing f77 subprograms with multiple entry
points may print too many arguments in the wrong order, but
their values are correct.
The range of an f77 array subscript is assumed to be 1 to n,
where n is the dimension corresponding to that subscript.
This is only significant when the user omits a subscript, or
uses * to indicate the full range. There is no problem in
general with arrays having subscripts whose lower bounds are
not 1.
Page 9 (last mod. 1/16/87)