xdb(1)

NAME
xdb - C, FORTRAN, Pascal, and C++ Symbolic Debugger

SYNOPSIS
dir] file] file] file] process_ID] library]
file] file] file] num] [objectfile [corefile]]

DESCRIPTION
is a source level debugger for C, HP FORTRAN, HP Pascal, and C++ programs. It provides a controlled environment for their execution. See the HP-UX Symbolic Debugger User's Guide for a comprehensive description of xdb .

objectfile is an executable program file having zero or more of its component modules compiled with the debug option turned on (enabled by the option of the and compilers). The support module must be included as the last object file linked, except for libraries included with the option to (see ld(1)). The support module is included automatically when is invoked as part of a compile command that uses the option. The default for objectfile is Note that by default links in shared libraries instead of archive libraries.

corefile is a core image from a failed execution of objectfile. The default for corefile is

  Options
recognizes the following options:

    Specify
        dir as an alternate directory where source files are located.

    Specify a record
        file, which is invoked immediately (for overwrite, not for append).

    Specify a restore state
        file, which is processed before the option (if any) and after the option (if any).

    Specify a playback
        file which is invoked immediately.

    Specify the process
        ID of an existing process the user wants to debug.

    Use the line-oriented interface.

    Pre-load information about this shared
        library, means always pre-load shared library information.

    Redirect standard input to the child process
        from the designated file or character device.

    Redirect standard output from the child process
        to the designated file or character device.

    Redirect standard error from the child process
        to the designated file or character device.

    Set the size of the string cache to
        num bytes (default is 1024, which is also the minimum).

    Enable debugging of shared-libraries.

At start-up, the debugger executes commands from the file if it exists.

ENVIRONMENT VARIABLES

  Display

This variable specifies the terminal type.
    There is no default for the terminal type.

This variable specifies the window height in lines of text.
    The default for this variable is 24 if not otherwise determinable.

This variable specifies the window width in text columns.
    The default for this variable is 80 if not otherwise determinable.

  Command Line Editing

This variable specifies the history file.
    The default for this variable is

This variable specifies the actual number of commands
    allowed in the history file. The default for this variable is

