DBX(1) — USER COMMANDS

NAME

dbx − debugger

SYNOPSIS

dbx [ −r ] [ −i ] [ −I dir ] [ objfile ] [ coredump ]

DESCRIPTION

Dbx is a tool for source level debugging and execution of programs under the UNIX operating system. Objfile is an object file produced by a compiler with the appropriate flag (−g) specified to produce symbol information in the object file. IMPORTANT: every stage of the compile process, including the ld phase, should include the −g option. Currently, cc(1) and f77(1) produce the appropriate source information.

If no objfile is specified, dbx looks for a file named a.out in the current directory. 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 core exists in the current directory or a coredump file is specified, dbx can be used to examine the state of the program when it faulted.

Debugger commands in the file .dbxinit are executed if that file exists either in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current directory.

OPTIONS

−rExecute objfile immediately. Parameters follow the object file name (redirection is recognized). 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 not a terminal.

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

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

Dbx just prompts and waits for a command unless −r is specified.

DBX INTERFACE

The dbx interface for debugging programs consists of several groups of commands:

Execution and Tracing
Runs the program being debugged, traces its execution, and stops at selected places.

Displaying and Naming Data
Displays data and locates variables in the debugged program.

Accessing Source Files
Provides operations (such as editing) on the actual source text of the program.

Machine Level Commands
Provides access to memory locations and machine registers.

Miscellaneous
Miscellaneous commands such as help, and call up a shell.

The most useful basic commands to know about are run to run the program being debugged, where to obtain a stack backtrace with line numbers, print for displaying variables, and stop for setting breakpoints.

Expressions

Dbx Expressions are combinations of variables, constants, procedure calls, and operators. Precede hexadecimal constants by a ‘0x’ and octal constants by a ‘0’. Enclose character constants in single quotes. Expressions cannot involve strings, structures, or arrays, although elements of structures or arrays may be used.

Dbx recognizes these operators:

+ − ∗ / div %
add, subtract, multiply, divide, integer divide and remainder.

<< >>
left shift and right shift.

& ∗
address of operator, and contents of operator.

< > <= >= == !=
less than, greater than, less than or equal, greater than or equal, equal to, and not equal to.

&& ||
logical and, and logical or.

The field reference operator (‘.’) can be used with pointers as well as records, making the C operator ‘−>’ unnecessary (although it is supported).

Precedence and associativity of operators are the same as C. Parentheses can be used to change precedence of operators.

Of course, if the program being debugged is not active and there is no core file, you may only use expressions containing constants — procedure calls require an active child process.

Dbx and Fortran

Note the following when using dbx with Fortran programs:

1.Array elements must be referenced with square brackets ‘[’ and ‘]’ rather than parentheses, that is, print whatsit[3] instead of print whatsit(3).

2.The main routine is referenced as MAIN (as distinguished from ‘main’). All other names in the source file which have upper case letters in them will be lower case in dbx, unless the −U option of f77 is used to compile the program.

3.When referring to the value of a logical type in an expression, use the value 0 or 1 rather than true or false.

Dbx Scope Rules

Dbx has two external variables which it uses to resolve scope conflicts. These are called ‘file’ and ‘func’ — see section 3, Accessing Source Files. The values of ‘file’ and ‘func’ change automatically as files and routines are entered and exited during execution of the user program. ‘File’ and ‘func’ can also be changed by the user. Changing ‘func’ also changes the value of ‘file’; however, changing ‘file’ does not change ‘func’.

‘Func’ is used for name resolution, as in the command: print grab where grab may be defined in two different routines. The search order (for C and Fortran programs at the time of writing) is:

1.Search for ‘grab’ in the routine named by ‘func’,

2.If ‘grab’ doesn’t exist in the routine named by ‘func’, the file containing the routine named by ‘func’ is searched,

3.finally the next outer level — the whole program in the case of C and Fortran — is searched for ‘grab’.

Clearly, if ‘grab’ is local to a different routine than the one named by ‘func’, or is a static variable in a different file than is the routine named by ‘func’, it won’t be found. Note, however, that print a.grab is allowed, as long as routine ‘a’ was entered and not exited yet. Note that the file that routine ‘a’ is in might have to be specified in the expression when the file name (minus suffix) is the same as a routine name. For example, if routine ‘a’ is found in module ‘a.c’, then print a.grab would be not enough — you would have to use print a.a.grab. If you are in doubt as to how to specify a name, use the whereis command, as in whereis grab to display the full qualifications of all instances of the specified name (grab in this case).

