dbx(CP)

Syntax

Description

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, dbx can be used to examine the state of the program when it faulted.

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

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

Command line options

-r

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

-x

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

-F

dbx assumes that file-scoped structure/union/enum definitions with the same name are identical. Specifying -F may significantly decrease dbx'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 dbx 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 dbx commands in file before reading from standard input.

-C++

Assume C++ mode. dbx 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, dbx just prompts and waits for a command.

If neither -C++ nor -C is specified, dbx 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 dbx. 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.

unsetenv name

Unset the value of variable name, that is, remove it from the program's environment.

trace

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

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

Printing variables and expressions

   [using qualified name]

dbx 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, dbx first checks to see if the word is an alias for either a command or a string. If it is an alias, then dbx 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 dbx 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

$hexchars
$hexints
$hexoffsets
$hexstrings

When set, dbx 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 dbx's usefulness for detecting errors.

$sleep

Specify the number of seconds that dbx 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, dbx 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 dbx 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 dbx 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, dbx determines which file has been exec'ed, and switches to the correct file. If $noexec is set, dbx 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 dbx. When in C++ output mode, all names and source files output by dbx 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 dbx 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 dbx.

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 dbx 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, dbx 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 dbx 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

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

Comments

Since symbolic debugging information is replicated (both in the object file and in dbx) 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 dbx.

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

See also