dbx.1

来自「<B>Digital的Unix操作系统VAX 4.2源码</B>」· 1 代码 · 共 1,322 行 · 第 1/3 页

.TH dbx 1 RISC
.SH Name
dbx \- source level debugger
.SH Syntax
\fBdbx \fR[\fB\-I \fIdir\fR] [\fB\-c \fIfile\fR] [\fB\-k\fR] [\fB\-i] [\fB\-r] [\fB\-pixie\fR] [\fIobject\fR [\fIcore\fR]]
.SH Description
The 
.PN dbx
command invokes a source-level debugger. Once you invoke 
.PN dbx ,
you issue
.PN dbx
commands that control the debugger. These commands allow you to examine source 
files, control
program execution, display the state of the program, and debug at the
machine level.
.PP
.NXR "dbx command (RISC only)"
.NXR "debugger" "dbx command"
.NXR "debugger" "source-level"
.PP
You can use command options to modify some steps that 
.PN dbx
performs during startup. (For information on the available options, see
Options.) Unless you specify the 
.B \-r
option, 
.PN dbx
prompts you for a command before it begins executing your program. The
.PN dbx
prompt appears as follows:
.EX
(dbx)
.EE
To leave 
.PN dbx
issue the
.B quit 
command.
.SS Arguments
On the command line, the \fIobject\fP argument names the object file
that you want
.PN dbx
to read as input. For complete 
.PN dbx
support, the object file must contain extended symbol table information.
The supported compilers each have a 
.B \-g
option that produces the symbol table information in the object file.
.PP
The extended symbol table contains the name of all
the source files translated by the compiler to create the object file.
This information allows you to look at all the source code that went
into creating an object file during your debugging session. (The
extended symbol table also contains other information.)
.PP
If your object file does not contain the extended symbol table
information, use the commands described in Debugging at the Machine
Level to debug your program.
.PP
If you omit the \fIobject\fP argument, 
.PN dbx
prompts you for the name of an object file. If you press the Return key,
.PN dbx
attempts to read a file named
.PN a.out
from the current directory. If no
.PN a.out
file exists, 
.PN dbx 
exits.
.PP
The \fIcore\fP argument names a core dump file. You can examine the
core dump file to determine the state of the program when it failed. 
.SS Initialization File
During its startup,
.PN dbx
reads and executes the commands in an initialization file, if one is
present. By default,
.PN dbx 
searches for the file
.PN \&.dbxinit
in the current directory. If no
.PN \&.dbxinit
file exists in the current directory,
.PN dbx
searches your home directory for the file. You can use the
initialization file to issue setup commands automatically when
you begin a 
.PN dbx
session.
.PP
.SS Debugger Expressions
You specify
.PN dbx
expressions using the C or Pascal syntax for expressions. The debugger
supports a subset of the expression syntax for both languages; that is,
it supports the syntax that is common between the two languages.
.PP
In some cases, the debugger supports the syntax of either C or Pascal.
For example, you can denote indirection using either an asterisk (*)
as a prefix or a circumflex (^) as a suffix.
You can use the field reference operator (.) with pointers
as well as records or structures, making the C operator (->) unnecessary
(although it is supported). 
.PP
You must enclose array expressions in brackets ([ ]). 
.PP 
You can also specify a register name in an expression.
You denote registers by \fB$r\fIN\fR where \fIN\fR is the number of the register.
.SS Debugger Name Resolution
The debugger resolves names by searching for the name in the
static scope of the current function.  If no name is defined in the
static scope, the debugger searches the dynamic scope. If neither scope
yields a defined name, the debugger chooses an arbitrary symbol and
displays the following message:
.EX
[using\ \fIqualified\.name\fP]
.EE
The debugger substitutes the qualified name of the arbitrary symbol for
\fIqualified.name\fP in the message.
.PP
You can override this name resolution procedure by qualifying 
identifiers with a block name, as in \fImodule\fP.\fIvariable\fP. 
For the C language, the debugger treats a source file as a module named
from the filename without 
.PN .c .
.SH Options
.PP
.TP 15
.B "\-c \fIfile\fR"
Selects a command file other than 
.PN \&.dbxinit .
.TP 15
.B "\-i"
Invokes 
.PN dbx
in interactive mode.  This option causes the debugger to not treat
source lines beginning with number signs (#) as comments.
.TP 15
\fB\-I \fIdir\fR 
Adds \fIdir\fP to the list of directories that
.PN dbx
searches for source files. By default, 
.PN dbx
searches the current directory and the directory where \fIobject\fP is 
located.
You can specify multiple directories by using multiple
.B \-I
options.  
.TP 15
.B \-k
Maps memory addresses. This option is useful for kernel debugging.
.TP 15
.B \-pixie
Reads in output from the
.PN pixie
utility. The
.PN pixie
utility is a code profiler.
.IP
For this option to work, you must have executable 
.PN pixie
output and the 
.PN nonpixie
executable file in the same directory. The 
.PN pixie
output must be named
.I filename.pixie,
where \fIfilename\fP is the name of the executable file.
.TP 15
.B \-r
Executes the object file immediately. If program execution terminates with an error,
.PN dbx
displays the message that describes the error. You can then either invoke
the debugger or let the program continue exiting. The
.PN dbx
debugger reads from
.PN /dev/tty
when you specify the 
.B \-r
option and standard input is not a terminal. If the program executes
successfully,
.PN dbx
prompts you for input.  
.SH dbx Commands
The debugger supplies a number of commands that you can issue at the
dbx prompt. This section describes each command.
.SS The Monitor
The following commands control the 
.PN dbx
monitor:
.TP 15
\fB!\fIstring\fR
.ns
.TP 15
\fB!\fIinteger\fR
.ns
.TP 15
\fB!\fI\-integer\fR
Executes a command from the history list. You can specify the command
name in the \fIstring\fP argument. If you specify an integer, 
.PN dbx
executes the command having that number in the history list. If you specify
\fI-integer\fP, the debugger executes the command that you issued
\fIinteger\fP commands ago. For example, if you specify -3, the
debugger issues the command you issued three commands ago. The debugger
echoes the command on standard output before executing it. 
.TP 15
\fBhelp\fR [\fItopic\fR]
With no argument, displays a list of topics for which help information is available. If
you name a topic, the debugger displays help information on that topic.
.TP 15
.B history
Displays a list of the previous commands you issued. By default, the debugger
displays the previous 20 commands. You can change the number of commands
.PN dbx
keeps in the history list by using the
.B set
command to modify the 
.B $lines 
debugger variable.
.TP 15
\fBquit\fR
Exit 
.PN dbx . 
.ne 4
.SS Controlling dbx
You can use the following commands to control the operation of the
.PN dbx
debugger:
.TP 15
\fBalias \fR[\fIname[(arg1,arg2,...)] "string"\fR]
Lists all existing aliases or defines an alias. If you omit all arguments
to the \fBalias\fP command, 
.PN dbx
displays a list of the existing aliases. 
.IP
You can supply arguments to define a new alias. If you specify
a 
.PN dbx
command for \fIstring\fP, the debugger assigns \fIname\fP as an alias
for that command. For example, to define an alias rr for the command
\fBrerun\fP, issue the following command:
.EX
(dbx) \f(CBalias rr "rerun"\fR
.EE
If you specify parameters in the
.B alias
command, the debugger substitutes the values you supply on the command
line when it executes the command. For example, to define halt as an
alias that sets a stop at a particular line, issue the following
command:
.EX
(dbx) \f(CBalias halt(x) "stop at x"\fR
.EE
Once you issue this command, 
.PN dbx
interprets the following commands the same:
.EX
(dbx) \f(CBhalt(12)\fP
(dbx) \f(CBstop at 12\fP
.EE
Both commands set a breakpoint at source line 12.
.IP
To remove an alias, use the 
.B unalias 
command, as shown:
.EX
(dbx) \f(CBunalias halt\fP
.EE
.TP 15
\fBdelete \fIevent-number, ...\fR 
.ns
.TP 15
\fBdelete all\fR
.ns
.TP 15
\fBdelete *\fR
Deletes the specified breakpoint, trace event, or record 
event from the status list.  The argument 
.B all
and the argument
.B *
delete all events from the status list.
.TP 15
\fBplayback input \fR[\fIfile\fR]
Replays commands that were saved with the \fBrecord input\fR command in a 
text file. If you omit \fIfile\fR, the debugger reads commands from the
temporary file it creates by default when you issue the \fBrecord
input\fR command.
.TP 15
\fBplayback output \fR[\fIfile\fR]
Replays debugger output that was saved with the \fBrecord output\fR 
command. If you omit \fIfile\fR, the debugger displays output stored in
a temporary file it creates by default when you issue the \fBrecord
output\fP command.
.TP 15
\fBrecord input \fR[\fIfile\fR]
Records all commands you enter at the 
.PN dbx
prompt. If you omit \fIfile\fR, the debugger creates a temporary file
that it deletes when you exit from the debugger.
.IP
The debugger associates an event number with each
.B record
command you issue.  You use the event number to turn off recording, as
described with the
.B delete 
command.
.TP 15
\fBrecord output \fR[\fIfile\fR]
Records all 
.PN dbx
output. If you omit \fIfile\fR, the debugger creates a temporary file
that it deletes when you exit from the debugger.
.IP
The debugger associates an event number with each
.B record
command you issue.  You use the event number to turn off recording, as
described with the
.B delete 
command.
.TP 15
\fBsource\fR \fIfile\fR
Executes the 
.PN dbx
commands from the specified file. This command is an alias for the
.B playback input
command.
.TP 15
\fBstatus\fR
Lists current breakpoints, record events, and trace events.
.TP 15
\fBset \fR[\fIvariable\fR \fB= \fIexpression\fR]
Lists existing debugger variables and their values or defines a value
for the named debugger variable. 
.IP
Some debugger variables contain either
a zero or nonzero value that controls
.PN dbx
behavior. For example, when set to a nonzero value, the 
.B $hexstrings 
variable
causes the debugger to display all strings in hexadecimal format. When
set to zero, this variable causes the debugger to display strings in character
format. You can set a variable like 
.B $hexstrings 
to a nonzero value as shown:
.EX
(dbx) \f(CBset $hexstrings = 1\fP
.EE
You can disable the variable using the 
.B unset
command, as shown:
.EX
(dbx) \f(CBunset $hexstrings\fP
.EE
.IP
You can create a debugger variable using
a name of your own.  A debugger variable name you create must not
conflict with the name of any variable in the program you are
debugging, and it must not begin with a dollar sign ($).
For information on existing
debugger variables, see Predefined Debugger
Variables. (Use the
.B assign
command to change the value of variables in your program.)
.TP 15
\fBsetenv \fIname\fR \fB"\fIstring\fR\fB"\fR
Sets the environment variable \fIname\fR to \fIstring\fR by changing
the value of an existing environment variable or creating a new one.
To reset the environment variable, specify a null string. The
following example shows how to reset the EDITOR environment variable:
.EX
(dbx) \f(CBsetenv EDITOR ""\fP
.EE
.TP 15
\fBsh \fR[\fIshell command\fR]\fI
Calls a shell from 
.PN dbx 
or executes the specified shell command. 
.TP 15
\fBtagvalue \fR(\fItagname\fR)
Returns the value of \fItagname\fR, where \fItagname\fP is a tag that
marks a function or
type definition in your program.  If the tag extends to more than
one line or if it contains arguments, the debugger issues an error
message. You can 
use \fBtagvalue\fR in commands where you specify a procedure or function
name. 
.\"ADD BACK IN EXAMPLE WHEN TAGVALUE IS FIXED!!!
.\"For
.\"example, if a tag getline is associated with a function, the following
.\"command is valid:
.\".EX
.\"(dbx) call tagvalue(getline) ()
.\".EE
.\"This command causes execution to begin at the location associated with
.\"the getline tag.
.IP
You create tags using the
.PN ctags
command.  See the
.MS ctags 1
reference page for information. The debugger uses the file named in
the 
.B $tagfile 
variable when resolving references to tags. 
.TP 15
\fBunalias \fIname\fR
Removes the specified alias.
.TP 15
\fBunset \fIvariable\fR
Removes the setting of a specified debugger variable.
.SS Examining Source Code
The following commands allow you to examine your source files during a
debugging session:
.TP 15
.B "/\fIregular expression\fR"
.ns
.TP 15
.B "?\fIregular expression\fR"
Searches forward or backward in the source code for the regular expression.
For information on forming regular expressions, see \fIThe Big Gray
Book: The Next Step with ULTRIX\fP.
.TP 15
\fBedit \fR[\fIfile\fR]
Invokes an editor on \fIfile\fP or the current source file if none is
specified. By default,
.PN dbx
invokes the
.PN vi
editor. You can override the default setting by modifying the
EDITOR environment variable.
.TP 15
\fBfile \fR[\fIfile\fR]
Changes the current file to \fIfile\fP, or, if you omit \fIfile\fP,
displays the name of the current file.
.TP 15
\fBfunc \fR[\fIexpression\fR]