DBX(1) — NEWS-OS Programmer’s Manual

NAME

dbx − source-level debugger

SYNOPSIS

dbx [ −I directory ] [ −c file ] [ −i ] [ −r ] [ −pixie ] [ object [ core ] ]

DESCRIPTION

dbx is a source-level debugger running under NEWS-OS. This enhanced version of dbx works with cc(1), pc(1), f77(1), cobol(1), pl1(1), as(1), and RISC NEWS machine code.

The object file used with the debugger is produced by specifying an appropriate option (usually −g) to the compiler. The resulting object file contains symbol table information, including the names of all source files that the compiler translated to create the object file. These source files are accessible from the debugger. If −g is not specified, limited debugging is possible.

If a core file exists in the current directory or a coredump file is specified, dbx can be used to look at the state of the program when it faulted.

dbx does not support columns greater than 511.

Running dbx

If a .dbxinit file resides in the current directory or in the user’s home directory, the commands in it are executed when dbx is invoked.

When invoked, dbx recognizes these command line options:

−Idirectory or −Idirectory
Tells dbx to look in the specified directory for source files. Multiple directories can be specified by using multiple −I options. dbx searches for source files in the current directory and in the object file’s directory whether or not −I is used.

−c file
Selects a command file other than .dbxinit.

−i Uses interactive mode. This option does not treat #s as comments in a file. It prompts for source even when it reads from a file. With this option, dbx also has extra formatting as if for a terminal.

−r Runs the object file immediately.

−pixie
Uses pixie output. The executable must be executable.pixie, and the non-pixie executable must be in the same directory as the pixie executable.

The dbx monitor offers powerful command line editing. For a full description of these emacs-style editing features, see csh(1).

Multiple commands can be specified on the same command line by separating them with a semicolon (;). If the user types a string and presses the stop character (usually ^z; see stty(1)), dbx tries to complete a symbol name from the program that matches the string.

dbx can also run under emacs as inferior, which means under this mode, dbx is controlled by emacs and communicates with emacs. When in emacs, command M-x run-dbx starts dbx and will prompt you for filename to be debugged.

The Monitor

These commands control the dbx monitor:

![string] [integer] [−integer]
Specifies a command from the history list.

help
Prints a list of dbx commands, using the NEWS-OS system more command to display the list.

history
Prints the items from the history list. The default is 20.

quit[!]
Exit dbx after verification. If ! is specified, verification isn’t required.

Controlling dbx

alias [name(arg1,...argN)"string"]
Lists all existing aliases, or, if an argument is specified, defines a new alias.

unalias alias command_name
Removes the specified alias.

delete expression1, ...expressionN

delete all
Deletes the specified item from the status list. The argument all deletes all items from the status list.

playback input [file]
Replays commands that were saved with the record input command in a text file.

playback output [file]
Replays debugger output that was saved with the record output command.

record input [file]
Records all commands typed to dbx.

record output [file]
Records all dbx output.

sh [shell command]
Calls a shell from dbx or executes a shell command.

status
Lists currently set stop, record, and trace commands.

tagvalue (tagname)
Returns the value of tagname. If the tags extends to more than one line, or if it contains arguments, an error occurs. tagvalue can be used in any expression.

set [variable = expression]
Lists existing debugger variables and their values. This command can also be used to assign a new value to an existing variable or to define a new variable.

unset variable
Removes the setting of a specified debugger variable.

Examining Source

/regular expression
Searches ahead in the source code for the regular expression.

?regular expression
Searches back in the source code for the regular expression.

edit [file]
Calls an editor from dbx.

file [file]
Prints the current file name, or, if a file name is specified, this command changes the current file to the specified file.

func [expression] [procedure]
Moves to the specified procedure (activation level), or, if an expression or procedure isn’t specified, prints the current activation level.

list [expression:integer]

list [expression]
Lists the specified lines. The default is 10 lines.

tag tagname
Sets the current file/line to the location specified by tagname. Operations are similar to the tag operations in vi(1).

use [directory1 ... directoryN]
Lists source directories, or, if a directory name is specified, this command substitutes the new directories for the previous list.

whatis variable
Prints the type declaration for the specified name.

which variable
Finds the variable name currently being used.

whereis variable
Prints all qualifications (the scopes) of the specified variable name.

Controlling Programs

assign expression1 = expression2
Assigns the specified expression to a specified program variable.

[n] cont [signal]

cont [signal] to line

