SunOS man pages : adb (1)
User Commands adb(1)
NAME
adb - general-purpose debugger
SYNOPSIS
adb [ -k ] [ -w ] [ -I dir ] [ -P prompt ] [ -V mode ]
[ objectfile [ corefile [ swapfile ] ] ]
DESCRIPTION
The adb utility is an interactive, general-purpose debugger.
It can be used to examine files and provides a controlled
environment for the execution of programs.
OPTIONS
The following options are supported:
-k Performs kernel memory mapping. Use when corefile is a
system crash dump or /dev/mem, or when using a swap-
file.
-w Creates both objectfile and corefile, if necessary,
and opens them for reading and writing so that they
can be modified using adb.
-I dir
Specifies a colon-separated list of directories where
files to be read with $< or $<< (see below) will be
sought; the default is /usr/platform/plat-
name/lib/adb:/usr/lib/adb, where plat-name is the name
of the platform implementation. plat-name can be found
using the -i option of uname(1).
-P prompt
Specifies the adb prompt string.
SPARC Only
-V mode
Specifies the disassembly and register display mode.
Options are: 1 (v8), 2 (generic V9), and 4 (v9 plus
Sun Ultra-SPARC specific instructions). The default
mode is determined by the type of corefile being exam-
ined.
OPERANDS
The following operands are supported:
objectfile
Normally an executable program file, preferably con-
taining a symbol table. If the file does not contain a
symbol table, it can still be examined, but the sym-
bolic features of adb cannot be used. The default for
objectfile is a.out.
SunOS 5.8 Last change: 13 Aug 1999 1
User Commands adb(1)
corefile
Assumed to be a core image file produced after execut-
ing objectfile. The default for corefile is core.
swapfile
The image of the swap device used. It is valid only
when used with the -k option.
USAGE
The adb utility reads commands from the standard input and
displays responses on the standard output. It does not sup-
ply a prompt by default. It ignores the QUIT signal. INTER-
RUPT invokes the next adb command. adb generally recognizes
command input of the form:
[ address ] [, count ] [ command ] [ ; ]
address and count (if supplied) are expressions that result,
respectively, in a new current location and a repetition
count. command is composed of a verb followed by a modifier
or list of modifiers.
The symbol `.' represents the current location; it is ini-
tially 0. The default count is 1.
Expressions
. The value of dot.
+ The value of dot incremented by the current increment.
^ The value of dot decremented by the current increment.
& The last address typed. (In older versions of adb, `"'
was used.)
integer
A number. The prefixes 0o and 0O indicate octal; 0t
and 0T, decimal; 0x and 0X, hexadecimal (the default).
int.frac
A floating-point number.
'cccc'
ASCII value of up to 4 characters.
<name The value of name, which is either a variable name or
a register name.
symbol
A symbol in the symbol table.
SunOS 5.8 Last change: 13 Aug 1999 2
User Commands adb(1)
(exp) The value of exp.
Unary Operators
*exp The contents of location exp in corefile.
%exp The contents of location exp in objectfile (In older
versions of adb, `@' was used).
-exp Integer negation.
~exp Bitwise complement.
#exp Logical negation.
Binary Operators
Binary operators are left associative and have lower pre-
cedence than unary operators.
+ Integer addition.
- Integer subtraction.
* Integer multiplication.
% Integer division.
& Bitwise conjunction ("AND").
| Bitwise disjunction ("OR").
# lhs rounded up to the next multiple of rhs.
Variables
Named variables are set initially by adb but are not used
subsequently.
0 The last value printed.
1 The last offset part of an instruction source.
2 The previous value of variable 1.
9 The count on the last $< or $<< command.
On entry the following are set from the system header in the
corefile or objectfile as appropriate.
b The base address of the data segment.
d The data segment size.
e The entry point.
SunOS 5.8 Last change: 13 Aug 1999 3
User Commands adb(1)
m The `magic' number
t The text segment size.
Commands
Commands to adb consist of a verb followed by a modifier or
list of modifiers.
Verbs
? Print locations starting at address in objectfile.
/ Print locations starting at address in corefile.
= Print the value of address itself.
: Manage a subprocess.
> Assign a value to a variable or register.
>/modifier/
Take the quantity specified by modifier from the
address of the value and assign it to a variable or
register. modifier can be one of the following:
c unsigned char quantity
s unsigned short quantity
i unsigned int quantity
l unsigned long quantity
RETURN
Repeat the previous command with a count of 1. Incre-
ment `.'.
! Shell escape.
?, /, and = Modifiers
The following format modifiers apply to the commands ?, /,
and =. To specify a format, follow the command with an
optional repeat count, and the desired format letter or
letters. The braces ({}) indicate that only one of the
included commands must be specified.
{ ?/= } [ [ r ] f ... ]
where r is a decimal repeat count, and f is one of the for-
mat letters listed below:
SunOS 5.8 Last change: 13 Aug 1999 4
User Commands adb(1)
o (`.' increment: 2) Print 2 bytes in octal.
O (4) Print 4 bytes in octal.
q (2) Print in signed octal.
Q (4) Print long signed octal.
g (8) Display 8 bytes in signed octal.
G (8) Display 8 bytes in unsigned octal.
d (2) Print in decimal.
D (4) Print long decimal.
e (8) Display 8 bytes in signed decimal.
E (8) Display 8 bytes in unsigned decimal.
x (2) Print 2 bytes in hexadecimal.
X (4) Print 4 bytes in hexadecimal.
J (8) Display 8 bytes in hexadecimal.
K (n) Print pointer or long in hexadecimal (displays
4 bytes for 32-bit programs and 8 bytes for 64-bit
programs).
u (2) Print as an unsigned decimal number.
U (4) Print long unsigned decimal.
f (4) Print a single-precision floating-point number.
F (8) Print a double-precision floating-point number.
b (1) Print the addressed byte in octal.
c (1) Print the addressed character.
C (1) Print the addressed character using ^ escape con-
vention.
s (n) Print the addressed string.
S (n) Print a string using the ^ escape convention.
y (8) Print 8 bytes in date format.
Y (4) Print 4 bytes in date format.
SunOS 5.8 Last change: 13 Aug 1999 5
User Commands adb(1)
i (4) Print as machine instructions. (SPARC)
i (variable) Print as machine instructions. (IA)
a (0) Print the value of `.' in symbolic form.
p (n) Print the addressed value in symbolic form.
t (0) Tab to the next appropriate TAB stop.
r (0) Print a SPACE.
n (0) Print a NEWLINE.
"..." (0) Print the enclosed string.
^ (0) Decrement `.'.
+ (0) Increment `.'.
- (0) Decrement `.' by 1.
? and / Modifiers
l value mask
Apply mask and compare for value; move `.' to matching
location.
L value mask
Apply mask and compare for 4-byte value; move `.' to
matching location.
M value mask
Apply mask and compare for 8-byte value; move `.' to
matching location.
w value
Write the 2-byte value to address.
W value
Write the 4-byte value to address.
Z value
Write the 8-byte value to address.
m b1 e1 f1[?]
Map new values for b1, e1, f1. If the ? or / is fol-
lowed by * then the second segment (b2,e2,f2) of the
address mapping is changed.
v Like w, but writes only one byte at a time.
SunOS 5.8 Last change: 13 Aug 1999 6
User Commands adb(1)
: Modifiers
The optional len is specified in decimal; if not specified,
it defaults to 1.
b commands
Set instruction breakpoint; set `.' to address and
execute commands when reached.
len w commands
Set write watchpoint (data breakpoint); set `.' to the
affected location and execute commands when any byte
in the range [address,address+len) is written.
len a commands
Set access watchpoint; set `.' to the affected loca-
tion and execute commands when any byte in the range
[address,address+len) is read or written.
len p commands
Set execution watchpoint; set `.' to the affected
location and execute commands when any instruction in
the range [address,address+len) is executed.
r Run objectfile as a subprocess.
d Delete breakpoint at address or watchpoint containing
address.
z Delete all breakpoints and watchpoints.
cs Continue the subprocess with signal s.
ss Single-step the subprocess with signal s.
es Single-step but do not step into called functions.
i Add the signal specified by address to the list of
signals passed directly to the subprocess.
t Remove the signal specified by address from the list
implicitly passed to the subprocess.
k Terminate (kill) the current subprocess, if any.
A Attach adb to an existing process ID. (For example,
0t1234:A would attach adb to decimal process number
1234.)
R Release the previously attached process.
$ Modifiers
<filename
SunOS 5.8 Last change: 13 Aug 1999 7
User Commands adb(1)
Read commands from the file filename.
<<filename
Similar to <, but can be used in a file of commands
without closing the file.
>filename
Append output to filename, which is created if it does
not exist.
l Show the current lightweight process (LWP) ID.
L Show all the LWP IDs.
P Specify the adb prompt string.
? Print process ID, the signal which stopped the subpro-
cess, and the registers.
r Print the names and contents of the general CPU regis-
ters, and the instruction addressed by pc.
x Print the names and contents of floating-point regis-
ters 0 through 15. (SPARC)
X Print the names and contents of floating-point regis-
ters 16 through 31. (SPARC)
x or X
Print the contents of floating point registers. $x and
$X accept a count which determines the precision in
which the floating point registers will be printed;
the default is 25. Using $X will produce more verbose
output than using $x. (IA)
y Print the names and contents of floating-point regis-
ters 32 through 47. (SPARC)
Y Print the names and contents of floating-point regis-
ters 48 through 63. (SPARC)
b Print all breakpoints and watchpoints and their asso-
ciated counts, types, lengths, and commands.
c C stack backtrace. On SPARC based systems, it is
impossible for adb to determine how many parameters
were passed to a function. The default that adb
chooses in a $c command is to show the six parameter
registers. This can be overridden by appending a hexa-
decimal number to the $c command, specifying how many
parameters to display. For example, the $cf command
will print 15 parameters for each function in the
SunOS 5.8 Last change: 13 Aug 1999 8
User Commands adb(1)
stack trace.
C Same as $c, but in addition it displays the frame
pointer values.
d Set the default radix to address and report the new
value. Note: address is interpreted in the (old)
current radix. Thus `10$d' never changes the default
radix.
e Print the names and values of external variables.
w Set the page width for output to address (default 80).
s Set the limit for symbol matches to address (default
255).
o All integers input are regarded as octal.
q Exit from adb.
v Print all non-zero variables in octal.
m Print the address map.
f Print a list of known source filenames.
p (Kernel debugging) Change the current kernel memory
mapping to map the designated user structure to the
address given by u; this is the address of the user's
proc structure.
i Show which signals are passed to the subprocess with
the minimum of adb interference.
V Change the current disassembly and register display
mode. Options are: 1 (v8), 2 (generic V9), and 4 (v9
plus Sun Ultra-SPARC specific instructions). Omitting
the numeric parameter prints information on the
current disassembly mode. (SPARC)
W Reopen objectfile and corefile for writing, as though
the -w command-line argument had been given.
See largefile(5) for the description of the behavior of adb
when encountering files greater than or equal to 2 Gbyte ( 2
**31 bytes).
EXAMPLES
Example 1: Starting adb on the running kernel
SunOS 5.8 Last change: 13 Aug 1999 9
User Commands adb(1)
To start adb on the running kernel, use (as root):
example# adb -k /dev/ksyms /dev/mem
/dev/ksyms is a special driver that provides an image of the
kernel's symbol table. This can be used to examine kernel
state and debug device drivers. Refer to the Debugging
chapter in Writing Device Drivers for more information.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
non-zero
The last command either failed or returned a non-zero
status.
FILES
/usr/lib/adb
/usr/platform/platform-name/lib/adb
Default directories in which files are to be read with
$< and $<<. platform-name is the name of the platform
implementation and can be found using uname -i (see
uname(1)).
/usr/lib/adb/sparcv9
/usr/platform/platform-name/lib/adb/sparcv9
Default directories in which files for 64-bit SPARC V9
are to be read with $< and $<<. platform-name is the
name of the platform implementation and can be found
using uname -i (see uname(1)).
a.out Default name for objectfile operand.
core Default name for corefile operand.
/dev/ksyms
Special driver to provide an image of the kernel's
symbolic table.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.8 Last change: 13 Aug 1999 10
User Commands adb(1)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcsu (32-bit) |
|_____________________________|_____________________________|
| | SUNWcsxu (64-bit) |
|_____________________________|_____________________________|
SEE ALSO
mdb(1), uname(1), a.out(4), core(4), proc(4), attributes(5),
largefile(5), ksyms(7D)
Writing Device Drivers
DIAGNOSTICS
When there is no current command or format, adb comments
about inaccessible files, syntax errors, abnormal termina-
tion of commands, and so forth.
NOTES
The adb utility may be implemented as a link to the new
mdb(1) utility in versions of Solaris after Solaris 8. The
adb and mdb utilities are both low-level debuggers that can
be used to examine user processes as well and the live
operating system or operating system crash dumps. The new
mdb utility provides complete backwards compatibility with
the existing syntax and features of adb, including support
for processing adb macro files. The mdb(1) man page
describes more fully the features of the new debugger,
including its adb compatibility mode. This mode will be
activated by default if the adb link is present and is exe-
cuted.
The adb utility is platform and release dependent. Kernel
core dumps should be examined on the same platform they were
created on.
BUGS
Since no shell is invoked to interpret the arguments of the
:r command, the customary wild-card and variable expansions
cannot occur.
Since there is little type-checking on addresses, using a
sourcefile address in an inappropriate context may lead to
unexpected results.
The $cparameter-count command is a work-around.
SunOS 5.8 Last change: 13 Aug 1999 11
|
 |
|
|
