NAME

dbx − debugger

SYNOPSIS

dbx [  −r  ] [  −i  ] [  −I dir  ] [  −c file  ] [ objfile ]

DESCRIPTION

dbx is a tool for source level debugging and execution of programs under UNIX.  objfile is an object file produced by a compiler with the appropriate flag (usually −g) specified to produce symbol information in the object file.  Currently, both cc(1) and f77(1) produce the appropriate source information.  The machine level facilities of dbx can be used on any program. 

The object file contains a symbol table that includes the name of all the source files translated by the compiler to create it.  These source files are available for perusal while using the debugger. 

If the file .dbxinit exists in the current directory, then the debugger commands in it are executed.  If a .dbxinit is not in the current directory, dbx checks for it in the user’s home directory. 

The command line options and their meanings are:

−r Execute objfile immediately.  If it terminates successfully, dbx exits.  Otherwise, the reason for termination will be reported and the user offered the option of entering the debugger or letting the program fault.  When −r is specified and standard input is not a terminal, Dbx will read from /dev/tty. 

−i Force dbx to act as though standard input is a terminal. 

−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 the file before reading from standard input. 

Unless −r is specified, dbx just prompts and waits for a command.  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.  When rerun is used without any arguments, the previous argument list is passed to the program; otherwise it is identical to run.  If objfile has been written since the last time the symbolic information was read in, dbx will read in the new information. 

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]
Have tracing information printed when the program is executed. A number is associated with the command that is used to turn the tracing off (see the delete command).  The first argument describes what is to be traced. If it is a source-line-number, then the line is printed immediately prior to being executed.  Source line numbers in a file other than the current one must be preceded by the name of the file in quotes and a colon, e.g., "mumble.p":17.  If the argument is a procedure or function name then every time it is called, information is printed telling what routine called it, from what source line it was called, and what parameters were passed to it. In addition, its return is noted, and if it is a function then the value it is returning is also printed. If the argument is an expression with an at clause, then the value of the expression is printed whenever the identified source line is reached.  If the argument is a variable, then the name and value of the variable are printed whenever it changes. During this form of tracing, execution is substantially slower. If no argument is specified, then all source lines are printed before they are executed. Execution is substantially slower during this form of tracing. The clause “in procedure/function” restricts tracing information to be printed only while executing inside the given procedure or function.  Condition is a boolean expression and is evaluated prior to printing the tracing information; if it is false, then the information is not printed. 

stop if condition

stop at source-line-number [if condition]

stop in procedure/function [if condition]

stop variable [if condition]
Stop execution when the given line is reached, procedure or function called, variable changed, or condition true.

status [> filename]
Print out the currently active trace and stop commands. 

delete command-number ...
The traces or stops corresponding to the given numbers are removed. The numbers associated with traces and stops are printed by the status command. 

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 (e.g., SIGINT). Signal names are case insensitive and the “SIG” prefix is optional. By default, all signals are trapped except SIGCLD, SIGALRM and SIGKILL.

cont integer

cont signal-name
Continue execution from where it stopped. If a signal 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” (e.g., it has called the standard procedure “exit”).  Dbx does not allow the process to exit, thereby letting the user examine the program state. 

stepExecute one source line. 

nextExecute up to the next source line.  The difference between next and step is that if the line contains a call to a procedure or function the step command will stop at the beginning of that block, while the next command will 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.

Printing Variables and Expressions

Names are resolved first using the static scope of the current function.  If the name is not defined in the static scope, then the dynamic scope is searched to resolve the name.  If static and dynamic searches do not yield a result, an arbitrary symbol is chosen and the message “[using qualified name]” is printed.  The name resolution procedure may be overridden by qualifying an identifier with a block name, e.g., “module.variable”.  All source files in C are treated as modules. Thus, to specify the block name (module), use the file name without the “.c” extension. 

Expressions are specified with an approximately common subset of C and Pascal syntax.  Indirection can be denoted using either a prefix “*” or a postfix “^”.  Array expressions are subscripted by brackets (“[ ]”).  The field reference operator (“.”) can be used with pointers as well as records, making the 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)”.  Type-name must be a simple single-word type (i.e., char, short) or a typedef’d type.  It may not be a complex type (such as ’char *’).  When there is no corresponding named type, the special construct “&type-name” and “$$tag-name” can be used to represent a pointer to a named type or C structure tag.  For example:

struct first_s { int i,j,k; } fs;
struct second_s { short i0,i1,j0,j1,k0,k1;} ss;
typedef struct first_s *first_p;
typedef struct second_s *second_p;
first_p fp;
second_p sp;

With the type information above, it is possible to ’cast’ a pointer to struct first_s to a pointer to struct second_s by:

assign fp=first_p(&ss)

or

assign fp=first_p(sp)

The following assignments, however, are illegal:

assign fp=sp
assign fp=&ss

assign variable = expression
Assign the value of the expression to the variable.

dump [procedure] [> filename]
Print the names and values of variables in the given procedure. If no procedure name is specified, print the values of the variables in the current procedure. If the procedure given is “.”, then the all active variables are dumped.

