DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

dbxtra(CP)


dbxtra -- dbx-based screen-oriented debugger

Syntax

dbxtra [-r] [-s] [-x] [-F] [-I dir] [-c file] [-C] [-C++] [objfile [coredump | processid]]

Description

dbxtra is a screen-oriented debugger based on dbx for source level debugging and program execution under UNIX System V. objfile is a COFF-format or ELF-format object file produced by cc(CP) with the appropriate flag (-g) specified to include symbol information. The machine-level facilities of dbxtra can be used on any program.

The object file contains a symbol table including the names of all source files the compiler used to create it. These files are available for perusal while using the debugger.

If a core file exists in the current directory or a coredump file is specified, dbxtra can be used to examine the state of the program when it faulted.

If a processid is specified, dbxtra attempts to attach to the given process.

If the file .dbxtrarc exists in the current directory or your home directory then the dbxtra commands in it are executed on start-up.

Command line options

The dbxtra command line options are:

-r
Execute objfile immediately. If it terminates successfully, dbxtra exits. Otherwise the reason for termination is reported and you can either enter the debugger or let the program fault. dbxtra reads from /dev/tty when -r is specified and standard input is not a terminal.

-s
Do not invoke the screen manager. dbxtra works in line mode only and will not respond to any of the screen-related commands (including screen).

-x
Ignore cross-reference file when initializing dbxtra. (See dbxref command below.)

-F
dbxtra assumes that file-scoped structure/union/enum definitions with the same name are identical. Specifying -F may significantly decrease dbxtra's memory usage (and startup time) for large programs. This happens because most structure definitions are in include files, which produces many copies of the symbol table information in each .o file. Using this option means that the symbol table in the debugger may not match your program in some cases. The default is to assume that structure/union/enum definitions with the same name may have different definitions.

-I dir
Add dir to the list of directories that are searched when looking for a source file. Normally dbxtra looks for source files in the current directory and in the directory where objfile is located. The directory search path can also be set with the use command.

-c file
Execute the dbxtra commands in file before reading from standard input.

-C++
Assume C++ mode. dbxtra works in C++ mode if C++ information is present in objfile, and attempts to find extended debugging information files.

-C
Specifically request C debugging only. C++ information is not used and toggling to C++ debugging mode is not allowed.

Unless -r is specified, dbxtra just prompts and waits for a command.

If neither -C++ nor -C is specified, dbxtra looks for a function named _main() in the file being debugged, and, if found, assumes C++ mode.

Execution and tracing commands


run [args] [ < filename] [ >[> filename]]
rerun [args] [ < filename] [ >[> filename]]
Start executing objfile, passing args as command line arguments; ``<'', ``>'', or ``>>'' can be used to redirect input or output in the usual manner (``>>'' appends to the file). Any arguments used with rerun are appended to the previous arguments and passed to the program; otherwise it is identical to run.

setenv name value
Set the value of environment variable name to be value in the environment of the debugged program. This command is useful whenever the debugged program requires a different value of environment variable than the value required by dbxtra. In particular, if the program's output is redirected to a terminal of a different type then the program requires a different value of the TERM variable. Unset the value of variable name, that is, remove it from the program's environment.

trace

The trace command is used to display source lines (or machine instructions) when executed, display the arguments and results of routines, and display when changes (or accesses) are made to variables or memory locations.

In the following, if an ``if condition'' clause is present, information is displayed only if condition is true. If an ``in routine'' clause is present, information is displayed only when routine is active. If inst is specified, trace displays machine instructions in addition to showing the source lines where they are executed.


trace [inst] [in routine] [if condition]
Display each source line before it is executed. If inst is specified, display each instruction, rather than each line.

trace [inst] line-number|address [if condition]
Display the given line-number before it is executed.

trace routine [in routine2] [if condition]
Display each call and return of routine.

The names of each caller is printed as well as the source line on which routine was called, and the parameters passed to it. In addition, routine's return is noted, and if routine is a function then the return value is also printed.


trace [inst] [change] variable [in routine] [if condition]
When the variable is modified, display its new value before executing the next source line. This uses 386 debug registers, if possible.