cont [signal] in procedure
Continues executing a program after a breakpoint. n breakpoints are ignored if n is specified before stepping; If specified, signal is delivered to the processing being debugged.

goto line
Goes to the specified line in the source.

next [integer]
Steps over the specified number of lines. The default is one. This command does not step into procedures.

rerun [arg1 ... argN] [<file1] [>file2]

rerun [arg1 ... argN] [<file1] [>&file2]
Reruns the program, using the same arguments that were specified to the run command. If new arguments are specified, rerun uses those arguments.

run [arg1 ... argN] [<file1] [>file2]

run [arg1 ... argN] [<file1] [>&file2]
Runs the program with the specified arguments.

return [procedure]
Continues executing until the procedure returns. If a procedure isn’t specified, dbx assumes the next procedure.

step [integer]
Steps the specified number of lines. This command steps into procedures. The default is one line.

Setting Breakpoints

catch [signal]
Lists all signals that dbx catches, or, if an argument is specified, adds a new signal to the catch list.

ignore [signal]
Lists all signals that dbx does not catch. If a signal is specified, this command adds the signal to the ignore list.

stop [variable]

stop [variable] at line [if expression]

stop [variable] in procedure [if expression]

stop [variable] if expression
Sets a breakpoint at the specified point.

trace variable [at line] [if expression]

trace variable [in procedure] [if expression]
Traces the specified variable.

when [variable] [at line] {command_list}

when [variable] [in procedure] {command_list}
Executes the specified dbx comma separated command list.

Examining Program State

dump [procedure] [.]
Prints variable information about the procedure. If a dot (.) is specified, this command prints global variable information on all procedures in the stack and the variables of those procedures.

down [expression]
Moves down the specified number of activation levels in the stack. The default is one level.

up [expression]
Moves up the specified number of activation levels on the stack. The default is one.

print expression1,...expressionN
Prints the value of the specified expression. If expression is a dbx keyword, it must be enclosed within parentheses. For example, to print out a variable called output (which is also a variable in the playback and record commands) you must type:

print (output)

printf "string", expression1,...expressionN
Prints the value of the specified expression, using C language string formatting. As in the print command, if expression is a dbx keyword, you must enclose it within parentheses.

printregs
Prints all register values.

where
Does a stack trace, which shows the current activation levels.

where n
Prints out only the top n levels of the stack.

Debugging at the Machine Level

[n] conti [signal]

conti [signal] to address

conti [signal] in procedure
Continues executing assembly code after a breakpoint. n breakpoints are ignored if n is specified before stepping; If specified, signal is delivered to the processing being debugged.

nexti [integer]
Steps over the specified number of machine instructions. The default is one. This command does not step into procedures.

stepi [integer]
Steps the specified number of machine instructions. This command steps into procedures. The default is one instruction.

stopi [variable] at address [if expression]

stopi [variable] in procedure [if expression]

stopi [variable] if expression
Sets a breakpoint in the machine code at the specified point.

tracei variable at address[at address if expression]

tracei variable in procedure [at address if expression]
Traces the specified variable in machine instructions.

wheni [variable] [at address] {command_list}

wheni [variable] [in procedure] {command_list}
Executes the specified dbx comma separated command list.

address[?]/<count><mode>
Searching forward (or backward, if ? is specified,) prints the contents address or disassembles the code for the instruction address; count is the number of items to be printed at the specified address. mode is one of the characters in the following table producing the indicated result:

dPrint a short word in decimal
DPrint a long word in decimal
oPrint a short word in octal
OPrint a long word in octal
xPrint a short word in hexadecimal
XPrint a long word in hexadecimal
bPrint a byte in octal
cPrint a byte as a character
sPrint a string of characters that ends in a null
fPrint a single precision real number
gPrint a double precision real number
iPrint machine instructions
nPrints data in typed format.

address/<count><value><mask>
Searches for a 32-bit word starting at the specified address; count specifies the number of word to process in the search; an address is printed when the the word at address, after an AND operation with mask, is equal to value.

Predefined dbx Variables

The debugger has these predefined variables:

$addrfmt Specifies the format for addresses. This can be set any specification that a C printf statement can format. The default is zero.

$byteaccess Same as $addrfmt.

$casesense When set to a nonzero value, specifies that uppercase and lowercase letters be taken into consideration during a search. When set to 0, the case is ignored. The default is 0.

$curevent Shows the last even number as seen in the status feature. Set only by dbx.

$curline Specifies the current line. Set only by dbx.

$cursrcline Shows the last line listed plus 1. Set only by dbx.