print expression [, expression ...]
Print out the values of the expressions.

whatis name
Print the declaration of the given name, which may be qualified with block names as indicated above.

which identifier
Print the full qualification of the given identifer, i.e., the outer blocks that the identifier is associated with.

up [count]

down [count]
Move the current context, which is used for resolving names, up or down the stack count levels.  The default count is 1.  Suppose our program has two routines that call A and B and both define variable foo.  If we are debugging B, all references to foo will refer to B.foo.  After an up command, B’s context will be ignored, and a reference to foo will refer to A.foo. 

where
Print out a list of the active procedures and functions.

whereis identifier
Print the full qualification of all the symbols whose name matches the given identifier. The order in which the symbols are printed is not meaningful.

Accessing Source Files

edit [filename]

edit procedure/function-name
Invoke an editor on filename. If no file name is specified, the current source file is used.  If a procedure or function name is specified, the editor is invoked for the file that contains it.  The editor that is invoked depends on which editor is specified as the default by the installation.  To override the default editor, set 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 no function name is specified, then print the current function. Changing the current function implicitly changes the current source file to the file that contains the function; it also changes the current scope used for name resolution.

list [source-line-number [, source-line-number]]

list procedure/function
List the lines in the current source file from the first line number to the second line number, inclusive. If a line range is not specified, the next 10 lines in the current file 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 value set by the set $listwindow command (see below). 

use directory-list
When looking for source files, set the list of directories to be searched.

Command Aliases and Variables

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 an alias “rr” for the command “rerun”, one can say

alias rr rerun

To define an alias called “b” that sets a stop at a particular line one can say

alias b(x) “stop at x”

Subsequently, the command “b(12)” will expand to “stop at 12”.

set name [= expression]
The set command defines values for debugger variables.  The names of these variables cannot conflict with names in the program being debugged, and are expanded to the corresponding expression within other commands.  The following variables have a special meaning:

$frame
Setting this variable to an address causes dbx to use the stack frame pointed to by the address for doing stack traces and accessing local variables. 

$hexchars

$hexints

$hexoffsets

$hexstrings
When set, dbx prints out out characters, integers, offsets from registers, or character pointers , respectively, in hexadecimal. 

$listwindow
The value of this variable specifies the number of lines to list around a function or when the list command is given without any parameters.  The default value is 10. 

$mapaddrs
Setting (unsetting) this variable causes dbx to start (stop) mapping addresses. 

unalias name
Remove the alias with the given name.

unset name
Delete the debugger variable associated with name. 

Machine Level Commands

tracei [address] [if cond]

tracei [variable] [at address] [if cond]

stopi [address] [if cond]

stopi [at] [address] [if cond]
Turn on tracing or set a stop using a machine instruction address.

stepi

nexti Single step as in step or next, but do a single instruction rather than source line. 

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

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 “+”, “−”, and indirection (unary “*”). 

Machine registers are denoted by “$dN” and “$aN”, where N is the number of the register.  Machine registers may be displayed with the print command and assigned to with the assign command.  They may not be used as objects in machine level commands. 

Miscellaneous Commands

helpPrint out a synopsis of dbx commands. 

quitExit dbx. 

sh command-line
Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used.

source filename
Read dbx commands from the given filename. 

FILES

a.out object file

.dbxinit initial commands

SEE ALSO

cc(1)
Getting Started with DBX

COMMENTS

dbx suffers from a “multiple include” malady.  If you have a program consisting of a number of object files and each is built from source files that include header files, the symbolic information for the header files is replicated in each object file.  Since about one debugger start-up is done for each link, having the linker (ld(1)) re-organize the symbol information would not save much time, though it would reduce some of the disk space used. 

This problem is an artifact of the unrestricted semantics of #include’s in C.  For example, an include file can contain static declarations that are separate entities for each file in which they are included. 

BUGS

Assigning strings of characters to character pointers overwrites the character pointer (and other data in the vicinity) with the string. 

The use of pseudo-casts in assignments is limited.  Dbx seems to understand many more combinations of the pseudo-casts in print commands that it does in assign commands.  With reference to the example previously given under the heading “Printing Variables and Expressions”, the following commands work:

print $$second_s(fp^)
print &$$second_s(fp^)
print $$second_s(fs)

However, the following command fails:

assign sp=&$$second_s(fs)

If given the command list func, where func is an entrypoint for which debugging information is not available (e.g. an assembly-language routine), dbx will reset the line number to the beginning of the current file. 

If you edit one of the program’s source files while in dbx (i.e., with the edit command), remake it through the editor, return to dbx and rerun the program, dbx aborts with an internal error.  However, if the program is edited through dbx and then remade by invoking a shell from dbx itself (with the sh command), a subsequent rerun does not cause this behavior. 

When tracing, it is very difficult to get dbx to respond to an interrupt, and the program can run away. 

If a function has been invoked in the current call chain which has failed to do a link (e.g., an assembly-language routine), dbx will drop the previous function in the call chain from a stack trace (given by the where command). 

Version 2.4  —  May 08, 1986