dbx(1) — VAX
Name
dbx − debugger
Syntax
dbx [−r] [−i] [−k] [−I dir] [−c file] [objfile[coredump]]
Description
The dbx debugger is a tool for source level debugging and execution of programs running under the ULTRIX operating system. Once you invoke dbx, you can issue dbx commands that control and trace program execution, print variable and expression values, and display and edit source files.
You can use command options to modify some steps that dbx performs during startup. (For information on the available options, see Options.) Unless you specify the −r option, dbx prompts you for a command before it begins executing your program. The dbx prompt appears as follows:
(dbx)
To leave dbx issue the quit command.
Arguments
On the command line, the objfile argument names the object file that you want dbx to read as input. For complete dbx support, the object file must contain extended symbol table information. The supported compilers each have an option, −g , that produces the symbol table information in the object file.
The extended symbol table contains information that makes your debugging session more convenient. For example, the extended symbol table contains the names of all the source files translated by the compiler to create the object file. This information allows you to look at all the source code that went into creating an object file during your debugging session.
If your object file does not contain the extended symbol table, use the commands described in Machine Level Commands to debug your program.
If you omit the objfile argument, dbx prompts you for the name of an object file. If you press the Return key, dbx attempts to read a file named a.out from the current directory. If no a.out file exists, dbx issues another prompt to allow you to enter a file name. If you press the Return key, dbx exits.
The coredump argument names a core dump file. You can examine the core dump file to determine the state of your program. If you omit coredump and a core file exists in the current directory, dbx reads in a file named core.
Initialization File
During its startup, dbx reads and executes the commands in an initialization file, if one is present. By default, dbx searches for the file .dbxinit in the current directory. If no .dbxinit file exists in the current directory, dbx searches your home directory for the file. You can use the initialization file to automatically issue setup commands when you begin a dbx session.
You can rename the dbx debugger. If you rename the debugger, you must also rename its initialization file. The debugger expects the initialization file’s name to be a period (.), followed by the first eight characters in the debugger’s name, followed by the string init. For example, if you rename dbx to srcdebugger, the debugger searches for an initialization file named .srcdebuginit.
Options
−cfile Executes the dbx commands in the specified file before reading from standard input.
−i Forces dbx to act as though standard input is a terminal.
−Idir Adds the specified directory to the list of directories that dbx searches for source files. Normally, dbx searches for source files in the current directory and in the directory where objfile is located. You can also issue the use command to set the directory search path.
−k Maps memory addresses. This option is useful for kernel debugging.
−r Executes objfile immediately. If the program executes successfully, dbx exits. If program execution terminates with an error, dbx displays the message that describes the error. You can then either invoke the debugger or let the program continue exiting. The dbx debugger reads from /dev/tty when you specify the −r option and standard input is not a terminal.
Execution and Tracing Commands
Using dbx commands, you can execute your program under control of the debugger. You can trace its execution and control whether your program traps certain signals. The following list describes the commands that allow you to execute and trace your program:
call procedure[(parameters)]
Executes the object code associated with the named procedure or function and passes any parameters you specify to the procedure.
catch integer
catch signal-name
ignore integer
ignore signal-name
Starts or stops trapping a signal before it is sent to the program. These commands are useful when you are debugging a program that handles signals, such as interrupts. You can specify a signal by number or by a name (for example, SIGINT). Signal names are case insensitive and the SIG prefix is optional. By default, dbx traps all signals except SIGCONT, SIGCHILD, SIGALRM, and SIGKILL.
cont [integer]
cont [signal-name]
Continues execution from where it stopped. If you specify a signal name or number, the process continues as though it received the signal. If you omit the signal name or number, program execution continues as if a signal had not been encountered. For information about signal names and numbers, see signal(.).
Execution cannot be continued if the process has called the standard exit procedure. The dbx debugger does not allow the process to exit, so you can examine the program state.
delete command-number ...
delete all
Removes the trace or stop event that corresponds to the specified number or removes all traces and stops. Trace and stop event numbers are assigned by dbx. You can display them using the status command.
The command delete all removes all existing traces and stops at once. The command delete * has the same effect.
nextExecutes to the next source line. If the source line that is executed contains a call to a procedure or function, the next command executes the entire procedure or function. Program execution stops following the return from the procedure; that is, execution stops prior to the source line that follows the call.
reread
Reads the object file before beginning program execution. The debugger reads the object file directly before executing the program in response to a run or rerun command. Reading the object file directly before executing the program ensures that the execution is unaffected by any corruption that might have occurred during a previous run.
return [procedure]
Executes until a return to procedure is executed or until the current procedure returns if none is specified.
run [args] [< filename] [> filename]
rerun [args] [< filename] [> filename]
Starts executing objfile, passing args as command line arguments. You can use angle brackets (< or >) to redirect input or output in the usual manner. If you issue the rerun command without any arguments, dbx passes the previous argument list to the program. Otherwise, the rerun command is identical to run. If you recompiled your program since the last time dbx read symbolic information, it reads in the new information.
status [> filename]
Displays the currently active trace and stop events.
stepExecutes one source line. If the source line contains a call to a procedure or function, the step command stops at the first line of the procedure or function.
stop if condition
stop at source-line-number [if condition]
stop in procedure/function [if condition]
stop variable [if condition]
Stops execution when the specified condition is true, the specified line number is reached, the specified procedure or function is called, or the specified variable changes value.
If you specify a condition with the source-line-number, procedure/function, or variable argument, execution stops only when the condition is true. For example, suppose you specified that execution should stop at line 14 if variable a is greater in value than variable b. The debugger continues execution if variable a equals variable b when it reaches line 14.
trace [in procedure/function] [if condition]
trace source-line-number [if condition]
trace procedure/function [in procedure/function] [if condition]
trace expression at source-line-number [if condition]
trace variable [in procedure/function] [if condition]
Displays tracing information during program execution. The dbx debugger associates a number with the source line that contains the trace. You use the number to turn off tracing, as described with the delete command.
The first argument to the trace command describes what is to be traced. You can specify a procedure or function name, a source line number, an expression, or a variable name.
Specifying a procedure or function name causes dbx to display the name of the calling routine, the source line that contains the call, and the parameters that are passed to the called routine. In addition, dbx notes the return of the named procedure or function and displays the return value, if any. The debugger displays this information each time the procedure or function is called.
If you specify the in procedure/function clause, dbx displays tracing information only while executing the specified procedure or function.
If you specify source-line-number, dbx displays the source line immediately prior to executing it. You can specify a source line number in a source file that is not the current one. To do so, precede the source line number with the source file name in quotation marks, as shown:
(dbx) trace "source_file.c":17
The example specifies tracing line 17 in source_file.c.
If you specify an expression at a source line number, dbx displays the value of the expression when it executes the source line.
Specifying a variable name causes dbx to display the name and value of the variable each time it changes. Program execution is substantially slower during this form of tracing.
The condition argument is a Boolean expression that dbx evaluates prior to displaying any tracing information; if the condition is false, dbx does not display the information.
If you omit the arguments to the trace command, dbx displays each source line before executing it. Program execution is substantially slower during this form of tracing.
Printing Variables and Expressions
The dbx debugger allows you to display the value of your program’s variables and expressions. This section describes how the debugger resolves ambiguous names, how you specify expressions, and the commands that you use to display the value of variables and expressions.
The debugger resolves names by first searching for the name in the static scope of the current procedure or function. If no name is defined in the static scope, the debugger searches the dynamic scope. If neither scope yields a defined name, the debugger chooses an arbitrary symbol and displays the following message:
[using qualified.name]
The debugger substitutes the qualified name of the arbitrary symbol for qualified.name in the message.
You can override this name resolution procedure by qualifying identifiers with a block name, as in module.variable. For the C language, the debugger treats a source file as a module named for the filename without the .c suffix.
You specify dbx expressions using the C or Pascal syntax for expressions. The debugger supports a subset of the expression syntax for both languages; that is, the debugger supports the syntax that is common between the two languages.
In some cases, the debugger supports the syntax of either C or Pascal. For example, you can denote indirection using either an asterisk (*) as a prefix or a circumflex (^) as a suffix. You can use the field reference operator (.) with pointers as well as records or structures, making the C operator (->) unnecessary (although it is supported). To specify a hexadecimal value, precede the value with the "0x" characters.
You must enclose array expressions in brackets ([ ]).
The debugger checks the type of each expression; you can override the type of an expression by using (expression)\type-name.
You can also specify a register name in an expression. You denote registers by $rN where N is the number of the register. You denote vector registers as follows:
$vN[K]
Denotes a vector data register where N is the register number and K is an index. The debugger treats each data register as a double-precision floating point array of 64 elements, indexed from 0 to 63.
$vaerDenotes the vector arithmetic error register, which dbx treats as a longword.
$vcrDenotes the longword vector count register.
$vlrDenotes the longword vector length register
$vmrDenotes the vector mask register. The debugger treats the $vmr as a Boolean array of 64 elements, indexed from 0 to 63.
For more information about VAX registers, see the VAX Architecture Manual.
The following list describes the debugger commands for printing variables and expressions:
assign variable = expression
assign vector-register = "value [,value]"
Assigns the value of the expression to the variable or stores the specified value in the specified vector register.
The assign command allows you to assign a value to one element of a vector register. (You cannot use the command to assign a value to a nonvector register.) You can change only one element in a register in a single command. If you omit the second value, dbx decodes the first value into the first half of the register. If you specify both values, the debugger decodes the first value into the first half of the register and the second value into the second half of the register.
The value can be an integer, floating point, or hexadecimal value.
dump [procedure] [> filename]
Displays the names and values of variables in the given procedure or the current one if none is specified. If you specify the dot (.), the debugger prints the values of all active variables.
print expression [, expression ...]
Displays the values of the specified expressions.
whatis name
Displays the declaration of the given name, which you can qualify using a block name.
up [count]
down [count]
Moves the current procedure or function, which is used for resolving names, up or down the stack count levels. The default for count is 1.
where
Displays a list of the active procedures and functions.
whereis identifier
Displays the full qualification of all the symbols whose name matches the given identifier. The order in which dbx displays the symbols is not meaningful.
which identifier
Displays the full qualification of the given identifier; that is, display the outer blocks that are associated with the identifier.
Accessing Source Files
You can use the following dbx commands to access source files during a debugging session:
/regular expression[/]
?regular expression[?]
Searches forward or backward in the current source file for the given pattern. For information on specifying a regular expression, see The Big Gray Book: The Next Step with ULTRIX.
cd [dirname]
Changes the current directory to the directory you specify. If you omit the dirname argument, dbx uses the directory specified in the HOME environment variable as the current directory.
edit [filename]
edit procedure/function
Invokes an editor on filename or the current source file if none is specified. If you specify a procedure or function name, the editor reads in the file that contains that procedure or function. Which editor is invoked by default depends on the installation. You can override the default setting by modifying the EDITOR environment variable.
file [filename]
Changes the current source file name to filename. If you omit filename, dbx displays the name of the current source file.
func [procedure/function]
Changes the current procedure or function. If you omit procedure/function, dbx displays the current procedure or function. Changing the current procedure or function implicitly changes the current source file to the one that contains the procedure or function; it also changes the current scope used for name resolution.
list [source-line-number [, source-line-number]]
list [source-line-number : integer]
list [procedure/function]
Lists the lines in the current source file from the first line number you specify to the second one you specify, inclusive. If you omit the second source-line-number argument, dbx begins at the first line number and displays the next 10 lines. If you omit both arguments, dbx begins the display at the current source line and displays 10 lines.
If you specify a source line number, a colon, and an integer, dbx lists lines in the current source file starting from source-line-number and continuing for integer number of lines.
If you specify the name of a procedure or function, lines n-k to n+k are listed, where n is the first statement in the procedure or function and k is equal to the $listwindow variable. The default value of $listwindow is 10.
pwdDisplays the pathname of the current directory.
use pathname pathname...
Sets the list of directories that dbx searches when looking for source files. You can specify either a full or relative pathname for pathname.
Command Aliases and Variables
The debugger allows you to define aliases and set variables to make your debugging sessions more efficient. The following list describes the commands you use to perform these tasks:
alias name command
alias name [(parameters)] string
Lists existing aliases or defines an alias for a dbx command or a string. Specify the alias name in the name argument and the dbx command or string in the command or string argument. You can define an alias that accepts parameters by specifying the parameters argument. For example, to define an alias rr for the command rerun, enter the following command:
(dbx) alias rr rerun
To define halt as an alias that sets a stop at a particular line, issue the following command:
(dbx) alias halt(x) "stop at x"
Once you issue this command, dbx interprets the following commands as equivalent:
(dbx) halt(12)
(dbx) stop at 12
Both commands create a stop event at line 12.
getenv name
Displays the value of the environment variable, name.
setenv name value
Sets the environment variable name to value by changing the value of an existing environment variable or creating a new one.
set [name [= expression]]
Lists existing debugger variables and their values or defines a value for the named variable.
Some debugger variables contain either a zero or nonzero value that controls dbx behavior. For example, when set to a nonzero value, the $hexstrings variable causes the debugger to display all strings in hexadecimal format. When set to zero, the variable causes the debugger to display strings in character format. You can set a variable like the $hexstrings variable to a nonzero value as shown:
(dbx) set $hexstrings
You can disable the variable using the unset command, as shown:
(dbx) unset $hexstrings
You can use the set command to create variables using a name of your own. Variables you create must not begin with a dollar sign ($), and the name of the variable must not conflict with names in the program you are debugging. When you create a variable, the set command treats expression as an address and creates a variable at the specified address. You can use the variable name in trace and stop commands to control program execution.
The following list describes the debugger variables:
$frame
If you set this variable to an address, dbx uses the stack frame at that address for stack traces and for accessing local variables. This variable is particularly useful for kernel debugging.
$hexchars
$hexints
$hexoffsets
$hexstrings
You can set these variables to cause dbx to display character strings, integers, offsets from registers, or character pointers, respectively, in hexadecimal format.
$historywindow
The value of this variable determines the number of commands dbx stores in the history list. By default, the history list contains 20 commands.
$listwindow
The value of this variable determines the number of lines dbx lists around a procedure or function or displays when you issue the list command without arguments. The default value for this variable is 10.
$mapaddrs
Setting (unsetting) this variable causes dbx to start (stop) mapping addresses. This variable is useful for kernel debugging.
$unsafecall
$unsafeassign
If you set one of these variables, dbx does not perform strict type checking. When the $unsafecall variable is set, strict type checking is turned off for arguments to procedure or function calls (for example, in the call command). When the $unsafeassign variable is set, strict type checking between the two sides of an assign command is turned off. Use these variables with care, because they severely limit the debugger’s usefulness for detecting errors.
unalias name
Removes the alias with the specified name.
unset name
Deletes the debugger variable associated with the name you specify.
Vector Environment Commands
The dbx debugger provides some special commands that you can use to debug a program that uses vectors. The following list explains these commands:
callv procedure/function[(parameters)]
Executes the object code associated with the named procedure or function. The callv command causes dbx to save the vector environment before it executes the procedure. The debugger restores the vector environment after the procedure exits.
fmask[/"hex constant"] vector_register
tmask[/"hex constant"] vector_register
Displays the contents of the specified vector data register using the vector mask register ($vmr) or the hexadecimal constant you specify as a mask value. Replace vector_register with the name of a vector register to specify which vector data register the debugger displays.
The fmask command causes the debugger to apply a false mask to the register value. The tmask command causes the debugger to apply a true mask to the register value.
nextvExecutes to the next vector instruction at the current or higher procedure level. The dbx debugger ignores vector instructions at lower procedure levels when executing this command. Thus, execution continues through lower level procedures, but stops prior to the next instruction at the current or higher procedure level.
stepvExecutes the next vector instruction. The debugger stops execution prior to the next vector instruction regardless of the procedure level of that instruction.
Machine Level Commands
You can use machine level commands to debug any program, regardless of whether the program object file contains extended symbol table information.
You can specify symbolic addresses by preceding the name with an ampersand (&). You denote registers by $rN where N is the number of the register. You denote vector registers by $vN where N is the number of the register. Addresses may be expressions made up of other addresses and the operators plus (+), minus (−), and indirection (unary asterisk, *).
The following describes the dbx machine level commands:
address , address/ [mode]
address / [count] [mode]
at source-line-number / [count] [mode]
Display the contents of memory starting at the first address and continuing up to the second address.
The second form causes dbx to display the contents of memory starting at address and continuing until count items are displayed. If you type a period (.) in the address field, dbx uses the address following the one it most recently displayed.
If you specify at source-line-number, dbx displays the contents of memory associated with the specified source line. You can specify how many items the debugger displays using the count argument.
The mode on each format specifies how dbx displays memory; if you omit it, the debugger uses the previous mode. The initial mode is X.
You can specify the following modes:
b Displays a byte in octal
c Displays a byte as a character
d Displays a short word in decimal
D Displays a long word in decimal
f Displays a single precision real number
g Displays a double precision real number
i Displays the machine instruction
o Displays a short word in octal
O Displays a long word in octal
s Displays a string of characters terminated by a null byte
x Displays a short word in hexadecimal
X Displays a long word in hexadecimal
nextiExecutes to the next machine instruction. If the machine instruction that dbx executes contains a call to a procedure or function, the debugger executes the entire procedure or function. Program execution stops following the return from the procedure; that is, execution stops prior to execution of the machine instruction that follows the call.
stepiExecutes one machine instruction. If the machine instruction contains a call to a procedure or function, the debugger stops at the first line of the procedure or function.
stopi [at] [address] [if condition]
Stops at the specified machine address or when the specified condition is met. If you specify both address and condition, the debugger stops at the specified address only when the specified condition is true.
tracei [address] [if condition]
tracei [variable] [at address] [if condition]
Displays tracing information during program execution. The first argument specifies an address at which tracing begins or the name of a variable to trace.
If you specify tracing a variable at a specific address, dbx displays the value of that variable when it reaches the address you specify.
The condition argument is a Boolean expression that dbx evaluates prior to displaying any tracing information. If the condition is false, dbx does not display the information.
Miscellaneous Commands
Use the following to get help about dbx, exit from the debugger, issue shell commands, and read commands from a file:
!string
!integer
Executes a command from the history list. You can specify the command name in the string argument. If you specify an integer, dbx executes the command having that number in the history list. For example, the following executes the third command in the history list:
dbx> !3
reread
The debugger echoes the command before execution.
helpDisplays a synopsis of dbx commands.
hi[story]
Displays a list of the previous commands you issued. By default, dbx displays the previous 20 commands. You can change the number of commands dbx keeps in the history list by modifying the $historywindow debugger variable. (For information on changing debugger variables, see Command Aliases And Variables.)
printf format, arg1, arg2,...
Formats a complex structure for display as specified. You use the same format characters for this command as for the printf subroutine. For information on specifying the format, see printf(.).
quitExits from dbx.
record input [filename]
Records all commands you enter at the dbx prompt. The debugger stores the commands in the specified file. You can replay the commands by naming the file on the source command line.
If you omit filename, the debugger terminates the existing recording session. If recording is not active, dbx ignores the command.
sh command-line
Passes the command line to the shell for execution. The SHELL environment variable determines which shell is used.
source filename
Reads dbx commands from the specified file.
Restrictions
If you have a program consisting of several object files and each is built from source files that include header files, the symbolic information for the header files is reproduced in each object code file. Since one debugger startup usually is done for each link, having the ld linker reorganize the symbol information will not save much time, although it will reduce some of the disk space used.
This problem results from the unrestricted semantics of #include statements in C. For example, an include file can contain static declarations that are separate entities for each file in which they are included. If your image is too large for dbx to run, compile with the −g option only those files that you are interested in debugging. However, even with Modula-2, there is a substantial amount of duplication of symbol information necessary for inter-module type checking.
The following restrictions apply to debugging FORTRAN programs:
•Inability to assign values to logical*2, complex, and double complex variables.
•Inability to represent parameter constants that are not type integer or real.
•Peculiar representations of the values of dummy procedures. (The value shown for a dummy procedure is actually the first few bytes of the procedure text. To find the location of the procedure, use an ampersand (&) to use the address of the variable.)
The dbx debugger does not allow you to run a program you do not own unless you are root. If you are not root, the following message might be displayed on your screen when you issue the run command:
can’t-write-to-process
This message is displayed when the dbx debugger tries to set breakpoints because of restrictions on the ptrace system call. The dbx debugger always tries set a breakpoint on exit. If you repeat the run command, your program runs without breakpoints.
The printf debugger command does not support the %s conversion specification.
Files
a.out Object file
.dbxinit Initialization file