$curpc Specifies the current address. Used with the wi and li aliases.

$datacache Caches information from the data space so that dbx must access data space only once. To debug the operating system, set this variable to 0; otherwise, set it to a nonzero value. The default is 1.

$debugflag

$defin

$defout For internal use by dbx.

$dispix For use when debugging pixie code. When set to 0, machine code is show while debugging. When set to 1, pixie code is shown. The default is 0.

$hexchars Output characters are printed in hexadecimal format (set, unset).

$hexin Specifies that input constants are hexadecimal.

$hexints When set to a nonzero value, changes the default output constants to hexadecimal. Overrides $octints.

$hexstrings When set to 1, specifies that all strings are printed in hexadecimal; when set to 0, strings are printed in character format.

$historyevent Shows the current history line.

$lines number of lines for history. The default is 20

$listwindow Specifies how many lines the list command prints.

$main Specifies the name of the procedure that dbx will start with. This can be set to any procedure. The default is main.

$maxstrlen Specifies how many characters of a string that dbx prints for pointers to strings. The default is 128.

$octin When set to non-zero, changes the default input constants to octal. When set, hexint overrides this setting.

$octints Output integers are printed octal format (set, unset).

$page Specifies whether to page long information. A nonzero value turns on paging; a 0 turns it off. The default is 1.

$pagewindow Specifies how many lines print when information runs longer than one screen. This can be changed to match the number of lines on any terminal. If set to 0, this variable assumes one line. The default is 22, leaving space for continuation query).

$pdbxport port name from /etc/remote[.pdbx] used to connect to target machine for pdbx.

$printwhilestep
For use with the step[n] and stepi[n] instructions. A non-zero integer specifies that all n lines and/or instructions should be printed out. A zero specifies that only the last line and/or instruction should be printed out. The default is zero.

$pimode Prints input when used with the playback input command. The default is 0.

$printdata When set to a nonzero value, the contents of registers used are printed next to each instruction displayed. The default is 0.

$printwide When se to a nonzero value, the contents of variables are printed in a horizontal format. The default is 0.

$prompt Sets the prompt for dbx.

$readtextfile When set to 1, dbx tries to read instructions from the object file rather than the process. dbx executes faster when debugging remotely using the System Programmer’s Package. This variable should always be set to 0 when the process being debugged copies in code during the debugging process. The default is 1.

$regstyle A zero value causes registers to be printed out in their normal r format (r0, r1, ... r31). A nonzero value causes the registers to be printed out in a special format (zero, at, v0, v1,...) commonly used in debugging programs written in assembly language. The default is 0.

$repeatmode When set to a nonzero value, after pressing the RETURN key (for an empty line), the last command is repeated. The default is 1.

$rimode When set to a nonzero value, input will is recorded while recording output. The default is 0.

$sigtramp Tells dbx the name of the code called by the system to invoke user signal handlers. This variable is set to sigtramp systems running under NEWS-OS.

$tagfile Contains a filename, indicating the file in which the tag command and the tabvalue macro are to search for tags.

Predefined dbx Aliases

The debugger has these predefined aliases:

? Prints a list of all dbx commands.

a Assigns a value to a program variable.

b Sets a breakpoint at a specified line.

bp Stops in a specified procedure.

c Continues program execution after a breakpoint.

d Deletes the specified item from the status list.

e Looks at the specified file.

f Moves to the specified activation level on the stack.

g Goes to the specified line and begins executing the program there.

h Lists all items currently on the history list.

j Shows what items are on the status list.

l Lists the next 10 lines of source code.

li Lists the next 10 machine instructions.

n or S
Step over the specified number of lines without stepping into procedure calls.

ni or Si
Step over the specified number of assembly code instructions without stepping into procedure calls.

p Prints the value of the specified expression or variable.

pd Prints the value of the specified expression or variable in decimal.

pi Replays dbx commands that were saved with the record input command.

po Prints the value of the specified expression or variable in octal.

pr Prints values for all registers.

px Prints the value for the specified variable or expression in hexadecimal.

q Ends the debugging session.

r Runs the program again with the same arguments that were specified with the run command.

ri Records in a file every command typed.

ro Records all debugger output in the specified file.

s Steps the next number of specified lines.

si Steps the next number of specified lines of assembly code instructions.

t Does a stack trace.

u Lists the previous 10 lines.

w Lists the 5 lines preceding and following the current line.

W Lists the 10 lines preceding and following the current line.

wi Lists the 5 machine instructions preceding and following the machine instruction.

Museum