dbx - source-level debugger

---

SYNOPSIS

AVAILABILITY

DESCRIPTION

dbx is a utility for source-level debugging and execution of programs written in C, or other supported languages such as Pascal and FORTRAN 77. dbx accepts the same commands as dbxtool.1 but uses a standard terminal (tty) interface.

objfile is an object file, produced by cc.1v or another 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 objfile 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 commands in the file .dbxinit are executed immediately before the symbol table is read, if that file exists in the current directory, or in the user's home directory if .dbxinit does not exist in the current directory.

OPTIONS

-f fcount

Alter the initial estimate of the number 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 objfile is located. The directory search path can be reset with the use command.

-k

Kernel debugging.

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

-sr tstartup

Read initialization commands from the temporary file named startup, and then remove that file.

USAGE

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

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, to display variables, and stop, to set breakpoints.

Filenames

Expressions

Operators

+ - * / div %

Add, subtract, multiply, divide, integer division, and remainder, respectively.

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.

If there is no corefile, only expressions containing constants are available. Procedure calls require an active child process.

Scope Rules

dbx uses the current file and function to resolve scope conflicts. Their 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.

Execution and Tracing Commands

^C

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

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 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. (Supported only on Sun-3).

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 [ -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. The -k option indicates 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.

modules

modules select [ all| objfile... ]

modules append objfile [ objfile... ]

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

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 (not supported on Sun-4)

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

Sun-2 and Sun-3 Registers

$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

Sun-3-Only Registers

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

$fpa[0-31]

double-precision interpretation of FPA registers.

$sfpa[0-31]

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

Sun386i Registers

$ss

stack segment register

$eflags

flags

$cs

code segment register

$eip

instruction pointer

$eax

general register

$ecx

general register

$edx

general register

$ebx

general register

$esp

stack pointer

$ebp

frame pointer

$esi

source index register

$edi

destination index register

$ds

data segment register

$es

alternate data segment register

$fs

alternate data segment register

$gs

alternate data segment register

Registers for the 80386 lower halves (16 bits) are:

$ax

general register

$cx

general register

$dx

general register

$bx

general register

$sp

stack pointer

$bp

frame pointer

$si

source index register

$di

destination index register

$ip

instruction pointer, lower 16 bits

$flags

flags, lower 16 bits

The first four Sun386i 16-bit registers can be split into 8-bit parts:

$al

lower (right) half of register $ax

$ah

higher (left) half of register $ax

$cl

lower (right) half of register $cx

$ch

higher (left) half of register $cx

$dl

lower (right) half of register $dx

$dh

higher (left) half of register $dx

$bl

lower (right) half of register $bx

$bh

higher (left) half of register $bx

Registers for the 80387 are:

$fctrl

control register

$fstat

status register

$ftag

tag register

$fip

instruction pointer offset

$fcs

code segment selector

$fopoff

operand pointer offset

$fopsel

operand pointer selector

$st0 - $st7

data registers

ENVIRONMENT

FILES

core

default core file

.dbxinit

local dbx initialization file

~/.dbxinit

user's dbx initialization file

SEE ALSO

[a manual with the abbreviation DEBUG]

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.

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.1 and lex.1

A step command issued at a procedure call will not work properly when debugging information is available for the function being called and that function is in a shared library.

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97