trace [inst] change address [in routine] [if condition]
When the four bytes at location address are modified, display the new value before executing the next source line. This uses 386 debug registers, if possible.

trace [inst] access variable [in routine] [if condition]
When variable is modified or accessed, display its new value before executing the next source line. This must use 386 debug registers.

trace [inst] access address [in routine] [if condition]
When the four bytes at location address are modified or accessed, display the new value before executing the next source line. This must use 386 debug registers.

stop

The stop command is used to stop execution when execution reaches a given location, or when a variable or memory location is changed or accessed.

In the following, if ``if condition'' is present, stop only if condition is true. If inst is specified, stop before executing the next instruction, otherwise stop before the next source line is executed.


stop [inst] if condition
When the boolean condition becomes true, stop before the next source line or instruction in the program is executed. This uses 386 debug registers, if possible.

stop [inst] at line-number|address [if condition]
Stop at the given line-number. If inst is specified, stop at the given instruction address.

stop in routine [if condition]
Stop at the first executable statement in routine.

stop [inst] [change] variable [if condition]
Stop at the next source line after the variable is modified. This uses 386 debug registers, if possible.

stop [inst] [change] address [if condition]
Stop at the next source line after any of the the four bytes at memory location address are modified. This uses 386 debug registers, if possible.

stop [inst] access variable [if condition]
Stop at the next source line after the variable is modified or accessed. This must use 386 debug registers.

stop [inst] access address [if condition]
Stop at the next source line after any of the after the four bytes at memory location address are modified or accessed. This must use 386 debug registers.

when

The when command is used to execute a series of commands when execution reaches a given location, when a condition is true, or when a variable or memory location is changed or accessed.

In the following, if ``if condition'' is present, perform the commands only if condition is true. If inst is specified, perform the commands before executing the next instruction, otherwise perform the commands before the next source line is executed.


when [inst] at line-number|address [if condition]
{command; [command; ... ]}
Execute the commands when execution reaches the given line-number. If inst is specified, execute the commands when execution reaches the given instruction address.

when in routine [if condition] {command; [command; ... ]}
Execute the commands at the first executable statement of the routine.

when [inst] condition {command; [command; ... ]}
When the boolean condition is true, execute the commands before each source line is executed. This uses 386 debug registers, if possible.

when [inst] change variable [if condition] {command; [command; ... ]}
When variable is modified, execute the commands before the next source line is executed. This uses 386 debug registers, if possible.

when [inst] change address [if condition] {command; [command; ... ]}
When any of the four bytes at memory location address are modified, execute the commands before the next source line is executed. This uses 386 debug registers, if possible.

when [inst] access variable [if condition] {command; [command; ... ]}
When the variable is modified or accessed, execute the commands before the next source line is executed. This must use 386 debug registers.

when [inst] access address [if condition] {command; [command; ... ]}
When any of the the four bytes at memory location address are modified or accessed, execute the commands before the next source line is executed. This must use 386 debug registers.

Other execution and tracing commands


status [ > filename]
Print out the currently active trace, when and stop commands. Inactive events (which have been made inactive with the disable command) are shown with an asterisk (*) after the event-number.

delete event-number ...
The trace, stop, or when commands corresponding to the given event-number are removed. The event-number associated with traces, stops and whens are printed by the status command.

disable event-number ...
The trace, stop, or when commands corresponding to the given event-number are disabled. Disabled events do not trigger until they are enabled.

enable event-number ...
The trace, stop, or when commands corresponding to the given event-number are enabled.

catch number
catch signal-name
ignore number
ignore signal-name
Start or stop trapping a signal before it is sent to the program. This is useful when a program being debugged handles signals such as interrupts. A signal may be specified by number or by a name (for example, SIGINT). Signal names are case insensitive and the SIG prefix is optional. By default all signals are trapped except SIGCONT, SIGCHILD, SIGALRM and SIGKILL.

cont integer
cont signal-name
Continue execution from where it stopped. If signal-name is specified, the process continues as though it received the signal. Otherwise, the process is continued as though it had not been stopped.

Execution cannot be continued if the process has ``finished'', that is, called the standard procedure exit. dbxtra does not allow the process to exit, thereby letting you examine the program state.


