SDB(1) (Extended Software Generation System Utilities) 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 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 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
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.
sdb does not truncate names. Variables local to a procedure
may be accessed using the form procedure:variable. If no
Page 1 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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
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 will
interpret a structure as a set of variables. Thus, sdb 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
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.
Page 2 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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
locations 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
file address=address+f1-b1
otherwise
b2<=address<e2
file address=address+f2-b2,
Page 3 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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
s Assume variable is a string pointer and print
characters starting at the address pointed to
Page 4 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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
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
then only variables local to that procedure are
matched. To match only global variables, the form
:pattern is used.
linenumber?lm
Page 5 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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/
Page 6 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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, 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
containing 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
containing 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
Page 7 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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, 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
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.
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.
Page 8 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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. 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
procedure 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
Page 9 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
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
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
effectively 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.
Page 10 May 1989
SDB(1) (Extended Software Generation System Utilities) 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 User's Reference Manual.
Page 11 May 1989
SDB(1) (Extended Software Generation System Utilities) SDB(1)
f77(1) in the FORTRAN Programming Language 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
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.
sdb cannot print the value of an F77 parameter. It will
erroneously print the address.
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 12 May 1989