This variable specifies the editing mode (
    or The default for this variable is to match the environment variable or otherwise, there is no default.

  Native Language Support

This variable determines the local language equivalent of
    (for yes/no queries). also determines the locale in which messages are displayed. The default value for this variable is

This variable determines the interpretation of text as single-
    and/or multi-byte characters and their printability when reading or writing character and string data. If is not specified in the environment or is set to the empty string, the value of is used as the default.

  International Code Set Support
Single- and multi-byte character code sets are supported.

LOCATION SYNTAX

line
    A number that refers to a particular line in a file.

location
    A particular line in a file and its corresponding address in the user's program. location has the following general forms:

        line
        file line]
        [file proc proc label]
        [class] label]

    To reference code addresses symbolically, use:

        [[class]

Variable Identifiers
Variables are referenced exactly as they are named in the source file or files. Uppercase/lowercase sensitivity is controlled by the command.

Several methods can be used to obtain the value of some variable var, depending on where and what it is:

var Search for var first as a local in the current procedure (or the most recent instance of the current procedure), next as a member of that procedure's class, or finally as a global.

Search
    class for variable.

Search for
    var in the current or most recent instance of proc. A leading :: indicates a global.

Use the instance of
    proc that is at depth depth (exactly), instead of the current or most recent instance.

Search for a global (not local) variable named
    var.

dot is shorthand for the last thing viewed.

Special Variables
Special variables are names for things that are not normally directly accessible. Special variables include:

The debugger has room in its own address space for several
    user-created special variables of type

These are the names of the program counter, the stack pointer, the
    CPU general registers, etc.

This is used to reference the return value
    from the last command-line procedure call. It can also be referenced as and

This lets you see and modify the current child process signal number.

This lets you see and modify the current language.
    Possible values are:

This is the default stack level for viewing local variables.

Alters the behavior of the ``print'' command
    when printing character data. Values that can be assigned are and

This lets you see and modify the current source line number.

This lets you see the current amount of memory (bytes)
    allocated at run-time for use by the debugger itself.

This lets you see and modify the number of machine instructions
    the debugger steps while in a non-debuggable procedure before setting an up-level breakpoint and free-running to it.

This is interpreted as a set of flags to control behavior of certain
    C++ capabilities.

        Set means print full base class information at each occurrence.

        Set means
            sets breakpoints on member functions of base classes, also.

        Set means
            sets breakpoints on member functions of base classes, also.

    The default for all bits is clear. Some commands take a or argument which causes the action to be as if the appropriate bit of was clear or set

COMMANDS
The debugger has a large number of commands for viewing and manipulating the program being debugged. They are explained below and are grouped according to functional similarity.

  Window Mode Commands
These commands control what is displayed in the source window. The source window by default comes up in source mode for viewing source code. If assembly language instructions are needed, the disassembly mode can be selected. Registers are also shown in this mode. If both assembly instructions and source code are needed, the split-screen mode can be selected. Commands are as follows:

    Toggle disassembly mode.

    Toggle split-screen mode.

    Display the general registers when the debugger
        is in disassembly (non-split-screen) mode.

    Display the floating-point registers
        when the debugger is in disassembly (non-split-screen) mode.

    Scroll the floating-point register display forward four lines.

    Scroll the floating-point register display back four lines.

    Set the size of the source viewing window.

    Update the screen to reflect the current location.

    Clear and redraw the screen.

  Path Map Commands
Path maps can be used to redirect portions of a source tree to different directories. Commands are as follows:

Add a path map to the list of path maps.

List path maps.
    The list is numbered for use with the command.

Delete path map.
    Default number is 1 (most recent path map). A deletes all path maps.

Adds
    directory to the list of alternate directory search paths for source files.

  File Viewing Commands
These commands may change the current viewing position, but they do not affect the next statement to be executed in the child process, if any. Commands are as follows:

View the source one window forward from the
    current source window.

View the source at the specified
    location, placing it in the center of the window.

View the source at the current procedure at
    depth on the stack.

View the assembly code at
    address in the source window (see the command).

Display the file name, procedure name, line number,
    and the current source statement corresponding to the object code being executed or examined.

Move to
    lines (default one) lines after the current line.

Move to
    lines (default one) lines before the current line.

Search forward through the current file for
    string, starting at the line after the current line.

Search backward for
    string, starting with the line before the current line.

Repeat the previous
    or command using the same string as the last search, starting at the current location being viewed.

The same as
    but the search goes in the opposite direction from that specified by the previous or command.

  Display Formats
The display formats tell the debugger's data viewing commands how output should be formatted. A format is of the form [count]formchar [size]. For example, prints, starting at the location of four two-byte numbers in hexadecimal.

Formats that print numbers use lowercase characters to represent data types and uppercase to represent data types. For example, prints in octal.

The following formats are available:

    Print in the ``normal'' format, based on the type.
        Arrays of and pointers to are interpreted as strings, and structures are fully dumped.

    Print in decimal (as
        or

    Print in unsigned decimal (as
        or

    Print in octal (as
        or

    Print in hexadecimal (as
        or

    Print in binary (as
        or

    Print a byte in decimal (either way).

    Print a character.

    Print a wide-character.

    Print in ``e'' floating-point notation (as
        or

    Print in ``f'' floating-point notation (as
        or

    Print in ``g'' floating-point notation (as
        or

    Print a disassembled machine instruction.

    Print a string using
        expr as the address of the first byte.

    Print a wide-character string using
        expr as the address of the first element.

    Print a wide-character string using
        expr as the address of a pointer to the first element.

    Print the template of an object (C++).

    Print the template of an object with base classes displayed (C++).

    Print a string using
        expr as the address of a pointer to the first byte.

    Show the type of
        expr (usually a variable or procedure name).

    This is identical to the
        format except for C++ classes and struct objects where base class and struct type information are also displayed.

    Print the name of the procedure containing address
        expr.

    Do a formatted dump of a structure.

    Identical to the
        format.

    Same as the
        format, except that for C++ class and struct objects the base class and struct data are also displayed.

There are some short hand notations for size:

    1 byte

    2 bytes

    4 bytes

    8 bytes
        Can only be used with floating-point formats.

    16 bytes
        Can only be used with floating-point formats.

  Data Viewing and Modification Commands

If  expr does not resemble anything else (such as a command), it is handled as if you had typed (print expression in normal format).

Print the contents (value) of
    expr using format.

Print the address of
    expr using format.

Back up to the preceding memory location
    (based on the size of the last thing displayed) and use format if supplied, or the previous format if not.

Go forward to the following memory location
    (based on the size of the last thing displayed) and use format if supplied, or the previous format if not.

Print the values of all static data members of
    class.

Print quietly (evaluate but do not print).
    argument can be anything allowed after

List all parameters and local variables of the current procedure (or of
    proc, if given, at the specified depth, if any).

List all
List all
List all
    (where to search for files).
List all shared libraries known to the debugger.
List all
    (signal actions).

List all (or matching)
    blocks in the current procedure (FORTRAN).
List all (or matching)
    (source files used to build objectfile).
List all (or matching)
    variables.
List all (or matching)
List all (or matching)
List all (or matching)
    names.
List all (or matching)
List all (or matching)
    variables (except registers).
List exception stop-on-throw and -catch state (C++).
List all (or matching) classes (C++).
List all (or matching) class templates (C++).
List all (or matching) template functions (C++).
List all (or matching) function templates (C++).
List all (or matching) overloaded functions (C++).
Show a memory-map of all currently loaded shared-libraries
    and the main program, or of the one specified.

  Stack Viewing Commands
Trace the stack for the first
    depth (default 20) levels.
Same as
    but local variables are also displayed, using format (except that all arrays and pointers are shown simply as addresses, and structures as first word only).
Move up (decreasing depth)
    offset levels in the stack. The default value of offset is 1.
Move down (increasing depth)
    offset levels in the stack. The default value of offset is 1.
Move to the top of the stack (this is the same as
Toggle the visibility of inter-procedural stubs in stack traces (
    PA-RISC only).

  Job Control Commands
These commands let you control execution of the program. The parent (HP Symbolic Debugger) and child (objectfile) processes take turns running. The debugger is only active and able to execute commands while the child process is stopped due to a signal or a breakpoint, or by terminating.
Run a new child process with the given or previous argument list,
    if any.
Run a new child process with no argument list.
Terminate (kill) the current child process, if any.
Continue after a breakpoint or a signal, ignoring the signal, if
    any. If a location is specified, a tempory breakpoint is set at that location.
Continue just like
    but allow the signal (if any) to be received. If a location is specified, a tempory breakpoint is set at that location.
Single step 1 (or
    count) statements (or instructions in disassembly mode).
Similar to
    but treat procedure calls as single statements (do not step ``into'' them). The and commands pass the current signal (like Set if necessary, to prevent this.

  Breakpoint Commands
The debugger provides a number of commands for setting and deleting breakpoints. Associated with any breakpoint are three attributes:
location
    A particular line in a file and its corresponding address in the user's program, if executable code exists for that line.
count
    The number of times the breakpoint is encountered prior to recognition. This can be suffixed with (permanent, which is the default) or (temporary).
commands
    Actions to be taken upon recognition of a breakpoint before waiting for command input. This is a list of debugger commands separated by and enclosed by
Each breakpoint can be individually activated or suspended, and there is an overall breakpoint mode which can be toggled. If any breakpoint is added or activated, or if all breakpoints are suspended, the global mode is toggled automatically.
Here are the breakpoint commands:
List all breakpoints.
Set a permanent breakpoint at the current location (or at
    location).
Delete breakpoint number
    number, or at the current location.

Delete all breakpoints (including ``procedure'' breakpoints).

After evaluating
    expr to what must be a class instance, set an ``instance'' breakpoint at the first executable line of proc for the instance's class.

After evaluating
    expr to what must be a class instance, set ``instance'' breakpoints at the first executable line of all member functions of the instance's class. The option indicates only members of the designated class. The option indicates members of base classes as well as members of the designated class.

Set ``class'' breakpoints at the first executable line
    of all member functions of class. See the previous command for information on and

Set ``overload'' breakpoints at the first executable line
    of all overloaded functions with name proc (which can be qualified by a class).

Set permanent breakpoints at the beginning
    (first executable line) of every debuggable procedure.

Set permanent breakpoints at the exit (final executable statement)
    of every debuggable procedure.

Set permanent breakpoints at the entry and exit (first and final
    executable statement) of every debuggable procedure. The given commands are associated with the entry breakpoint and default to

Delete all procedure breakpoints.

Delete all ``procedure exit'' breakpoints.

Delete all ``procedure trace'' breakpoints.

Define a global breakpoint command list to be executed
    whenever any breakpoint is hit (normal, instance, class, overload, procedure, procedure exit, or procedure trace).

Delete the global breakpoint command.

Set a breakpoint at the beginning (first executable line)
    of the procedure at the given stack depth (if depth is not given use the current procedure).

Set a breakpoint at the exit (last executable line)
    of the procedure at the given stack depth (if depth is not given use the current procedure).

Set an up-level breakpoint.

Trace the current procedure (or procedure at
    depth, or proc). By default, the entry breakpoint commands are which shows the top two procedures on the stack and continues.

Set a breakpoint at the given code address.

Toggle the exception stop-on-catch state.

Toggle the exception stop-on-throw state.

Define the stop-on-catch command-list.

Define the stop-on-throw command-list.

Set the count of breakpoint
    number to count.

Suspend the breakpoint having the
    num specified, or if a num is not entered, the breakpoint at the current line is suspended if one exists.

Suspend all breakpoints.

Activate breakpoint number
    num or if a num is not entered, the breakpoint at the current line is activated if one exists.

Activate all breakpoints.

Toggle the overall breakpoint mode between
    active and suspended.

  Auxiliary Breakpoint Commands

If  expr evaluates to a non-zero value, the first group of commands (the first block) is executed; otherwise it (and the following if any) is skipped.

If the
    command appears as the first command in a breakpoint command list, the normal announcement of address is not made.

Print the given string.

  Assertion Control Commands
Assertions are command lists that are executed before every instruction. If there is an active assertion, the program is single-stepped at the machine-instruction level and runs very slowly.

Each assertion can be individually activated or suspended, and there is an overall assertions mode which can be toggled. If any assertion is added or activated or if all assertions become suspended, the global mode is toggled automatically.

Here are the assertion commands:

Create a new assertion with the given command list
    which is not parsed until it is executed.

Activate assertion
    number.

Activate all assertions.

Delete assertion
    number.

Delete all assertions.

Suspend assertion
    number.

Suspend all assertions.

Toggle the overall assertions mode between
    active and suspended.

Force an exit from assertions
    mode immediately (default or mode is non-zero) or at the end of the command list ( mode non-zero).

  Signal Control Commands
These commands are used to modify and list the contents of the ``zignal'' (signal) handling table. Here are the signal control commands:

Toggles flags (
    or for signals (

Lists the current handling of all signals.

  Record and Playback Commands
These commands allow the recording of debugger sessions in a recordfile and the playing back of those sessions. Here are the record and playback commands:

Set or change the recordfile to
    file and turn recording on.

Same as
    but appends to file instead of overwriting.

Set or change the record-all file to
    file, for overwriting or appending.

Turn recording on.
Turn recording off.
Close the recording file
    When recording is resumed, new commands are appended to the file. In this context, is equivalent to

Turn record-all on
Turn record-all off
Close the record-all file

    In this context, is equivalent to

Toggle recording [record-all]; if on, turn it off; if off, turn it on.

Tell the current recording status (same as

Tell the current record-all status (same as
    ).

Start playback from
    file.

Start playback from
    file, using the single-step feature of playback.

  Save State Command

Save the current set of breakpoints, macros and assertions in
    file for later use with the command-line option.

  Macro Definition Commands

Define
    name as a macro whose value is replacement-text.

Remove the macro definition from
    name so that name no longer exists as a replacement string macro.

Toggle the state of the macro substitution mechanism between active and
    suspended.

  Miscellaneous Commands

Suspend the built-in
    more pagination facility of the debugger output.

Activate the built-in
    more pagination facility to paginate the debugger output.

<carriage-return>
Repeat the last command, if possible,
    with an appropriate increment, if any.

Invoke a shell program.

Flag
    text as a comment to be echoed to the command window.

Set the address printing format using
    printf(3S) format specifications (not debugger format styles). If no argument is provided, the format is set to the default,

Go to an address in the procedure on the stack at
    depth zero (not necessarily the current procedure).

Print commands/syntaxes related to this
    topic using more(1). Use for a list of topics.

Print information (inquire) about the state of the debugger
    and various toggles.

Print the current text
    (objectfile) and core (corefile) address maps.

Toggle the address mapping of
    corefile between the initial map and the modifiable mapping pair which the user can set with the command.

Set the
    (objectfile) or the modifiable (corefile) address map.

Quit the debugger.

Toggle case sensitivity in searches.

ADOPTING AN EXISTING PROCESS
The symbolic debugger command line option process_ID allows for the debugging of a free-running process. To adopt a process, the effective user IDs of the debugger and the process to be adopted must match, or the effective user ID of the debugger must be root. When a process is adopted, it halts, and the debugger displays where the program is halted, at which point the program can be debugged. If the user quits the debugger without killing the process, the debugger removes all breakpoints from the process and allows it to continue running. If a program is designed to be adopted by the debugger when in a certain state (such as an error condition), it is important that the program do something such as enter an infinite loop, rather than calling the system routine (see sleep(3C)). A sleeping program cannot be adopted correctly by the debugger, although a suspended process (i.e., blocked on a read) can be.

When using the command-line option with to debug shared libraries in an adopted process, prepare the executable_file by executing:

Once the file is prepared for debugging, run executable_file in the background and adopt it using:

The syntax for this use of the command is:

    Enables shared library debugging of the adopted process
        by setting private data switches within the file.

    Disables shared library debugging of the adopted process
        by clearing private data switches within the file.

    This command reports whether:
        shared-library debugging is enabled or disabled, symbolic-debugging information is present, or symbolic-debug information has already been preprocessed. file is not changed when the option is given. If all three conditions are true, an exit value of 0 is returned; otherwise 1.

Note that for the or options, file must be writable by the user.

WARNINGS
The debugger does not terminate on an interrupt but jumps instead to its main loop and awaits another command. However, this does not imply that sending the debugger an interrupt is harmless. It can result in internal tables being left in an inconsistent state that could produce incorrect behavior.

Code that is not compiled debuggable or does not have a corresponding source file is dealt with in a half-hearted manner. The debugger shows for unknown file and procedure names, cannot show code locations or interpret parameter lists, etc. However, the linker symbol table provides procedure names for most procedures, even if they are not debuggable.

On some systems, if the debugger is run on a shared objectfile you cannot set breakpoints. (This may only apply if someone else is also executing the program.) This may be indicated by the error "Bad access" when you attempt to start a child process. If another person starts running objectfile while you are debugging, they and you may have some interesting interactions.

The debugger will probably be unusable on systems that have been booted from something other than (such as if was booted instead on a Series 300/400 system).

The debugger has no knowledge about or control over child processes forked in turn by the process being debugged. Programs being debugged should not execute a different program via without a (see exec(2) and fork(2)).

Child process output may be (and usually is) buffered. Hence it may not appear immediately after you step through an output statement such as (see printf(3S)). It may not appear at all if you kill the process.

If the address given to a command is not a code address in the child process, meaningless results or errors may ensue.

Single stepping floating-point instructions may show delayed results for operations that are actually emulated via exception traps (e.g. on the Series 300/400 MC68040 processor). Actual results will not be apparent until the next floating-point operation is performed.

Debugging dynamically loaded code is inherently difficult, since no symbols within it are known to the debugger.

If you set the address printing format to something printf(3S) does not like, you may get an error (usually memory fault) each time you try to print an address, until you fix the format with another command.

Do not use the command to manipulate the signal. This signal is used by the debugger to synchronize with and control the traced process, and unpredictable results may occur if it is otherwise manipulated. A corrolary to this is that applications that make use of the signal are at best difficult to debug.

If you single step or run with assertions through a call to (see setjmp(3C)), the child process will probably take off free-running because the debugger sets, but never hits, an up-level breakpoint.

Do not modify any file while the debugger has it open. If you do, the debugger gets confused and may display garbage.

Although the debugger tries to do things reasonably, it is possible to confuse the recording mechanism. Be careful about trying to play back from a file currently open for recording, or vice versa; strange things can happen.

The output of some program generators such as have compiler-line-number directives in them that can confuse the debugger (see yacc(1)). It expects source line entries in the symbol table to appear in sorted order.

DEPENDENCIES

  Series 300/400
The command is not supported on the Series 300 or 400.

  Series 700/800 (PA-RISC)
All programs are shared executables. This implies three limitations. You cannot set breakpoints or single step a program if another process is running it; the error message results. If debugging a program, and another process starts to run the same program, either through your process executing a or another process, such as a shell, executing an this second process can hit one of your breakpoints and generate a SIGTRAP. You cannot single step through a call to

AUTHOR
was developed by HP and Third Eye Software.

FILES
Default
    objectfile to debug.
Default
    corefile to debug.
Text file listed by the
    command.
Unformatted text file used to generate xdb.help.
Auxiliary object file (support module) to link with all debuggable programs.
The xdb message catalog.
The pxdb message catalog.
Demo files.
The xdb startup command file.

SEE ALSO
adb(1), cc(1), echo(1), fc(1), ksh(1), ld(1), more(1), pc(1), creat(2), exec(2), fork(2), open(2), ptrace(2), ecvt(3C), multibyte(3C), printf(3S), setjmp(3C), shl_load(3X), system(3S), a.out(4), core(4), user(4), lang(5), signal(5).

HP-UX Symbolic Debugger User's Guide
HP-UX Symbolic Debugger Quick Reference.