dbg(1) CLIX dbg(1)
NAME
dbg - Runs the DBG symbolic debugger
SYNOPSIS
dbg [flag ... ] objfil
FLAGS
-c corfil
Sets process to the state defined in corfil, which is a core file.
Open file information, shared memory, and semaphores are not
recorded.
-e Makes evaluate the default dbg command.
-h histfil
Uses histfil as the history file for this debug session. The
default is $HOME/.dbg_history.
-i [initfil]
Uses initfil as the dbg initialization file rather than the default
$HOME/.dbg_init. The dbg command looks for initfil first in the
current directory, then in the home directory. If the -i flag is
used with no specified initfil, then no initialization file is
executed. If no initialization filename is given, another
command-line flag or two hyphens (--) must appear before any object
filename.
-p path[:path ... ]
Defines the search path for source files.
-P prompt
Defines the prompt for dbg.
-s Uses the shared library object file symbol tables if the executable
module is linked with them.
DESCRIPTION
The dbg command runs the DBG symbolic debugger, an Intergraph-developed
debugger which supports high-level language debugging for executable
modules derived from C, C++ and FORTRAN source code. Executable modules
derived from other languages may be examined and manipulated, but in a
symbolic or absolute disassembly mode only. The dbg command features
include built-in language expression parsing and evaluation for C and
FORTRAN, a multiple window display mode, conditional breakpoints, kernel-
assisted watchpoints, command-line recall, core-file debugging, user-
defined macros, and online help.
2/94 - Intergraph Corporation 1
dbg(1) CLIX dbg(1)
The specified objfil is assumed to be an executable program file. If
source-line debugging is to be performed, compile one or more routines in
objfil with the -g (debug) compiler flag.
When invoked, dbg examines the symbol table of objfil and attempts to
create a process from the executable module. Assuming the process
creation is successful, dbg then opens the address space of the process
through the proc file system. If the -c (core file debugging) flag is
specified, dbg sets the process state according to the contents of corfil.
The dbg command looks for a .dbg_init file in the current working
directory, or in the home directory if one is not found. The -i flag
allows the specification of a different (or no) initialization file. This
file is assumed to contain a series of dbg commands. These commands are
read and executed invisibly. This file may be used to establish a
preferred initial dbg environment. At this point, dbg is ready to accept
commands.
Command interpretation in dbg is table-driven and supports abbreviation of
command names and qualifiers. Qualifiers are always introduced by the
slash (/) character. Argument interpretation is handled primarily by the
language expression parsers and a common expression evaluator.
Variables and expressions used during a debugging session are interpreted
according to the current high-level source language. The current source
language setting is controlled through the language command. Syntax
errors similar to those displayed by the respective language compilers are
generated for improper variable references and expressions.
High-level language expressions are the primary vehicles for formulating
requests and initiating action in dbg. Expressions are used to perform
common operations such as examining variables, depositing data in
variables, and controlling the flow of debugger commands. The evaluate
command is provided for parsing and evaluating language expressions. The
evaluate command may also be used for setting variable values.
In addition to evaluating source language expressions, the declare command
can create instances of local debugger variables. These variables, like
expressions, are interpreted in the context of the current high-level
source language. Once defined, debugger variables may be used in
expressions just as if they were variables contained within the process
with one exception: local debugger variables cannot reference addresses in
the address space of the process, nor can process variables reference
addresses of debugger variables. A fixed precedence order resolves name
conflicts between process variables and local variables. Mechanisms for
overriding precedence are provided. Local debug variable definitions may
be removed with the undeclare command.
The dbg command supports iteration and flow control commands in the form
of built-in while and if statements. These commands rely on the
expression parsing and evaluation for the condition portion of the
2 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
command. The action portion of the command can be a combination of
debugger commands and expressions.
All command-line flags must precede the name of the process file to be
debugged. Arguments to the debug process must be positioned after the
process filename.
Commands
The following conventions are used in describing commands:
1. Commands may be abbreviated as long as the resulting abbreviation is
still unique.
2. The cmd-list may be a single command or several commands enclosed in
braces {} and separated by semicolons.
3. The breakpoint bp is one of the following:
⊕ @line-number
⊕ address
⊕ [::]["filename"]function_name
The following list of commands is in alphabetical order. Some commands
have qualifiers, which are denoted with a slash (/).
alias [id[[(parameters)] "string"]]
Defines aliases for commands and key sequences. By using the alias
command, the user can reduce typing errors by equating a key, key
sequence, or a few letters with a complex command string. An
example of each form of the alias command appears in the EXAMPLES
section of this manual page.
The user defines an alias by selecting an id which will be
equivalent to a command string. When the defined id is entered as
a dbg command, the string is substituted.
To define an alias, use the following command format:
alias id "string"
An id is a sequence of letters, digits, underscores (_), and dollar
signs ($). The id may not begin with a digit. The string assigned
to the id must be enclosed in a pair of double quotes ("").
Control characters may be contained in the string by using a caret
(^) to represent <Ctrl>.
An alias may also be defined to have parameters associated with a
string. The format of the command is as follows:
2/94 - Intergraph Corporation 3
dbg(1) CLIX dbg(1)
alias id(p1, ... , pn) "string"
The parameters p1, ... , pn can be any parameters (using the same
format as the id) separated by commas, and the associated string
must be enclosed in a pair of double quotes. The string may also
contain the input parameters in any order and the parameters may be
repeated. When the defined id is entered as a dbg command, the
arguments to be substituted for the parameters must be separated by
commas. An argument may contain embedded commas if they are
included in the string or are delimited by parentheses ().
A list of currently available aliases can be displayed by entering
alias at the dbg prompt.
alias/delete id
Deletes an alias.
When the user specifies the id, the id and its associated string
are removed from the alias list. Alias definitions need not be
deleted to be redefined to a new string. A new definition replaces
the previous one.
alias/key[/delete/query] key_id "string"
Defines a key or series of keys to have associated strings. All of
the keys on the keypad and some of the membrane keys may be bound
to strings. When the bound key sequence is pressed, the string is
automatically substituted. Keys bound to strings may be inserted
anywhere in a dbg command or may constitute an entire command.
Key sequences are defined in two ways: direct entry and query
response. With direct entry, the following command is used:
alias/key key_name ... key_name "string"
The user must enter the name of the key(s) comprising the key
sequence and enclose the associated string in double quotes. (A
list of valid key names may be found in the dbg help file
describing the alias/key command.) For example, the user defines
membrane key <A1> to be bound to the string step/line/def\n. When
<A1> is pressed, this command executes. (The final \n will execute
the string. Without the \n, the command must be completed in order
to execute.)
With the query entry method, the following command is used:
alias/key/query
When the user enters this command, dbg issues a prompt of
/alias/key/QUERY:. The user presses the desired key or keys and
enters the associated string in double quotes. As the keys are
pressed, dbg displays the key names on the screen, so the user does
4 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
not enter the key names.
To display the keys bound to strings, enter the following command
and a list of keys and key sequences with associated strings is
displayed.
alias/key
To delete a key binding, the user may enter the key names or be
prompted to press the keys. The following command deletes the key
binding. Note that the key name must be typed.
alias/key/delete key_name ... key_name
To delete keys using the query method, enter the following command:
alias/key/delete/query
The dbg command displays the /alias/key/delete/QUERY: prompt.
Press the key(s) and the specified key binding is deleted.
break[/delete[/all]|/quiet|/return|/query] [bp[,bp ... ]]
Displays the breakpoints. If a breakpoint or list of breakpoints
is given, the particular breakpoint(s) information displays.
The following qualifiers may be used with the break command.
Unless otherwise specified, a breakpoint or list of breakpoints may
be specified with the qualifiers.
/delete[/all] Deletes the specified breakpoints and confirms
before deletion. If the /all qualifier is also
used, all known breakpoints are deleted without
confirmation.
/quiet Does not display stop information for the specified
breakpoint.
/return Establishes a breakpoint at the last instruction of
the function identified by bp. The return value of
the function displays when the break occurs.
/query Sets breakpoints, but if there is more than one
possibility for a symbol, displays a list from
which to choose.
break bp[,bp ... ] [cmd-list]
Sets breakpoints and executes the specified list of commands. (See
the EXAMPLES section for more information on specifying
breakpoints.)
break/count bp[,bp ... ] [cmd-list]
2/94 - Intergraph Corporation 5
dbg(1) CLIX dbg(1)
Breaks on countth occurrence and executes the specified list of
commands.
dbg/editor
Displays the current dbg editing style, either vi or emacs
emulation. The dbg editor may be set with one of these qualifiers:
/emacs Sets the dbg editing style to emacs.
/vi Sets the dbg editing style to vi.
dbg/query[/on|/off]
Displays the current state of the function name search mode which
is used by the break, go, scope, timer, and trace commands. This
command has two qualifiers:
/on Forces dbg to display a list of all matching function names,
even when only one of them is valid in the current scope, and
allow the user to select any number of them.
/off Makes the dbg command select the function name based on
current scope.
dbg/version
Displays dbg's version number and compilation date.
declare [declaration[,declaration ... ]]
Displays local variable declarations. If a declaration or list of
declarations is given, this command declares the specified local
debug variables. A declaration may be any valid C or FORTRAN
declaration statement. The source language used to parse a
declaration is established by the language command.
display[/curses|/line]
Shows the current dbg display mode. The user may change the
display mode by using these two qualifiers:
/curses Enters curses display mode. In this mode, the display
screen is divided into a source line display window, a
shared debugger and process output display window, and a
command entry window. The source display window contents
are automatically updated to reflect the current scope
setting. The output display window is a log of all output
generated by the debugger and the process being debugged.
See the command-line recall and editing features listed in
the table under Miscellaneous Features. This command has
the following qualifier:
/assembly Creates a disassembly display window in
addition to the standard source, output, and
command windows. The contents of this window
6 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
are updated based on the current program
counter (PC).
/line Enters line display mode. In this mode, each line of code
(either source code or assembly code) is displayed on the
screen before it executes. Output from the dbg command
and the debugged process are mixed with the source code
line shown on the screen.
down [count]
Moves the current function, which is used for resolving names, down
the stack one frame. If a number is specified with this command,
the current function is moved down the stack by count frames.
dump [function_name]
Displays the contents and addresses of local variables for the
current function or for the latest occurrence of the specified
function on the stack.
evaluate
Displays the succeeding data item using the type and format of the
preceding evaluate command. The starting address is incremented
according to the data type.
evaluate expression[,expression ... ]
Evaluates expression. The expression may be any valid C or FORTRAN
expression.
evaluate var=value
Loads variables with a new value.
evaluate[/type:[count]|/format|/special][expression]
Evaluates the specified expression in the manner specified by the
/type, /format, or /special qualifier. The /type, /format, and
/special qualifiers may be combined to control the action of
evaluate.
The evaluate/type:[count]expression command evaluates the contents
of the address yielded from the expression as count items of type
type.
The type applies only to expression results that possess addresses
(lvalues). Valid type values are character, double, float,
instruction, integer, long, and short. The following rules apply
to the default type used for the display when addresses are
specified as integer constants:
/instruction:1 if the address is a text address
/char:1 if the address is not on an even-byte boundary
2/94 - Intergraph Corporation 7
dbg(1) CLIX dbg(1)
/short:1 if the address is not aligned on a four-byte
boundary
/int:1 otherwise
The value of count may be any natural number.
The expression may be an integer constant, function name, or an
expression yielding an lvalue.
The evaluate/format expression command evaluates the expression and
displays as format.
The format controls the display of expression evaluation results.
Valid values for format are decimal, hexadecimal, octal, unsigned,
and x (same as hexadecimal). The default format is decimal.
The evaluate/special expression command evaluates the expression
using the special method.
The following special options modify the behavior of evaluate as
indicated:
address Examines the address, not the contents, of the given
symbol.
debug Searches only variables local to the debugger.
environ Changes the search algorithm to check environment
variables first.
follow Modifies the display algorithm to follow pointers to
structures and unions.
global Changes the search algorithm to check global variables
first.
quiet Suppresses output generated by the evaluated command.
register Changes the search algorithm to check register names
first. If no expression is given, all registers are
displayed.
static Changes the search algorithm to check static variables
first.
string Displays ASCII characters until the first null byte is
encountered.
symbolic Displays the closest symbol plus offset (if any) for
text and data values.
8 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
type Displays the type of the variable or expression. (The
expression is not evaluated.)
value Echoes back integer constants. (This option is useful
to display a constant using a different format.)
The default search order for looking up symbol names in expressions
is as follows: process local variables, process static variables,
process global variables, debugger variables, environment
variables, and process registers. The following table provides
information on accessing registers:
r0-r15 General 32-bit registers.
f0-f7 64-bit floating-point registers.
psw Process status word.
ssw System status word.
pc Program counter.
find [/forward|/backward|/regular] [pattern]
Repeats last search forward. If a pattern is specified, searches
for the pattern in the currently scoped source file. The pattern
is a sequence of characters delimited by any character not in the
sequence. Any displayable character may be used as a delimiter
except for a semicolon (;), as long as the character is not
contained in pattern. The search begins at the current line.
These qualifiers may be used with the find command:
/forward [pattern]
Searches forward for pattern. If pattern is left off, this
command repeats the last search.
/backward [pattern]
Searches backward for pattern. If pattern is left off, this
command repeats the last search.
/regular pattern
Interprets pattern as a regular expression. The regular
expression follows the conventions used by the ed command.
]]
go[/jump|/pass[/signal]|/delete/[/all]|/return[function]|/query] [bp[,bp ...
Resumes executing the process after dbg received control due to a
break, watch, generated signal, or user intervention. If any
breakpoints are given, this command sets temporary breakpoints and
continues processing. The following qualifiers are available:
2/94 - Intergraph Corporation 9
dbg(1) CLIX dbg(1)
/jump bp
Sets the program counter to the address associated with the
specified breakpoint. Caution: use this qualifier with
extreme caution. The go/jump command resets the current PC
to the specified address. The dbg command makes no effort
to restore registers, stack frames, or variable contents.
Jumping to an address outside the current function is likely
to be disastrous.
The same register may be used to hold several different
variables over the course of a function. Therefore, a jump
backwards may yield an incorrect value for a variable even
though an examination of the source would not disclose its
modification.
/pass [bp[,bp ... ]]
Continues processing, passing any pending signals to the
process. If any breakpoints are given, sets the temporary
breakpoints as well as passing signals and continuing the
processing.
/pass/signal signal[,signal ... ]
Generates and passes the specified signals, and continues
processing.
/delete bp[,bp ... ]
Deletes specified breakpoints and continues.
/delete/all
Deletes all breakpoints and continues.
/return [function]
Continues processing, stopping at the end of the current
function and displaying its return value. If a function is
specified, stops at the end of function and displays its
return value.
/query bp[,bp ... ]
Sets temporary breakpoints and continues processing. If
there is more than one possibility for a symbol, it displays
a list from which to choose.
help[/verbose] [dbg_cmd[/dbg_qualifier ... ]
Accesses the dbg online help facility. The /verbose qualifier
alters the help mode so that all of the information available for
the specified command, including each valid qualifier, displays.
history [start-num [end-num]]
Displays the dbg command history. The start-num and end-num
arguments specify the first and last commands to display. If end-
num is not specified, then dbg will display command start-num up to
10 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
the last command in the history. If no range is specified, the
last 16 commands are displayed. Commands are numbered from 1 to
the maximum number defined by the DBGHISTSIZ environment variable,
with command 1 being the oldest.
if (condition) cmd-list1 [else cmd-list2]
If condition is true, executes cmd-list1. Otherwise, executes
cmd-list2.
The if statement is most useful when used as part of a command list
on statements such as break, watch, and step.
language[/c|/cplusplus|/fortran]
Displays the language setting. The language setting controls
interpretation of language expressions and declarations. This
command has three qualifiers:
/c Sets the default language to C.
/cplusplus Sets the default language to C++.
/fortran Sets the default language to FORTRAN.
playback filename
Plays back the dbg session recorded in the file filename.
process
Displays information on all currently active dbg processes.
process/attach exefil|pid
Attaches to the existing process, which is either exefil or has the
process ID specified by pid.
process/create exefil [args]
Creates a new process under the control of dbg. The -p flag is
available to alter the source path; the -c flag may be used to
specify a core file. (See the FLAGS section for more information.)
process/detach [exefil|pid]
Detaches the current process or the specified process from dbg. If
no process is supplied, the current process is detached. The dbg
program will ask whether to kill the process or leave it running.
process/kill [exefil|pid]
Kills all processes using the confirmation mode. If either the
process exefil or the process ID pid is given, that specific
process is killed.
The kill qualifier has these two qualifiers:
/active Kills the currently active process using confirmation
2/94 - Intergraph Corporation 11
dbg(1) CLIX dbg(1)
mode.
/all Kills all processes.
quit Quits the dbg session and exits.
quit/normal
Quits the dbg session and exits, setting the keypad to normal mode.
The /normal qualifier is the default.
quit/application
Quits the dbg session and exits, setting the keypad to application
mode.
quit/default
Displays the current quit default settings. If given qualifiers,
set them as defaults. These four qualifiers may be given.
/normal Sets the keypad to normal mode when exiting from the
dbg session.
/application Sets the keypad to application mode when exiting from
the dbg session.
/eof Allows the use of <Ctrl-D> to quit dbg if it is the
first character of the command line.
/ignoreeof Prevents the use of <Ctrl-D> to quit dbg.
record[/append|/off] [filename]
Displays the name of the current record file. If a filename is
specified, the current dbg session is recorded in that file.
These qualifiers are available for the record command:
/append filename
Appends the current dbg session to filename.
/off Stops recording the current dbg session.
redirect[/append|/in|/off] filename
Redirects the output of dbg to filename. The qualifiers are
available for the redirect command:
/append filename
Appends the output of dbg to filename.
/in filename
Redirects the input of dbg from filename.
/off Redirects the output of dbg back to stdout.
12 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
run [args]
Starts or restarts the process. Any previously defined arguments
are recalled unless a list of arguments is supplied. Redirection
of input from and output to special and ordinary files is
supported.
These qualifiers are available for the run command:
/clear [args]
Starts or restarts the process, clearing any arguments
previously passed. If an argument list args is specified,
these arguments are passed to the process.
/recall [args]
Starts or restarts the process, recalling any previously
defined arguments. If an argument list args is specified,
these arguments are appended to any previously defined
arguments.
/new process-file [args]
Starts the process whose .text and .data reside in process-
file. If an argument list args is specified, the argument
list is passed to the process.
scope [/query]["filename"|["filename"]function]
Displays the current scope setting. The current scope defines
source lines available for viewing with the type command and for
searching with the find command. When control is returned to dbg
due to a breakpoint or watchpoint, the scope is set to the function
containing the current program counter (PC).
If a filename is supplied, the scope is set to the specified file.
If a function name is given, the scope is set to the specified
function. The scope command has one qualifier which may be used in
designating a function.
/query function Sets scope to the specified function, but if
there is more than one possibility for the
function, displays a list from which to choose.
scope/pc
Sets the scope to the file, function, and line containing the
current PC.
signal Displays all signal settings. This command allows individual
signals affecting the process to be ignored by the process and/or
by dbg, set so that they return control to dbg (the default), or
set so that they are passed to the process without causing dbg to
regain control.
Signals can be specified by name or number. A range of signals can
2/94 - Intergraph Corporation 13
dbg(1) CLIX dbg(1)
be specified by separating signal numbers with a colon (:). Names
cannot be used in a range specification.
signal signal[,signal ... ]
Displays settings of the listed signals.
signal/stop
Displays all signals set to stop.
signal/stop signal[,signal ... ]
Specifies signals that, when caught, cause processing to stop and
control to be passed to dbg.
signal/stop/all [signal[,signal ... ]]
Sets all signals, except those listed, to stop processing and pass
control to dbg when caught.
signal/go
Displays all signals set to be ignored by dbg and the process.
signal/go signal[,signal ... ]
Specifies signals to be ignored by both dbg and the process being
debugged.
signal/go/all [signal [, signal] ... ]]
Sets all signals, except those listed, to be ignored by both dbg
and the process being debugged.
signal/go/pass
Displays all signals set to be ignored by dbg but passed to the
process.
signal/go/pass signal[,signal ... ]
Specifies signals to be ignored by dbg but passed to the process.
signal/go/pass/all [signal [, signal] ... ]]
Sets all signals, except those listed, to be ignored by dbg but
passed on to the process being debugged.
source When used with no qualifiers, displays the default source path.
This command expands or restricts the source file directories
searched for high-level language source files.
source ""
Deletes the current source definition. Notice there is no space
between the quotes.
source "pathname[:pathname ... ]"
Sets the source path. More than one path may be specified, as long
as each pathname is separated from the previous pathname with a
colon.
14 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
source/append "pathname[:pathname ... ]"
Appends given pathnames to the source path.
stack [number]
Displays a default number of frames. If number is given, displays
number of frames.
These qualifiers are available for the stack command:
/all Displays all frames.
/default [number]
Shows the default number of frames displayed by the stack
command. If number is given, sets the default number of
frames displayed to number.
step[qualifier] [number]
Steps the default number of instructions or source lines. If
number is given, steps number instructions or source lines.
These qualifiers are available for the step command.
/line Steps to the next source line.
/instruction Steps to the next instruction.
/over Steps over any function call to the next instruction
or source line.
/into Steps into any function call to the next instruction
of source line.
/quiet Does not display source and/or instruction lines
when stepping.
/verbose Displays source and/or instruction lines when
stepping. This option can be used to temporarily
override the /quiet option.
/default Displays the default step command. Specified with
other options, this command will establish those
options as the default. No stepping occurs.
timer[/off|/on|/del|/all|/reset|/query|/between] [function ... ]
Times individual named functions. Each time a specified function
is called the clock is read and saved. When the function returns
the clock is read again, and the time difference is computed and
added to a running total for the function. At any time the user
may request a display of timing results. These times may be
accumulated for the length of a dbg session or may be reset at any
time. On the Clipper the granularity of the result is 1/60 of a
2/94 - Intergraph Corporation 15
dbg(1) CLIX dbg(1)
second, which is not fine enough to time short functions.
The timer presents the time in two ways. Each time dbg halts after
a run or go command, the system and user times for the debugged
process is displayed. Total time as well as the time since the
last halt are shown.
If timer is entered with no options, the timer status (``on'' or
``off'') and previously specified functions (with the accumulated
time and number of calls) are displayed. The options of this
command are as follows:
/on Turns timer on. Times will be shown at each
dbg halt after a go or run command.
[/on] function, ... Adds function name(s) to the list of
functions to be timed. The /on qualifier is
assumed.
/del function, ... Deletes the specified function(s) from the
list of functions to be timed.
/del [/all] Prompts the user to delete each timed
function from the list of functions to be
timed. If the /all qualifier is used, all of
the functions will be removed without query
and timing will be turned off.
/off Turns timer off. All functions are removed
from the timing list. This option is the
same as /delete/all.
/reset Resets all accumulated function times to 0.
/query Adds function name(s) to the list of
functions to be timed, but if there is more
than one possibility for the function,
displays a list from which to choose.
/between Takes two functions and times from the
address represented by the first named
function and the address represented by the
second named function.
trace[/into|/over|/del|/ignore|/off|/on|/query] [function ... ]
Results in a display of a function call showing the function name,
input parameters, and where the function call originated. When the
traced function returns, the function name is again shown as well
as the contents of the machine register r0. These displays are
nested to show call depth.
16 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
The trace command has three basic modes, /into, /over, and /ignore.
All modes specify a list of functions to be traced, but each
employs a different method of tracing. The /into mode uses a
single-stepping method to trace functions, while /over and /ignore
do not. The trace/over mode is the default.
The three modes can interact. For example, if the user specifies
the trace/into mode and a function marked trace/over is called,
this function will not be single-stepped and no function below it
will be traced. Single-stepping will resume when this function
returns. With trace/over, the call to the named function is shown.
If, however, trace/ignore is used, the call is not shown.
The following options can be used with the trace command:
/into[/query] function, ...
Marks each named function with a special breakpoint. When
the function is called the breakpoint is triggered. The
function is stepped one machine instruction at a time. Each
instruction is checked to determine whether it is a call or
a return. The calls are followed and the called function is
also traced. When /query is given, if there is more than
one possible match for a function, a list is displayed from
which to choose.
[/over][/query] function, ...
Marks the function entry and return points with special
breakpoints. When the function is called, the tracing
continues until a return break is encountered. This method
does not single-step and is faster than the trace/into
method. When /query is given, if there is more than one
possible match for a function, a list is displayed from
which to choose.
/del[/all][/over|/ignore|/into]
Deletes any or all of the functions marked with /into,
/over, or /ignore modes. If /all is given, the user is not
prompted and all functions are deleted from the trace list.
The individual trace modes /over, /ignore, or /into may also
be given so that only functions of that type are deleted.
/ignore[/query] function, ...
As with /over, the function's entry and return points are
marked, and the code is not single-stepped. No tracing
information is given for the specified functions. This
qualifier is intended to be used to speed up executions by
ignoring certain functions when others have been specified
with /trace/into.
/off Turns off the trace. Tracing of all entries in the trace
list is ignored but the list is retained.
2/94 - Intergraph Corporation 17
dbg(1) CLIX dbg(1)
/on Turns on the trace mode. Any previously established /into,
/over, or /ignore function tracing will now be active.
trace/malloc
Checks the malloc list of the process to see if it is a circular
list of valid pointers to malloc blocks. This will only work with
the standard malloc found in libc.a, not the various debug versions
or libmalloc. It reports if the malloc list is intact, corrupted,
or not yet initialized.
trace/malloc/ignore
Checks the malloc list as in the trace/malloc/verbose command, but
only reports back if the list is corrupted. This is useful for
setting up a loop which would be stopped only by the list being
corrupted.
trace/malloc/verbose
Checks the malloc list and displays the pointers contained in the
malloc block headers until it finds a corrupt address. Each
address is flagged as IN USE if it has not been deallocated.
type Displays the next source line. This assumes that the current
source line is defined. The current source line is defined and/or
altered by the type, find, scope, and step commands and also as a
result of interruption of process execution. The current source
line will not be defined or altered if the process being debugged
was not compiled with the -g (debug) flag. All forms of the type
command will alter the current source line.
These qualifiers are available for the type command:
/pc Displays the source line representing the current program
counter (PC).
/count Displays the next count source lines.
/-count Displays the previous count source lines. The current
source line is set to current - count.
type . Displays the current source line. The current source line may
differ from the source line representing the current PC due to
prior use of the scope, type, or find command.
type number
Displays the specified source line.
type number:number
Displays a range of source lines. If the first number is omitted,
it defaults to line number 1. The second number defaults to the
last known line within the file. A dot (.) can be used in either
position.
18 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
undeclare [variable[,variable ... ]]
Undeclares local debug variables using the confirmation mode. If
any local debug variables are specified, they are undeclared.
This qualifier is available for the undeclare command:
/all Undeclares all local debug variables without confirmation.
up [count]
Moves the current function, which is used for resolving names, up
the stack one frame. If a number is specified, move the current
function up the stack count frames.
watch Displays the current watchpoint settings.
watch wp[,wp ... ] cmd-list
Sets the specified watchpoints which are triggered when the given
locations are modified (written).
These qualifiers are available for the watch command:
/count wp[,wp ... ] cmd-list
Sets watchpoints to stop on the countth modification of the
memory associated with the respective wp.
/type[:count] wp[,wp ... ] cmd-list
Watches locations as count number of elements of data type
type.
/access
Sets the specified watchpoints, which are triggered when the
given locations are accessed (read or written).
/delete [wp[,wp ... ]]
Deletes watchpoints using the confirmation mode. If any
watchpoints are specified, only those watchpoints are
deleted.
/delete/all
Deletes all watchpoints.
/quiet Does not display stop information about the specified
watchpoints.
while (condition) cmd-list
While condition is true, executes the commands in cmd-list.
window/size
Displays the size(s) of the current window(s).
window/size[/percent] number1,number2[,number3]
2/94 - Intergraph Corporation 19
dbg(1) CLIX dbg(1)
Sets the current window sizes to the given number of lines. The
number arguments correspond to the windows from top to bottom, so
if there is no assembly window present, only two arguments may be
specified. If /percent is specified, then the arguments are
treated as percentages of the total number of lines available.
window/size/default
Resets the current windows to their default sizes.
window/scroll[/source|/assembly|/output][/page] [+][-]number
Scrolls the specified window by number lines, where a negative
corresponds to scrolling backwards. If no window is specified, the
default is the source window. If /page is present, then the number
given is treated as the number of pages to scroll.
window/scroll[/source|/output][/top|/bottom]
Positions the specified window to the top or bottom of its file or
buffer.
window/shift[/page] [+][-]number
Shifts the source window horizontally by number characters, where a
negative corresponds to shifting left. If /page is present, then
the number given is treated as the number of pages (or screens) to
shift by.
window/reset[/scroll|/shift]
Resets the windows to the position they were in before scrolling
began. If /scroll is present, then only the vertical scrolling
position is reset. If /shift is present, then only the horizontal
shift of the source window is reset.
!command
Executes command in the current shell.
!<Return>
Escapes to the current shell.
The current shell is defined through the environment variable
SHELL. The sh command is used if this definition does not exist.
To pass a semicolon or a right brace (}) to the shell so it is not
seen as a dbg command separator, escape it by prefixing it with a
backslash (\).
#comment
Indicates that the text following the number sign (#) on the dbg
command line is to be treated as a comment.
Miscellaneous Features
The command-line recall and editing features of emacs and vi are available
for dbg. The default editing mode is determined by the EDITOR environment
20 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
variable. The dbg/editor command allows users to select one of these
editing modes. This command may be used to change editing modes at any
time.
The following two tables each show the editing commands for each editing
mode and in which dbg windows they may be used. The commands listed for
each editing mode are the only commands which may be used with dbg.
Note: The caret symbol (^) followed by a character means to press and
hold <Ctrl> as the character is pressed. The notation M- followed by a
character means to press and release <Esc> or <Meta> before the character
is pressed.
This first table shows the valid commands for the emacs editing mode and
the dbg windows in which they may be used.
dbg/editor/emacs Sets the dbg editing mode to emacs.
Command line editing
________________________________________________
repeat last command <Return>
recall previous command ^p, up arrow key
recall next command ^n, down arrow key
move back one character ^b, left arrow key
move forward one character ^f, right arrow key
move to beginning of line ^a
move to end of line ^e
search recall buffer ^r
delete current character ^d
delete previous character <Delete>
delete entire line ^u
delete to end of line ^k
Curses Window editing
___________________________________
change windows ^xo, ^w
refresh screen ^l
Source, Assembly and Output windows only
_________________________________________
move up one page M-v
move down one page ^v
move up one line ^p, up arrow key
move down one line ^n, down arrow key
enlarge window ^xz
shrink window ^x^z
2/94 - Intergraph Corporation 21
dbg(1) CLIX dbg(1)
Source and Output windows only
_______________________________________________
move to end of file/buffer M->
move to beginning of file/buffer M-<
Source window only
__________________________________________
shift display left ^e, right arrow key
shift display right ^a, left arrow key
reverse search ^r
forward search ^s
This table shows the valid commands for the vi editing mode and the dbg
windows in which they may be used.
dbg/editor/vi Sets the dbg editing mode to vi.
Command line editing
______________________________________________________
repeat last command <Return>
recall previous command k, up arrow key
recall next command j, down arrow key
move back one character h, left arrow key
move forward one character l, space, right arrow key
move to beginning of line 0, ^
move to end of line $
search recall buffer /
delete current character x
delete previous character X
delete entire line dd
delete to end of line D
The following commands switch to input mode
___________________________________________________
insert text i
add text after the current character a
add text at the end of the line A
delete to end of line C
Curses Window editing
_________________________________________________
change windows ^xo, ^w
refresh screen/goto command window ^l, ^r
Source, Assembly and Output windows only
________________________________________
move up one page ^b
move down one page ^f
move up one line k, up arrow key
22 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
move down one line j, down arrow key
enlarge window ^xz
shrink window ^x^z
2/94 - Intergraph Corporation 23
dbg(1) CLIX dbg(1)
Source and Output windows only
_______________________________________________
move to end of file/buffer g
move to beginning of file/buffer 1g
Source window only
_________________________________________
shift display left $, right arrow key
shift display right 0, left arrow key
reverse search ?
forward search /
Environment Variables
DBGHISTSIZ defines the maximum number of lines written to the dbg history
file. If this variable is not set, 50 is the maximum.
EXAMPLES
These examples show how to start dbg and to use the command-line flags.
1. This example starts dbg to debug a program called the_module.
dbg the_module
2. This example starts dbg and uses a history file named history1_file.
dbg -h history1_file
3. This example starts dbg, defines the prompt to be debug>, and
specifies a.file as the program to be debugged.
dbg -P "debug>" a.file
4. This example starts dbg to debug the a.file program, specifies
evaluate as the default command, uses session2_history as the history
file, and sets the prompt to DEBUG>.
dbg -e -h session2_history -P "DEBUG>" a.file
These examples illustrate the uses of various dbg commands.
1. This example defines the key sequence es to have the value of the
command eval/string. If the user enters es str_name, the contents of
str_name is displayed.
alias es "eval/string"
24 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
2. This example defines the key sequence to have the value of the command
eval/v a /b.
alias x(a, b) "eval/v a / b"
Now, if the user, for example, enters x(4 , 2), the result of 2 is
displayed.
3. Using the example alias es eval/string, this command deletes the es
alias.
alias/delete es
4. With this alias, the user defines membrane key <A2> to have the value
of step/line/def\n. Each time <A2> is pressed, the command executes.
alias/key a2 "step/line/def\n"
5. With this alias, the user defines the keypad numeral 1 to be equal to
the string begin_block.
alias/key kp1 "begin_block"
6. When this command is entered, the user is prompted to press a key or
keys and then enter a string to be associated with the key or keys.
This is like direct entry, only the user does not actually type the
name of the keys.
alias/key/query
7. This example displays the current key bindings.
alias/key
8. This example deletes the key binding of <A1>. If the user presses
this key after this command has executed, nothing happens.
alias/key/delete a1
9. In this example, after this command is entered, the user is prompted
to press a key or a series of keys. When a key or series of keys is
pressed, the associated binding is deleted.
alias/key/delete/query
2/94 - Intergraph Corporation 25
dbg(1) CLIX dbg(1)
10. This example sets a breakpoint at the main() function.
break main
11. This example sets a breakpoint at line 20 of the current file.
break @20
12. This example sets a breakpoint at line 20 of the input.c file.
break @ "input.c" 20
13. This example deletes the breakpoint set at the main() function.
break/delete main
14. This example sets a breakpoint at the printf() function and returns
control to dbg the 10th time printf() is called.
break/10 printf
15. This example displays the return value of get_token() and displays
token each time get_token() returns.
break/return get_token { eval/str token; go}
16. This example breaks on the read_file() function if the variable
file_number equals 5; otherwise, continues execution. The expressions
in the condition and action portions of the if statement are executed
when the break occurs and in the scope of the function where the break
occurs.
break read_file if (file_number != 5) go
17. This example displays the values of variables i, j, and k in
hexadecimal.
evaluate/hex i, j, k
18. This example loads the variable int_1 with a value of 6.
eval int_1=6
26 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
19. This example displays the contents of the 10 double precision values
beginning at the address contained in the variable dbl_ptr.
evaluate/double:10 dbl_ptr
20. This example displays the address of the variable i.
eval/addr i
21. This example allows the user to examine the low-order byte of the
st_dev member of the stat structure.
eval/hex stat.st_dev >> 8 & 0xff
22. This example displays the result of subtracting 1.234 from the
floating-point register f0.
eval/reg f0 - (double)1.234
23. This example searches for the string if (i == in the current file
beginning at the current source line.
find /if (i ==/
24. This example searches backward from the current line in the current
file for the string now is the time.
find/back 'now is the time'
25. This example searches for a string beginning with ab or ad in the
current file.
find/pat a[bd]*
26. This example continues execution if variable i exceeds variable j by
20. Otherwise, sets a breakpoint at the func() function and then
continues execution.
if ( i >= j + 20 ) go
else { break func ; go }
27. This example starts or restarts a.out with stdout and stderr
redirected to /dev/ttx01.
2/94 - Intergraph Corporation 27
dbg(1) CLIX dbg(1)
run a.out >/dev/ttx01 2>&1
28. This example ignores SIGHUP in both dbg and the process.
signal/go sighup
29. In this example, if signal number 10 is received by the process, dbg
is not interrupted and the signal is passed to the process.
signal/go/pass 10
30. This example establishes the default step action to be step by source
line and steps into called functions.
step/def/into/line
31. This example watches the address range associated with variable x_pos
and breaks when a write to this range occurs.
watch x_pos
32. This example watches the eight-byte address range beginning at the
address of i and breaks when a write to this range occurs.
watch/double i
33. This example watches the 20-byte address range beginning at the
address associated with variable a. It breaks if the PC register is
not in the address range associated with main(). This effectively
watches for writes to the array a that occur outside of the main()
function. (In this case, func1 immediately follows main().)
watch/char:20 a if (pc > main && pc < func1) go
34. This example steps until the variable i equals or exceeds 1000.
while ( i < 1000 ) step
35. This example steps from the current PC in the process until a call
instruction is encountered. (0x4500 is the op-code for a call
instruction.) When a call instruction is found, control will be
returned to dbg. This example also illustrates the use of debugger
variables.
28 Intergraph Corporation - 2/94
dbg(1) CLIX dbg(1)
declare short s
eval s = *(short *)pc
while ( (s&0xff00)!=0x4500 ) { step/inst ; eval s = *(short *) pc }
36. This example sets the source and assembly windows to 10 lines each,
and the output window to 4 lines.
window/size 10,10,4
37. This example sets the source and assembly windows to each be 30% of
the total number of screen lines, and sets the output window to 20%.
window/size/percent 30,30,20
38. This example scrolls the assembly window down 10 lines.
window/scroll/assembly 10
39. This example shifts the source window to the left 20 characters.
window/shift -20
40. This example reads and executes commands from file dbgcmds. Input
will revert to the controlling terminal device when the end-of-file
(EOF) is encountered in dbgcmds.
$ dbg a.out <dbgcmds
FILES
$HOME/.dbg_init The default dbg initialization file.
$HOME/.dbg_history The default dbg command history file.
/usr/lib/dbg.hlp The online help file.
EXIT VALUES
This command exits with a value of 0 if successful. If unsuccessful, it
exits with a nonzero value.
RELATED INFORMATION
Commands: acc(1),af77(1), cc(1), f77(1), emacs(1), vi(1), sh(1), syms(1),
CC(1)
2/94 - Intergraph Corporation 29
dbg(1) CLIX dbg(1)
Files: proc(7), core(4)
CLIX Programmer's Guide
30 Intergraph Corporation - 2/94