sdb(1) UNIX System V(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.
-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.
10/89 Page 1
sdb(1) UNIX System V(Extended Software Generation System Utilities) sdb(1)
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.
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.
Page 2 10/89
sdb(1) UNIX System V(Extended Software Generation System Utilities) sdb(1)
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
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.
10/89 Page 3
sdb(1) UNIX System V(Extended Software Generation System Utilities) sdb(1)
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.
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.
Page 4 10/89
sdb(1) UNIX System V(Extended Software Generation System Utilities) sdb(1)
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.
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:
10/89 Page 5
sdb(1) UNIX System V(Extended Software Generation System Utilities) sdb(1)
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.
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.
Page 6 10/89
sdb(1) UNIX System V(Extended Software Generation System Utilities) sdb(1)
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 (for example, 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.
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
10/89 Page 7
sdb(1) UNIX System V(Extended Software Generation System Utilities) sdb(1)
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), a.out(4), 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
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, and so on, is defined is
attached to the process. For shared objects attached at startup (for
example, 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.
Page 8 10/89