adb(1) General Commands Manual adb(1)
NAME
adb - absolute debugger
SYNOPSIS
path] kernelfile memfile
path] kernelfile crashdir
path] crashdir
path] [objfile] [corefile]
path] pid [execfile]
DESCRIPTION
The command executes a general-purpose debugging program that is sensitive to the underlying architecture of the processor and operating
system on which it is run It can be used to examine files and provide a controlled environment for executing HP-UX programs.
inspects exactly one object file, referred to as the and one memory file, referred to as the Either of these files can be the NULL file,
specified by the argument, which is a file with no contents. The object file and the memory file are specified using the following argu-
ments:
kernelfile An HP-UX kernel, usually
memfile or memfile is assumed to be on an HP-UX system running kernelfile if kernelfile is specified. is supported only on PA-RISC
platforms.
crashdir A directory containing an HP-UX system crash dump, which is assumed to be produced from kernelfile if kernelfile is specified.
objfile Normally an executable program file. It can also be a relocatable object file, shared library file or a DLKM module. The
default for objfile is
corefile A core image file produced after executing objfile. The default for corefile is
execfile The executable file corresponding to pid, the process ID of the process to be adopted for debugging by
The current object file may be any one of kernelfile, the file in crashdir, objfile, or execfile. The current object file preferably
should contain a symbol table; if it does not, the symbolic features of cannot be used, although the file can still be examined. The cur-
rent memory file may be any one of memfile, the system memory dump in crashdir, corefile, or the memory of process pid.
Requests to are read from standard input and responds on standard output. If the flag is present, objfile is created (if necessary) and
opened for reading and writing, to be modified using ignores QUIT; INTERRUPT causes return to the next command.
There are two modes of operation for backward compatibility mode and normal mode. Backward compatibility mode is the default on PA-RISC
systems. Normal mode is the default on Itanium systems.
On startup executes commands from the file
To debug a MxN process or the core, requires the MxN debug library, Depending on the application type, it loads (for 32 bit PA-RISC sys-
tems) or (for 64 bit PA-RISC systems) or (for Itanium(R)-based systems). If the relevant library is not found in the specified path, you
should set the shell variable to the path where the correct library can be found.
Options
recognizes the following command-line options, which can appear in any order but must appear before any file arguments:
Print a usage summary and exit.
If this option is used, all other options and arguments are ignored.
Ignores
path specifies a list of directories where files read with or (see below) are sought. This list has the same syntax as, and similar
semantics to, the shell variable; the default is
Specify the normal mode. This is the default on Itanium systems.
This option is mutually exclusive with the option. The last one specified takes effect.
Specify backward compatibility mode. This is the default on PA-RISC systems.
This option is mutually exclusive with the option. The last one specified takes effect.
Adopt process with process ID
pid as a ``traced'' process; see ttrace(2). This option is helpful for debugging processes that were not originally run under
the control of
This option must be specified to enable the file write commands of
Objfile is opened for reading and writing. It also enables writes to memfile if it is a kernel memory file.
The following command-line options to are obsolete and are no longer required. (If used they generate a warning.)
Previously
required this option to recognize HP-UX crash dumps or
Previously
required this option to recognize multiple file HP-UX crash dumps.
Requests to follow either the traditional form:
[address] [ ] [command-char] [command-arguments]
or the new form:
keyword [command-arguments]
Only the traditional form is available in backward compatibility mode.
If address is present, is set to address. is the state variable which keeps track of the current address. is another state variable which
keeps track of increments to as steps through a format string; see below. Initially and are set to For most commands, count specifies the
number of times the command is to be executed. The default count is address and count are expressions.
The interpretation of an address depends on the context in which it is used. If a subprocess is being debugged, addresses are interpreted
in the address space of the subprocess. (For further details see below.)
The command-char and command-arguments specify the command to run. See below.
Expressions
All expression primaries are treated as 64-bit unsigned integers and the expression also evaluates to a 64-bit unsigned integer. The fol-
lowing primaries are supported:
integer A number. The prefixes (zero), and force interpretation in octal radix; the prefixes and force interpretation in deci-
mal radix; the prefixes and force interpretation in hexadecimal radix; the prefixes and force interpretation in binary
radix. Thus = = = = sixteen. If no prefix appears, the default radix is used; see the command. The radix is initial-
ized to hexadecimal. Note that a hexadecimal number whose most significant digit would otherwise be an alphabetic char-
acter must have a (or prefix.
The ASCII value of up to 8 characters.
If more than 8 characters are specified, the value is undefined. A backslash can be used to escape a single quote
Register. The value of the register is obtained
from the register set corresponding to the current memory file. Register names are implementation dependent; see the
command.
symbol A symbol is a sequence of uppercase or lowercase letters, underscores, or digits, not starting with a digit. A back-
slash can be used to escape other characters. The value of the symbol is taken from the symbol table in the current
object file.
variable A variable name consists of alphabets and numerals and always starts with $. Names of registers in the target processor
are reserved as variable names and can be used to access registers in expressions.
In backward compatibility mode, a variable is a single numeral or alphabet except for registers and the prefix letter is
Here is a list of variables supported in both modes.
The count on the last
command.
The base address of the data segment.
The data segment size.
The text segment size.
The entry point.
The stack segment size.
The ``magic'' number as defined in
On entry, b, d, and t are set from the headers in the current memory file. If the current memory file does not appear
to be valid these values are set from the current object file. e is set from the current object file.
Note: These are set only from core files and object files.
The following primaries are supported only in the normal mode:
The value of
The value of
increased by the value of
The value of
decreased by the value of
The last
address typed.
The following primaries are supported only in backward compatibility mode:
The value of
The value of
increased by the value of
The value of
decreased by the value of
" The last address typed.
The following C arithmetic, relational and logical operators are supported and have the same precedence as in C:
The C unary sign operators and and the operator are also supported.
In addition to the above operators the following specific unary operators are supported and have the same precedence as the other unary
operators:
The contents of the location addressed by
exp in the current memory file.
@exp The contents of the location addressed by exp in the current object file.
The following adb specific binary operator has the same precedence as the operator:
exp1 rounded up to the next multiple of exp2.
In backward compatibility mode, the operator has the same semantics as the operator. The unary operator is not available in this mode.
Sub-expressions containing any of the following operators should be protected by if used in address or count expressions:
In addition to the above, in backward compatibility mode the operator also should be protected.
Commands
As mentioned above, commands may be specified in the or the In backward compatibility mode, only the traditional form is supported.
Traditional Form Commands
The following categories of commands are specified in the traditional command form:
o File commands
o Keyword commands
o Process commands
o Thread commands
o Shell commands
In backward compatibility mode:
o Variable commands
These commands operate on the current object file or the current memory file and are used to read, write, etc.
file_selector[ modifier] [ | index] [arglist]
The file_selector can be one of these:
The selected file is the current object file.
The selected file is the current memory file.
This special symbol is only used for printing the value of
The modifier specifies the operation on the file; modifier can be:
(no modifier)
It takes a single optional argument list which is a format string. prints data from the selected file according to the
format string. If a format string is not present and the file selector is or then uses the format string used by either
of these earlier. If the file selector is and a format string is not present, then uses the format string used by the
previous command.
/ [ , size ] value [ mask ]
Search the selected file. Words of size, size starting at are masked with mask and compared with value until a match is
found. If found, is set to that address of masked object. If mask is omitted, no mask is used. is set to 0. Valid
values of size are 1, 2, 4, 8. If no size is specified then is assumed. value and mask are unsigned integers of size
size bytes.
For example: Search for 4 byte value, 4 ( 6 & 5 ) in the current object file, starting at expr.
= [ , size ] value1 value2 ...
Write a size sized value at the addressed location. is incremented by size after each write. is set to 0. Values of
size and values are same as for / modifier. For this operation, the file should be opened with option.
For example: Write 6 & 5 in the current object file at addresses expr and expr+4 respectively, starting at expr.
> [ , index ] b e f
Set the indexth mapping triple parameters of the selected file to the corresponding argument values in order. Refer to
If fewer than three arguments are given, remaining maps remain unchanged. The arguments are expressions. If not speci-
fied, index is assumed to be 0. For example: Set b, e, f (index 0) of the current object file to 1, 2, 3 respectively.
In backward compatibility mode the following modifiers are also present.
It has same behavior as that when no modifier
is present. However, it uses the second mapping triple to locate the file address of data to be printed.
It has same behavior as modifier
with an implicit size of 2. It sets to 2.
It has same behavior as modifier
with an implicit size of 4. It sets to 4.
It has same behavior as modifier
with an implicit size of 2. It sets to 2. It increments by the total size of all the values written minus
It has same behavior as modifier
with an implicit size of 4. It sets to 4. is set as for
It has same behavior as modifier
with an implicit index of 0.
It has same behavior as modifier
with an implicit index of 1.
For these modifiers, no explicit size or index can be mentioned. These modifiers are deprecated. Run the Keyword Command Form using the
traditional command form by prefixing the command with Please refer to for the complete list of keyword commands. These commands deal with
managing subprocesses. can run an object file as a subprocess. Also, it can adopt a subprocess given its pid. can debug multi-threaded
and/or forked subprocesses. It can also debug multiple subprocesses at the same time. However, at any time it focuses on a one subprocess
and one of its threads called the and respectively.
The command consists of followed by the modifier and an optional list of arguments. They are:
r [ objfile ]
Run objfile as a subprocess. If address is given explicitly, the program is entered at this point; otherwise the pro-
gram is entered at its standard entry point. The value count specifies how many breakpoints are ignored before stop-
ping. arguments to the subprocess may be supplied on the same line as the command. Semicolon is not used as a command
separator. An argument starting with < or > causes the standard input or output to be established for the command. All
signals are turned on when entering the subprocess. Such a subprocess is referred to as a
If there are other created subprocesses running, all are killed. It does not kill any attached subprocesses. This
becomes the current subprocess.
e [ objfile ]
Set up a subprocess as in no instructions are executed.
a [ objfile ]
Causes to adopt process with pid as a traced subprocess. If the objfile is specified, uses it to lookup symbol informa-
tion. Count has same meaning as in Such a subprocess is referred to as an This subprocess becomes the current subpro-
cess.
k [ pid | * ]
Kills a created subprocess. If no argument is specified it kills the current subprocess. If a pid is given, it kills
the subprocess with that pid. If is given, it kills all created subprocesses.
The current subprocess is chosen from the remaining subprocesses.
de [ pid | * ]
The arguments can be a pid or a Same as however it applies to attached subprocesses. detaches from them.
c [ signal ]
Continues the current subprocess with signal signal. It continues all the threads of the subprocess. If no signal is
specified, the signal that caused it to stop is sent. If address is specified, the current thread continues at this
address. Breakpoint skipping is the same as for
s [ signal | arg1 arg2 ... ]
Step the current thread count times. If address is given, then the thread continues at that address, else from the
address where it had stopped. If no signal is specified, the signal that caused it to stop is sent. If there is no
current subprocess, object file is run as a subprocess as for In this case no signal can be sent; the remainder of the
line is treated as arguments to the subprocess.
b [ command ]
Sets breakpoint at address in the current subprocess The breakpoint is executed count-1 times before causing a stop.
Each time the breakpoint is encountered, the command is executed. This breakpoint is a subprocess breakpoint. If any
of the thread executes the instruction at this address, it will stop. Multiple breakpoints can be set at the same
address.
d [ num | * ]
Deletes all breakpoints at address in the current subprocess, if it is specified. If is specified, it deletes all the
current subprocess breakpoints. If num is specified, breakpoint with number num is deleted.
en [ num | * ]
Enables all breakpoints at address in the current subprocess, if it is specified. If is specified, it enables all the
current subprocess breakpoints. If num is specified, breakpoint with number num is enabled.
di [ num | * ]
Disables all breakpoints at address in the current subprocess, if it is specified. If is specified, it disables all the
current subprocess breakpoints. If num is specified, breakpoint with number num is disabled.
z signum [ +s | -s | +r | -r | +d | -d ]
Changes signal handling for a specified signum for all the threads of the current subprocess. Disposition can be speci-
fied as:
Stop subprocess when signum is received.
Do not stop
subprocess when signum is received.
Report when
signum is received.
Do not report when
signum is received.
Deliver
signum to the target subprocess.
Do not deliver
signal to the target subprocess.
w [ pid ] Switches from the current subprocess to the subprocess with process ID pid. This process becomes the current subpro-
cess. This subprocess must be an already attached or created subprocess. Both subprocesses are in stopped state after
this command.
wc [ pid ] Same as however the previous current subprocess is not stopped.
These commands manage the threads in the current subprocess. The command consists of a followed by a modifier and an optional argument
list.
s [ signum ] Same as However it is strictly for the current thread only.
c [ signum ] Same as However it continues only the current thread. And count refers to the breakpoint to skip for the current thread.
b [ command ] Same as However it applies to the current thread only.
d [ num | * ] Same as However it applies to current thread only.
en [ num | * ] Same as However it applies to the current thread only.
di [ num | * ] Same as However it applies to the current thread only.
z signum [ +s | -s | +r | -r | +d | -d ]
Same as However it is meant for the current thread only. If a signum occurs in the context of this thread this disposition
value is used instead of that of the subprocess.
es [ signum ] Sets the flag for this signum for the current thread. It means that if this signal signum occurs in the context of this
thread's signal disposition value is used instead of that of the subprocess.
w [ pid ] Switch from the current thread to some other thread. Both the threads are in stopped state after this, and the thread with
threadid becomes the current thread. This command is also applicable to core file debugging. It switches from present
thread to given thread and makes the given thread as the current thread.
This action consists of a character followed by a string. The string is passed unchanged to the shell defined by the environment variable
or to This is supported in backward compatibility mode only. It consists of a followed by a variable, var and an optional value. This
action assigns value to the variable or register named by var.
If not specified, value is assumed to be the value of This behavior is deprecated.
Keyword Form Commands
All commands in this form consist of a keyword followed by a variable number of arguments.
In backward compatibility mode, a must precede these keyword form commands.
< filename Reads commands from filename. If this command is executed in a file, further commands in the file are not seen.
In backward compatibility mode, if a count is given, it is placed in variable 9 before the first command in the file is
executed. This behavior is deprecated.
<< filename Similar to except it can be used in a file of commands without causing the file to be closed.
In backward compatibility mode, variable 9 is saved when the command executes and is restored when it completes. This
behavior is deprecated.
> filename It sends output to filename, which is created if it does not already exist.
In backward compatibility mode, the output is appended to filename.
>> filename Similar to except that the output is appended to filename.
Print the process ID and register values.
Print the general registers and the instruction
addressed by the process counter.
Print all the registers.
Print the floating-point registers.
Print the double precision floating-point registers.
Print all breakpoints, their number, associated counts, state and
commands of the current subprocess.
Print information about all the subprocesses
being traced by that is, their process IDs, their types (created or attached), counts, and threadids.
Print information about the
current debuggee. If the current debuggee is a subprocess, then it prints subprocess information (process ID, type,
count) and prints information about each thread (thread ID, count, signal) of the subprocess. If the current debuggee
is a core then it prints information about each thread present in the core (thread no, utid, lwpid, PC value and PC Sym-
bol).
Print information about the current thread
(thread ID, count, signal). If the current debuggee is a core then it prints information about the current thread of
the core. (utid, lwpid and register information).
The arguments can be
address and count. Print C stack backtrace. If address is given, it is taken as the address of the current frame
(instead of the normal stack frame pointer). If count is given, only the first count frames are printed.
In backward compatibility mode, this command has a non-standard deprecated behavior. If arguments are not mentioned, it
uses address and count.
w [ width ] Set the page width for output to width. (The default is 80.)
In backward compatibility mode, this command has a non-standard deprecated behavior. If width is not mentioned, address
is taken as width.
s [ offset ]
Set to offset.
In backward compatibility mode, this command has a non-standard deprecated behavior. If offset is not mentioned,
address is taken as offset.
The default radix for all integers input is set to octal.
d [ radix ] Set the default radix to radix.
In backward compatibility mode, this command has a non-standard deprecated behavior. If radix is not mentioned, address
is taken as radix.
The default radix for all integers input is set to hexadecimal.
Quit
Print the value of all
variables.
Print the address map.
This includes both the initial and default maps for a valid corefile with an indication of which is currently active.
Print a list of
signals and how they are handled for the current subprocess.
Print a list of
signals, their associated flags, and how they are handled for the current thread.
Print all DLKM modules or shared libraries.
n [ nodenumber ]
Without arguments print node information on a CCNUMA machine. With a nodenumber argument, change to that node.
p traditional_cmd
This keyword command takes a traditional command as argument and interprets it.
a var value Assign value to variable var.
pa Virtual_Offset
Prints the physical address for a given Virtual Offset in HEX format. Space ID is taken from the adb variable space.
You can set the adb variable space using the keyword command a explained earlier.
The following commands can run only in backward compatibility mode.
newline Print the process ID and register values.
Toggle the address mapping of memfile between the initial map set up
or a valid memory file and the default mapping pair which the user can modify with the file action modifier If the mem-
ory file was invalid, only the default mapping is available.
N [ nodenumber ]
Print the number of nodes on V-class multinode machines and the current node number. To switch to another node, enter
Print double precision floating point registers.
Print all registers.
Print unwind tables.
Format String
A is used to specify the formatting to be done before data is printed by There are two types of format strings supported by and A tradi-
tional style format string is a sequence of A format string is always preceded by a comma and enclosed within double quotes (""), and is a
sequence of format specifiers and other characters. Each format specifier should be preceded by a character. Characters other than format
specifiers are printed as is. If needed, should be escaped by It supports C language style character escape sequences.
While processing a format string, scans the format string from left to right and applies each encountered to the object addressed by the
sum of and After each conversion specifier is processed, is incremented by count times size (implicit or explicit) of that conversion spec-
ifier. If the format string is used to print the value of (using action and remain unchanged. For operator, is updated appropriately.
In backward compatibility mode, only the traditional style format string is supported. A can be a or a
Each conversion specifier consists of an optional count or pspec followed by an optional size specifier character, followed by a conversion
specifier character.
count This is available only for the traditional style format string. The count specifies the number of times this conversion specifier is
to be repeated. If not specified, count is assumed to be 1.
pspec This is available only for the format string. It is a sequence of flags, fieldwidth and precision as in the printf(3S) library func-
tion.
size specifier character
This specifies the size of object to which this is applied. Size can be specified in two ways. One is using absolute size specifier
and other is relative size specifier. Absolute size specifiers are as follows.
The size of the object is 1 byte.
The size of the object is 2 bytes.
The size of the object is 4 bytes.
The size of the object is 8 bytes.
The size of the object is 16 bytes.
Relative size specifiers are as follows
The size of the object is the size of a machine word of the target processor.
The size of the object is half the size of a machine word of the target processor.
The size of the object is double the size of a machine word of the target
processor.
The size of the object is the size of a pointer on the target processor. This will
be different for wide files and narrow files.
The size of the object is the size of an instruction of the target processor. This
will be supported only on processors where this is constant.
Conversion Specifier Character
The following characters are supported
The value of dot is printed in symbolic form.
The object is printed as a character.
The object is printed as an unsigned octal number.
The object is printed as a signed decimal number.
The object is printed as an unsigned decimal number.
The object is disassembled as an instruction and printed.
The object is printed in a floating point format according to its size.
The object is printed in symbolic form.
The object is assumed to be a null terminated string and printed. This cannot
be used to print
The object is cast to type
and printed in the ctime(3C) format.
Here the format strings support only and If the size specifier character is not specified, it is assumed to be for conversion charac-
ter for conversion characters and for for and for everything else.
For example.
A dot operator consists of an optional count, optional size specifier character, and a dot operator character.
count count specifies the number of times this dot operator is to be repeated. If not specified, count is assumed to be 1. The
count is always 1 for format strings.
Size Specifier Character
Same as size specifier character of conversion specifier.
Dot operator character
This can be one of these
Increment
by count times size.
Decrement
by count times size.
For example:
In backward compatibility mode, the can be a conversion specifier, dot operator, spacing specifier, or a literal string.
A conversion specifier consists of an optional count followed by a conversion specifier character.
count Specify the number of times this conversion specifier is to be repeated. If not specified, count is assumed to be 1.
Conversion Specifier Character
These have an implicit size. No explicit size is recognized. The following format characters are available: (Their implicit
sizes are mentioned next to them.)
The object is printed as an unsigned octal number.
The object is printed as an unsigned octal number.
The object is printed as a signed octal number.
The object is printed as a signed octal number.
The object is printed as a signed decimal number.
The object is printed as a signed decimal number.
The object is printed as a unsigned hexadecimal number.
The object is printed as a unsigned hexadecimal number.
The object is printed as a unsigned hexadecimal number.
The object is printed as a unsigned decimal number.
The object is printed as a unsigned decimal number.
The object is printed as a floating point number.
The object is printed as a double precision floating point number.
The object is printed as a hexadecimal number.
The object is printed as an octal number.
The object is printed as a character (the sign bit is ignored).
The object is printed as a character using the following escape convention.
First, the sign bit is discarded, then character values 000 to 040 are printed as followed by the corresponding char-
acter in the range 0100 to 0140. The character is represented as
The object is assumed to be a sequence of bytes terminated with a
n as an instruction and printed. The value of n is the number of bytes occupied by the instruction. This cannot be
used to print
The object is assumed to be a sequence of bytes terminated with a null byte.
These bytes of the object are printed as a sequence of characters using the escape convention. The value of n is the
number of bytes in the object including the null byte. This cannot be used to print
The object is printed in the date format (see
ctime(3C)).
The object is disassembled as an instruction and printed. The value of
n is the number of bytes occupied by the instruction.
The value of dot is printed in symbolic form.
The object is printed in symbolic form. The value of
n s machine-dependent.
For example:
A dot operator consists of an optional count followed by a dot operator character.
count Same as that of count of conversion specifier.
Dot operator character
A dot operator character is one of these:
is decreased by count times size corresponding to the previous
conversion specifier character.
is increased by count.
is decreased by count.
For example:
A spacing specifier consists of an optional count or an optional tabstop followed by a
count Same as that of count of conversion specifier.
tabstop
Same as that of count of conversion specifier. However, it is used only with the t spacing specifier. If no value is men-
tioned, it is assumed to be 1.
spacing specifier character
A spacing specifier character can be one of these:
Move to the next tab stop appropriate for tabstop. For example,
moves to the next 8-space tab stop.
Print a space.
Print a newline character.
For example:
A literal string is any number of characters enclosed within double quotes ("").
For example:
Address Maps
In files like object files and application core files, the virtual memory address is the not the same as the file offset. So keeps an
array of for these files to map a given virtual memory address to a file offset. Each address map is a triple: start virtual address (b),
end virtual address (e) and start file offset (f). The triple specifies that all addresses from b to e - 1 occupy a contiguous region in
the file starting at f. Given a virtual address a such that b<= a< e, the file offset of a can be computed as f+ a- b.
State variables
There are several variables which define the state of at any instant in time. They are:
Current address. Initial value is 0.
Current address increment. Initial value is 0.
Prompt string used by adb. Initial value is ``
The current input radix. Initial value is as in the assembly language of the
target processor.
The maximum width of the display. Initial value is 80.
If an address is within this limit from a known symbol,
prints the address as symbol_name+offset, else the address is printed. Initial value is
List of directories to be searched for
macros. Initial value is
Pager command used by adb.
Initial value is
Set to 1 if is in backward compatibility mode. Initial value depends on the host processor.
Note
is a symbolic link to This symbolic link is maintained for backward compatibility with some old scripts which may be using
EXTERNAL INFLUENCES
International Code Set Support
Single- and multi-byte character code sets are supported.
RETURN VALUE
comments about inaccessible files, syntax errors, abnormal termination of commands, etc. Exit status is unless the last command failed or
returned non-zero status.
AUTHOR
was developed by HP.
FILES
SEE ALSO
ttrace(2), crt0(3), ctime(3C), end(3C), a.out(4), core(4), signal(5).
adb(1)
