debug(1) debug(1)
NAME
debug - source-level, interactive, object file debugger
SYNOPSIS
debug [opts][[-f none|procs|all][-r][-l start_loc] cmd_line]
debug [opts][-f none|procs|all][-l object_file] live_object ...
debug [opts] -c core_file object_file
opts: [-V][-i c|x][-X opt][-d defaults][-s path][-Yitem,dir]
DESCRIPTION
debug is a tool that facilitates the finding of errors in user
programs by allowing the user to control the execution of a
program and examine its state. The user can create a new
process from an executable program, take over control of an
existing process, or examine the state of a process that
terminated abnormally with a core dump (see core(4)). Live
programs can be executed one source statement or machine
instruction at a time, or can be instructed to run until some
event occurs. Program variables and the processor registers
may be examined or modified, and the user can request a trace
back of active functions, disassembly of a portion of the
program's executable code or a raw dump of any area of the
program's memory.
To take full advantage of the symbolic capabilities of debug,
the programs examined and controlled by debug should be
compiled with the -g option to the compiler [see cc(1)]. If
the controlled program has not been compiled with -g, the
capabilities of debug will be limited, but the program can
still be controlled and examined.
debug provides both a command line interface and an X Windows
based graphical user interface. Only the command line
interface is described here.
Invocation
debug can be invoked in one of three ways. In the first, the
user may specify a cmd_line. cmd_line consists of one or more
executable files, and their associated arguments. The
individual commands can be linked by shell-style pipes, and
the input and output of the cmd_line can be redirected
(characters special to the shell must be quoted). debug
creates a new controlled process for each command specified in
cmd_line, taking care of any necessary redirections of input
and output. The processes are set up to stop at the starting
address specified by start_loc. If no start_loc is supplied,
Copyright 1994 Novell, Inc. Page 1
debug(1) debug(1)
the processes are set up to stop at the symbol main, if
present, otherwise at the starting address specified by the
object file. debug then exec's each command, passing each the
specified arguments.
If no cmd_line is specified, debug simply enters interactive
mode.
In the second form of invocation, the user specifies one or
more existing processes by giving a list of live_objects:
either pathnames (entries in the /proc directory) or process
ids. In either case, the debugger attempts to control the
specified objects as live processes and, if successful,
suspends their execution.
Finally, the user may specify an executable program in one of
the object file formats understood by debug, along with a
core_file. debug interprets the core_file as a record of the
process state at the time of the death of the process
associated with the object_file and lets the user examine the
contents of the process stack, registers and data segments.
debug associates the name of each object (program name) with
all processes derived from the current invocation of that
object. This name may be used in any command that accepts a
process list. If the object name matches the name of an
already existing debugger-controlled program, the debugger
will create a new name for the program. The default program
name may be reset using the rename command (see below).
Options
The following options are recognized:
-c Associate the core image core_file with the specified
object_file.
-d Specify a defaults file containing debugger commands.
If no defaults is given, debug will search for a file
called .debugrc in the user's home directory. If a
default command file exists, debug executes the commands
it contains before it processes any other command line
options or user requests.
-f Specify whether debug will follow all child processes
created by any of the live_objects or by any of the
programs given in the cmd_line, ( procs, or all) or none
of the child processes ( none). See ``Process
Control''.
Copyright 1994 Novell, Inc. Page 2
debug(1) debug(1)
-i The interface mode for the debugger. -i c instructs
debug to use the command line interface. -i x instructs
debug to use the X Window based interface. If no -i
option is given, debug uses the X Window interface, if
the necessary hardware and software is present,
otherwise, it uses the command line interface.
-l For the first form of invocation, specify the location
at which debug will stop the process after it is
created. For the second form of invocation, specify an
alternate object_file from which to load symbolic
information when debugging a live_object. If no
alternate object is specified, debug finds the object
file from which the process image was created. If -l is
used, only one live_object may be specified. See create
and grab under ``Commands''.
-r Redirect input and output of the created objects to a
pseudo-terminal (this does not affect subsequent
redirection by the shell or the processes themselves).
See ``Redirection of Process I/O''.
-s Specify initial value for the global search path,
%global_path. The path is a colon separated list of
directory pathnames. See ``Directory Search Paths''.
-V Print out version information about debug.
-X Specify option to be passed to the X Windows
initialization routine. This option may be specified
multiple times.
-Y Specify a new directory dir for the location of item.
item can consist of any of the following:
a file containing definitions of built-in
aliases for debug
g graphical user interface for debug
Command Language
debug provides a simple, user-extensible command language,
with a syntax similar to sh(1) in style, using keywords and
dash options. Command options may appear in any order.
Multiple options may be specified together, as in symbols -lf
or separately, as in symbols -l -f, but multiple occurrences
of the same option letter are invalid.
Several commands separated by semi-colons (;) may be given on
a single line. A backslash (\) at the end of a line indicates
that the command is continued on the following line. The
output of a command may be redirected to a file or shell
pipeline using the sh syntax of >, >> and |. (For example,
symbols -g | pg). As in the shell, > and >> may appear
Copyright 1994 Novell, Inc. Page 3
debug(1) debug(1)
anywhere within a command, but | must appear at the end of a
debugger command, since the rest of the line is treated as a
shell command that will receive the output of the debugger
command. A sequence of debugger commands may be enclosed in
curly braces ({}), forming a command block. The output of
such a block may be redirected as a whole. A debugger comment
is introduced by a pound sign (#). Any characters following a
pound sign on a line will be ignored.
Many debugger commands have built-in aliases. These are one
or two character names that may be used wherever the full
command is used. The user can redefine any of the built-in
aliases, or may define his or her own aliases. An alias can
consist of any valid debugger command sequence and may take
parameters. See alias under ``Commands'' for more details.
On-line help is available for all debugger commands and on
many other topics, as well. See help for details.
Built-In Variables
debug maintains a set of special variables that describe the
current debugger state and allow the user to customize certain
debugger features. These variables all begin with a percent
sign (%). The processor registers are also considered to be
built-in variables and use the same naming convention. The
current value of a debugger variable may be seen with the
print or symbols commands. Some built-in variables are read-
only. Those that can be modified may be changed using the set
command.
User-Defined Variables
The user may also define variables in the debugger. The names
of these variables consist of a dollar sign followed by a C-
style identifier ($username). A user-defined variable is
defined by assigning it an initial value using the set
command, and may subsequently be modified. All of the user's
environment variables are imported to debugger variables of
the same name when debug is invoked.
User-defined variables are polymorphic, having either string
or numeric values, according to the type of the last value
assigned to them. Any variable, string or numeric, may be
used where a string value is required, and any string-valued
variable which is convertible to an integer via the strtol(3C)
function may be used where a numeric value is required.
Copyright 1994 Novell, Inc. Page 4
debug(1) debug(1)
Command Editing and History
debug supports a subset of the ksh(1) command-line editing
facility [see ksh(1)]. Both vi and emacs modes are available.
The initial mode is determined by examining the values of the
VISUAL and EDITOR environment variables, as in ksh. The
current mode is available in the debugger built-in variable
mode, and may be changed using the set command. The debugger
command history is written to the file specified by the
environment variable DEBUG_HISTORY, if this variable exists
and is non-null. Otherwise, the command history is written to
the file .debug_hist in the user's home directory. The
debugger command history file is preserved across invocations
of debug and is subject to the ksh history file size
monitoring constraints.
debug also supports the ksh fc command, which allows command
history searching, editing, listing and rerunning.
Process Control
An application designed to run in the UNIX System V
environment can consist of one or more processes coordinated
through some interprocess communication mechanism. These
processes may have been created from a common ancestor via
fork(2), or may have no particular ancestral relationship. A
process is derived from an object file and zero or more static
or dynamic shared libraries via exec(2), and is modified by
attaching or detaching dynamic shared libraries during its
execution.
Each process may consist of a single thread of control, or of
multiple threads of control, all sharing a common address
space. The threads abstraction is implemented by a set of
library interfaces (see, for example, thr_create(3thread)).
These interfaces are, in turn, built on top of an operating
system abstraction known as light-weight processes, or LWPs.
debug provides control over both single and multiprocess
applications and over both single and multithreaded processes.
For each active process under its control, debug detects when
the object program and shared library association changes and
maintains current knowledge of the associations. In
particular, processes may attach or detach shared objects
into/from their address spaces using the interfaces
dlopen(3C), dlclose(3C), dlsym(3C).
Copyright 1994 Novell, Inc. Page 5
debug(1) debug(1)
debug provides control of an arbitrary number of threads
within a given process. These threads may be bound threads or
multiplexed threads (see thr_create). The only restriction is
that the user may not start (run or step) a multiplexed thread
that is not currently running on an LWP. Note that debug
provides control of multithreaded applications only via the
library threads abstraction. It does not provide direct
access to LWPs.
By default, debug detects when a new process is created by one
of its controlled threads or processes and includes the new
object in its set of controlled objects. The user can release
such newly created objects from debugger control by using the
release command (see below). The default behavior may be
overridden by individual create or grab commands, or may be
changed by setting the value of the built-in variable %follow.
Legal values are:
none Do not control child processes.
procs Follow all child processes.
all Follow all child processes (same as procs).
debug assigns a unique identifier to each process and thread
under its control. Process identifiers are in the form pid
(p1, p2, p3, ...). Thread identifiers are in the form pid.id
(p1.1, p1.2, p2.5, ...). debug maintains a record of the
current process in the built-in variable %proc. The current
thread is maintained in the built-in variable %thread. For
all debugger commands that accept an optional list of threads
and processes, the default action, if no such list is given,
is to apply the command to the current thread (or the current
process, if it is single-threaded).
When debug begins execution, the current process is set to the
first process specified on the command line, whether a live
process or one the debugger creates. The current thread is
set to the first thread, for a process created by the
debugger, and to an arbitrary thread for a grabbed process.
The user may change the debugger's notion of the current
thread or process by changing the contents of %thread or %proc
with the set command.
Copyright 1994 Novell, Inc. Page 6
debug(1) debug(1)
Foreground and Background Execution
Most users of traditional single-process debuggers are
accustomed to a synchronous interface with the debugger: the
user enters a command that sets a process in motion, and the
debugger suspends its own execution until the process stops,
only then returning control to the user. In a multiprocess or
multithreaded application, if a debugger synchronously watches
one process or thread for too long, or takes too long to
address a breakpoint or other event in some component, the
timing of process interactions is affected. While it is
impossible to avoid the problem of affecting the subject
application entirely, the debugger can minimize this effect by
reacting very quickly to all threads and processes at the same
time. This implies asynchronous process interaction, which in
turn implies an asynchronous user interface.
When the user enters a command that sets a controlled object
in motion, debug, by default, waits for that object to stop
before returning control to the user. If the debugger built-
in variable %wait is set to 0 or no, or background, the
debugger does not wait for the affected object to stop. The
default behavior may be re-asserted by setting %wait to 1 or
yes, or foreground. This global behavior may be overridden by
each command that sets a process in motion.
Redirection of Process I/O
When debugging a multiprocess or multithreaded application, a
user can quickly get confused by output coming to the terminal
from several different processes or threads at once,
especially if several processes or threads are running in
asynchronous mode. There is also a potential for confusion if
more than one object is waiting for input from the user.
When the user creates a debugger-controlled object, debug does
not, by default, attempt to intercept the input or output for
the generated processes. Subject process output is unlabeled,
and the subject competes with the debugger for the terminal
input. If the debugger variable %redir is set to 1 or yes,
the process or thread I/O is redirected to a pseudo-terminal.
All output from that process or thread is labeled with an
indication of which pseudo-terminal has been written.
Subsequent input to the process or thread must be made through
the input command (see below). The default behavior may be
re-asserted by setting %redir to 0 or no. This global
behavior may be overridden by an individual create command.
Copyright 1994 Novell, Inc. Page 7
debug(1) debug(1)
debug does not attempt to redirect the I/O of grabbed
processes, or of the child processes of some created subject,
since it cannot tell what those processes may have already
done to redirect their own I/O. Note, too, that all of the
processes and threads that result from a single create command
read and write from/to the same pseudo-terminal.
Process Lists
A process list is a way to specify one or more processes and
threads as the target of a command. Many debugger commands
take an argument (-p proc_list) that lists the names of those
processes and threads which should be affected by the command.
A program is the set of all processes and threads created as
the result of invoking a single binary executable. It does
not include processes created from different executables when
a process within a program execs.
The command language represents process lists as comma-
separated lists of process names. A process name is defined
as either:
the keyword all, denoting all controlled processes and
threads,
a user or debugger-generated program name, denoting all
processes and threads created from the current
invocation of the same executable,
a debugger-generated thread id, of the form
pinteger.integer, denoting a specific controlled thread,
a debugger-generated process id, of the form pinteger,
denoting either all threads that belong to a specific
controlled process, or, if the process is not
multithreaded, the process itself,
the debugger built-in variable %program, denoting all
active processes and threads derived from the current
program,
the debugger built-in variable %thread, the current
thread,
the debugger built-in variable %proc, the current
process, or all threads derived from the current
process,
Copyright 1994 Novell, Inc. Page 8
debug(1) debug(1)
a decimal integer, denoting the process which has the
given integer as its system pid (or all threads derived
from that process),
any user-defined variable that has an integer value,
interpreted as a system pid,
any user-defined variable that has a string value, which
can be interpreted as one of the above forms, or as a
list of the above forms.
Context Variables
The context for the execution of most debugger commands that
describe the state of controlled objects is determined by a
subset of the debugger built-in variables. %program, %proc
and %thread determine the object(s) to which a command
applies. Setting one affects the others. In addition, there
is a set of context variables specific to each thread or
process. For each controlled object, the following debugger
built-in variables are available:
%db_lang The source language of the current context.
%frame The current frame (an integer representing the
frame number).
%func The current function.
%file The current source file.
%line The current source line number.
%list_file The next file to be displayed by the list command.
%list_line The next line to be displayed by the list command.
%loc The current program address.
These variables are reset whenever the thread or process that
owns them stops for any reason. %frame may be explicitly set
by the user to any active frame and changes the value of the
other context variables accordingly. %func may be explicitly
set to any function with a currently active frame and results
in setting %frame to the most recent instance of that
function. %db_lang, %file, %line, and %loc are read-only. If
no debugging or symbolic information is available for the
Copyright 1994 Novell, Inc. Page 9
debug(1) debug(1)
current function, %db_lang, %func, %file, %list_file, %line,
and %list_line, may be null.
Verbosity Levels
When a user process or thread under the debugger's control
stops for any reason, single step, breakpoint, signal, and so
on, the debugger generates output to the terminal. This
output can sometimes be more voluminous than the user would
desire. For that reason the amount of user-visible output can
be adjusted on a global basis by setting the %verbose
variable. The legal values are:
quiet No output is generated for debugger events.
source The debugger displays the next source or
disassembly line.
events If the process stops for an event (system call,
signal or stop event) the debugger announces the
type of event and the current location. For all
stops, it displays the next source line.
reason (default)
This is the same as events, except that the
debugger announces each single step in addition to
all of the events.
all The highest verbosity level. Currently, this is
the same as reason.
Certain commands allow the user to specify the quiet verbosity
level, with a -q option, overriding the global %verbose
setting.
Thread State Changes
A thread may undergo several different kinds of state changes
during its lifetime: it is created and it exits; it can be
suspended or continued; and a multiplexed thread may give up
its LWP or be picked up by an LWP. The debugger variable
%thread_change governs the behavior of the debugger when any
of these state changes occur. The valid values are:
ignore The debugger will not print a message announcing
the change or stop the thread involved. A newly
created or continued thread, or a thread picked up
by an LWP will be set running, if possible.
Copyright 1994 Novell, Inc. Page 10
debug(1) debug(1)
announce The debugger will print a message announcing the
state change but will not stop the thread involved.
A newly created or continued thread, or a thread
picked up by an LWP will be set running, if
possible.
stop (default)
The debugger will print a message announcing the
state change and stop the thread involved, if
possible. A continued thread or a thread picked up
by an LWP will be stopped (or in the Off LWP
state). For thread creation, the thread that
created the new thread will be stopped and the new
thread will stop when it reaches the function
specified in the thr_create call.
Directory Search Paths
To associate program addresses with source listings, debug
must know where to look for the source of the programs being
debugged. The built-in variable %global_path contains a
colon-separated list of directory pathnames. debug combines
this information with the names of source files it derives
from the debugging information in the object file, to search
for source code. In addition to the global path, each program
may have a program-specific path. This path is stored in the
built-in variable %path. Each program has its own version of
this variable. When attempting to find the source for a given
program, debug searches first the list of directories in that
program`s %path variable, and then the list specified by
%global_path.
Events
Events in the debugger are triggers in the execution sequence
of a process or thread that cause control to pass from the
process or thread to the debugger. These triggers are
activated at the user's request and consist of changes in the
process address space, signals and entry to or exit from
system calls. Events may also consist of user-specified
actions taken by the debugger when a controlled entity stops
for any reason.
Event triggers may apply to a given thread or process or to a
set of threads and processes. The event fires if any of the
specified objects encounter the trigger. Commands that create
events apply, by default, to the current program, rather than
the current thread.
Copyright 1994 Novell, Inc. Page 11
debug(1) debug(1)
With each event, the user may specify an optional debugger
command block. This block is executed whenever the event
triggers. Events and their associated commands can be
deleted, or temporarily deactivated and then reactivated.
For each user-specified event, debug assigns a unique
identifier in a common name space. This identifier may be
used in the commands that delete, enable, disable and list
events. The last event identifier assigned is maintained in
the special variable %lastevent, which is updated
automatically by the debugger. When an event triggers, debug
executes the commands associated with the event, after setting
the special variables %program, %proc, %thread, %file, %line,
%func, %frame, %loc, %db_lang to indicate the context in which
the event occurred, and %thisevent to the event number of the
triggered event. These variables are set only for the
execution of the commands associated with the triggering
event. They revert to their previous values (or are updated
to reflect the new debugger state) when those commands
complete.
The default action for each event is to announce the
occurrence of the event and display the current source line
(or current instruction, if no line number information or
source is available).
When a controlled process dies, debug remembers the events
created for that process. If a new process is created for the
same program, all events that applied to the entire program
(the default) are re-instantiated for the new process. Events
that were created to apply only to a single process within a
multiprocess program or to a single thread, are not recreated.
Similarly, when a process creates a new child process via
fork(2), all events that apply to the entire program from
which the parent process is derived are copied in the child
process. Events that apply to the parent process only or to a
single thread are not copied.
When a new thread is created within a process, all events that
applied to the entire process or the entire program are copied
in the sibling thread. Events that applied only to the
original thread that created the new thread are not copied.
Expressions
Many debugger commands accept programming language
expressions. Each expression is evaluated using the syntax
Copyright 1994 Novell, Inc. Page 12
debug(1) debug(1)
and semantics of the current language, subject to possible
limitations of the debugger on that language. The current
language, %db_lang, is determined dynamically from the source
language of the current file. The debugging information in an
object file supplies a language attribute describing the
programming language of the source file. If the debugger
cannot determine the program's source language, %db_lang
defaults to C. The user may override the information in the
object file by setting the variable %lang. If the user sets
%lang to the null string (""), the debugger reverts to using
%db_lang. Expressions referencing variables defined in files
compiled from different languages do not change the current
language.
debug accepts expressions containing any combination of
program variables or functions, qualified names, built-in
debugger variables, and user-defined debugger variables. A
qualified name specifies a program identifier that may not be
visible in the current context. The syntax is:
[[thread id]@][[file]@][[function]@][[line number]@]identifier
or
[[thread id]@]frame number@identifier
or
[[thread id]@]object name@[[source file]@]identifier
The qualified name is evaluated left to right, and may be
disambiguated by supplying @'s as needed.
Expressions beginning with a dash (-) or containing character
sequences with special meanings to debug must be enclosed in
parentheses, square brackets or curly braces. The special
character sequences are: >, >>, |, ||, &&, #, `,', ;, newline.
Support for the C Language
When %db_lang is set to C, debug supports evaluation of all
legal ANSI C expressions, except those involving macro
expansion, or structure, union, or enumeration type
declarations. An example of a type declaration in an
expression is
((struct { int i; char c; } *)p)->c = 'a';
debug evaluates C expressions using ANSI C semantics rather
than the pre-ANSI C (or transition mode) semantics. The main
effect is on type promotions involving unsigned types, where
ANSI C semantics are value preserving rather than unsigned
Copyright 1994 Novell, Inc. Page 13
debug(1) debug(1)
preserving. The debugger's behavior may differ from the
behavior of programs compiled with cc -Xt (for transition
mode).
Support for the C++ Language
When %db_lang is set to C++, the debugger accepts a subset of
C++ expressions, including:
all expressions accepted when %db_lang is C,
calls to member functions, including virtual member
functions and static member functions,
calls to overloaded functions,
expressions using type names as typedefs,
expressions using overloaded operator functions, and
expressions accessing class members with an implied
"this" pointer, when the process is stopped in a class
member function.
Within this subset, debug conforms to the C++ Reference
Manual. debug accepts and prints names as they appear in the
C++ source, not as they appear in the object file.
The print and set commands have a verbose option (-v) that
prints the function prototype for any functions the debugger
calls in evaluating the expression. This is useful for
understanding what's happening in expressions using overloaded
functions or operators.
If given a pointer to a base class object with virtual
functions, and if debug can determine that the type of the
object pointed to is a class derived from the base class, the
whatis command will display both the base class and the
derived class. The print command will also display the object
in terms of the derived type.
Breakpoints (stop events) may be set on:
class member functions, including constructors,
destructors, and conversion functions,
Copyright 1994 Novell, Inc. Page 14
debug(1) debug(1)
overloaded operator functions, and
overloaded functions, using the full prototype, or
overloaded functions, without the prototype information.
In that case, debug will display a list of the
functions, and ask the user to pick one or all of the
choices.
A stop event may also be created on a specific object and
member function combination, using the syntax:
stop pointer->function
stop object.function
debug will stop the process or thread upon entering the
function only if the ``this'' pointer matches the specified
object. If the function is a virtual function, debug will set
the breakpoint on the appropriate overriding function.
Definitions
The syntax and semantics for each command are described below.
The following terms are used in the synopses and descriptions:
address A constant, user-defined variable, built-in
variable or register name that evaluates to an
address (an integer or pointer value).
block A list of commands, enclosed in braces,
separated by newlines or semicolons.
call A system call name or number. Case is not
significant.
cmd A simple command or a block.
cmd_line A shell-style command line (possibly including
shell scripts, environment variables, pipes,
and I/O redirection) which will be interpreted
by the shell, but the resulting processes will
be controlled by the debugger.
core_file The relative or complete pathname of a file
which was created by the kernel upon abnormal
termination of some process.
Copyright 1994 Novell, Inc. Page 15
debug(1) debug(1)
count An unsigned decimal integer.
event_command Any of onstop, stop, signal or syscall.
event_num A small integer, assigned by the debugger when
any event is created, that identifies the
resulting set of actions.
expr An expression in the current language. See
``Expressions'', above.
func_name The name of a function in the current process.
location A designation of an address in a subject
process. It includes line numbers, program
symbols, processor registers, and limited
expressions involving these components. The
syntax is:
address[_constant] # includes debugger and user variables
[thread id@][filename@]func_name[_constant]
[thread id@][filename@]line_number
object_file The relative or complete pathname of an
executable object file (an ``a.out'') in COFF
or ELF format.
pattern Simple regular expressions used to restrict a
list of names. sh(1) syntax is used.
process_id A system process identifier.
proc_list See ``Process Lists''.
reg_exp A simple internationalized regular expression
using the syntax accepted by ed(1).
signal A signal name or number. A signal name may be
specified with or without the SIG prefix, and
case is not significant.
stop_expr An expression denoting conditions under which
specified processes should be stopped. See
stop.
Copyright 1994 Novell, Inc. Page 16
debug(1) debug(1)
. . . Denotes optional repetition of the preceding
element.
xxx|yyy Denotes that either xxx or yyy, but not both,
may appear.
Commands
! shell-command
This command passes the entire command line, less the
exclamation mark, to the shell ($SHELL, if set, or else
/usr/bin/sh) for execution. Note that any redirection
will be interpreted by the shell, not the debugger.
If the shell escape operator is given twice, with no
arguments, that is, !!, debug re-executes the last shell
escape specified.
alias [-r] [name [tokens]]
The alias command, with no arguments, lists the current
aliases and their definitions. If the -r option is
present, it removes the alias with the given name from
the list of aliases. If no -r option is present, but a
name is given, the alias command displays the
definition, if any, for the alias with the given name .
If any characters, other than spaces, tabs, or comments,
follow the name argument, the command establishes a new
alias for the name , consisting of all the characters up
to, but not including, the comment or newline.
Alias definitions may contain the special identifiers
$1, $2, . . . Each such special identifier $n in an
alias definition is replaced by the nth argument in an
alias invocation, where the arguments are numbered
beginning at 1. Each argument must be preceded by
whitespace and is terminated by whitespace, a newline,
the comment character (#) or the beginning of a block
({). The special identifiers $1, $2, . . . will not be
replaced within a quoted string.
If an alias definition contains the special identifier
$#, it will be replaced during invocation of the alias
with the number of arguments actually used during the
current alias invocation. If an alias definition
contains the special identifier $*, it will be replaced
during invocation of the alias with a list of all
arguments passed during the current alias invocation,
Copyright 1994 Novell, Inc. Page 17
debug(1) debug(1)
each separated from the next by a single space.
Aliases may be defined in terms of other aliases, but
not recursively. At least 20 levels of nested alias
definitions are supported.
If the name given is the same as any existing built-in
command, a warning will be generated. Aliases take
precedence over built-in commands.
break The break command causes the debugger to exit from the
innermost enclosing while loop (see while).
cancel [-p proc_list] [signal ...]
cancel takes a list of signals, that are specified as in
the kill command. If debug has intercepted any of the
listed signals for any of the specified objects, it will
ensure that those objects do not see the specified
signals when they continue execution. If no signals are
specified, debug cancels all pending signals for the
specified objects.
cd [pathname]
The cd command changes the debugger's current working
directory to pathname. If no pathname is given, cd uses
the directory specified by the environment variable
HOME.
c count] [stop_expr|call...| signal...]
change event_num [-p proc_list] [-eqvx] [-
[block]
The change command allows the user to modify various
attributes associated with a previously assigned event.
event_num must come before the optional stop expression,
signal or system call specifications and must be the
number of an event that is currently defined (although
it may be disabled).
The list of threads and processes to which the event is
applied may be changed with the -p option.
The -q option specifies that debug will not announce the
occurrence of the event. -v specifies that the event
occurrence will be announced.
Copyright 1994 Novell, Inc. Page 18
debug(1) debug(1)
The -e and -x options work as in the syscall command,
and specify whether the system call will be trapped on
entry, exit or both entry and exit.
The -c option specifies the number of times the event
must occur before it triggers. The -c option is valid
only for stop and syscall events.
Alternate expressions, signals or system calls and/or an
alternate command block, may be specified.
The resulting event will have the same event number as
event_num . Note that the change command does not allow
the type of event: onstop, stop, signal or syscall, to
be changed. Further note that the command list must be
in the form of a block (that is, with enclosing braces)
to distinguish it from a stop expression, system call or
signal name.
continue
The continue command causes the debugger to begin
execution of the next iteration of the innermost
enclosing while loop. The debugger continues by re-
evaluating the expr part of the while command (see
while).
create [-f none|procs|all] [-dr] [-l start_loc] [cmd_line]
cmd_line consists of one or more executable files, in
any of the object file formats understood by the
debugger, and their associated arguments. The
individual commands can be linked by shell-style pipes,
and the input and output of the cmd_line can be
redirected. Shell meta-characters need not be quoted.
The length of cmd_line is limited only by the length of
the argument list accepted by exec (ARG_MAX).
debug creates a new controlled process for each command
specified in cmd_line , taking care of any necessary
redirections of input and output. The processes are set
up to stop at the location specified by start_loc. If
no start_loc is supplied, the processes are set up to
start at the symbol main, if it exists, otherwise at the
starting address specified by the object file. debug
then exec's each command, passing each the specified
arguments.
Copyright 1994 Novell, Inc. Page 19
debug(1) debug(1)
If no cmd_line is specified to create, debug re-executes
the last create command issued, (first killing all
processes created as a result of the last create
command, if they still exist) in effect, re-running the
last process (or processes) created with the same set of
arguments.
If the -r option is specified, debug redirects the I/O
of the resulting subjects to a pseudo-terminal, as
described above. If the -d option is given no
redirection is attempted. If neither -r nor -d is
specified, the default is determined by the value of the
debugger variable %redir.
debug resets its notion of the current program to the
first executable specified on the cmd_line . The
current process is reset to the process generated from
that executable. The current thread is set to the first
thread in that process, if the program uses the threads
interfaces.
The -f option may be used to specify whether the
debugger should take control of child processes, and
overrides the default behavior of the debugger. The
arguments to the -f option have the same meanings as do
the legal values for the %follow built-in variable (see
``Process Control'').
debug associates the name of each object (program name)
with all processes derived from the current invocation
of that object. This name may be used in any command
that accepts a process list. If the command name
matches the name of an already existing debugger-
controlled program, debug creates a new name for the
program. The default program name may be reset with the
rename command (see below).
delete event_num ...
delete -a [-p proc_list] [event_command]
delete can be invoked in one of two ways. In the first,
the user specifies a list of previously assigned event
identifiers. debug deletes any associated events,
removing the planted breakpoint or canceling the signal
or system call trigger.
Copyright 1994 Novell, Inc. Page 20
debug(1) debug(1)
In the second form, all debugger events for the current
thread or process (or all events associated with the
optional proc_list ) are deleted. If an event_command
(onstop, stop, signal or syscall) is given, only events
of the type specified are deleted.
dis [-p proc_list] [-c instr_count] [location]
The dis command with no arguments displays the result of
disassembling %num_lines instructions. %num_lines
starts out at 10 and may be reset by the user. If an
instr_count is given, dis displays instr_count
instructions, instead.
If a location is given, dis begins disassembling at that
address. If no location has been specified, and the
context for the specified process or thread has not
changed since the last dis invocation on that object,
dis begins with the address following the last
instruction displayed for that object. Otherwise, dis
begins its display with the current location, as
specified by the debugger variable %loc, which is reset
whenever the context for the specified process or thread
changes.
If more than one thread or process is specified by the
proc_list argument, the disassembly request is performed
for each thread or process in turn.
disable event_num ...
disable -a [-p proc_list] [event_command]
disable can be invoked in one of two ways. In the
first, the user specifies a list of previously assigned
event identifiers. The debugger marks any associated
events as inactive, but does not delete them. The event
identifiers are still valid, but the actions specified
by the events are not performed.
In the second form, all debugger events for the current
thread or process (or all events associated with the
optional proc_list) are disabled. If an event_command
is given, only events of the type specified are
disabled.
dump [-p proc_list] [-c byte_count] location
The dump command displays %num_bytes bytes of memory, 16
bytes per line, starting at the address specified by the
Copyright 1994 Novell, Inc. Page 21
debug(1) debug(1)
location truncated to a multiple of 16, in hexadecimal
and ASCII. If a byte_count is given, that many bytes of
memory are dumped instead. %num_bytes starts out at 256
and may be set by the user.
If more than one thread or process is specified by the
proc_list argument, the dump request is performed for
each thread or process in turn.
enable event_num . . .
enable -a [-p proc_list] [event_command]
enable can be invoked in one of two ways. In the first,
the user specifies a list of previously assigned event
identifiers. For each, if the associated event is
currently disabled, the debugger reactivates it.
In the second form, all disabled debugger events for the
current thread or process (or all events associated with
the optional proc_list ) are enabled. If an
event_command is given, only events of the type
specified are enabled.
events [-p proc_list] [event_num ...]
The events command without any arguments prints the
entire list of user-specified events for the current
program. For each event, the event identifier and
status (active or disabled), event type, list of
associated threads and processes, the event trigger
(stop expression, system call or signal) and the
beginning of the associated command list is printed.
If a proc_list is specified, those events associated
with the list of threads or processes are printed. If a
list of event numbers is given, a more detailed record
of the specified events is printed, including the full
set of associated commands.
export $username
The export command makes a user-defined variable and its
value available in the debugger's environment. The
variable is thereafter passed to all processes created
by debug. If the value of $username is changed using
the set command, after it has been exported, it must be
explicitly re-exported for the new value to be visible
in the environment. $username is exported without the
leading $ sign.
Copyright 1994 Novell, Inc. Page 22
debug(1) debug(1)
fc [-e ename] [-nlr] [first [last]]
fc -e - [old=new] [command]
In the first form, a range of commands from first to
last is selected from the last HISTSIZE commands
(environment variable, default 128) that were entered.
The arguments first and last may be specified as numbers
or as strings. A string is used to locate the most
recent command starting with the given string. A
negative number is used as an offset to the current
command number. If the -l option is given, the commands
are listed on standard output. Otherwise, the editor
program ename is invoked on a temporary file containing
the commands. If ename is not supplied, the value of
the environment variable FCEDIT (default /usr/bin/ed) is
used as the editor. When editing is completed, the
edited commands are executed.
If first is not specified, the default is the previous
command for editing and the previous 16 commands for
listing. The -r option reverses the order of the
commands; the -n option suppresses command numbers when
listing.
In the second form, the command is re-executed after the
substitution old=new is performed. If command is not
supplied, the default is the previous command.
grab [-f none|procs|all] [-l object_file] live_object ...
grab -c core_file object_file
The grab command can take one of two forms. In the
first, the user specifies one or more existing processes
by giving a list of live_objects (either pathnames,
entries in the /proc directory, or process ids). In
either case, debug attempts to control the specified
objects as live processes and, if successful, suspends
their execution. debug resets its notion of the current
program to the executable from which the first process
specified was derived. The current process is reset to
the first process specified. The current thread is set
to an arbitrary thread within the current process, if it
uses the threads interfaces.
debug, by default, loads symbolic information for the
process from the object file from which the process was
created. The -l option specifies an alternate
object_file from which to load symbolic information. If
Copyright 1994 Novell, Inc. Page 23
debug(1) debug(1)
-l is used, only one live_object may be specified. This
option is useful when debugging long running
applications that have no symbol information.
The -f option may be used to specify whether the
debugger should take control of child processes, and
overrides the default behavior of the debugger. The
arguments to the -f option have the same meanings as do
the legal values for the %follow built-in variable (see
``Process Control'')
In the second form of grab, the user specifies an
executable program in one of the object file formats
understood by the debugger. debug interprets the
core_file as a kernel-created record of the process
state at the time of the death of the process associated
with the object_file and lets the user examine the
contents of the process stack, registers and data
segments.
debug associates the name of each object with all
processes derived from the current invocation of that
object. This name may be used in any command that
accepts a process list. If the command name matches the
name of an already existing debugger-controlled program,
debug creates a new name for the program. The default
program name may be reset using the rename command (see
below).
halt [-p proc_list]
debug instructs the specified threads or processes to
stop execution and waits for them to stop.
help [topic]
The help command, with no arguments, lists all of the
available commands and help topics. If a command name
is given, it gives a detailed syntax and usage message
for that command. If a ``help topic'' name is given, it
lists the help available on that topic. Each debugger
command has a help message which describes its syntax,
options, and usage, and gives examples of its use. In
addition, there are help topics which are not also
command names, to explain the syntax for process lists,
expressions, command output redirection and
``locations,'' and to list the available languages for
expression evaluation.
Copyright 1994 Novell, Inc. Page 24
debug(1) debug(1)
if (expr) cmd [else cmd]
This is the traditional conditional branch statement,
similar to that present in C, with the exception that
semicolons are not necessary, except to separate
multiple commands on a single line.
expr can be any valid expression in the current language
(see ``Expressions''). The expression is evaluated, and
if it evaluates to ``true'' in the semantics of the
current language, the cmd associated with the if clause
is executed. Otherwise, if there is an else clause, the
cmd associated with it is executed.
The if construct is more likely to be used in commands
associated with events, or in scripts, than to be typed
interactively as a top-level command.
input [-p proc_name|-r pseudo_tty] [-n] string
The input command is used to send user input to a
process whose I/O has been redirected by the debugger to
a pseudo-terminal (see ``Redirection of Process I/O'').
The first argument may be either the name of a single
program or process (as specified in a process list), or
the name of a pseudo-terminal, as used by debug to label
process output. If a proc_name is specified, debug
finds the pseudo-terminal (if any) associated with that
program. If neither a program nor a pseudo-terminal is
specified, debug attempts to find a pseudo-terminal
associated with the current program.
debug sends the input string to the specified pseudo-
terminal, after appending a new-line. If the -n option
is given, no new-line is appended.
It is an error if the specified proc_name has no
associated pseudo-terminal.
jump [-p proc_list] location
location may be any debugger expression that resolves to
an address in one of the specified threads or processes.
For each thread or process specified, if the given
object is currently stopped, and if the specified
location is valid for that process, debug adjusts the
program counter for that object to that location.
Subsequent run or step commands for that object continue
execution from the specified location . debug does not
Copyright 1994 Novell, Inc. Page 25
debug(1) debug(1)
attempt to adjust the thread or process stack if the
specified location is in a different function.
kill [-p proc_list] [signal]
kill sends a single signal to the current thread or
process or to the list of threads and processes
specified by proc_list. Unlike most other debugger
commands, if a process identifier is given in the
proc_list, the signal is sent to the process as a whole,
rather than to each thread in the process.
If no signal is specified, the default is SIGKILL.
signal may be either a valid signal number (as defined
in <sys/signal.h>) or a symbolic name, formed from the
manifest constant name listed in <sys/signal.h>, with or
without the SIG prefix. Case is ignored.
list [-p proclist] [-c count] [line|func_name|reg_exp]
The list command displays source lines for the specified
threads or processes. The default is the current thread
or process.
If no count argument is given, the list command displays
%num_lines source lines. %num_lines starts out at 10
and may be reset by the user. If a count is given, list
displays count lines, instead.
The starting place for the listing may be specified in
several ways. If a regular expression is given, the
current file is searched for the next occurrence of a
line which matches the given reg_exp , beginning from
the line immediately following the current line
(preceding, if the reg_exp is surrounded by question
marks). If a match is found, and no count is given,
only the line containing the match is listed. If a
count is given, the line containing the match begins the
display. ed(1) syntax is used for regular expressions.
A function name as an argument causes the list command
to begin its display at the first line of the named
function. The function may be specified as in the
location syntax: a name, the debugger built-in variable
%func, or filename@ func_name.
Copyright 1994 Novell, Inc. Page 26
debug(1) debug(1)
A line number may be specified as in the location
syntax: a single decimal constant, the debugger built-in
variables %line or %list_line, or filename@ line.
If no starting location is specified, the list command
begins the display with %list_file@%list_line.
%list_file is set to the current file (%file) and
%list_line is set to the current line (%line) whenever
the current context changes. In addition, %list_line is
set to the last line displayed each time list is
invoked. Thus, if the current context has not changed
and no starting location is specified, list begins with
the last line displayed in the previous list invocation.
logoff
The logoff command stops session logging.
logon [filename]
The logon command starts debugger session logging. All
debugger input and output are sent to filename in
addition to being echoed at the terminal. Output lines
are printed as comments.
If no filename is given, the last filename used in a
logon command is assumed, and new debugger commands and
output are appended to that file.
map [-p proc_list]
The map command prints out a list of all mapped segments
for the current process, or for each thread or process
specified in proc_list. The listing includes the
virtual address range and access permissions for all
segments, and the pathname, for all segments associated
with the a.out and associated shared libraries.
Note that since all threads within a process share a
common address space, the virtual memory map will be
identical for each thread within a process.
onstop [-p proc_list] [cmd]
The onstop command, by default, applies to all threads
or processes derived from the current program. The
onstop command with no arguments prints out the list of
onstop events with their associated commands.
Copyright 1994 Novell, Inc. Page 27
debug(1) debug(1)
cmd is a debugger command block. The commands are
executed whenever the specified list of processes stops
for any reason.
print [-p proc_list] [-v] [-f fmt] expr [, expr] . . .
The print command displays the results of evaluating the
(comma-separated) list of expressions. The expressions
are evaluated in the context of the current thread or
process, unless other threads or processes are specified
in the proc_list argument. If more than one thread or
process is specified, the expressions are evaluated and
printed in the context of each specified object, with
the %proc and %thread debugger variables set to the
process and thread identifiers of the object in which
the expressions are being evaluated. All events which
would be triggered as a side effect of evaluating an
expression (breakpoints in a function, a call to which
appears in the expression, for example) are ignored, as
if they had been disabled.
The -f option allows specification of a list of format
expressions to be used when printing values. The fmt is
a string enclosed in quotation marks ("") and may
contain a subset of the format expressions accepted by
printf [see fprintf(3S)]. A format expression may have
the following form:
%[flags][width][.[precision]][conversion] specifier
The flags, width, precision, and conversion fields have
the same meanings as in the printf routine, with the
exception that positional parameters are not accepted.
The specifier may be one of the following characters
(specifiers marked with an asterisk (*) may not be
available on all systems):
a*,A* floating-point in hexadecimal with exponent (as
power of two)
b*,B* unsigned binary integer
C* wide character
c unsigned char
d,i signed decimal integer
e,E floating point in style [-]d.ddde_dd
f floating point in style [-] ddd.dddd
g,G floating point in either of above 2 styles
Copyright 1994 Novell, Inc. Page 28
debug(1) debug(1)
o unsigned octal integer
p void * (generic data pointer; hexadecimal address)
S* wide character string
s string
u unsigned decimal integer
x,X unsigned hexadecimal integer
z debugger default style for the expression
% %
Any character in the fmt that is not part of a format
expression is printed as given. The default format for
a particular expression is determined by the expression
evaluator for the current language. The expression
evaluators will attempt to present information formatted
in a way that is meaningful for the given language. For
example, for C, a pointer to a character would be
printed as a character string, a reference to an array
variable would print all members of that array and
dereferencing a pointer to a structure would print each
member of that structure. Each expr may be any valid
expression in the current language (see
``Expressions'').
Each expression in the list is converted to its
printable representation, a newline is added, and the
result displayed. This process is repeated for each
object named in the proc_list . If a fmt is given, no
terminating newline is printed unless specified in the
fmt . The -v option specifies verbose mode. The
debugger prints the function prototype of any function
that was called as a result of evaluating the given
expressions. This is particularly useful in evaluating
C++ expressions to see how overloaded functions or
operators are resolved.
ps [-p proc_list]
The ps command prints the debugger-generated
identifiers, kernel-generated identifiers, current
state, location, if the object is stopped, and object
name for all controlled threads and processes, or for
only those objects specified by the -p option, if
present.
pwd The pwd command prints the debugger's current working
directory. The current working directory may be changed
using the cd command.
Copyright 1994 Novell, Inc. Page 29
debug(1) debug(1)
quit The quit command causes the debugger to exit, releasing
and running any grabbed processes and killing any
processes created by the debugger.
If a user wishes to leave a grabbed process suspended,
perhaps to be grabbed at a later time from a different
invocation of the debugger, he or she should use the
release command with the -s option before quitting.
regs [-p proc_list]
The regs command displays in hexadecimal the contents of
the processor registers for the current thread or
process. If more than one thread or process is
specified by the proc_list argument, the register
display is performed for each object in turn.
release [-s] [-p proc_list]
debug removes all planted breakpoints from all threads
or processes specified in proc_list and relinquishes
control over them. Releasing all threads within a given
process is equivalent to releasing the entire process.
If the -s option is specified, the processes are
released, but halted. Otherwise, the released objects
are allowed to continue execution. The -s option is
ignored for threads. If the current thread or process
is released, debug chooses a new object to become
current.
Processes released in the halted state may be grabbed by
the debugger in a different debug session.
release can be used on core images as well as live
processes. The debugger deletes the core image and
associated object file from the list of objects that can
be examined.
rename prog_name name
The rename command changes the name by which a related
group of processes are known. All threads and processes
derived from a single invocation of the executable from
which prog_name was derived, can be referred to by the
new name. name can be used in any command that accepts
a proc_list and will appear in any debugger output that
would have used prog_name.
Copyright 1994 Novell, Inc. Page 30
debug(1) debug(1)
run [-p proc_list] [-bfr] [-u location]
debug starts the current thread or single-threaded
process or each object specified by proc_list.
Execution continues from the program address at which it
was suspended when the given object last stopped, or at
the address specified in a preceding jump command.
The -f and -b options allow the global behavior set by
the %wait debugger variable to be overridden. -f
specifies foreground execution for the threads or
processes. -b specifies background execution.
The -r option causes debug to continue execution of the
given object until each returns from its current stack
frame, that is, until the return address of the current
function is reached (or until some other event causes
execution to halt).
The -u option specifies that debug continues execution
of the specified objects until the address specified by
location is reached (or until some other event causes
execution to halt).
A multiplexed thread that is not currently running on an
LWP cannot be set running.
script [-q] fname
The script command reads and executes debugger commands
from the named file. Commands are echoed before
execution, unless the -q option is given.
Scripts may nest; the debugger implementation does not
place a limit on the number of nested scripts (although
external limits, such as the number of open files
supported by stdio, may apply).
set [-p proc_list] [-v] expr
set [-p proc_list] debug_or_user_var [=] expr [, expr] ...
The set command has two forms. In the first, expr may
be any valid expression in the current language (see
``Expressions''). While any valid language expression
may be given, the typical use of the set command is to
evaluate assignment expressions. The -v option
specifies verbose mode. The debugger prints the
function prototype of any function that was called as a
result of evaluating the given expressions. This is
Copyright 1994 Novell, Inc. Page 31
debug(1) debug(1)
particularly useful in evaluating C++ expressions to see
how overloaded functions or operators are resolved.
In the second form of the command, set is used to change
the value of a debugger built-in variable name or user-
defined variable name. Debugger built-in variables may
have special semantics associated with them, such as
%path, which requires a string value having a particular
structure, or %frame, which denotes a frame number and
must be within the range of currently active frame
numbers. Setting a built-in variable such as %frame,
may cause the values of other built-in variables to
change as well (for example, %line or %func). There is
also an implied string concatenation operator. Any pair
of string-valued expressions which appear separated by
commas will be concatenated into a single string-valued
expression before the assignment is performed.
The debug_or_user_var and expr are both evaluated in the
context of the current thread or single-threaded
process, unless one or more other threads or processes
have been specified in the proc_list argument. If more
than one thread or process is specified, the set command
is evaluated in the context of each of the specified
objects, in turn.
signal [-p proc_list] [[-iq] signal ... [cmd]]
The signal command, by default, applies to all threads
or processes derived from the current program. Signals
are different from other debugger events in that the
debugger catches all signals by default. That is, when
a signal is posted to a thread or process, the debugger
stops that object and announces that the signal has been
posted. The user can then request that the signal be
canceled before the thread or process actually receives
it (see cancel).
debug can be instructed to ignore a given signal for a
particular object (or set of objects) with the -i option
to the signal command. So signal -i sigusr1 instructs
the debugger to let SIGUSR1 go directly to the current
thread or process, while signal sigusr1 re-establishes
the default action for SIGUSR1 for the current object.
Copyright 1994 Novell, Inc. Page 32
debug(1) debug(1)
The signal command can also be used to create events
triggered by the receipt of a signal. If a user
associates a command block with a signal or set of
signals, the debugger creates an event number for that
signal in the same name space as the other event
commands. These events may be manipulated using events,
delete, disable or enable. Multiple events may be
assigned for the same signal in any given thread or
process. The creation of an event for a signal takes
precedence over any instruction to ignore that signal
(using signal -i).
The -q option specifies that debug will not announce the
occurrence of the signal and applies only to signal
events.
The signal command with no signal arguments prints the
current signal disposition for each signal and the
current list of user-specified signal events, including
the event identifier and current status (active or
disabled), list of associated processes, signal name and
the beginning of any associated command block.
stack [-p proc_list] [-c count] [-f frame] [-a address] [-
s stack]
The stack command with no arguments prints the entire
call stack for the current thread or process. Frames
are numbered from 0 for the bottom of the stack (initial
stack frame). Displays begin with the top of the stack,
unless the -f option is given, in which case they begin
with frame. The count argument restricts the display to
at most count frames from each stack. If more than one
object is specified by the proc_list argument, the stack
request is performed for each object in turn.
The address and stack arguments may be used to specify
beginning values for the program counter and/or stack
pointer, respectively. This can be useful when
attempting to print a stack trace for a process that has
jumped to an illegal address or whose stack pointer has
been corrupted. Both the address and stack arguments
must be hexadecimal numbers.
step [-p proc_list] [-bfioq] [-c count]
The step command continues execution of the current
thread or single-threaded process or of each object
Copyright 1994 Novell, Inc. Page 33
debug(1) debug(1)
specified by proc_list.. The -i option specifies
stepping at the machine instruction level. The
specified objects are instructed to execute a single
machine instruction, or count instructions, if a count
is specified.
The default is stepping at the source statement level.
debug continues execution until the object reaches the
next source statement as defined by the compiler-
generated debugging information. If a count is
specified, the debugger repeats the step command count
times, or until execution is interrupted by some other
event. An explicit count of zero is interpreted to mean
``step forever.''
The -o option specifies stepping over function calls.
When the debugger encounters a subroutine call while
stepping with the -o option, it will set a temporary
breakpoint at the return point of the call and run at
``full speed'' until the temporary breakpoint is
reached. Stepping over function calls is available with
both the instruction and source level stepping.
The -f and -b options allow the global behavior set by
the %wait debugger variable to be overridden. -f
specifies foreground execution for the threads or
processes. -b specifies background execution.
The -q option specifies quiet stepping: the debugger
does not announce the step action nor the new source
line.
A multiplexed thread that is not currently running on an
LWP cannot be stepped.
stop [-p proc_list] [[-q] [-c count] stop_expr [cmd]]
The stop command specifies conditions in the address
space of one or more controlled objects that should
cause a list of threads or processes to stop. By
default, the stop command applies to all threads or
processes derived from the current program.
A stop_expr consists of one or more stop events , joined
by the special debugger conjunction (&&) or disjunction
(||) operators. These operators are left-associative,
and debug does not guarantee the order in which their
Copyright 1994 Novell, Inc. Page 34
debug(1) debug(1)
operands are evaluated. A stop event can take one of
three forms:
location
* lvalue
(expr)
Each type of stop event has some action that will cause
the event to be noticed by the debugger. When such an
action occurs, the entire stop_expr is evaluated for
``truth''. If true, the event triggers in the normal
way (debug informs the user of the event and executes
any associated commands).
A location is an address in the process's text where
debug can set a breakpoint. When the thread or process
reaches the specified location debug notices the event.
For location stop events that refer to function names,
the expression is true as long as that function is
active. For location stop events that apply to a
particular address or line number, the expression is
true only when the thread or process is at that address
or line.
lvalue may be any expression in the current language
that would be valid on the left-hand side of an
assignment statement in that language. The debugger
notices this event when the contents of the location
change. The change itself makes this kind of stop event
true.
expr can be any valid expression in the current
language. The debugger notices the stop event when any
of the identifiers involved in the expression changes
value. The entire expression is then evaluated in the
context of the current language.
stop events are evaluated continuously while the thread
or process is executing. The debugger is free to choose
whatever means it has available to achieve this effect.
This may include hardware support or may involve
continuous single stepping of the object.
The optional count specifies the number of times the
stop_expr must evaluate to true before the event
triggers. After count times, the event triggers each
time the stop_expr evaluates to true.
Copyright 1994 Novell, Inc. Page 35
debug(1) debug(1)
The -q option specifies that debug will not announce the
occurrence of the event.
The stop command with no stop_expr arguments prints the
list of user-specified stop expressions including the
event identifier and current status (active or
disabled).
[pattern]
symbols [-p proc_list] [-o object] [-n filename] [-dfgltuv]
The symbols command with no arguments displays ``local''
symbols; that is, names of variables which are defined
within the current function (%frame) and are visible
from the current location. This is also the behavior of
the -l option.
The -g option displays only the names of global
variables which are visible from the current location.
This includes only those symbols defined within the
current object (executable program or shared library).
The -o option, in conjunction with -g, displays the
names of global variables in the named object.
The -f option displays only the names of variables which
are local to the current file ( %file) and are visible
from the current location (%loc). If the -n option is
used, the symbols local to filename are displayed
instead.
The -d option displays the debugger built-in variables.
The -u option displays the debugger-maintained, user-
defined variables.
If a pattern is given, the display is further restricted
to symbols which match the pattern. sh(1) syntax is
used.
If the -v option is specified, the value of each symbol
is displayed, along with its name. The -t option
displays the type of the variable.
If more than one thread or process is specified by the
proc_list argument, the symbols request is performed in
the context of each object in turn.
Copyright 1994 Novell, Inc. Page 36
debug(1) debug(1)
syscall [-p proc_list] [[-eqx] [-c count] call ... [cmd]]
The syscall command, by default, applies to all threads
or processes derived from the current program. The
syscall command with no call arguments prints the
current list of user-specified system call actions,
including the event identifier and current status
(active or disabled), list of associated processes,
system call name and the beginning of any associated
command block.
Each call may be given as either a system call entry
number, or as the name used in the C language interface
to the call. The -e option specifies system call entry,
and is the default. The -x option specifies system call
exit. Both may be given on a single invocation of the
syscall command. For each call listed, the debugger
arranges for the specified objects to stop on entry to
or exit from that call, or on both entry and exit. The
resulting set of actions is then assigned a unique event
identifier.
The optional count specifies the number of times the
call must occur before the event triggers. After count
times, the event triggers each time the call occurs.
The -q option specifies that debug will not announce the
occurrence of the system call.
whatis [-p proc_list] expr
whatis prints the type of expr as evaluated in the
current context. expr can be any valid expression in
the current language.
If no proc_list is given, the type of expr is evaluated
in the context of the current thread or process.
Otherwise, it is evaluated for each object specified by
the proc_list, in turn.
If %db_lang is set to C++ and the expression given is a
pointer to a base class object with virtual functions,
if the debugger can determine that the type of the
object pointed to is a class derived from the base
class, whatis will print the names of both the base and
derived classes.
Copyright 1994 Novell, Inc. Page 37
debug(1) debug(1)
while (expr) cmd
This is the traditional conditional loop statement,
similar to that present in C, with the exception that
semicolons are not necessary, except to separate
multiple commands on a single line.
expr can be any valid expression in the current language
(see ``Expressions''). The expression is evaluated, and
if it evaluates to ``true'' in the semantics of the
current language, the cmd is executed. The expression
is then re-evaluated.
Unlike if, the while construct is often useful as a
top-level command.
Built-In Command Aliases
b stop
exit quit
h help
history fc -l
l list
n step -o
next step -o
ni step -io
p print
q quit
r run
rr fc -e -
s step
si step -i
sig signal
syms symbols
sys syscall
t stack
Summary of Built-In Variables
%db_lang The current language as determined from the
object file (read-only, thread specific).
%file The current file (read-only, thread
specific).
%follow Should debug follow child processes? Valid
values are none, procs, all (global).
Copyright 1994 Novell, Inc. Page 38
debug(1) debug(1)
%frame The current active stack frame. Affects
%db_lang, %func, %file, %line, %list_file,
%list_line, %loc (thread specific).
%func The current function. Affects %frame
(thread specific).
%global_path The list of directory pathnames used to
search for source files for all processes.
Searched after the program specific list
%path (global).
%lang The current language. Setting %lang
overrides the language as determined from
the object file and maintained in %db_lang
(global) .
%lastevent The id of the last event created (read-only,
global).
%line The current line (read-only, thread
specific).
%list_file The name of the file to be displayed by the
list command. Reset when the current
context changes (thread specific).
%list_line The number of the next source line to be
displayed by the list command. Reset when
the current context changes. Set to the
last line displayed by any invocation of
list (thread specific).
%loc The current location (read-only, thread
specific).
%mode Mode for command line editing (global).
Valid values are vi and emacs. Setting
%mode to NULL turns off command line
editing.
%num_bytes The default number of bytes printed by the
dump command (global).
Copyright 1994 Novell, Inc. Page 39
debug(1) debug(1)
%num_lines The default number of lines printed by the
dis and list commands (global).
%path The list of directory pathnames used to
search for source files for a given program.
Searched before the global list %global_path
(program specific).
%proc The current process (global).
%program The current program (global).
%prompt The string used by debug to prompt the user
for input; default is debug> (global).
%redir Should process I/O be redirected to a
pseudo-terminal for processes created by
debug? Valid values are 0, 1, no, yes
(global).
%result The result status of any debugger command.
0 indicates success, non-zero failure
(read-only, global).
%thisevent The id of the event whose associated command
list is currently being executed (read-only,
global).
%thread The current thread (global).
%thread_change Control debugger behavior when a thread
changes state (global).
%verbose Level of verbosity for event notification
(global). Valid values are quiet, source,
events, reason, all.
%wait Should threads and processes run in the
foreground or background? Valid values are
0, 1, background, foreground, no, yes
(global).
%register The processor registers.
Copyright 1994 Novell, Inc. Page 40
debug(1) debug(1)
DIAGNOSTICS
If debug is invoked with invalid arguments, it prints a
diagnostic message and exits with a non-zero exit status. If
the command-line processing fails for any other reason, debug
continues execution, allowing the user to enter requests
interactively. debug prints diagnostics for any failure in
processing user requests. The result status of each command
is recorded in the debugger variable %result. A value of 0
indicates successful execution; a non-zero value indicates
failure.
If debug cannot create or execute processes for any of the
commands specified in cmd_line, it acts as if the entire
cmd_line request had failed. In particular, any processes
that had been created as part of the same cmd_line request are
killed.
On the other hand, if debug cannot gain control of one or more
of the live_objects specified in the second form of
invocation, it continues to attempt to control the other
objects specified.
If debug is invoked with the -i x option and cannot start the
X Window based interface, it prints a diagnostic message and
exits with a non-zero exit status.
FILES
$HOME/.debug_hist command history log
$HOME/.debugrc defaults file
LIBDIR/debug_alias built-in alias definitions
LIBDIR/debug.ol.ui graphical interface
LIBDIR usually /usr/ccs/lib
/usr/lib/locale/C/MSGFILES/debug.str
default message file
/usr/lib/locale/locale/LC_MESSAGES/debug.str
language-specific message file
/usr/lib/locale/C/MSGFILES/debug.ui.str
X interface default message file
/usr/lib/locale/locale/LC_MESSAGES/debug.ui.str
X interface language-specific message
file
/usr/X/lib/locale/C/help/debug/*
help screens
/usr/lib/locale/C/MSGFILES/dbg.help.thr
default help messages
Copyright 1994 Novell, Inc. Page 41
debug(1) debug(1)
/usr/lib/locale/locale/LC_MESSAGES/dbg.help.thr
language-specific help messages
REFERENCES
cc(1), core(4), dlclose(3C), dlopen(3C), dlsym(3C), ed(1),
exec(2), fork(2), fprintf(3S), ksh(1), sh(1), strtol(3C),
thr_create(3thread)
Copyright 1994 Novell, Inc. Page 42