ADB(1)

NAME
adb - general-purpose debugger

SYNOPSIS
adb [ -w ] [ -k ] [ -I dir ] [ objectfile [ corefile ] ]

AVAILABILITY

adb is available with the Debugging software installation option. Refer to for information on how to install optional software.

DESCRIPTION

adb is an interactive, general-purpose debugger. It can be used to examine files and provides a controlled environment for the execution of programs.

objectfile is normally an executable program file, preferably containing a symbol table. If the file does not contain a symbol table, it can still be examined, but the symbolic features of adb cannot be used. The default for objectfile is a.out. corefile is assumed to be a core image file produced after executing objectfile. The default for corefile is core.

OPTIONS

-k  Perform kernel memory mapping; should be used when corefile is a system crash dump or /dev/mem.

-w  Create both objectfile and corefile, if necessary, and open them for reading and writing so that they can be modified using adb.

-I dir
    specifies a directory where files to be read with $< or $<< (see below) will be sought; the default is /usr/lib/adb.

USAGE
Refer to adb in for more complete information on how to use adb. Note: Some commands require that you compile progams to be debugged with the -go compiler flag; see cc(1V) for details. These commands are not currently available on Sun-4 systems; they are marked `-go only' below.

  Commands
adb reads commands from the standard input and displays responses on the standard output. It does not supply a prompt. It ignores the QUIT signal. INTERRUPT 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 address, 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 initially zero. The default count is `1'.

  Verbs
?   Print locations starting at address in objectfile.
/   Print locations starting at address in corefile.
=   Print the value of address itself.
@   Interpret address as a source address. Print locations in objectfile or lines of source, as appropriate. -go only.
:   Manage a subprocess.
$r  Print names and contents of CPU registers.
$R  Print names and contents of MC68881 registers, if any.
$x  Print the names and contents of FPA registers 0 through 15, if any.
$X  Print the names and contents of FPA registers 16 through 31, if any.
>   Assign a value to a variable or register.
RETURN
    Repeat the previous command with a count of 1. Increment `.'.
!   Shell escape.

  Modifiers

Modifiers specify the format of command output. Each modifier consists of a letter, preceded by an integer repeat count.

  Format 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:

    [ v ] [ [ r ] f ... ]

where v is one of these four command verbs, r is a repeat count, and f is one of the format letters listed below:
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.
d   (2) Print in decimal.
D   (4) Print long decimal.
x   (2) Print 2 bytes in hexadecimal.
X   (4) Print 4 bytes in hexadecimal.
h   (2) Print 2 bytes in hexadecimal in reverse order. Sun386i systems only.
H   (4) Print 4 bytes in hexadecimal in reverse order. Sun386i systems only.
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.
e or E
    (12) Print a 96-bit MC68881 extended-precision floating-point number. Sun-2 or Sun-3 systems only.
b   (1) Print the addressed byte in octal.
B   (1) Print the addressed byte in hexadecimal. Sun386i systems only.
c   (1) Print the addressed character.
C   (1) Print the addressed character using ^ escape convention.
s   (n) Print the addressed string.
S   (n) Print a string using the ^ escape convention.
Y   (4) Print 4 bytes in date format.
i   (n) Print as machine instructions.
M   (n) Print as machine instructions along with machine code. Sun386i systems only.
z   (n) Print with MC68010 machine instruction timings. Sun-2 or Sun-3 system only.
I   (0) Print the source text line specified by `.'. -go only.
a   (0) Print the value of `.' in symbolic form.
p   (4) Print the addressed value in symbolic form.
A   (0) Print the value of `.' in source-symbol form.
P   (4) Print the addressed value in source-symbol 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.

  Modifiers for ? and / Only
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.
w value
    Write the 2-byte value to address.
W value
    Write the 4-byte value to address.
m b1 e1 f1[ ?]
    Map new values for b1, e1, f1. If the ? or / is followed by * then the second segment (b2,e2,f2) of the address mapping is changed.

  : Modifiers
