sdb(1) (Extended Software Generation System Utilities) sdb(1)
NAME
sdb - symbolic debugger
SYNOPSIS
sdb [-e] [-s signo] [-V] [-W] [-w] [objfile [corfile [directory-
list]]]
DESCRIPTION
sdb is the symbolic debugger for C and assembly programs. sdb may be
used to examine executable program files and core files. It may also
be used to examine live processes in a controlled execution
environment.
The objfile argument is the name of an executable program file. To
take full advantage of the symbolic capabilities of sdb, this file
should be 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.
objfile may also be a path name in the /proc directory, in which case
the currently executing process denoted by that path name is
controlled by sdb.
The corfile argument is the name of a core image file. A core image
file is produced by the abnormal termination of objfile or by the use
of gcore. A core image file contains a copy of the segments of a
program. The default for corfile is core. A core image file need
not be present to use sdb. Using a hyphen (-) instead of corfile
forces sdb to ignore an existing core image file.
The directory-list argument is a colon-separated list of directories
that is used by sdb to locate source files used to build objfile. If
no directory list is specified, sdb will look in the current
directory.
The following options are recognized by sdb:
-e Ignore symbolic information and treat nonsymbolic addresses as
file offsets.
-s signo
Where signo is a decimal number that corresponds to a signal
number [see signal(2)], do not stop live processes under
control of sdb that receive the signal. This option may be
used more than once on the sdb command line.
-V Print version information. If no objfile argument is specified
on the command line, sdb will exit after printing the version
information.
8/91 Page 1
sdb(1) (Extended Software Generation System Utilities) sdb(1)
-W Suppress warnings about corfile being older than objfile or
about source files that are older than objfile.
-w Allow user to write to objfile or corfile.
sdb recognizes a current line and a current file. When sdb is
examining an executable program file without a core file, the current
line and current file are initially set to the line and file
containing the first line of main. If corfile exists, then current
line and current file are initially set to the line and file
containing the source statement where the process terminated. The
current line and current file change automatically as a live process
executes. They may also be changed with the source file examination
commands.
Names of variables are written as in C. 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.
Structure members may be referred to as variable.member, pointers to
structure members as variable->member, and array elements as
variable[number]. Pointers may also be dereferenced by using the
form pointer[number]. Combinations of these forms may also be used.
The form number->member may be used where number is the address of a
pointer, and number.member where number is interpreted as the address
of a structure instance. The template of the structure type used in
this case will be the last structure type referenced. When sdb
displays the value of a structure, it does so by displaying the value
of all elements of the structure. The address of a structure is
displayed by displaying the address of the structure instance rather
than the addresses of individual elements.
Elements of a multidimensional array may be referred to 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. If no subscripts
are specified, sdb will display the value of all elements of the
array.
A particular instance of a variable on the stack is referred to as
procedure:variable,number. The number is the occurrence of the
specified procedure on the stack, with the topmost occurrence being
1. The default procedure is the one containing the current line.
Addresses may be used in sdb commands as well. Addresses are
specified by decimal, octal, or hexadecimal numbers.
Page 2 8/91
sdb(1) (Extended Software Generation System Utilities) sdb(1)
Line numbers in the source program are specified by the form
filename:number or procedure:number. In either case, the number is
relative to the beginning of the file and corresponds to the line
number used by text editors or the output of pr. A number used by
itself implies a line in the current file.
While a live process is running under sdb, all addresses and
identifiers refer to the live process. When sdb is not examining a
live process, the addresses and identifiers refer to objfile or
corfile.
Commands
The commands for examining data in the program are:
t Prints a stack trace of the terminated or halted program. The
function invoked most recently is at the top of the stack. For
C programs, the stack ends with start, which is the startup
routine that invokes main.
T Prints the top line of the stack trace.
variable/clm
Print the value of variable according to length l and format m.
The 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 signed decimal
u unsigned decimal
o octal
x hexadecimal
f 32-bit single precision floating point
g 64-bit double precision floating point
8/91 Page 3
sdb(1) (Extended Software Generation System Utilities) sdb(1)
s Assumes that variable is a string pointer and prints
characters starting at the address pointed to by the
variable.
a Prints characters starting at the variable's address. Do
not use this with register variables.
p pointer to procedure
i Disassembles machine-language instruction with addresses
printed numerically and symbolically.
I Disassembles machine-language instruction with addresses
printed numerically only.
Length specifiers are effective with formats c, d, u, o, x. The
length specifier determines the output length of the value to be
displayed. This value may be truncated. The count specifier c
displays that many units of memory, starting at the address of
the variable. The number of bytes in the unit of memory is
determined by l or by the size associated with the variable. If
the specifiers c, l, and m are omitted, sdb uses defaults. If a
count specifier is used with 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.
For a limited form of pattern matching, use the sh
metacharacters * and ? within procedure and variable names.
(sdb does not accept these metacharacters in file names, as the
function name in a line number when setting a breakpoint, in the
function call command, or as the argument to the e command.) If
no procedure name is supplied, sdb matches both local and global
variables. If the procedure name is specified, then sdb matches
only local variables. To match global variables only, use
:pattern. To print all variables, use *:*.
linenumber?lm
variable:?lm
Prints the value at the address from the executable or text
space given by linenumber or variable (procedure name),
according to the format lm. The default format is i.
variable=lm
linenumber=lm
number=lm
Prints the address of variable or linenumber, or the value of
number. l specifies length and m specifies the format. If no
format is specified, then sdb uses lx (four-byte hex). m allows
you to convert between decimal, octal, and hexadecimal.
Page 4 8/91
sdb(1) (Extended Software Generation System Utilities) sdb(1)
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; structures are allowed only if assigning to another
structure variable of the same type. 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, except the
floating point registers, are viewed as integers. Register names
are identical to those used by the assembler (for example,
%regname where regname is the name of a register). 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 Prints the machine registers and the current machine-language
instruction.
X Prints the current machine-language instruction.
The commands for examining source files are:
e
e procedure
e filename
e directory/
e, without arguments, prints the name of the current file. The
second form sets the current file to the file containing the
procedure. The third form sets the current file to filename.
The current line is set to the first line in the named procedure
or file. Source files are assumed to be in the directories in
the directory list. The fourth form adds directory to the end
of the directory list.
/regular expression/
Searches forward from the current line for a line containing a
string matching regular expression, as in ed. The trailing /
may be omitted, except when associated with a breakpoint.
?regular expression?
Searches backward from the current line for a line containing a
string matching regular expression, as in ed. The trailing ?
may be omitted, except when associated with a breakpoint.
p Prints the current line.
z Prints the current line and the following nine lines. Sets the
current line to the last line printed.
8/91 Page 5
sdb(1) (Extended Software Generation System Utilities) sdb(1)
w Prints the 10 lines (the window) around the current line.
number
Specifies the current line. Prints the new current line.
count+
Advances the current line by count lines. Prints the new
current line.
count-
Resets the current line by count lines back. Prints the new
current line.
The commands for controlling the execution of the source program are:
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. The R
command runs the program with no arguments. An argument
beginning with < or > redirects the standard input or output,
respectively. Full sh syntax is accepted. If count is given,
it specifies the number of breakpoints to be ignored.
linenumber c count
linenumber C count
Continues execution. sdb stops when it encounters count
breakpoints. The signal that stopped the program 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 continues. The breakpoint is deleted
when the command finishes.
linenumber g count
Continues with execution resumed at the given line. If count is
given, it specifies the number of breakpoints to be ignored.
s count
S count
s single steps the program through count lines or if no count is
given, then the program runs for one line. s will step from
one function into a called function. S also steps a program,
but it will not step into a called function. It steps over the
function called.
i count
I count
Single steps by count machine-language instructions. The signal
that caused the program to stop is reactivated with the I
command and ignored with the i command.
Page 6 8/91
sdb(1) (Extended Software Generation System Utilities) sdb(1)
variable$m count
address:m count
Single steps (as with s) until the specified location is
modified with a new value. If count is omitted, it is, in
effect, infinity. Variable must be accessible from the current
procedure. This command can be very slow.
level v
Toggles verbose mode. This is for use when single stepping with
S, s, or m. If level is omitted, then just the current source
file and/or function name is printed when either changes. If
level is 1 or greater, each C source line is printed before it
executes. If level is 2 or greater, each assembler statement is
also printed. A v turns verbose mode off.
k Kills the program being debugged.
procedure(arg1,arg2,...)
procedure(arg1,arg2,...)/m
Executes the named procedure with the given arguments.
Arguments can be register names, 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
Sets 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 at the breakpoint and control is returned
to sdb. Otherwise the commands are executed when the breakpoint
is encountered. Multiple commands are specified by separating
them with semicolons. Nested associated commands are not
permitted; setting breakpoints within the associated
environments is permitted.
B Prints a list of the currently active breakpoints.
linenumber d
Deletes 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 Deletes all breakpoints.
8/91 Page 7
sdb(1) (Extended Software Generation System Utilities) sdb(1)
l Prints the last executed line.
linenumber a
Announces a line number. If linenumber is of the form
proc:number, the command effectively does a linenumber:b l;c.
If linenumber is of the form proc:, the command effectively does
a proc:b T;c.
Miscellaneous commands:
#rest-of-line
The rest-of-line represents comments that are ignored by sdb.
!command
The command is interpreted by sh.
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. If the previous command disassembled an
instruction, then disassemble the next instruction.
end-of-file character
Scrolls the next 10 lines of instructions, source, or data
depending on which was printed last. The end-of-file character
is usually control-d.
< filename
Read commands from filename until the end of file is reached,
and then continue to accept commands from standard input.
Commands are echoed, preceded by two asterisks, just before
being executed. This command may not be nested; < may not
appear as a command in a file.
M Prints the address maps.
" string "
Prints the given string. The C escape sequences of the form
\character, \octaldigits, or \xhexdigits are recognized, where
character is a nonnumeric character. The trailing quote may be
omitted.
q Exits the debugger.
V Prints version stamping information.
SEE ALSO
cc(1), signal(2), core(4), syms(4).
ed(1), gcore(1), sh(1) in the User's Reference Manual.
The ``sdb'' chapter in the Programmer's Guide: ANSI C and Programming
Page 8 8/91
sdb(1) (Extended Software Generation System Utilities) sdb(1)
Support Tools.
NOTES
If objfile is a dynamically linked executable, variables, function
names, and so on that are defined in shared objects may not be
referenced until the shared object in which the variable, etc., is
defined is attached to the process. For shared objects attached at
startup (e.g., libc.so.1, the default C library), this implies that
such variables may not be accessed until main is called.
The objfile argument is accessed directly for debugging information
while the process is created via the PATH variable.
8/91 Page 9