skip [n]
Continue execution from where it stopped. If n is specified, that many breakpoints are ignored before the program stops. If n is not given, one breakpoint is skipped. Execution cannot be continued if the process has ``finished'', that is, it has called the standard procedure exit.

step [n]
Execute n source lines (default value 1).

next [n]
Execute up to the next n source lines (default value 1). The difference between this and step is that if the line contains a call to a procedure or function the step command stops at the beginning of that block, while the next command does not.

return [procedure]
Continue until a return to procedure is executed, or until the current procedure returns if none is specified.

call procedure(parameters)
Execute the object code associated with the named procedure or function.

jump line-number
Continue execution from the specified line-number. The line-number must be in the current function.

goto line-number
Continue execution and stop before the first instruction at the specified line-number is executed. This creates in effect a temporary break point which only affects execution when the command is used. A filename:line-number pair with filename in double quotes can be used to specify a line-number outside the current file.

Screen related commands

The commands in this section are effective only when dbxtra is invoked in screen mode (the default mode). In this mode the screen is divided into two equal sized windows. The top window contains program source and the bottom window is used for the usual dbxtra session (that is, dbxtra commands and output and the program's input and output). The separating bar (in reverse video) shows the current file and procedure name. A pointing arrow ``->'' on the left marks the current execution line (the line to be executed next).


NOTE: In an emergency situation it is undesirable to kill dbxtra with SIGKILL because it leaves the screen in an unknown mode, and may also leave some orphaned processes. Instead, use three SIGQUIT signals in a row without any input between them.


screen [on | off]
Turn screen mode on/off (no argument is equivalent to on). If screen mode is already on, screen redraws the screen.

more [on | off]
Turn on/off more-like features for dbxtra and the debugged program's output (no argument is equivalent to on). The line count is reset each time the keyboard is touched so that only lines between commands are more'd.

vt100 [on | off]
Turn on/off vt100 emulator for the debugged programs output, (default is on). The vt100 emulation facility allows full screen applications to be debugged with dbxtra. The debugger provides an emulated vt100 screen for program input/output. This screen is displayed automatically when the debugged program is running.

forward [n]
backward [n]
Scroll the source window forward and backward n lines (the default is one window).

display [ [line-number] expression [, expression ... ]]
undisplay [expression-number|expression ...]
display puts the value of its argument list of expressions in a special-purpose window. The values are updated whenever the program stops execution. The named expressions are added to the currently displayed expressions on a new line in the display window (display a,b puts a and b on the same line, whereas display a ; display b puts them on two separate lines). If the optional line-number is specified, the expressions are added to the display line given by the number. If no arguments are given, the list of displayed expressions is printed, each preceded by an index number that can be used as an argument for undisplay.

undisplay removes one or more expressions from the display window. If expression-number is specified, the display line corresponding to that number is removed from the display. If an expression is specified, that expression is removed from within one of the display lines. If no arguments are given to undisplay, then the last line of expressions is removed.

Function keys

dbxtra allows the user to associate a function key or a sequence of keys with one or more screen functions. The following commands are used to define and print keys and turn key interpretation on and off.

bindkey [key [string]]
unbindkey key
Bind (unbind) key with the contents of string.

key can be specified as a terminfo key name (for example, key_up, key_f1) or as a string of characters. Control characters that are part of the key can be typed verbatim, or specified in ^X notation (for example, <Esc> is ^[) or specified in the \nnn notation (where nnn is the octal representation of the ASCII value).

string contains one or more screen editing commands separated by a semi-colon (``;'').

If string is not specified to the bindkey command, dbxtra prints the definition of the given key. If key is not specified dbxtra prints all key definitions. The definitions are printed according to the bindkey command syntax such that if the output of bindkey is redirected to a file, that file can be used to create key definitions in subsequent sessions.


keys [on | off]
Turn on/off interpretations of keys into screen functions (if no argument is provided, it defaults to on). Turning off screen mode (screen off) automatically turns off key interpretation.

Screen functions

Functions with arguments take the string following the function name to the next delimiter (``;'') or to the end of string. If the argument contains a ``;'' it must be preceded by a backslash (``\''). Variables (name) in the argument are evaluated before being passed to the function.

The following screen functions are implemented:


bof
Cursor to end of file.

bol
Cursor to beginning of line.

close
Close a window.

cursor_down
One line down.

cursor_left
One character left.

cursor_right
One character right.

cursor_up
One line up.

del_bol
Delete from cursor location to beginning of line (only on entered line).

del_char
Delete character at cursor location (only on entered line).

del_word
Delete a word to the left of the cursor (only on entered line).

eof
Cursor to end of file.

eol
Cursor to end of line.

expand
Expand current window by two lines.

expand_lower
Expand current window at lower edge by one line.

expand_upper
Expand current window at upper edge by one line.

goto_line
Cursor to line number.

goto_mark
Cursor to mark set by set_mark (see below).

half_page_back
Scroll half page backward.

half_page_forw
Scroll half page forward.

load_file
Load file into current window.

line_back
Scroll one line backward.

line_forw
Scroll one line forward.

move_capability
Move a named capability to current window.

next_command
Copy next dbxtra command as current command.

next_window
Move cursor to next window.

page_back
Scroll one page backward.

page_forw
Scroll one page forward.

prev_command
Copy previous dbxtra command as current command.

prev_window
Move cursor to previous window.

quote_char
Accept next char as is (escape key interpretation).

redraw
Redraw the screen.

screen_function
Enter a screen function by name rather than key.

send_echo
Send the argument to dbxtra with echo.

send_edit
Same as above but allow line editing before sending.

send_noecho
Send the argument to dbxtra with no echo.

set_mark
Set a mark in a window for use by goto_mark.

show_xref
Show the next source location given by xref. xref displays a list of line numbers for lines containing the specified symbol. To put such a line at the top of source window, move the cursor in the bottom window to the line number in question, and press the character sequence bound to show_xref.

shrink
Shrink current window by two lines.

split
Split a window into two. Splitting dbxtra session window creates a program window.

toggle_follow_cursor
Toggles between the static portion of the full screen window and the portion of the window containing the cursor. This is only useful when the program window is being used.

toggle_full_screen
Toggles between the full screen window and the standard dbx/source window layout. Since this is a screen function, it can only be used when the program is not executing.

toggle_line_numbers
Toggle with/without line numbers.

toggle_more
Toggle more/nomore for current window.

toggle_wrap_around
Toggle wrap around of long lines.

word_left
One word left.

word_right
One word right.
The following screen function variables are implemented and evaluate to:

$command
dbxtra command typed by the user at cursor line.

$events
Event ids of breakpoints on cursor line.

$expr
Like $var but including matching parentheses, field operators (``.'' and ``->'') and spaces following dereference operator (``*.'')

$file
Source file name in current window.

$keyboard
String entered at the keyboard at evaluation time.

$line
Source line number of cursor position.

$var
The longest string of alphanumeric and underscore (``_'') characters at the cursor position.

Printing variables and expressions

Names are resolved first using the static scope of the current function, then using the dynamic scope if the name is not found in the static scope. If static and dynamic searches do not yield a unique symbol, an arbitrary symbol is chosen and the following message is printed:
   [using qualified name]
The name resolution procedure may be overridden by qualifying an identifier with a block name, for example, module.variable. For C and C++, source files are treated as modules named by the file name without .c.

dbxtra attempts to choose the most reasonable symbol for a given context. For example, a call symbol(exp) only looks for a symbol that is a function or procedure. If this is not the desired behavior, then the command set $allmatch allows any symbol to match in any context. This context checking is most useful for C++ debugging.

Expressions are specified with an approximately common subset of C and Pascal syntax. Indirection can be denoted using either a prefix ``*'' or a postfix ``^'' and array expressions are subscripted by brackets (``[ ]''). Array subranges (slices) are separated by two dots (``..'') and are subscripted by brackets ([exp..exp]). The field reference operator (``.'') can be used with pointers as well as records, making the C and C++ operator ``->'' unnecessary (although it is supported).

Types of expressions are checked; the type of an expression may be overridden by using type-name(expression). An alternate form of overriding types is expression \ typename. A pointer to a named type may be constructed with expression \ & typename.

A limited form of C casts are supported using (type) expression. type may be any of the C basic types (such as int or char) or a C structure type, followed by any number of asterisks (``*.'') Due to an implementation restriction, typedef names may not be used.

C structure types are represented by struct name. In the same manner, union name, enum name and class name may be used. Using this form, name is a single unqualified word.


assign variable = expression
Assign the value of expression to variable.

dump [procedure] [> filename]
Print the names and values of variables in procedure, or the current one if none is specified. If the procedure given is ``.'', then all active variables are dumped.

print expression [, expression ...]
Print out the values of the expressions.

whatis expression
Print the declaration of the given expression. If cross-reference information has been loaded, macro definitions are printed.

which identifier
Print the full qualification of the given identifier, that is, the outer blocks that the identifier is associated with.

up [count]
down [count]
Move the current function, which is used for resolving names, up or down the stack count levels. The default count is 1.

where
Print out a list of the active procedures and function.

whereis identifier
Print the full qualification of all the symbols whose name matches the given identifier. If cross-reference information has been loaded, print the file names and line numbers where each global symbol is defined. The order in which the symbols are printed is not meaningful.

dbxref [-i] [-ofile] [options] [files]
Generate the cross-reference file (default name dbxtra.xref) necessary for the xref and enhanced whatis, and whereis commands. options are the cc(CP) options -I, -D, and -U, and files is the list of C files. The -i option tells dbxref to do an incremental cross-reference. If files is omitted, all C files that are referenced in the object file are used. The -ofile option tells dbxref to place the output in file. An extension of .xref is added if necessary. The command to invoke dbxref is passed to the user's shell, so all shell environment variables and meta-characters may be used.

An incremental cross-reference is used to update the cross-reference when only some of many files have been modified. The old information relevant to those files is forgotten, and the files are re-scanned, and the information integrated with the old data.


xref identifier
If cross-reference information has been loaded, print a cross-reference for the given symbol. Only global variables, functions, and macros may be xrefed. The cross-reference information is generated with the dbxref command. If the requested name is a function then the following information is printed:

Referenced from:
A list of functions which call the named function. Each function name is followed by the filename in which the call occurs, and one or more line numbers.

Reference to functions/macros:
A list of functions and macros with arguments called by the named function. Each function name is followed by one or more line numbers where the call occurs. An M is present at the beginning of the line if this is a macro call.

Reference to variables/macros:
A list of global variables and parameterless macros referenced by the named function. Each variable name is followed by one or more line numbers where the reference occurs, but there is no distinction between the use of a variable and an assignment to a variable. An M is present at the beginning of the line if this is a macro reference.

If the name given to xref is a macro or a global variable, then only the referenced from information is given. The xref command does not accept other argument types (local variables, type names or structure tags).

If C++ mode is on, xref displays the classes that a subroutine or class is a friend to.

Accessing source files


/regular expression[/]
?regular expression[?]
Search forward or backward in the current source file for the given pattern.

edit [filename]
edit procedure/function-name
Invoke an editor on filename or the current source file if none is specified. If a procedure or function name is specified, the editor is invoked on the file that contains it. Which editor is invoked by default depends on the installation. The default can be overridden by setting the environment variable EDITOR to the name of the desired editor.

file [filename]
Change the current source file name to filename. If none is specified then the current source file name is printed.

func [procedure/function]
Change the current function. If none is specified then print the current function. Changing the current function implicitly changes the current source file to the one that contains the function; it also changes the current scope used for name resolution.

list .
list procedure/function
list [source-line-number [, source-line-number]]
List the lines in the current source file from the first line-number to the second inclusive. If no lines are specified and the user is in screen mode, then no new source lines are displayed and the user is informed about the forward command. Otherwise, the next 10 lines are listed. If the name of a procedure or function is given lines n-k to n+k are listed where n is the first statement in the procedure or function and k is a small number that depends on the size of the window. If the argument is ``.'' then the current execution location is listed. (Note that list . only changes the source location and not the current function for scope purposes).

use directory-list
Set the list of directories to be searched when looking for source files.

Command aliases


alias
alias name name
alias name ``string''
alias name (parameters) ``string''
When commands are processed, dbxtra first checks to see if the word is an alias for either a command or a string. If it is an alias, then dbxtra treats the input as though the corresponding string (with values substituted for any parameters) had been entered. For example, to define the alias rr for the command rerun, type:

alias rr rerun

To define an alias called b that sets a stop at a particular line, type:

alias b(x) ``stop at x''

Subsequently, the command b(12) expands to stop at 12.

If no parameters are specified, the alias command prints all the currently defined aliases (most dbxtra commands have predefined aliases).

Aliases are not transitive. You cannot do alias x run; alias y x, and expect y to execute the run.


unalias name
Remove the alias with the given name.

set name [= expression]
The set command defines values for debugger variables. The name of a debugger variable cannot conflict with the names of variables in the program being debugged. When used within other commands, a debugger variable is expanded to its corresponding expression.

unset name
Delete the debugger variable associated with name.

Debugger variables

The following debugger variables have a special meaning:

$hexchars
$hexints
$hexoffsets
$hexstrings
When set, dbxtra prints out characters, integers, offsets from registers, and character pointers respectively in hexadecimal.

$listwindow
The value of this variable specifies the number of lines to list around a function when the list command is given a function or procedure as its argument. The default value is 10.

$printbases
When set, members of base classes inherited by the current object or class are printed in print or whatis command output.

$unsafecall
$unsafeassign
When $unsafecall is set, strict type checking is turned off for arguments to subroutine or function calls (for example, in the call statement). When $unsafeassign is set, strict type checking between the two sides of an assign statement is turned off. These variables should be used only with great care, because they severely limit dbxtra's usefulness for detecting errors.

$sleep
Specify the number of seconds that dbxtra sleeps at each statement when tracing the whole program in single-step (in screen mode only). The default value is 1 second.

$nodebugregs
When $nodebugregs is set, dbxtra does not attempt to use 386 hardware debug registers. The trace access, when access, and stop access commands need the registers enabled to function. The hardware debug registers will not detect access or modification performed by UNIX (such as read and write system calls), and it may be desirable to turn off use of the debug registers.

$nodebugwarn
When dbxtra attempts to use 386 debug registers, and there are no free registers, a warning message is printed, and slow emulation is performed. If $nodebugwarn is set, the warning message is suppressed.

$allmatch
When $allmatch is set, the choosing of the correct symbol in a given context is not done. In this case, all symbols are equally reasonable.

$noclobber
If set then redirecting the output of a command into an existing file fails.

$windowshell
If set then the sh command invokes a shell in the interaction window instead of turning the screen mode off automatically.

$stringlen
Gives the number of characters (rounded up to the next word boundary) to be printed from a character pointer without seeing a null. If a string is truncated by reaching the $stringlen limit, it is terminated with an ellipsis. $stringlen defaults to 512.

$machinecode
Setting $machinecode affects the disassembly output. The hexadecimal contents of the instruction locations are shown in place of the function:line-number field.

$pccformat
Setting $pccformat causes the disassembly instruction format to be the format generated by the current release of the C compiler (cc).

$fork
If UNIX supports the ptrace(S) stop on fork request, dbxtra allows debugging of children of the debugged process. If $fork is not set, the child process is ignored, and executes to completion.

$fork may be set to a string with the following values:


parent
dbxtra continues debugging the parent process. The child process is run to completion.

child
dbxtra begins debugging the child process. The parent process is run to completion.

push
dbxtra pushes a new dbxtra to debug the child process. dbxtra resumes debugging the parent process when the child dbxtra exits.

both
If dbxtra is running under the Motif screen manager, a new Motif dbxtra will be started to debug the child process.

prompt
The user is asked to choose one of the above choices.

$noexec
If UNIX supports the ptrace(S) stop on fork request, dbxtra determines which file has been exec'ed, and switches to the correct file. If $noexec is set, dbxtra does not switch executable files. The exec command may be used to manually change files.

Machine level commands


stepi
nexti
Single-step as in step or next, but do a single instruction rather than source line.

regs
Display the contents of the 80386 registers in a human-readable form.

fpregs
Display the contents of the 80387 floating point registers in a human-readable form. The contents of the control and status words are displayed, and then the floating point register stack is shown.

address, address/ [mode]
address / [count] [mode]
Print the contents of memory starting at the first address and continuing up to the second address or until count items are printed. If the address is ``.'', the address following the one printed most recently is used. The mode specifies how memory is to be printed; if it is omitted the previous mode specified is used. The initial mode is X. The following modes are supported:

i print the machine instruction
d print a short word in decimal
D print a long word in decimal
u print a short word in unsigned decimal
U print a long word in unsigned decimal
o print a short word in octal
O print a long word in octal
x print a short word in hexadecimal
X print a long word in hexadecimal
b print a byte in octal
c print a byte as a character
s print a string of characters terminated by a null byte
f print a single precision real number
g print a double precision real number

Symbolic addresses are specified by preceding the name with an &. Addresses may be expressions made up of other addresses and the operators ``+'', ``-'', ``*'', unary ``-'', unary ``*'' (dereference), each operator assuming its usual precedence. This precedence can be overridden using parentheses ``('' and ``)''.


Miscellaneous commands


cc
Toggle between C++ and C output modes. This command is not enabled if the -C (C code only) flag was specified when invoking dbxtra. When in C++ output mode, all names and source files output by dbxtra refer to C++ names and source; when in C mode, all names output are C names, and thus somewhat confusing when debugging a C++ program. Both C++ and C names may be specified by the user in either mode. To examine the C source produced by the C++ compiler, the program must be compiled with CC -dbxC instead of CC -g or CC -dbx.

help [command]
help [string]
Print out a synopsis of dbxtra commands or subjects. If command is specified, the section from the manual page for that command is printed. For commands (or subjects) that include non-alphanumeric characters the command name must be quoted (for example, help ``/'').

quit
Exit dbxtra.

sh [command-line]
! command-line
Pass the command-line to the shell for execution. If no command is specified then invoke an interactive shell. The SHELL environment variable determines which shell is used.

source filename
Read dbxtra commands from the given filename.

kill
This kills the current process being debugged. After a kill, the executable file is not active, and it may be recompiled. At the next run or rerun command, dbxtra notices the file has changed, and rereads the symbol table.

detach
If the version of UNIX supports the ptrace(S) detach request, the process being debugged has all breakpoints removed, and it is allowed to execute at full speed. If detach is not supported, the process is killed.

exec filename
If the process being debugged does an exec(S) system call, this tell dbxtra that a new symbol table should be read in.

version
Print the version information for dbXtra. This should be given for support calls.

C++ debugging features

This version of the debugger supports C++ in a straightforward fashion; dbxtra is given knowledge of both C++ and C names and source files. At any time, the user may input either the C or C++ names for a function, structure member or variable; the cc command only affects the output from dbxtra to the user.

Classes in C++ become structures in C, reference variables (for example, int&) become pointers, and simple symbolic constants (const) become variables in the proper scope. Overloaded functions are prompted for. Enum types become ints, and enum constants become literal constants with no hint as to where they came from. Overloaded operator function names are of the form operator+ (no blanks), where ``+'' is replaced by the overloaded operator. Overloaded new and delete operators are specified as new and delete, not operatornew and operatordelete. To examine the translated C source along with the original C++ source, the source file must have been compiled with CC -dbxC; compiling with -dbx alone does not provide access to the C source.

Files

a.out object file
.dbxtrarc initial commands
dbxtra.xref cross-reference file

Comments

dbxtra is intended for use on COFF or ELF object files only. dbxtra will generate a bad magic number error message if it is invoked on non-COFF or non-ELF object files.

Since symbolic debugging information is replicated (both in the object file and in dbxtra) for each instance of a header file, storage is quickly taken up by replicated information when several source files #include the same header. In the case of C++ debugging, judicious use of the -F flag may save significant amounts of memory when starting up dbxtra.

Executable code within header files are not properly traced by dbxtra.

See also

cc(CP), dbx(CP), dbXtra(CP).
© 2003 Commands for Programming (CP)
SCO OpenServer Release 5.0.7 -- 11 February 2003