b commands
    Set breakpoint, execute commands when reached.
B commands
    Set breakpoint using source address, execute commands when reached. -go only.
w commands
    Set a data write breakpoint at address . Like b except that the breakpoint is hit when the program writes to address . Sun386i systems only.
D   Delete breakpoint at source address. -go only.
r   Run objectfile as a subprocess.
cs  The subprocess is continued with signal s.
ss  Single-step the subprocess with signal s.
Ss  Single-step the subprocess with signal s using source lines. -go only.
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   Single-step the subprocess with signal s using source lines. -go only.
es  Like s, but steps over subroutine calls instead of into them. Sun386i systems only.
u   Continue uplevel, stopping after the current routine has returned. Should only be given after the frame pointer has been pushed on the stack. Sun386i systems only.
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 the current subprocess, if any.
A   Attach the process whose process ID is given by address. The PID is generally preceded by 0t so that it will be interpreted in decimal. Sun386i systems only.
R   Release (detach) the current process. Sun386i systems only.

  $ Modifiers
<filename
    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.
?   Print process ID, the signal which stopped the subprocess, and the registers.
r   Print the names and contents of the general CPU registers, and the instruction addressed by pc.
R   On Sun-3 systems with an MC68881 floating-point coprocessor, print the names and contents of the coprocessor's registers.
x   On Sun-3 systems with a Floating Point Accelerator (FPA), print the names and contents of FPA floating-point registers 0 through 15. On Sun-4 systems, print the names and contents of the floating-point registers 0 through 15.
X   On Sun-3 systems with an FPA, print the names and contents of FPA registers 16 through 31. On Sun-4 systems, print the names and contents of floating-point registers 16 through 31.
b   Print all breakpoints and their associated counts and commands.
c   C stack backtrace. On Sun-4 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 hexadecimal 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 stack trace.
C   C stack backtrace with names and (32 bit) values of all automatic and static variables for each active function. (-go only).
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. (-go only).
p   Print a list of known procedure names. (-go only).
p   (Kernel debugging) Change the current kernel memory mapping to map the designated user structure to the address given by _u ( u on Sun386i systems); 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.
W   Reopen objectfile and corefile for writing, as though the -w command-line argument had been given.
l   Set the length in bytes (1, 2, or 4) of the object referenced by :a and :w to address. Default is 1. Sun386i systems only.

  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.
B   The number of an address register that points to the FPA page. Sun-3 systems only.
d   The data segment size.
e   The entry point.
F   On Sun-3 systems, a value of `1' indicates FPA disassembly.
m   The `magic' number (0407, 0410 or 0413).
s   The stack segment size.
t   The text segment size.

  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. An initial `_' will be prepended to symbol if needed. Sun-2, Sun-3, and Sun-4 systems but not Sun386i systems.
_symbol
    An external symbol. Sun-2, Sun-3, and Sun-4 systems but not Sun386i systems.
routine.name
    The address of the variable name in the specified routine in the symbol table. If name is omitted, the address of the most recent stack frame for routine.
(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.
^Fexp
    (CTRL-F) Translate program address to source address. (-go only).
^Aexp
    (CTRL-A) Translates source address to program address. (-go only).
`name
    (Backquote) Translates procedure name to sourcefile address. (-go only).
"file"
    The sourcefile address for the zero-th line of file. (-go only).

  Binary Operators

Binary operators are left associative and have lower precedence 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.

FILES
/usr/lib/adb
a.out
core

SEE ALSO
cc(1V), dbx(1), ptrace(2), a.out(5), core(5), kadb(8S)

DIAGNOSTICS

adb, when there is no current command or format, comments about inaccessible files, syntax errors, abnormal termination of commands, etc. Exit status is 0, unless last command failed or returned nonzero status.

BUGS

There does not seem to be any way to clear all breakpoints.

adb uses the symbolic information in an old and now obsolete format generated by the -go flag of cc(1V); it should be changed to use the new format generated by -g.

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 kluge.