./_Man_Local_html/html1/dbx.1.html

Manual page for DBX(1)

dbx - source-level debugger

SYNOPSIS

dbx [ -f fcount ] [ -i ] [ -Idir ] [ -kbd ] [ -P fd ] [ -r ] [ -s startup ] [ -sr startup ]
[ execfile [ corefile | process-id ] ]

DESCRIPTION

dbx is a utility for source-level debugging and execution of programs written in Sun C, C++, FORTRAN , Pascal, Modula-2, and ANSI C. dbx accepts the same commands as dbxtool.1 but uses a standard terminal (tty) interface.

execfile is an executable file, produced by a compiler, with the -g option to include a symbol table. This symbol table contains the names of all the source files used to create it, and these files are available for perusal while using the debugger.

If no execfile is specified, you can use dbx's debug command to specify the program to debug.

If there is a file named core in the current directory, or a corefile argument is specified, you can use dbx to examine the state of the program when the core file was produced.

dbx executes commands in the .dbxinit file immediately before it reads the symbol table. dbx first searches for .dbxinit in the current directory. If .dbxinit does not exist in the current directory, dbx looks in the user's home directory.

OPTIONS

-f fcount: Alter the initial estimate of the number of functions in the program being debugged. The initial setting is 500.
-i: Force dbx to act as though the standard input were a terminal or terminal emulator.
-I dir: Add dir to the list of directories in which to search for a source file. dbx normally searches the current directory and the directory where execfile is located. The directory search path can be reset with the use command.
-kbd: Debug a program that sets the keyboard into up-down translation mode. This flag is necessary if a program uses up-down decoding.
-P fd: Create a pipeline to a dbxtool.1 process. fd is the file descriptor through which to pipe output to the front-end process. This option is passed automatically to dbx by dbxtool.
-r: Execute execfile 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 a response. dbx reads from the terminal (/dev/tty) when -r is specified and standard input is a file or pipe.
-s startup: Read initialization commands from the file named startup instead of from .dbxinit.
-sr startup: Read initialization commands from the temporary file named startup, instead of from .dbxinit and then remove startup.

USAGE

Refer to dbx in the [a manual with the abbreviation DEBUG] manual.

The basic commands to know are: run, to run the program being debugged; where, to obtain a stack trace with line numbers; print, to display variables; and stop, to set breakpoints.

Expressions