‘File’ is used to:

1.resolve conflicts when setting ‘func’ — for example, when a C program has two static routines with the same name,

2.know which file to use for commands which take only a source line number — for example, stop at 55, and:

3.know which file to use for commands such as the ‘edit’ command which has optional arguments or no arguments at all.

When dbx first comes up, the value of ‘file’ is the first source file in the compiler/load list and the value of ‘func’ is the module for this same file (that is, without the suffix ‘.c’ or ‘.f’). This causes name resolution to take place on a global level, that is, names are resolved such that the most global element is found. As soon as execution begins, however, ‘func’ always has a value corresponding to a routine name.

Note that changing ‘func’ doesn’t affect the place where dbx continues execution when the program is restarted.

1. Execution and Tracing Commands

run [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. Otherwise, all characters in args are passed through unchanged. If no arguments are specified, the argument list (if any) typed previously is used. If objfile has been written since the last time the symbolic information was read in, dbx reads in the new information.

cont [at source-line-number] [number]
Continue execution from where it stopped, or, if the clause ‘at source-line-number’ is given, from that line number. The clause number causes execution to continue as if that signal had occurred.

Source-line-number is evaluated relative to the current ’file’ and must be within the current procedure/function or the stack will be incorrect and unexpected behavior will result. Execution cannot be continued if the process has ’finished’, that is, called the standard procedure ’exit’. Dbx does not allow the process to exit, thereby letting the user examine the program state.

trace [in procedure/function] [if condition]

trace source-line-number [if condition]

trace procedure/function [if condition]

trace expression at source-line-number [if condition]

trace variable [in procedure/function] [if condition]
Display tracing information when the program is executed. A number is associated with the command that is used to turn the tracing off (see the delete command).

If no argument is specified, all source lines are displayed before they are executed. Execution is substantially slower during this form of tracing.

The clause ‘in procedure/function’ restricts tracing information to be displayed only while executing inside the given procedure or function. Note that the ‘procedure/function’ traced must be visible in the scope in which the trace command is issued — see the ‘func‘ command.

Condition is a Boolean expression and is evaluated prior to displaying the tracing information; the information is displayed only if condition is true.

The first argument describes what is to be traced. The effects of different kinds of arguments are described in the list below.

Source Line Number
Display the line immediately prior to executing it. 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, for example, "mumble.p":17.

Procedure or Function Name
Every time the procedure or function is called, display information 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’s a function, also display the value the function is returning.

Expression
If the argument is an expression with an at clause, the value of the expression is displayed whenever the identified source line is reached.

Variable
The name and value of the variable is displayed whenever it changes. Execution is substantially slower during this form of tracing.

Tracing is turned off whenever the block in which it was turned on is exited. For instance, if the program is stopped inside some procedure and tracing is invoked, the tracing will end when the procedure is exited. To trace the whole program, tracing must be invoked before issuing the run command.

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.

when in procedure/function { command; ...}

when at source-line-number { command; ...}

when Boolean condition { command; ...}
Execute the given dbx commands when the procedure or function is called, line number is reached, or Boolean condition is true. The braces and semicolon, separating each command, are mandatory.

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

delete command-number
Remove the trace or stop corresponding to the given number. The status command displays the numbers associated with traces and stops.

catch number

ignore number
Start or stop trapping signal number before it is sent to the program. This is useful when a program being debugged handles signals such as interrupts. Initially all signals are trapped except SIGHUP, SIGCONT, SIGCHILD, SIGALRM, SIGKILL, SIGSTP, and SIGWINCH.

stepExecute one source line.

nextExecute up to the next source line. The difference between this and step is that if the line contains a call to a procedure or function step stops at the beginning of that routine, while next does not.

2. Displaying and Naming Data

print expression [, expression ...]
Display the values of the expressions. Variables having the same identifier as one in the current block may be referenced as ‘block-name.variable’, where block-name is a unique identifier for a block. For example, to access variable ‘c’ inside routine ‘a’ which is declared inside module ‘a.c’, you would have to use print a.a.c to make the name ‘a’ unambiguous. Use whereis to find the qualified name of an identifier.

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

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

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

assign variable = expression

set variable = expression
Assign the value of the expression to the variable. Currently no type conversion takes place if operands are of different types.

call procedure(parameters)
Execute the object code associated with the named procedure or function. If the source file that the routine is defined in was compiled with the -g flag, the number and type of parameters must match. However, if C routines are called which are not compiled with the -g flag, dbx will not do parameter checking. The parameters are simply pushed on the stack as given in the parameter list. Currently, string and structure parameters are not passed properly for C and parameters greater than four bytes (for example, complex and double precision variables) and alternate return points are not passed properly for Fortran.

where
Display a list of the active procedures and functions.

dump [> filename]
Show the names and values of all active variables.

3. Accessing Source Files

edit [filename]

edit procedure/function-name
Invoke an editor on filename or the current source file if none is specified. If a procedure or function name is specified, the editor is invoked on the file that contains it. Which editor is invoked by default depends on the installation. The default can be overridden by setting the environment variable EDITOR to the name of the desired editor.

file [filename]
Change the current source file name to filename (apple.c for instance). Display the current source file name if no filename is specified.

func [procedure/function/program name]
Change the current function. Display the current function if none is specified. Changing the current function implicitly changes the current source file variable file to the one that contains the function; it also changes the current scope used for name resolution. If the entire scope of the program is desired, the argument should be the object file name.

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 inclusive. If no lines are specified, the next 10 lines 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 small. If the list command’s argument is a procedure or function, the scope for further listing is changed to that routine — use the file command to change it back.

use directory-list
Set the list of directories to be searched when looking for source files.

4. Machine Level Commands

tracei [address] [if cond]

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

stopi [variable] [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]
Display the contents of memory starting at the first address and continuing up to the second address or until count items are displayed. If no address is specified, the address following the one displayed most recently is used. The mode specifies how memory is to be displayed; if it is omitted the previous mode specified is used. The initial mode is ‘X’. The following modes are supported:

idisplay the machine instruction

ddisplay a short word in decimal

Ddisplay a long word in decimal

odisplay a short word in octal

Odisplay a long word in octal

xdisplay a short word in hexadecimal

Xdisplay a long word in hexadecimal

bdisplay a byte in octal

cdisplay a byte as a character

sdisplay a string of characters terminated by a null byte

fdisplay a single precision real number

gdisplay a double precision real number

Symbolic addresses used in this context are specified by preceding the name with an ‘&’. Registers are denoted by ‘$d0-$d7’ (data registers), ‘$a0-$a7’ (address registers), ‘$fp’ (frame pointer), ‘$sp’ (stack pointer), and ‘$pc’ (program counter). Note that $fp is equivalent to register a6 and $sp is equivalent to register a7. For example, to print the contents of all registers in hex, you would type “&$d0/20X” or “&$d0,&$a7/X”. To print the contents of register d0, you could also type “print $d0” (you can’t currently specify a range with print). Addresses may be expressions made up of other addresses and the operators ‘+’, ‘−’, ‘∗’, and indirection (unary ‘∗’).

5. 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 old-command-name
Respond to new-command-name as though it were old-command-name.

help [cont ] [trace ] [stop ] [when ]
Display a synopsis of dbx commands. If an argument is given, the synopsis is restricted to show variations of only that particular command.

source filename
Read dbx commands from the given filename. Especially useful when the filename has been created by redirecting a status command from an earlier debugging session.

quitExit dbx.

FILES

a.outdefault object file
coredefault core file
~/.dbxinitinitial commands

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) re-organize the symbol information won’t save much time, though it would reduce some of the disk space used. The 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.

Currently the only way to type cast is on the machine level using the mode specifier (e.g. print (char ∗) p is not allowed).

Dbx does not correctly handle expressions involving pointers to objects where the pointer is offset by some integer value (for example, ∗(p-5)).

BUGS

Dbx doesn’t handle Fortran entry points well — it treats them as if they were independent routines.

Dbx doesn’t handle assigning to C bit fields and Fortran complex types correctly (see the assign/set command).

The use command and -I option don’t override the current directory if there is source by the same name in the current directory.

If you link with the -g flag but don’t compile anything with it, dbx core dumps when reading in the object file.

Sun Release 1.1 — Last change: 16 February 1984

Museum

Related Articles