sdb(1) CLIX sdb(1)
NAME
sdb - Symbolic debugger
SYNOPSIS
sdb [-w] [-W] [objfil [corfil [directory_list]]]
FLAGS
-w Permits the overwriting of locations with the objfil address space.
-W Suppresses warnings.
DESCRIPTION
The sdb command is a symbolic debugger that can be used with C and FORTRAN
programs. It may be used to examine their object files and core files and
provide a controlled environment for the execution of the files.
The file objfil is an executable program file that has been compiled with
the -g (debug) flag. If it has not been compiled with the -g flag, the
symbolic capabilities of sdb will be limited, but the file can still be
examined and the program debugged. The default file for objfil is a.out.
The corfil is assumed to be a core image file produced after executing
objfil; the default file for corfil is core. The core file need not be
present. A hyphen (-) in place of corfil forces 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 the specified objfil.
A current line and current file exist at all times. If corfil exists,
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 using the -W flag.
Names of variables are written just as they are in C or FORTRAN. The sdb
command does not truncate names. 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.
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. FORTRAN 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 .
2/94 - Intergraph Corporation 1
sdb(1) CLIX sdb(1)
variable. A number may be used in place of a structure variable name. In
this case, the number is 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 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. The sdb command displays this value, 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
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 a FORTRAN 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.
An instance of a variable on the stack may be referenced by using the form
procedure:variable,number. All variations mentioned in naming variables
may be used. The 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 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 filename: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.
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
2 Intergraph Corporation - 2/94
sdb(1) CLIX sdb(1)
a written address is calculated as follows:
b1<address<e1 -> file address=address+f1-b1
otherwise
b2<address<e2 -> file address=address+f2-b2
Otherwise, the requested address is not legal. In some cases (as 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 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.
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 as follows:
t Displays a stack trace of the terminated or halted program. This
command will not work properly unless the program has been compiled
to use a stack frame pointer (-g or -ga compiler flags).
T Displays the top line of the stack trace.
variable[/clm]
Displays 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, will be displayed. The length
specifiers are as follows:
b one byte
h two bytes (halfword)
l four bytes (longword)
Legal values for m are as follows:
c Character
d Decimal
u Decimal, unsigned
o Octal
2/94 - Intergraph Corporation 3
sdb(1) CLIX sdb(1)
x Hexadecimal
f 32-bit single-precision floating-point
g 64-bit double-precision floating-point
s Assume variable is a string pointer and display characters
starting at the address pointed to by the variable.
a Display 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
displayed numerically and symbolically
I Disassemble machine-language instruction with addresses
displayed numerically only
Length specifiers are only effective with the c, d, u, o, and x
formats. The c, l, and m specifiers may be omitted. If all are
omitted, sdb chooses a length and a format suitable from the
variable's type declared in the program. If m is specified, 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
how many units of memory to display, beginning at the address of
variable. The number of bytes in a 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, the number of characters specified is displayed.
Otherwise, successive characters are displayed until either a null
byte is reached or 128 characters are displayed. The last variable
may be redisplayed with the command ./.
The sh 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
Displays 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=[l][m]
linenumber=[l][m]
4 Intergraph Corporation - 2/94
sdb(1) CLIX sdb(1)
number=[l][m]
Displays the address of variable or linenumber or the value of
number in the format specified by lm. If no format is given, lx is
used. The last variant of this command provides a convenient way
to convert between decimal, octal, and hexadecimal.
variable!value
Sets 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 by 'character.
Numbers are viewed as integers unless a decimal point or exponent
is used. In this case, they are treated as if they are 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
interpreted as the address of a variable with type int. C
conventions are used in any type conversions necessary to perform
the indicated assignment.
x Displays the machine registers and the current machine-language
instruction.
X Displays the current machine-language instruction.
The commands for examining source files are as follows:
e procedure
e filename
e directory/
e directory filename
The first two forms set the current file to the file containing
procedure or to filename. 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/
Searches 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?
Searches backward from the current line for a line containing a
string matching regular expression as in ed(1). The trailing ? may
be deleted.
p Displays the current line.
2/94 - Intergraph Corporation 5
sdb(1) CLIX sdb(1)
z Displays the current line followed by the next nine lines. Sets
the current line to the last line displayed.
w (Window.) Displays the 10 lines around the current line.
number Sets the current line to the given line number. Displays the new
current line.
count+ Advances the current line by count lines. Displays the new current
line.
count- Retreats the current line by count lines. Displays the new current
line.
The commands for controlling the source program execution are as follows:
[count] r [args]
[count] R
Runs 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 stdin or stdout to be redirected, respectively.
If count is given, sdb will ignore count breakpoints.
[linenumber] c [count]
[linenumber] C [count]
Continues after a breakpoint or interrupt. If count is given, sdb
will ignore count breakpoints. The signal that caused the program
to stop is reactivated with the C command and ignored with the c
command. If a line number is specified, a temporary breakpoint is
placed at the line and execution is continued. The breakpoint is
deleted when the command finishes.
[linenumber] g [count]
Continues after a breakpoint with execution resumed at the given
line. If count is given, sdb will ignore count breakpoints.
s [count]
S [count]
Single steps the program through count lines. If no count is
given, the program runs for one line. The S command is equivalent
to s except that it steps over function calls and s steps into the
function.
i
I Single steps one machine-language instruction. The signal that
caused the program to stop is reactivated with the I command and
ignored with the i command.
variable$m [count]
address:m [count]
6 Intergraph Corporation - 2/94
sdb(1) CLIX sdb(1)
Single steps (as with s) until the specified location is modified
with a new value. If count is omitted, it is effectively infinity.
The variable must be accessible from the current procedure. Since
this command is done by software, it can be very slow.
[level] v
Toggles verbose mode for use when single stepping with S, s, or m.
If level is omitted, only the current source file and/or subroutine
name is displayed when either changes. If level is 1 or greater,
each C source line is displayed before it is executed; if level is
2 or greater, each assembler statement is also displayed. A v
command turns verbose mode off if it is on for any level.
k Kills the program being debugged.
procedure(arg1,arg2, ... )
procedure(arg1,arg2, ... )/m
Executes 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 displayed
according to format m. If no format is given, it defaults to d.
This facility is only available if the program was compiled with
the -g flag.
[linenumber] b [commands]
Sets a breakpoint at the given line. If a procedure name without a
line number is given (for example, proc:), a breakpoint is placed
at the first line in the procedure even if it was not compiled with
the -g flag. If linenumber is not specified, a breakpoint is
placed at the current line. If commands are not specified,
execution stops just before the breakpoint and control returns 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 Displays a list of the currently-active breakpoints.
[linenumber] d
Deletes a breakpoint at the given line. If linenumber is not
specified, the breakpoints are deleted interactively. Each
breakpoint location is displayed and a line is read from stdin. If
the line begins with a y or d, the breakpoint is deleted.
D Deletes all breakpoints without confirmation.
l Displays the next line to execute.
linenumber a
2/94 - Intergraph Corporation 7
sdb(1) CLIX sdb(1)
(Announce.) If linenumber has the form proc:number, the command
effectively executes a linenumber b l. If linenumber has the form
proc:, the command effectively executes a proc: b T.
Miscellaneous commands:
!command
The command is interpreted by sh.
newline
If the previous command displayed a source line, advance the
current line by one line and display the new current line. If the
previous command displayed a memory location, display the next
memory location.
end-of-file character
(Scroll.) Displays the next 10 lines of instructions, source, or
data, depending on which was displayed last. The end-of-file
character is usually the <Ctrl-D> sequence.
< filename
Reads commands from filename until the end-of-file is reached, and
then continue to accept commands from stdin. When a command in
this file tells sdb to display a variable, 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 Displays the address maps.
M [?/][*] b e f
Records 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 this case, the
second segment (b2, e2, f2) of the mapping is changed. If fewer
than three values are given, the remaining map parameters are
unchanged.
" <string>
Displays the given string. The C escape sequences with the form
\character are recognized, where character is a non-numeric
character.
q Exits the debugger.
The following commands also exist and are intended only for debugging the
debugger:
V Displays the version number.
Q Displays a list of procedures and files being debugged.
8 Intergraph Corporation - 2/94
sdb(1) CLIX sdb(1)
Y Toggles debug output.
EXAMPLES
1. This example debugs the executable module foo, ignoring any core
files, and looks for source files first in the /usr/src directory, and
then in the /usr2/src directory.
sdb foo - /usr/src : /usr2/src
2. This example sets the foo file to the state described in the core file
core.save , and looks for source files in the /usr/src directory.
sdb foo core.saved /usr/src
FILES
a.out An executable object file in the a.out format.
core A core image file.
CAUTIONS
When sdb displays the value of an external variable that has no debugging
information, a warning is displayed before the value. The size is assumed
to be an integer.
Data stored in text sections cannot be distinguished from functions.
Line number information in optimized functions is unreliable, and some
information may be missing.
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 that formats data from a core image.
The sdb command cannot display the value of a FORTRAN parameter. It will
erroneously display the address.
Tracebacks containing FORTRAN subprograms with multiple entry points may
display too many arguments in the wrong order, but their values are
correct.
The range of a FORTRAN 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.
Arrays having subscripts whose lower bounds are not 1 produce no problems.
2/94 - Intergraph Corporation 9
sdb(1) CLIX sdb(1)
EXIT VALUES
The exit values are not valid.
RELATED INFORMATION
Commands: acc(1), af77(1), cc(1), f77(1), sh(1), ed(1)
10 Intergraph Corporation - 2/94