dbx expressions are combinations of variables, constants, procedure calls, and operators. Variables are either variables in the program being debugged or special dbx variables whose names begin with $. 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.
: dbx has two division operators. `/' always yields a floating-point result and div always yields an integral result.
<< >> & | ~: 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 to, greater than or equal to, equal, not equal, and negation.
&& ||: Logical AND and logical OR
sizeof (cast): Size of variable or type and type cast.
. ->: Field reference and pointed-to-field reference (however, dot works for both in dbx).

Precedence and associativity of operators are the same as for C; parentheses can be used for grouping.

Scope Rules

dbx resolves scope conflicts based on the values of the current file and function. These values are updated as files and functions are entered and exited during execution. You can also change them explicitly by using the file and func commands. When the current function is changed, the current file is updated along with it, but not vice versa.

Commands to List Active and Post-Mortem Procedures

where[ n]: List all, or the top n, active functions on the stack.
up [n]: Move up (towards ``main'') the call stack n levels. If omitted, n is taken to be one.
down [n]: Move down the call stack n levels. If omitted, n is taken to be one.

Commands to Name, Display, and Set 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 to a display-number as shown by the display command with no arguments.
whatis identifier
whatis type: Print the declaration of the given identifier or type. types are useful for printing 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).
dump [ function ]: Display the names and values of local variables and parameters in the current or specified function.

Commands to Set Breakpoints

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 when all is specified, or those corresponding to each dbx cmd-no (as displayed by status).
clear [ sourceline]: Clear all breakpoints at the current stopping point if no argument is given, or at sourceline.
catch [ signal [[ , ] signal ] ... ]: Display all signals currently being caught if no argument is given, 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.

Commands to Run and Trace Programs

^C: Interrupt. Stop the program being debugged and return to dbx.
run [ args ] [ < infile ] [ > outfile | >> outfile ]: Start executing execfile. If no arguments are specified, dbx uses 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 | >> outfile ]: Like the run command, except that when args are omitted, no args 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 signal number or name specified by the catch command.

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

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. next steps past functions.
call function(parameters): Execute the named function. Arguments are passed according to the rules for the source-language of function.

Commands to Access Source Files and Directories

edit [ filename ]
edit [ procedure/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 [ procedure/function ]: Print the name of the current procedure/function or change to the given procedure/function. Also changes the current scope.
list [ startline [ , endline ] ]
list function: List the lines in the current source file from startline through endline . If no endline is given, list startline only. If neither startline nor endline is given, list the next 10 lines. If the name of a procedure or function is given, list from five lines above to five lines below the first line of of the procedure or function.
use [ directory ]: Set the list of directories in which to search for source files.
cd [ directory ]: Change the current working directory for dbx to the value of the HOME environment variable if no argument is given, or to directory .
pwd: Print the current working directory for dbx.
/reg-exp[/]: Search downward in the current file for reg-exp. The search begins with the line immediately after the current line and, if necessary, continues until the end of the file. The matching line becomes the current line.
?reg-exp [?]: Search upward in the current file for reg-exp. The search begins with the line immediately before the current line and, if necessary, continues until the top of the file. The matching line becomes the 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.
setenv name string: Set environment variable name to string.
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 speed seconds
dbxenv stringlen num 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. (Supported only on Sun-3 systems).
fpabase: Sets the base register for FPA instruction disassembly. The default is off. (Supported only on Sun-3 systems).
makeargs: Sets arguments to pass to make. 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 [ execfile [ corefile | pid ] ]: With no arguments, print the name of the current program. With arguments, restart dbx and re-read the specified object module, saving some status information. Begin debugging execfile optionally using corefile or the current process ID pid.
kill: Stop debugging and execution 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.
modules
modules select [ all| execfile ] [ execfile] ...
modules append execfile [ execfile] ...: The modules command displays or sets the current modules selection list. If the modules selection list is set, the debugger reads debugging information only for object files in this list. Debugging information for object files not in the modules selection list is ignored.
: modules with no arguments displays the set of object files for which source level debugging information is currently available, including the path names of any associated source files. If the debugger cannot access a source file for which it has debugging information, it displays the source file name with a trailing `?' (question mark) character. Source file path names reflect the current search path as set by the use command or the -I option.
: modules select displays the current modules selection list if no execfile is given. Otherwise, modules select sets the modules selection list to the specified object files. To get complete debugging information, the debugger may need to read object files not in the modules selection list. `modules select' displays these ``implied'' file names with trailing `*' (asterisk) characters (see NOTES). `modules select all' discards the modules selection list.
: modules append appends the specified object files to the modules selection list.
: If the modules selection list includes an object file not in the executable being debugged, the debugger issues a warning.

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: Single step as in step , but do a single machine instruction rather than a source line.
nexti: Single step as in next, but do a single machine instruction rather than a source line.
address,address / [ mode ]
address / [count ] [ mode ]
+/: [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. If a + is specified, the address following the one displayed most recently is used. The mode specifies how memory is displayed; if omitted, the last specified mode is used. The initial display mode is X. The following modes are supported:

b: byte in octal
c: byte as a character
d: word in decimal
D: longword in decimal
E: extended-precision real number (not supported on Sun-4)
f: single precision real number
F: double-precision real number
i: the machine instruction
o: word in octal
O: longword in octal
s: strings as characters terminated by a null
x: word in hexadecimal
X: longword in hexadecimal

: An address can be specified as an item from the following list, as an expression made up of other addresses and the operators `+', `-', `*', and indirection (unary `*'), or as an arbitrary expression enclosed in parentheses.

&name: symbolic address
integer: numeric address

address = [ mode ]: Display the value of the address.

Machine Registers

The machine registers for the current machine type are represented as special dbx variables. They can be used in expressions as any other dbx variable can. The registers and their variable names are:

Sun-3 Registers

$d[0-7]: data registers
$a[0-7]: address registers.
$fp[0-7]: MC68881 data registers
$fp: frame pointer, equivalent to register a6
$sp: stack pointer, equivalent to register a7
$pc: program counter
$ps: program status
$fpc: MC68881 control register
$fps: MC68881 status register
$fpi: MC68881 instruction address register
$fpf: MC68881 flags register (unused, idle, busy)
$fpg: MC6881 floating-point signal type
$fpa[0-31]: double-precision interpretation of FPA registers.
$fpa[0-31]s: single-precision interpretation of FPA registers.

Sun-4 Registers

$g[0-7]: global registers
$o[0-7]: ``out'' registers
$i[0-7]: ``in'' registers
$l[0-7]: ``local'' registers
$fp: frame pointer, equivalent to register i6
$sp: stack pointer, equivalent to register o6
$y: Y register
$psr: processor state register
$wim: window invalid mask register
$tbr: trap base register
$pc: program counter
$npc: next program counter
$f[0-31]: FPU ``f'' registers
$fsr: FPU status register
$fq: FPU queue

Additions to dbx for C++

Symbolic Names

cfront mangles the original source names of locals, member functions, functions, and so on. dbx will demangle all those mangled names into C++ symbolic format in dbx output.

Constants

dbx can print the value of const identifiers. For example, you can give a command like whatis i where i has a const declaration.

The Keyword Class

You can use the keyword class to specify that you want information about a class instead of about a function with the same name. This is most useful within constructor functions, because dbx will assume that you want information on the constructor instead of the class.

Fields in Anonymous Unions

dbx can access fields in anonymous unions.

Member Data Fields

Given a class variable, you can refer to member data fields the same way you refer to the members of an ordinary C structure.

Member Functions

To see the member functions and friend classes/functions of a class listed, use the -v(verbose) flag of the whatis command.

This Pointer

When inside a member functions, you can ask to display the value of the this pointer (a pointer to the object for which a non-static member function is called) via dbx commands such as print or dump .

Overloaded Function Names

When a function name is overloaded, the translator distinguishes between different functions by assigning them different names internally. These internal names are called mangled names. dbx translates the mangled name back to its original name. You can see a list of mangled names using the dbx list command.

Overloaded Operators

dbx supports overloaded operator syntax for a limited operator set: +, -, *, /, ,(comma), ^, &, |, &&, ||, >>, <<, %, and []. It supports overloaded operators for classes.

Reference Variables

You can refer to a reference variable as with any variable, just by giving its name.

Scope Resolution Operator

In dbx, you can use the scope resolution operator :: (two colons) to specify which particular variable or function is designated by a name that may be shared by many variables or functions.

Virtual Function Table Pointer

When you print out the contents of a class or class object that has a virtual function table, dbx includes the field with the pointer to the table in the listing.

ENVIRONMENT

dbx checks the environment variable EDITOR for the name of the text editor to use with the edit command.

FILES

core: default core file
.dbxinit: local dbx initialization file
~/.dbxinit: user's dbx initialization file

NOTES

Because the cc command does not generate or support 8-bit symbol names, it is inappropriate to make dbx 8-bit clean. See cc.1v for an explanation about why cc is not 8-bit clean.

To save space, the linker eliminates debugging information redundantly defined in multiple include files. If the linker excluded some of the symbols for an object file in the modules selection list, the debugger must read debugging information from the object files where these symbols were first defined. If these ``implied'' modules are not in the modules selection list, `modules select' displays their names with trailing `*' (asterisk) characters.

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

Unlike C, dbx does not recognize an array or function name as 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. To get the address of an array, take the address of its first element. To get the address of a function, take the address of its name.

Casts do not work with FORTRAN 77 or Pascal.

Last modified 21/April/97