DBX(1) — USER COMMANDS
NAME
dbx − source-level debugger for C, FORTRAN 77 and Pascal programs
SYNOPSIS
dbx [ −r ] [ −i ] [ −I dir ] [ −k ] [ −kbd ] [ objfile [ corefile ] ]
DESCRIPTION
dbx is a utility for source-level debugging and execution of programs written in C, FORTRAN 77 and Pascal. It accepts the same commands as dbxtool(1), using a standard terminal interface rather than the window system.
objfile is an object file produced by cc(1V), f77(1) or pc(1) (or a combination of them) with the appropriate flag (−g) specified to produce symbol information in the object file.
If no objfile is specified, use the debug command to specify the program to be debugged. The object file contains a symbol table which includes the names of all the source files translated by the compiler to create it. These files are available for perusal while using the debugger.
If a file named corefile exists in the current directory or a corefile is specified, dbx can be used to examine the state of the program when it faulted.
Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if that file exists in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current directory.
OPTIONS
−rExecutes objfile immediately. Parameters follow the object file name (redirection is handled properly). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for termination and waits for user response. dbx reads from /dev/tty when −r is specified and standard input is a file or pipe.
−iForces dbx to act as though standard input is a terminal or terminal emulator.
−I dirAdds 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.
−kKernel debugging.
−kbdDebugs a program that sets the keyboard into up/down translation mode. This flag is necessary if the program you are debugging uses up/down encoding.
USAGE
Refer to dbx in Program Debugging Tools for the Sun Workstation.
The most useful basic commands to know about are run to run the program being debugged, where to obtain a stack trace with line numbers, print for displaying variables, and stop for setting breakpoints.
Filenames
Filenames within dbx may include shell metacharacters. The shell used for pattern matching is determined by the SHELL environment variable.
Expressions
dbx expressions are combinations of variables, constants, procedure calls, and operators. Hexadecimal constants must be preceded by a ‘0x’ and octal constants by a ‘0’. Character constants must be enclosed in single quotes. Expressions cannot involve strings, structures, or arrays, although elements of structures or arrays may be used.
Operators
+ − ∗ / div %
add, subtract, multiply, divide, integer division, and remainder
<< >> & | ~
left shift, right shift, bitwise AND, bitwise OR, and bitwise complement
& ∗ address of operator and contents of operator
< > <= >= == != !
less than, greater than, less than or equal, greater than or equal, equal to, not equal to, and not
&& || logical AND, logical OR
sizeof (cast)
size of variable or type, and type cast
. -> Field reference, pointed-to field reference (dot works for both in dbx).
Precedence and associativity of operators are the same as in C, and parentheses can be used for grouping.
If there is no corefile file, only expressions containing constants are available. Procedure calls require an active child process.
Scope Rules
dbx uses the variables file and func to resovle scope conflicts. Their values are updated as files and functions are entered and exited during execution. You can also change them explicitly. When func is changed, file is updated along with it, but not vice versa.
Execution and Tracing Commands
INTERRUPT
Stop the program being debugged and enter dbx.
run [ args ] [ < infile ] [ >| >> outfile ]
Start executing objfile, reading in any new information from it. With no args, use the argument list from the previous run command.
args Pass args as command-line arguments to the program.
<|>|>> Redirect input or output, or append output to a file.
rerun [ args ] [ < infile ] [ >| >> outfile ]
Like the run command, except that when args are omitted, none are passed to the program.
cont [ at sourceline ] [ sig signal ]
Continue execution from where it stopped.
at sourceline
Start from sourceline
sig signal Continue as if signal had occurred. signal may be a number or a name as with catch.
trace [ in function ] [ if condition ]
trace sourceline [ if condition ]
trace function [ if condition ]
trace expression at sourceline [ if condition ]
trace variable [ in function ] [ if condition ]
Display tracing information. If no argument is specified, each source line is displayed before execution. Tracing is turned off when the function or procedure is exited.
in function Display tracing information only while executing the function or procedure function.
if condition
Display tracing information only if condition is true.
sourceline Display the line immediately prior to executing it. Source line-numbers from another file are written as "filename":n.
function Display the routine and source line called from, parameters passed in, and return value.
expression at sourceline
Display the value of expression whenever sourceline is reached.
variable Display the name and value whenever variable changes.
stop at sourceline [ if condition ]
stop in function [ if condition ]
stop variable [ if condition ]
stop if condition
Stop execution when the sourceline is reached, function is called, variable is changed, or condition becomes true.
when in function { command ; [ command ; ] ... }
when at sourceline { command ; [ command ; ] ... }
when condition { command ; [ command ; ] ... }
Execute the dbx command(s) when function is called, sourceline is reached, or condition is true.
status [ > filename ]
Display active trace, stop and when commands, and associated command numbers.
delete all
delete cmd-no [ , cmd-no ] ...
Remove all traces, stops and whens, or those corresponding to each dbx cmd-no (as displayed by status).
clear [ sourceline]
Clear all breakpoints at the current stopping point, or at sourceline.
catch [ signal [ , signal ] ... ]
Display all signals currently being caught, or catch signal before it is sent to the program being debugged. A signal can be specified either by name (with the SIG prefix omitted, as with kill(1)) or number. Initially all signals are caught except SIGHUP, SIGEMT, SIGFPE, SIGKILL, SIGALRM, SIGTSTP, SIGCONT, SIGCHLD, and SIGWINCH.
ignore [ signal [ , signal ] ... ]
Display all signals currently being ignored, or stop catching signal, which may be specified by name or number as with catch.
step [ n ]
Execute the next n source lines. If omitted, n is taken to be ‘1’. Steps into functions.
next [ n ]
Execute the next n source lines. If omitted, n is taken to be ‘1’. Steps past functions.
Naming, Printing and Displaying Data
Variables from another function or procedure with the same name as one in the current block must be qualified as follows:
[` sourcefile `] function` variable
For Pascal variables there may be more than one function or procedure name, each separated by a backquote.
print expression [ , expression ] ...
Print the value of each expression, which may involve function calls. Program execution halts when a breakpoint is reached, and dbx resumes.
display [ expression [ , expression ] ... ]
Print a list of the expressions currently being displayed, or display the value of each expression whenever execution stops.
undisplay [ expression [ , expression ] ... ]
Stop displaying the value of each expression whenever execution stops. If expression is a constant, it refers shown by the display command with no arguments.
whatis identifier
whatis type
Print the declaration of the given identifier or type. types are useful to print all the members of a structure, union, or enumerated type.
which identifier
Print the fully-qualified name of the given identifier.
whereis identifier
Print the fully qualified name of all symbols matching identifier.
assign variable = expression
set variable = expression
Assign the value of expression to variable. There is no type conversion for operands of differing type.
set81 fpreg=word1 word2 word3
Treat the concatenation of word1 word2 word3 as a 96-bit, IEEE floating-point value and assign it to the MC68881 floating-point register fpreg. (Supported only on Sun-3).
call function(parameters)
Execute the named function. Arguments are passed according to the rules for the source-language of function.
where [ n ]
List all, or the top n, active functions on the stack.
dump [ function ]
Display the names and values of local variables and parameters in the current or specified function.
up [ n ]
down [ n ]
Move up (towards "main") or down the call stack, one or n levels.
File Access Commands
edit [ filename | function ]
Edit the current source file, or the given filename or the file that contains function.
file [ filename ]
Print the name of the current source file, or change the current source file to filename.
func [ function| program | objfile
Print the name of the current function, or change to the given function, program, or objfile. Also changes the current scope.
list [ startline [ , endline ] ]
list function
List the next ten lines from current source file, list from startline through endline, or and list from five lines above, to five lines below the first line of function.
use [ directory-list ]
Print or set the list of directories in which to search for source files.
cd [ directory ]
Change the current working directory for dbx to directory (or to the value of the HOME environment variable).
pwd Print the current working directory for dbx.
/reg-exp[/]
?reg-exp[?]
Search the current file for the regular expression reg-exp, from the next (previous) line to the end (top). The matching line becomes the new current line.
Miscellaneous Commands
sh command-line
Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used.
alias new-command-name character-sequence
Respond to new-command-name as though it were character-sequence. Special characters occurring in character-sequence must be enclosed in quotation marks. Alias substitution as with the C-Shell (csh(1)) also occurs.
help [ command ]
Display a synopsis of dbx commands, or print a short message explaining command.
make Invoke make(1) with the name of the program as its argument. Any arguments set using dbxenv makeargs are also passed as arguments.
source filename
Read and execute dbx commands from filename. Useful when the filename has been created by redirecting an earlier status command.
quit Exit dbx.
dbxenv
dbxenv case sensitive | insensitive
dbxenv fpaasm on | off
dbxenv fpabase a[0-7] | off
dbxenv makeargs string
dbxenv stringlen num
dbxenv speed seconds
Display dbx attributes or set the named attribute:
case Controls whether upper- and lower-case characters are treated as different values. The default is sensitive.
fpaasm Controls FPA instruction disassembly. The default is on.
fpabase Sets the base register for FPA instruction disassembly. The default is off.
makeargs Sets arguments to pass to make(1). The default is "CC=cc −g".
speed Set the interval between execution during tracing. The default is 0.5 seconds.
stringlen Controls the maximum number of characters printed for a “char ∗” variable in a C program. The default is 512.
debug [ −k ] [ objfile [ corefile | pid ] ]
With no arguments, print the name of the current program. With arguments, stop debugging the current program and begin debugging objfile having either corefile or the current process ID pid.
−k Kernel debugging.
kill Stop debugging of the current program, but be ready to debug another.
detach Detach the current program (process) from dbx. dbx will be unable to access or modify its state.
proc [ pid ]
For kernel debugging. Display which process is mapped into the user area, or map pid to the user area.
Machine-Level Commands
tracei [ address ] [ if condition ]
tracei [ variable ] [at address ] [ if condition ]
Trace execution of a specific machine-instruction address.
stopi [ variable ] [ if condition ]
stopi [at address ] [ if condition ]
Set a breakpoint at a machine instruction address.
stepi
nexti Single step as in step or next, but do a single machine instruction rather than a source line.
address,address / [ mode ]
address / [count ] [ mode ]
Display the contents of memory starting at the first (or current) address up to the second address, or until count items have been displayed. The initial display mode is X. The following modes are supported:
i the machine instruction
d word in decimal
D longword in decimal
o word in octal
O longword in octal
x word in hexadecimal
X longword in hexadecimal
b byte in octal
c byte as a character
s strings as characters terminated by a null
f single precision real number
F double-precision real number
E extended-precision real number
An address can be specified as an item from the following list, or as and expression made up of other addresses and the operators ‘+’, ‘−’, ‘∗’, and indirection (unary ‘∗’).
&name symbolic address
$d[0-7] data registers
$a[0-7] address registers
$fp frame pointer, equivalent to register a6
$sp stack pointer, equivalent to register a7
$pc program counter
$ps program status
$fp[0-7] MC68881 data registers
$fpc MC68881 control register
$fps MC68881 status register
$fpi MC68881 instruction address register
$fpf MC68881 flags register (unused, idle, busy)
$fpg MC68881 floating-point signal type
$fpa[0-31]
double-precision interpretation of FPA registers.
$sfpa[0-31]
single-precision interpretation of FPA registers.
address = [ mode ]
Display the value of the address.
ENVIRONMENT
dbx checks the environment variable EDITOR for the name of the text editor to use with the edit command.
FILES
coredefault core file
~/.dbxinitinitial commands
SEE ALSO
Debugging Tools for the Sun Workstation
BUGS
dbx does not correctly handle C variables that are local to compound statements. When printing these variables it often gives incorrect results.
dbx does not handle FORTRAN entry points well — it treats them as if they were independent routines.
dbx does not handle assigning to FORTRAN complex types correctly (see the assign/set command).
Some operations behave differently in dbx than in C:
•dbx has two division operators — / always yields a floating-point result and div always yields an integral result.
•An array or function name does not signify the address of the array or function in dbx. An array name signifies the entire array, and a function name signifies a call to the function with no arguments. The address of an array can be obtained by taking the address of its first element, and the address of a function can be obtained by taking the address of its name.
Casts do not work with FORTRAN 77 or Pascal.
Executable code incorporated into a source file using an #include preprocessor directive confuses dbx.
dbx is confused by the output of program generators such as yacc and lex.
Sun Release 3.2 — Last change: 23 July 1986