sdb
PURPOSE
Provides a symbolic debugger for C and assembler pro-
grams.
SYNOPSIS
sdb [ -w ] [ -W ] [ -n namelist ] [ objfil [ corfil [ directory-list ] ]
]
DESCRIPTION
The sdb command provides a symbolic debugger to be used
with C and assembler programs. With it you can examine
object and core files and provide a controlled environ-
ment for running a program. You can set breakpoints at
selected statements or run the program one line at a
time. You can debug using symbolic variables and
instruct sdb to display them in their correct format.
Normally, objectfile is an executable file produced by
invoking cc with the -g flag. If you have not compiled
objectfile using the -g flag or if it is not executable
(because of compiler or loader errors), the symbolic
capabilities of sdb are limited, but you can still
examine the file and debug the program. objectfile
should always be in the same directory as the source
files used to construct it. Its default name is a.out.
The corefile parameter specifies a core image file. Its
default is core. The system writes out this core image
of a process when it ends abnormally. Specifying -
(minus) for corefile instructs sdb to ignore any core
image file that may be present. The colon-separated list
of directories specified by the dirlist parameter identi-
fies the location of the source files used to build
corefile. The default is the current directory. If
dirlist is the name of a file, the contents of the file
should be a colon-separated list of directory names.
While running, sdb always recognizes a current line and
current file. If corefile exists, sdb initially sets the
current line and the current file to the line and the
file that contains the source statement at which the
process ended. Otherwise, it sets them to the first line
in main and the file containing main. There is also a
current function, which is the function you are working
with at any given time. You can change the current line,
file, or function with the e command.
Write variable names as you do in C language programs.
Access variables local to a function by using the form
function:variable. The current function is the default
function. You can also specify a variable by its
address. Since you can use all forms of integer con-
stants which are valid in C, addresses can be expressed
as decimal, octal, or hexadecimal values.
Refer to structure members as variable.member, pointers
to structure members as variable->member, and array ele-
ments as variable[number].
If you use the form number.member or number->member, sdb
assumes number to be the address of the last structure
referred to. Generally, sdb interprets a structure as a
set of variables. Thus, it displays the values of all
elements when you request it to display a structure. If,
however, you request the address of a structure, it dis-
plays this value and not the addresses of individual ele-
ments.
Refer to elements of a multidimensional array as
variable[number][number] or as variable[number,number].
In place of number, use the form number;number to indi-
cate a range of values. You can also use an "*"
(asterisk) to represent all legitimate values for a sub-
script or omit subscripts to indicate the full range of
values. As with structures, sdb displays all the values
of an array or of a section of an array if you omit
trailing subscripts. If you omit subscripts, it displays
only the address of the array itself or of the section
specified.
Refer to a variable on the stack by using the form func-
tion:variable,. Here, number specifies the variable's
location on the stack, counting the top, or most recently
pushed variable, as the first. Use this for recursive
function calls. The current function is the default.
Refer to line numbers as filename:number or
function:number. The current file and current function
are the default values.
Notes:
1. Data stored in text sections is indistinguishable
from functions.
2. Line number information in optimized functions is
unreliable, and some information may be missing.
3. Source line and local symbol information for routines
in shared libraries is not implemented, and these
modules should not be compiled with the -g flag.
Break points may be set in these routines by address
only, and code in shared library modules may be
single-stepped by instruction only.
4. The sdb command cannot comprehend a module in which C
functions (as opposed to declarations and pre-
processor definitions) occur in include files.
FLAGS
-n kernel-image Specifies the name of the running
kernel (or the one running when
corefile was produced). This enables
proper traces back through the
floating-point emulation code. /unix
is the default value.
-w Allows overwriting of locations in
objectfile.
-W Turns off the warnings normally given
if source files cannot be found or are
newer than objectfile.
SUBCOMMANDS
Examining Program Data
T Displays the top line of the stack trace.
t Displays a stack trace of the program
that ended abnormally.
variable/[nlf] Displays variable or n memory locations
starting at the address of variable.
The l parameter selects the number of
bytes in one memory location. Your
choices are:
b One byte
h Two bytes
l Four bytes.
The f parameter selects the display
format. This can be one of the fol-
lowing:
a Displays all bytes from the address of
the variable to the first null byte.
c Displays a character value.
d Displays a decimal value.
f Displays a 32-bit, single-precision
floating-point value.
g Displays a 64-bit, double-precision
floating-point value.
I Interprets values as assembly language
instructions and displays numerically.
i Interprets values as assembly language
instructions and displays them numer-
ically and symbolically.
o Displays an octal value.
t Displays "F" if variable= 0; other-
wise, displays "T".
p Displays a pointer to a function.
s Treats variable as a string pointer
and displays characters beginning with
the address to which it points and
ending at the first null byte reached.
u Displays an unsigned decimal value.
x Displays a hexadecimal value.
If you do not specify n, l, or f, sdb
chooses a value appropriate to variable
type as declared in the source file.
Specifying a memory location size only
works with formats c, d, o, u, and x.
You can specify the number of memory
locations (n) to be displayed by the s or
a formats. For strings that contain two-
byte extended characters, the font shift
character is represented by a backslash
followed by lowercase s and the font
shift number.
For example, \s1 means that the current
byte being displayed is a font shift
character. This form of representation
for the font shift byte is only available
when a count is specified. However, if
the first character contained in the
address specified by the a format is the
second byte of a two-byte extended char-
acter, then that byte is displayed
without the proper shift affixed to con-
struct the whole two-byte sequence. The
default action for these formats is to
display characters until either a null
byte is reached or 128 characters have
been displayed. The command ./ (dot
slash) redisplays the last variable.
You can use the special sh characters "*"
(asterisk) and "?" (question mark) in
function and variable names, providing a
limited form of pattern matching. If you
give no function name, global variables
and variables local to the current func-
tion are matched. If you specify a func-
tion name, then only variables local to
that function are matched. To match only
global variables, use the form :pattern.
The sdb command recognizes structures,
arrays, and pointers so that all of the
following commands work:
array[2][3]/
sym.id/
psym->usage/
xsym[20].p->usage/
line?[lf]
variable?[lf] Displays the value found in objectfile at
the address selected by line or variable
(function name), using the specified
length and format. The default format is
i.
line=[lf]
variable=[lf]
number=[lf] Displays the address of variable or line
or the value of number in the specified
length and format. The default is lx.
number=[lf] provides a convenient way to
convert decimal, octal, and hexadecimal
values.
variable!value Sets variable to the given value. value
may be a numeric or character constant or
another variable. Expressions that
produce more than one value, such as
structures, are not allowed as value.
However, variable may be an expression
which represents more than one variable,
such as an array or structure name.
Specify a character constant with an
initial ' (single quote), for example,
'c. Numbers are treated as integers
unless they contain a decimal point or an
exponent. In the latter case, they are
treated as having the type double. Reg-
ister values are viewed as integers. If
you give an address of a variable, it is
treated as the address of a variable of
type int. C conventions are used in any
type conversions that are necessary to
perform the indicated assignment.
x Displays the machine registers and the
current assembly language instruction.
X Displays the current assembly language
instruction.
Displaying and Manipulating Source Files
e function
e file
e dir/
e dir file Changes the current function, file, or
directory. Specifying only function also
sets the current file to the one con-
taining the selected function. sdb
reports the current function, file, or
directory for any unspecified parameters.
/pattern/ Searches forward from the current line
for a line containing a string matching
pattern. The trailing / (slash) can be
omitted. See "ed" for a discussion of
pattern notation.
?pattern? Searches backward from the current line
for a line containing a string matching
pattern. The trailing ? (question mark)
can be omitted.
p Displays the current line.
z Displays the current line and the fol-
lowing nine lines. Sets the current line
to the last line displayed.
w Displays the 10 lines around the current
line (a window).
number Sets the current line to number. Dis-
plays the new current line.
number+ Advances the current line by the speci-
fied number of lines. Displays the new
current line.
number- Decreases the current line by the speci-
fied number of lines. Displays the new
current line.
Ctrl-D Scrolls. Pressing Ctrl-D displays the
next 10 lines of source or data.
Enter If the previous command displayed a
source line, pressing the Enter key
advances the current line by one line and
displays the new current line. If the
previous command displayed a memory
location, pressing the Enter key displays
the next memory location.
Controlling the Running of the Source Program
[num] r [p [p2] . . . ]
[num] R Runs the program with the given parame-
ters. If you specify no parameters with
r, it reuses previously specified parame-
ters. R runs the program with no parame-
ters. A parameter beginning with < (left
angle bracket) or > (right angle bracket)
redirects input or output, respectively.
If given, num selects the number of
breakpoints to be ignored.
[line] b [command[; command] . . . ]
Sets a breakpoint at the given line. If
you specify a function name without a
line number, sdb places a breakpoint at
the first line in the function, even if
it was not compiled with the -g flag. If
you do not specify a line, a breakpoint
is placed at the current line. If you
specify no commands, the program stops
running just before the breakpoint and
returns control to sdb. Otherwise sdb
performs the specified commands when the
breakpoint is encountered, and then the
program being debugged continues. If the
k command is specified, however, control
returns to sdb.
B Lists the currently active breakpoints.
[line] d Deletes a breakpoint at the selected
line. If you select no line, breakpoints
are deleted interactively. sdb displays
each breakpoint location and reads a line
from standard input. If the line begins
with a y or d, then it deletes the break-
point.
D Deletes all breakpoints.
[line] c [num]
[line] C [num] Continues running program after a break-
point or an interrupt. C continues after
resetting the signal that caused the
program to stop. c ignores the signal.
An optional num selects the number of
breakpoints to ignore. If you specify a
line, sdb places a temporary breakpoint
at the line and continues the program.
It deletes the breakpoint when the
command finishes.
[line] g [num] Continues after a breakpoint, with exe-
cution resumed at the given line. num
specifies how many breakpoints to ignore.
l Displays the last executed line.
i
I Runs the program one machine level
instruction at a time, ignoring the
signal that stopped the program (i) or
passing the signal back to the program
(I).
s [num]
S [num] Runs the program for one or the specified
number of lines. S is equivalent to s
except that it does not stop within
called functions. Use S if you are con-
fident that the called function works,
but want to test the calling routine.
variable$m [num]
address:m [num] Runs the program until the specified
location is modified with a new value or
is modified a specified num of times.
The variable must be accessible from the
current function.
line a If line is of the form function:number,
this command has the effect of the sdb
subcommand: "line b l". If line is of
the form function:, it has the effect of
the sdb subcommand: "function: b T".
[level] v Toggles verbose mode, for use with the S,
s or m commands. If you omit level, then
just the current source file or subrou-
tine 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.
If verbose mode is on for any level,
another v turns it off.
function(p [p . . . ])[/f]
Runs the named function, passing to it
the specified parameters. These can be
integer, character, or string constants
or the names of variables accessible to
the current function. You can specify
the format of displayed values. The
default format is d (decimal).
k Kills the program being debugged.
M Displays the address maps. Program
addresses are mapped to file addresses
using two field triples: b1, e1, f1 and
b2, e2, f2. The f1 field is the length
of the header at the beginning of the
file; the f2 field is the displacement
from the beginning of the file to the
data. For a plain executable file with
mixed text and data, this is the same as
the length of the header; for shared text
and split instruction/data files, this is
the length of the header plus the size of
the text portion.
The b and e fields are the starting and
ending locations for a segment. Given an
address A, calculate its location in the
file (either a.out or core) as follows:
If b1 < A < e1
then file address = (A-b1) f1
If b2 < A < e2
then file address = (A-b2) f2
M[?/][*] b e f Records new values for the address map.
The parameters ? and / specify the text
and data maps respectively. The first
segment is changed unless you specify *,
in which case the second segment is
changed. (These segments differ only in
programs with split instruction and data
space. In this case, use the second
segment to examine the data section of
the a.out file rather than the data
section of the core image file.) If you
give fewer than three values, the
remaining map parameters are left
unchanged.
" string Displays the given string. sdb recog-
nizes C escape sequences of the form
\character.
!AIX-command Performs the specified AIX-command.
<file Reads commands from file until reaching
the end of file and then continues to
accept commands from standard input.
When a command in such a file tells sdb
to display a variable, the variable name
is displayed along with the value. This
command cannot be nested.
>file Redirects standard output to file.
q Exits the debugger.
Debugging the Debugger
Q Displays a list of functions and files
being debugged.
V Displays the version number.
FILES
a.out, core
RELATED INFORMATION
The following commands: "cc," "ed," and "sh."
The a.out and core files in AIX Operating System Tech-
nical Reference.
"Overview of International Character Support" in Managing
the AIX Operating System.
"Debugging Programs" in AIX Operating System Programming
Tools and Interfaces.