Warning: Low number of available file descriptors (256).  If the
program has too many threads, you might need to set the
mt_scalable option, or increase the hard limit on the number of
file descriptors.  See `help dbxenv' under mt_scalable.
# Copyright 06/23/98 Sun Microsystems, Inc. All Rights Reserved
#
# helpfile.dbx 1.326 98/06/23
# This is the dbx help file
# Written by Neil Smithline on Sun Sep 20 07:52:08 1992 by copying
# from dbx online help (the old printf mechanism).
#
# The file format is that:
#       comments begin with a `#' and are ignored.
#       #ifdef FOO, #endif works
#       topics begin with a `:topicname' on a line by itself
#       topics with subtopics are `:topicname$$subtopicname' on a line
#               by itself
#       one-line help (for the "commands" command) is `%cmd - helpstring'
#       CDE help-tag markup may be placed on a line that begins with `$'
# A `\' can be put at the beginning of a line and will escape the next
# character.
#
# CDE help-tag markup: use $<ex> ... $<\ex> for examples
#   use $<image> ... $<\image> for fixed format, but not typewriter font
#   use $<p indent> for an indented paragraph
#   use $<otherhead> or $<procedure> for headings
#   use $<newline> to force a newline
#   use $# to prefix text lines that should NOT appear in the CDE helpfile
#
# "See also" should start a separate line.
#
# The script is smart enough to recognize most lists.  For nested lists,
# the second level should use " o " for the bullet, not " * ".
#
# I18N - topicnames should not be translated unless immediately preceded by
# a comment line containing "I18N"
#
# I18N - do not translate any of the command names in this file. To generate
# a list of all dbx command names, run dbx and type
#
#        commands -all
#
# Try not to leave unintentional blank lines as they might end up
# in the output.  If you want to skip a line for clarity, make it
# a null comment.
#
# Tabs are expanded by the preprocessing step to avoid dependencies on
# the user's tab settings.  The filter assumes tabs are set every 8 columns.
#
# Top-level help, result of `help' with no arguments
:command$$summary

Use `commands' to see a command summary consisting of one-line
descriptions of each dbx command.

Execution and Tracing
  cancel       catch        clear        cont         delete       
  fix          fixed        handler      ignore       intercept    
  next         pop          replay       rerun        restore      
  run          runargs      save         status       step         
  stop         trace        unintercept  when         whocatches   

Displaying and Naming Data
  assign       call         dis          display      down       
  dump         examine      exists       frame        hide       
  print        undisplay    unhide       up           whatis
  where        whereami     whereis      which      

Accessing Source Files
  bsearch      cd           edit         file         files        
  func         funcs        line         list         loadobject   
  loadobjects  module       modules      pathmap      pwd          
  search

Debugging Multiple Threads
  lwp          lwps         sync         syncs        thread       threads 

Runtime Checking
  check        showblock    showleaks    showmemuse   suppress    
  uncheck      unsuppress

Miscellaneous
  attach       collector    commands     dalias        dbxenv
  debug        detach       document     help          history
  import       kalias       kill         language      mmapfile
  quit         setenv       sh           source        !
  !!

GUI Interface to dbx
  button       unbutton

Machine Level
  adb          examine      listi        nexti        registers    
  regs         stepi        stopi        tracei       wheni    

Language Specific Information Help Topics
  c++          fortran      fortran90    fortran77

# I18N (do not translate "alias", ".dbxrc", "-E", "FAQ", "forwardref",
# "ksh", "lwpid", "MT", or "tid" from the message below)

Other Help Topics
  alias           anachronisms  array-slicing  callbacks     changes
  changes301      changes31     changes32      changes40     changes50
  changes60       changes61     changes62      .dbxrc        dbx
  editing         environment   events         FAQ           fix-pitfalls
  follow-fork     format        forwardref     invocation    ksh
  lwpid           MT            optimized-code options       path
  prettyprint     redirection   registers      rtc           scope
  signals         startup       tid

The command `help <cmdname>' provides additional
help for each command or topic.  For new and changed features,
see `help changes', and `help FAQ' for
answers to frequently asked questions about dbx.

########################################################################
################################# Other Topics #########################
########################################################################
# I18N - translate this topicname to match same word in `Other Topics' message
:array-slicing (topic)
dbx supports array slicing in the `print' and `display' commands for
C, C++, and Fortran.

The array-slicing syntax for C and C++:

    print <arr-exp>[<first-exp>..<last-exp>:<stride-exp>]

where:

    <arr-exp> is an expression that evaluates to an array or pointer type,
    <first-exp> and <last-exp> are the first and last elements to be printed,
    <stride-exp> is the stride. 

<first-exp>, <last-exp>, and <stride-exp> are (optional) expressions that
 should evaluate to integers. <first-exp> and <stride-exp> default to
 0 and 1, respectively. <last-exp> is optional for array types and defaults 
 to its upper bound.

Examples:

(dbx) print arr[2..4]
arr[2..4] =
[2] = 2
[3] = 3
[4] = 4

(dbx) print arr[..2]
arr[0..2] =
[0] = 0
[1] = 1
[2] = 2

(dbx) print arr[2..6:2]
arr[2..8:2] =
[2] = 2
[4] = 4
[6] = 6


The array-slicing syntax for Fortran:

   print <arr-exp>(<first-exp>:<last-exp>:<stride-exp>)

where:
   
    <arr-exp> is an expression that should evaluate to an array type,
    <first-exp> and <last-exp> are first and last elements to be printed,
    <stride-exp> is the stride.

<first-exp>, <last-exp>, and <stride-exp> are (optional) expressions
 that should evaluate to integers. <first-exp> and <last-exp> default
 to the lower and upper bound, respectively. <stride-exp> defaults to 1.

Examples:

(dbx) print arr(2:6)
arr(2:6) =
    (2) 2
    (3) 3
    (4) 4
    (5) 5
    (6) 6

(dbx) print arr(2:6:2)
arr(2:6:2) =
    (2) 2
    (4) 4
    (6) 6

#
# I18N - translate this topicname to match same word in `Other Topics' message
:changes (topic)
The major new features of 7.0 (Forte Developer 7) relative to 6.2 are:

o The following dbxenv variables have been removed:
     aout_cache_size
     locache_enable
     delay_xs

  The aout_cache_size and locache_enable variables were used to control 
  when dbx would discard symbolic information from programs and 
  shared libraries.  The default behavior is now unchangeable, 
  dbx will discard symbolic information from an executable when
  a new executable is debugged, and libraries will be reused until
  they are updated on disk, or until the dbx session is terminated.

  The delay_xs variable was used to disable the demand-loading of 
  symbolic information from programs and shared libraries compiled 
  with the -xs flag, and force all the information to be loaded at 
  once. Demand loading is now on all the time.

  For help in dealing dbxenv variables and dbx version differences,
  see `help dbxenv'.

o There is a new `loadobject' command to control and list
  the symbols loaded by dbx.  See `help loadobject'.
  For example, `excluded' loadobjects are implemented differently.

o The default prompt will now be the last path component of
  argv[0] instead of the entire string in argv[0].  This fixes a bug
  where V9 dbx users who don't set PS1 would see "(.../mumble/foo/bar/dbx) "
  as their prompt instead of "(dbx) ".

o The new command-line option "-x exec32" has been added to suppress using
  64-bit dbx binary of systems which support SparcV9 binaries.

See also `help changes62'

:changes62 (topic)
The major new features of 6.2 (Forte Developer 6 update 2) relative to 6.1 are:

o The dbx environment variable "rtc_use_traps" has been removed. 
  Traps are used automatically as long as the hardware is UltraSparc.
o There is now some basic support for looking at core files from 
  different versions of Solaris. See `help core mismatch' for details.
o Stepping to a specific function support. See `help step to' for details.
o Fortran intrinsics support on Intel has been removed.
o Dbx automatically translates some old dbxenv variables to their new
  names. See `help dbxenv' for details.
o The default command-line editing mode is now emacs. See "How do I enable
  command-line editing?" in FAQ for details (`help FAQ').
o Two new collector commands have been implemented: `pause' and `resume'.
  See `help collector' for details.
o The collector enable_once command has been removed.
o The collector store command has been extended to include experiment groups.
  
See also `help changes61'

:changes61 (topic)
The major new features of 6.1 (Forte Developer 6 update 1) relative to 6.0 are:

o The dbx environment variable "cfront_demangling" has been removed. 
  The "-F" option to dbx (allow cfront-demangling) has also been removed.
  Use an earlier version of dbx to get cfront support.
o This release continues to support Fortran intrinsics on Intel, even
  though the Intel Fortran compiler was not shipped with WorkShop 6.
  The next dbx release will not support Fortran intrinsics on Intel.
  
See also `help changes60'

:changes60 (topic)
The major new features of 6.0 (WorkShop 6) relative to 5.0 are:

o The readonly ksh variable `firedhandlers' can be used in conjunction with
  `delete' and `handler' commands as an alternative to `clear'. (see
  `help handler' and `help delete').
o The `clear' command now facilitates partial clearing of individual
   breakpoints used by inclass, inmethod and infunction. (see `help clear').
o Output of traces can be redirected to files (see `help trace').
o New dbxenv variable `stack_find_source' to control whether dbx will
  automatically 'up' to a stack frame with source when the program stops.
  (see `help dbxenv' under `stack_find_source').
o New dbxenv variable `proc_exclusive_attach' to control whether dbx can
  attach to a process that is under the control of another debugger or
  debugging tool. (see `help dbxenv' under `proc_exclusive_attach').
o New dbxenv variable `step_granularity' to control whether `step' and `next'
  work on statements or whole lines. (see `help dbxenv' under
  `step_granularity').
o New dbxenv variable `mt_scalable' to help debugging multi-threaded
  applications with a great many LWPs. (see `help dbxenv' under
  `mt_scalable').
o Breakpoints in C++ inlined member functions work correctly. This includes 
  proper evaluation of handler conditions (-if).
o LWP related commands (see `help lwp' and `help lwps') are now always
  available, not just when debugging a multi-threaded application.
o When Control-C doesn't seem to stop a hung process, the third
  consecutive Control-C will force the process to stop by other means.
  (See `help interrupt').
o Full line number information is now recorded when you compile with -g -O.
  You can now 'step' and 'next' through optimized code, although the current 
  line will jump forward and back due to code scheduling.  The values of 
  variables printed from within dbx continue to be unreliable, in optimized
  code.

The following incompatibilities exist between this version and release 5.0:

o The old syntax for the trace command is no longer accepted. (see `help trace'
  for more information.)
o The dbxenv `mt_watchpoints' has been eliminated. Watchpoints are always
  allowed.
o Objective C is no longer supported.  Use release 5.0 to debug Objective C.

See also `help changes50'

:changes50 (topic)
The major new features of 5.0 (WorkShop 5.0) relative to 4.0 are:

o Even faster and more functional data watchpoints (see `help event watchpoint')
  (Solaris 2.6,2.7).
o New shell variables $machtype & $datamodel (see `help event variables').
o `pop -c' can be used to clean up after a `call' that failed (see 
  `help pop' and `help call').
o More functional, "extended", button command (see `help buttonx').
o Symbolic information of loadobjects can be skipped during startup (see
  `help loadobjects' and `help loadobject management').
o Symbolic information of loadobjects can be preloaded so that breakpoints
  may be placed in shared objects that will be dlopen()'ed in the future
  (see `help loadobjects' and `help loadobject management').
o New commands dealing with thread-level synchronization (locks) (see `help
  sync' and `help thread').
o The debugging information of modules compiled with -xs option is not 
  loaded during dbx start up anymore. Instead it is loaded on demand.
  This results in substantial startup speed improvements making the use
  of -xs less prohibitive. (see `delay_xs' in `help dbxenv').
o Dbx provides explicit control over whether unhandled and unexpected C++
  exception are intercepted. Previously they were always intercepted.
  (see `help intercept').
o Support for debugging of core files from remote hosts. (see
  `help loadobject exclusion').

The following incompatibilities exist between this version and release 4.0:

o Event specification modifiers without `-' are no longer accepted. See
  `help anachronisms'.
See also `help changes40'

:changes40 (topic)
The major new features of 4.0 (WorkShop 4.0) relative to 3.2 are:

o The Collector now supports MT applications (see `help collector mt')
o Runtime checking (RTC) is supported with fork/exec/attach (see `help
  rtc attach' for details)
o RTC has an API for tracing application specific allocators (see `help rtc api')
o New command `regs' to print current value of registers (see `help regs')
o New command `showblock' to give details about heap block (see 
  `help showblock')
o Enhanced `pathmap' command (see `help pathmap')
o New dbxenv variable `language_mode' (see `help dbxenv' under `language_mode')
o New dbxenv variable `output_inherited_members' (see `help dbxenv' under 
  `output_inherited_members')
o Two new dbx read-only variables: $helpfile and $helpfile_html (see
  `help help')
o New -v (verbose) flag to the `module' and `modules' commands 
  (see `help module' and `help modules')
o New +r flag to print and display commands (see `help print')
o Default value of dbxenv variable `scope_look_aside' has been changed
  to on (see `help dbxenv' under scope_look_aside and `help scope')
o New `inobject' event for support of `stop inobject <c++_obj_exp>'
  (see `help c++ inobject' and `help event specification')
o `inclass' event now supports template classes (see `help c++ inclass' and 
  `help event specification')
o `stop at <lineno>' now supports C++ template definitions as well as
  C++ inlined functions defined in header files (see `help event specification'
  under `at' event)
o Support for new C++ operators: `const_cast', `dynamic_cast',
  `reinterpret_cast', and `static_cast'
o Support for new C++ `typeid' operator 
o An HTML version of the help file is available (see `help help')

See also `help changes32'
# I18N - translate this topicname to match same word in `Other Topics' message
:changes32 (topic)
The major new features of 3.2 (SPARCWorks 3.1) relative to 3.1 are:

o  Objective C support
o  Fortran 90 support (see `help fortran')
o  Runtime checking (RTC) gives information about memory usage
   (see `help check' and `help showmemuse')
o  `whereis -a' shows symbolic name of address (see `help whereis')
o  Support for Pascal's `with' statement
o  SPARC V8+ support (see `help dbxenv' and `help registers')
o  Better support for stripped binaries
o  One-line descriptions of all commands (see `help commands')
o  dbx outputs and accepts the suffixes `U', `L', and `LL' to denote
   unsigned, long, and long long quantities.

See also `help changes31'.
# I18N - translate this topicname to match same word in `Other Topics' message
:changes31 (topic)
The major new features of 3.1 (SparcWorks 3.0.2) relative to 3.0.1 are:

o  Runtime Checking (RTC) now supports multi-threaded applications.
     See `help rtc mt'.
o  `adb' mode (see `help adb' for details)
o  Output format control (see `help dbxenv' under `output_base')
o  Array-slicing for C and C++ (see `help array-slicing')
o  Support for Fortran intrinsic functions.
o  `print' flags for $[] (see `help ksh expressions')
o  Printf-like output format control (see `help format')
o  Support for user-supplied pretty printing functions (see 
     `help prettyprint')
o  The `runargs' command (see `help runargs')

See also `help changes301'.
#
# I18N - translate this topicname to match same word in `Other Topics' message
:changes301 (topic)
The major new features of 3.0.1 relative to 2.0.1 are:

(1) New KornShell-like command interpreter (see `help ksh' for details)
(2) Support for multi-threaded programs (see `help MT')
(3) Better C++ support (see `help c++')
(4) Language expressions using $[] (see `help ksh expressions')
(5) More powerful event mechanism (see `help events')
(6) Fast data watchpoints (see `help event watchpoint')
(7) Automatic following of exec() and fork() (see `help follow-fork'
    and `help debug clone')
(8) Fix and Continue (see `help fix')
(9) Runtime Checking (see `help rtc', `help check', and `help showleaks')

The following incompatibilities exist between this version and release 2.0.1:

(1) The `address/format' command is now `x address/format'
(2) The `address=format' command is now `x address=format'
(3) The `/pattern' command is now `search pattern'
(4) The `?pattern' command is now `bsearch pattern'
(5) The `set' command is now the KornShell `set' command; use `assign'
(6) The syntax of the `modules' command has changed (see `help module' and
    `help modules')
(7) The core file is used only if explicitly requested
(8) Redirected output from `status' is no longer usable as input (see
    `help status')
#
#
:anachronisms (topic)
As dbx evolves, commands and syntax also evolve to new forms.
While an attempt is made to maintain backward compatibility, this is not
always possible. In such cases when dbx detects an older syntax it will
accept it but emit an "anachronism" warning message. This means that
in some future release of dbx the command or syntax will no longer be
accepted.

The following backward compatibilities are currently maintained:

o With release 4.0 of dbx the `trace' command was brought in line with the
  syntax used by `stop' and `when'. The BSD dbx style command syntax for
  `trace' is still accepted where possible. See `help trace' and `help tracei'.

o With release 4.0 of dbx the `use' command is mapped to the appropriate
  `pathmap' command. See `help use'.

o Release 4.0 of dbx switched to getopt() compatible command-line
  options, but old style cmdline options are still accepted.

o In release 3.2 of dbx, the -d option of the fix command was replaced with -f.

o Since release 3.0 the `stop' and `when' commands have been using a keyword,
  like `in' and `at', to distinguish events. If the keyword wasn't recognized,
  A <variable> or <expression> was assumed. With release 4.0 the
  keywords `cond' and `change' were introduced in order to phase
  out keywordless syntax for event specifications of the forms
  <variable>, <cond-expr>, but these forms are still accepted. See
  `help event specification'.

The following backward compatibilities are no longer supported:

o With release 3.0 of dbx the free-form English-like syntax of event
  specifications accepted by `stop' and `when' was regularized. See
  `help event specification'. All event specification modifiers now
  are to be prefixed with `-'. The following `-'less modifiers are no
  longer accepted:

        if <cond>
        in <func>
        <lwpid>
        <tid>
#
:.dbxinit (dbx topic)
Very old versions of dbx read a startup file called ".dbxinit" which used a
slightly different syntax.  Until recently dbx would still read those older
format files if it didn't find a ".dbxrc" file but it did find a ".dbxinit"
file.  Dbx no longer supports this.  If you still have a ".dbxinit" file that
you want to use you will need to update the syntax slightly and rename it to
".dbxrc".

You can simply change any "alias" commands to use "dalias" if you want to, or
you can change the syntax to match the new ksh-style 'alias' command.

In other words change `alias foo bar baz' to `dalias foo bar baz', or 
                      `alias foo bar baz' to `alias foo="bar baz"'

For some useful aliases and customizations you can look in `help .dbxrc'.




:.dbxrc (dbx topic)
\# To populate a new .dbxrc file with the contents of this help topic, 
\# use the command:
\#      help .dbxrc >$HOME/.dbxrc
\# To enable a useful set of options, use:
\#      help .dbxrc | sed 's/^##/  /' >$HOME/.dbxrc
\# Then:
\#      source $HOME/.dbxrc
\
\
\# The following section provides the typical entries in a .dbxrc file:
\
\#  set +o path              # uncomment this line to disable $PATH searching
\## set -o ignoresuspend     # uncomment to cause dbx to ignore ^Z
\## set -o emacs             # uncomment to enable emacs-style command editing
\#  set -o vi                # uncomment this line for vi-style editing
\## dbxenv output_short_file_name on  # print short pathnames for files
\## dbxenv scope_look_aside on # find file static symbols even when not in scope
\## dbxenv output_dynamic_type on  # cause `-d' to be the default for printing
\                                  # and displaying (C++)
\#  dbxenv stack_verbose off # suppress printing of arguments and line numbers
\                            # in `where' (improves performance)
\## button ignore step up    # add `step up' button to GUI
\
\# Enable dbx journaling to help Sun support personnel diagnose bugs
\# in the field.  If you are debugging on a sparcv9 machine running
\# a 64-bit kernel, uncomment the following two commands:
\#
\#  import /opt/SUNWspro/lib/v9/debugging.so >/dev/null
\#  log -default -start
\#
\# otherwise, uncomment these two commands:
\#
\#  import /opt/SUNWspro/lib/debugging.so >/dev/null
\#  log -default -start

\
\# Useful aliases:
\#
\## kalias alias=kalias         # ensure that KSH alias syntax is used
\## alias n=next
\## alias N=nexti
\## alias s=step
\## alias S=stepi
\## alias su="step up"
\## alias c=cont
\## alias p=print
\## alias q=quit
\## alias w=where
\## alias si="stop in"
\## alias sa="stop at"
\## alias sm="stop modify"
\## alias sr="stop returns"
\## alias sif="stop infunction"
\## alias sim="stop inmember"
\## alias sic="stop inclass"
\## alias en="handler -enable"
\## alias di="handler -disable"
\## alias wi=whatis
\## alias l=list
\## alias u=up
\## alias d=down
\## alias h=history
\## alias f=frame
\## alias goto="stop at !:1 -temp; cont"
\## button lineno goto
\
\# Useful functions:
\
\## function hex    # print arg in hex
\## {
\##     : ${1?"usage: $0 <expr>  # print <expr> in hex"}
\##     typeset -i16 x
\##     ((x = $[(int)$*]))
\##     echo - $* = $x
\## }
\## typeset -q hex
\
\## function pp # print pointer; print expression as symbolic
\## {           # address and hex value
\##     : ${1?"usage: $0 <expr> # print expr as symbolic address and hex value"}
\##     builtin examine $[(int)$*]/X
\## }
\## typeset -q pp
\
\## function offsetof  # print offset of $2 in type $1: offsetof strct fld
\## {
\##     : ${2?"usage: $0 <structname> <fieldname>  # offset of fld in struct"}
\##     [ -z "$3" ] || { echo "$0: unexpected argument" >&2 && return; }
\##     echo - $[(int)(&((($1*)0)->$2))]
\## }
\## alias off=offsetof
\
\## function environment  # dump the environment variables of the target process
\## {
\##     [ -z "$1" ] || { echo "$0: unexpected argument" >&2 && return; }
\##     typeset -i i=0
\##     typeset env="((char **)$[(char**)environ])"
\##     while :
\##     do
\##         x=$[($env)[$i]]
\##         echo "$i: " "${x#0x*\ }"
\##         case "$x" in
\##         *\(nil\)*)    break;;
\##         esac
\##         ((i += 1))
\##     done
\## }
\
\## function hexdump         # dump $2 (default: sizeof $1) bytes in hex
\## {
\##     : ${1?"usage: $0 <exp> [<size>]  # dump <size> bytes in hex"}
\##     typeset -i16 p="$[(void *)&$1]"                     # address of $1
\##     typeset -i s="${2:-$[sizeof ($1)]}" >/dev/null 2>&1 # number of bytes
\## 
\##     builtin examine $p/$[(${s:-4}+3)/4]X
\## }
\## typeset -q hexdump
\
\## alias hd=hexdump
\
\## button literal hexdump        # uncomment to install GUI button
\
\## if $havegui
\## then
\##     SMSO=                    # can't use reverse video in GUI
\##     RMSO=
\## else
\##     SMSO=$(tput smso)        # start standout mode (reverse video)
\##     RMSO=$(tput rmso)        # end standout mode
\## fi
\
\## PS1="$SMSO(dbx !)$RMSO " # reverse-video prompt with history number
\
\# Example of the _cb_prompt callback routine (see `help callbacks')
\
\# function _cb_prompt
\# {
\#     if $mtfeatures
\#     then    # set prompt for MT debugging
\#             PS1='${SMSO}${thread} ${lwp} <!>${RMSO} '
\#     else    # set prompt for non-thread debugging
\#             PS1='${SMSO}dbx<!>${RMSO} '
\#     fi
\# }
\
#
# I18N - translate this topicname to match same word in `Other Topics' message
:events (topic)
When an event occurs, dbx allows you to stop a process, execute arbitrary
 commands, or print information. The simplest example of an event is
a breakpoint. Examples of other events are faults, signals, system calls,
dlopen's and watchpoints.

The following commands create `handler's for events, each with a specific
side-effect:

        stop <eventspec>        # stop and prompt the user when the specified
                                # event occurs  
        when <eventspec> { <cmd> ; [ ... ] }
                                # execute commands when specified event occurs 
        trace <eventspec>       # Print a "trace" of the given event

For a complete list of events, their definitions and the <eventspec> syntax
accepted by the `stop', `when' and 'trace' commands, see
`help event specification'.

The above commands return the ID of the handler they create, <hid>. The ID
can be used in the following commands. `all' can usually be substituted
for <hid>.

status [ <hid> ]        # list the specified handler; all, if none specified
handler -disable <hid>  # disable the specified handler  
handler -enable <hid>   # enable the specified handler  
handler -reset <hid>    # reset <hid>'s counter (see `help event specification')
delete <hid>            # delete the specified handler  
clear <lineno>          # delete any handler on the specified line.
clear                   # shorthand for `clear $lineno'

See also `help event'.
# I18N - translate this topicname to match same word in `Other Topics' message
:finding-files (topic)
Dbx occasionally has trouble finding source and object files associated
with a program. Mechanisms, scenarios and workarounds follow ...

Mechanisms

By default symbolic information is stored in ".o" files. In order to
get at the source line information dbx has to find and load the ".o".
The location of the ".o" is recorded in an index in the executable.
This full pathname is recorded by the compiler and reflects the
compiler's idea of the working directory and full paths.

Not all symbolic information is stored in the executable to keep its
resulting size small.  If the old behavior is still desired, compile
the source with the compiler -xs flag and all symbolic information will
be copied into the executable

In past releases the time to load all of the symbolic information into
dbx was a problem. However, since version 5.0 , the information is
extracted on demand, making the initial load time as fast as the case
where -xs is not used.

Once the symbolic information is loaded dbx may want to show you source
lines and will attempt to open the source file corresponding to a ".o".
The correspondence of a source file and a ".o" is recorded in
the executable's index.

Dbx accesses object files based on the recorded full pathnames, but
with sourcefiles the user typically only wants to specify the basename
of the file:
        stop at test.cc:34
Dbx will search for this file in its internal database.

Failure scenarios and how to deal with them ...

o Source files have been removed.
  Not much to be done here. Dbx will not be able to show you the source
  but if it can get at the object files (or if -xs was used) you can get
  stack traces, print variable values and even know what line you're on.

o Object files have been removed.
  This is a bit worse because the bulk of symbolic information will become
  inaccessible. You can get around this by compiling your code using the 
  -xs flag.

o Source or object files have been moved (but not renamed).
  Use the pathmap command. For a thorough discussion see `help pathmap' but,
  in short, if a file has been moved from
        /home/jack/project/main.c
  to
        /home/jill/project/main.c
  issue "pathmap /home/jack /home/jill". Pathmap only works on the directory
  path, so if Jill had renamed "main.c" to "Main.c" pathmap cannot help.

o Symbolic links of directory names
  You compiled your code in 
        /home/jack/project
  but you are debugging it after having cd'ed through the soft link
        /company/projects/project-j -> /home/jack/project
  (Or the other way around). There should be no problems in either case.

o Symbolic links of file names
  If your project is laid out as follows
        .../proj/src/t.c
        .../proc/sparc/t.c -> ../src/t.c
        .../proc/intel/t.c -> ../src/t.c
  There should be no problems.
  However, if the name of the soft link is different from the name of 
  the actual file dbx will not be able to locate the source files in all
  cases. An example would be:
        .../proj/win/Toot.cpp
        .../proj/unix/toot.cc -> ../win/Toot.cpp
  In such cases the rule is "If you compiled with the soft link name, dbx
  will find the file by it's soft link name, and vice-versa".

o Source or object files being accessed from a different machine.
  The files are compiled on the machine 'bean' but Jack is debugging
  them from Jill's machine. The debugger will be looking for files
  under /home/jack/project which is inaccessible from Jill's machine.
  The solution, again, is pathmap used as follows:
        pathmap /home/jack /net/bean/home/jack

o Ambiguous source file name
  Your project is structured as follows:
        /home/professor/project/main/file.c
        /home/professor/project/module1/file.c
        /home/professor/project/module2/file.c
  or more commonly, suppose your app is made up of components maintained
  by different people:
        /home/jack/project/...
        /home/jack/project/test.c
        /home/jill/project/...
        /home/jill/project/test.c
  (In a large enough project this is unavoidable). Here if you issue
  "stop at test.c:35", dbx will pick a file at random.
  To solve this problem, note that dbx searches for file names using a
  a right-anchored best-match algorithm, so issue one of
        stop at main/file.c:50
        stop at jill/project/test.c

#
# I18N - translate this topicname to match same word in `Other Topics' message
:fix-pitfalls (topic)
        Fix and Continue Restrictions and Precautions
        ---------------------------------------------

You can modify sources in the following ways when using Fix and Continue:

 * Add, delete, or change lines of code in functions
 * Add or delete functions
 * Add or delete global and static variables


        Restrictions
        ------------

dbx might have problems when functions are mapped from the
old file to the new file. To minimize such problems when editing a
source file, be careful not to:

 * Change the name of a function
 * Add, delete, or change the type of arguments to a function
 * Add, delete, or change the type of local variables in functions
   currently active on the stack (see `pop' for more information)
 * Only the body of a C++ template function definition can be modified.
   Any changes to the declaration of a template or to template instances 
   requires a complete remake of the program
 * Fixing shared object files (.so) may require a change in the source
   of the a.out. Shared objects have to be dlopen'ed in a special
   mode (`RTLD_NOW|RTLD_GLOBAL' or `RTLD_LAZY|RTLD_GLOBAL') in order
   for Fix and Continue to work correctly.

        Precautions
        -----------

Resuming program execution after performing a Fix and Continue can
cause errors that may not be directly related to the actual
modifications to the source. Before resuming program execution after
you have modified the source, you should be aware of the following
conditions:

 * If a function being modified is already instantiated on the stack
   (not the top frame), the program executes the old code (the
   unmodified code) when returning to that frame.

 * Breakpoints in already instantiated functions on the stack in the
   old code are lost.

 * Changes made to global variables are not undone by the pop or fix
   command. Use `assign' to manually reassign correct values to
   global variables.

 * Values of static variables are normally retained across fixes.
   However, if the file was not originally compiled with debugging
   information, static variables in that file are reinitialized after
   each fix. Use `assign' to manually reassign correct values
   to static variables.

 * If the number of lines of source code are changed due to your edits, 
   the placement of the breakpoints might be incorrect. dbx warns you that
   the breakpoints have moved to a new line. You should check the locations
   of the breakpoints with the status command in the new code before running
   the program.

 * The program counter is moved to the beginning of the same line in
   the new (fixed) function. If the function has been modified, the
   program counter can end up at a wrong line. In that case, do one of
   the following:

        o Use the `pop' command. It pops one or more frames from the
          stack. Then `cont' to re-enter the function.

        o Use `cont at <linenum>' to continue from another
          line (effectively moving the pc before executing).

        o Manually repair data structures (using `assign')
          before continuing.

        o Rerun the program.

 * If you change a C++ template definition, you must issue the fix
   command on all files that define instances of that template.

# I18N - translate this topicname to match same word in `Other Topics' message
:forwardref (topic)
dbx correctly handles all forward references that are later defined in 
the current scope. For example, with the following code:

        struct foo;
        struct foo *fp;
        struct foo { /* stuff */ };

dbx allows you to dereference fp (eg: "print *fp"). If the forward reference
 is not defined in this scope dbx may have some problems handling the 
dereference. For example:

        struct bar;
        struct bar *bp;
        /* no further definition of struct bar */

dbx will not always be able to evaluate the command "print *bp". If
so, you can explicitly cast the pointer to a known type such as: 

        print *(`bar.cc`struct bar *)bp

where `bar.cc' is a file that defines struct bar. In C++ this can be
abbreviated to:

        print *(`bar.cc`bar *)bp

or, as an alternative, you can issue the command "module bar.cc"
and then all subsequent prints of type bar will be successful.
:follow-fork (command)

dbxenv follow_fork_mode ...     # When process executes a fork/vfork/fork1 ...
dbxenv follow_fork_mode parent  # ... stay with parent (default)
dbxenv follow_fork_mode child   # ... follow child
dbxenv follow_fork_mode both    # ... follow both parent and child (GUI only)
dbxenv follow_fork_mode ask     # ... ask which of the above the user wants

dbxenv follow_fork_inherit ...  # When following child ...
dbxenv follow_fork_inherit on   # ... inherit events
dbxenv follow_fork_inherit off  # ... don't inherit events (default)
See also `help dbxenv' under the variable named follow_fork_mode_inner
:optimized-code (topic)

When programs are compiled with optimization and debugging enabled
at the same time (-O -g), dbx operates in a restricted mode.

The details about which compilers emit which kind of symbolic
information under what circumstances is considered an unstable
interface and likely to change from release to release.

Source line information is available, but the code for one source line 
may appear in several different places for an optimized program, so
stepping through a program by source line will result in the "current line"
jumping around in the source file, depending on how the code was scheduled
by the optimizer.

Tail call optimization can result in missing stack frames when the last
effective operation in a function is a call to another function.

Generally, symbolic information for parameters, locals, and globals is
available for optimized programs.  Type information about structs, unions
and C++ classes, and the types and names of locals, globals and parameters
should be available.  The C++ compiler will not provide symbolic
type information about locals, but the C compiler will. 

Complete information about the location of these items in the program isn't 
available for optimized programs.

Global variables may be printed and assigned to as normal, although
they might have inaccurate values if the final register-to-memory store 
has not happened yet.

Parameters can only be printed if you're stopped at the very beginning
of a function, since the parameter registers can be re-used by the compiler.
The values of stack variables cannot be printed or manipulated in optimized 
programs because the stack and register locations of these variables aren't
recorded.

There is also a chapter related to compiler optimizations in the Forte
Developer Analyzer manual that might be helpful when debugging an optimized
program.
:optimization
                        # See `help optimized-code'.
#
# I18N - translate this topicname to match same word in `Other Topics' message 
:dbx
                        # See `help invocation'.
:options
                        # See `help invocation'.
:^C (topic)
See `help interrupt'
:interrupt (topic)
A running process can be interrupted using ^C. The process will stop on
a SIGINT and dbx will prompt. A `cont', `step' etc. will resume execution and
drop the SIGINT. To forward the SIGINT use "cont -sig int" or similar.

Under certain conditions you'll see the warning:
        warning: Interrupt ignored but forwarded to child.
When dbx and the debugged process are under the control of the same
terminal (the usual case when debugging outside of a gui and using `run')
a ^C is converted to a SIGINT that is passed to both dbx and the process.
Dbx ignores the SIGINT sent to it and eventually you will get a prompt when
the debugged process receives its SIGINT.

Occasionally a ^C is ineffective. This typically happens when debugging
multi-threaded applications or if SIGINT is blocked by the application. In
such situations a third ineffective ^C will cause dbx to try and stop the
process by other more intrusive means.

:invocation (topic)
dbx recognizes the following command-line options:

        -c <cmds>       # Execute <cmds> before prompting for input
        -C              # Preload the Runtime Checking library (see `help check')
        -d              # Used with -s, removes <file> after reading
        -f              # Force loading of core file, even if it doesn't match.
        -h              # Print the usage help on dbx
        -I <dir>        # Add <dir> to `pathmap' set (see `help pathmap')
        -k              # Save and restore keyboard translation state
        -q              # Suppress messages about reading stabs
        -r              # Run program; if program exits normally, exit
        -R              # Print the readme file on dbx
        -s <file>       # Use <file> instead of .dbxrc
        -S              # Suppress reading of site-specific init file
        -V              # Print the version of dbx
        -w <n>          # Skip <n> frames on `where' command.  
        -x exec32       # 32 bit mode.  
                          Suppress using the 64-bit dbx binary of systems which
                          support SparcV9 binaries.  Use the SparcV8/32-bit
                          binary instead.
        --              # Marks the end of the option list; use this if the
                        # program name starts with a dash

The following options are for debugging dbx:
        -e              # Echo each command before execution

If `-r' is used, the program's arguments follow the name of the program.
In all other cases, the program name must be last, or be followed by the
name of a core file or a process ID.

        dbx [options] <prog>              # Debug <prog>
        dbx [options] <prog> <core>       # Debug <prog> with core file <core>
        dbx [options] <prog> <pid>        # Debug <prog> with process ID <pid>
        dbx [options] - <pid>             # Debug process ID <pid>; dbx finds
                                          # the program via /proc
        dbx [options] - <core>            # Debug using core file <core>;
                                          # see also `help debug'
        dbx [options] -r <prog> <args>    # Run <prog> with arguments <args>;
                                          # if abnormal termination, start
                                          # debugging <prog>, else just exit

#
:core (topic)
A core file can be specified on the command line when dbx 
is started, or it can be supplied as an option to the `debug'
command once dbx is running.  That way the image of a process
which has crashed can be examined to find out why it crashed.
When a core file is specified, the executable can optionally be 
omitted by supplying `-' for the executable name.

Finding the binary
------------------

If a core file is named without a binary, dbx will attempt to 
extract the program name from the core file. Dbx may not find
the executable if its full path name is not available in the core file.
When long pathnames are used to run a program, sometimes the pathname
is truncated in the core file.  If this happens, just specify
the complete pathname of the binary when you tell dbx to load
the core file.

Truncated core files
-------------------

If you have problems loading a core file, the first thing to be aware
of is whether you have a truncated core file.  There is a shell
command to specify a maximum allowable size of core files.  If you
have this setting too low when the core file is created, then dbx will
have trouble reading the resulting truncated core file.  In the csh
shell, read about the `limit' command, in the sh and ksh shells, read
about the `ulimit' command.

If dbx complains about a truncated core file, the best thing to do
is to change the `limit' setting in your shell start-up file, re-source
the start-up file, then try to produce a fresh core file.

If the core file is incomplete, and it's missing the stack segment,
then stack retrace information won't be available.  If the
runtime linker information is missing, then the list of loadobjects
won't be available. In this case, you will also get an error message
about `librtld_db.so' not being initialized.  If the list of LWP's
is missing, then no thread information, lwp information or stack retrace
information will be available, and you will get an error saying
the program was not "active", if you run the `where' command.

When possible, dbx will tell you when a core file is truncated, and
how long it probably should have been.

Solaris compatability
---------------------

If you have problems loading a core file, another possible problem
is due to the core file being created on a different version of Solaris.
The best workaround is to run dbx on a system with the same OS and patch 
level as the system where the core file was created.

For information about support for core files that were dumped on 
versions of Solaris different from the current one, see `help core mismatch'

(see also `help debug' and `help invocation' and `help core mismatch')
#
:core$$mismatch (subtopic)
Support for this feature is subject to change in future releases of dbx.
The current implementation is considered clumsy.

== Here is an explanation of the problem:

Sometimes a core file is created on one system (the core-host) and
you want to load the core file on another machine (the dbx-host).  One
problem is the shared libraries used by the program on the core-host
won't be the same libraries as those on the dbx-host.  To get proper
stack traces involving the libraries, you'll want to make these original
libraries available on the dbx-host and use the options explained
below to tell dbx where to look for those libraries.  Another problem
is that dbx uses system libraries in /usr/lib to help understand the 
implementation details of the run time linker and threads library
on the system.  It may also be necessary to provide these system
libraries from the core-host so that dbx can understand the 
runtime linker data structures and the threads data structures.

The user libraries and system libraries can change in patches
as well as major Solaris upgrades, so this problem can even 
show up (for example) on the same host, if a patch was installed 
after the core file was collected, but before running dbx on the 
core file.

Here are some of the errors that might show up if you are looking at a 
mismatched core file.  Usually, only one or two of these will
show up at a time.

dbx: core file read error: address 0xff3dd1bc not available
dbx: warning: could not initialize librtld_db.so.1 -- trying libDP_rtld_db.so
dbx: cannot get thread info for 1 -- generic libthread_db.so error
dbx: attempt to fetch registers failed - stack corrupted
dbx: read of registers from (0xff363430) failed -- debugger service failed


== Here is how to use dbx on a mismatched core file:

1. turn on the `core_lo_pathmap' dbxenv variable.
2. use the pathmap command to tell dbx where the libraries are
3. use the debug command to load the program and the core file

The following example assumes that the root partition of the core-host
has been exported over NFS and can be accessed via /net/core-host/
on the dbx-host machine.

(dbx) dbxenv core_lo_pathmap on
(dbx) pathmap /usr      /net/core-host/usr
(dbx) pathmap /appstuff /net/core-host/appstuff
(dbx) debug prog prog.core

In the case where you aren't exporting the root partition of
the core-host, you will need to copy the libraries by hand.
It's not necessary to re-create the symbolic links. (For example,
you don't need to make a link from libc.so -> libc.so.1, just
make sure libc.so.1 is available.)

Things to remember:

 - The pathmap command doesn't recognize a pathmap for '/' so you
   can't currently say: "pathmap / /net/core-host"

 - The single-argument mode for pathmap doesn't work with loadobject
   pathnames, so use the two argument <from-path to-path> mode.

 - It is likely that things will work best if the dbx-host
   has a either the same or a more recent version of Solaris than the 
   core-host.  Although this is not always necessary.

 - The system libraries that might be needed are:
   For the runtime linker:
       /usr/lib/ld.so.1
       /usr/lib/librtld_db.so.1
       /usr/lib/sparcv9/ld.so.1
       /usr/lib/sparcv9/librtld_db.so.1
   For the threads library:
       /usr/lib/libthread_db.so.1
       /usr/lib/sparcv9/libthread_db.so.1
       /usr/lib/lwp/libthread_db.so.1
       /usr/lib/lwp/sparcv9/libthread_db.so.1
   Depending on which implementation of libthread you're using.
   The /usr/lib/lwp files should only apply to Solaris 8 and
   only if you are using the "alternate libthread" library.

   For the xxx_db.so libraries, you will need the 'sparcv9' versions 
   if dbx is running on a 64-bit capable Solaris, (If the command 
   'isalist' shows sparcv9) since these system libraries are loaded 
   and used as part of dbx, not as part of the target program.

   The ld.so.1 libraries are part of the corefile image just like
   libc.so or any other library.  So you need the sparc/sparcv9 
   flavor which matches the program that made the corefile.

 - If you are looking at a core file from a threaded program,
   and "where" doesn't show a stack, try using lwp commands like this.

   (dbx) where
   current thread: t@0
     [1] 0x0(), at 0xffffffff
   (dbx) lwps
   o>l@1 signal SIGSEGV in _sigfillset()
   (dbx) lwp l@1
   (dbx) where
   =>[1] _sigfillset(), line 2 in "lo.c"
     [2] _liblwp_init(0xff36291c, 0xff2f9740, ...
     [3] _init(0x0, 0xff3e2658, 0x1, ...
     ...
   
   The lack of a thread stack can indicate a problem with thread_db.so.1
   Therefore, you might also want to try copying the proper libthread_db.so.1
   library from the core-host (see above).


#
:env
                        # See `help environment'.
:environment (topic)
Certain environment variables affect dbx if defined at invocation time:

        TMPDIR          Use instead of /tmp on all dbx temp files

dbx specific environment variables have a "DBX_" prefix. The prefix "_DBX_"
 has been reserved for internal environment variable names. See 
`help ksh environment' and `help dbxenv'.
#
# I18N - translate this topicname to match same word in `Other Topics' message
:format (topic)
The `print', `rprint', and `display' commands and the `$[]' construct
take a flag (`-f' or `-F', see also `help print') which sets the output format
for integer, string, or floating point types. This format is used when dbx is
about to print an integer (long or short), string (char * or wchar_t *), or
floating-point (float, double, long double) expression.  That is, the expression
itself may be a structure or array; each integer, string, or floating-point
member will be printed using the given format, if applicable. If the format
does not apply to the given type, the format string is silently ignored and
dbx uses its built-in printing mechanism.

The allowed formats are a subset of those used by `printf(3S)'. The following
 restrictions apply:

      *  No `n' conversion.
      *  No `*' for field width or precision.
      *  No `%<digits>$' argument selection.
      *  Only one conversion specification per format string.

The allowed forms are defined by the following simple grammar:

        FORMAT  ::=  CHARS % FLAGS WIDTH PREC MOD SPEC CHARS
        CHARS   ::=  <any character sequence not containing a %>
                |    %%
                |    <empty>
                |    CHARS CHARS
        FLAGS   ::=  + | - | <space> | # | 0 | <empty>
        WIDTH   ::=  <decimal_number> | <empty>
        PREC    ::=  . | . <decimal_number> | <empty>
        MOD     ::=  h | l | L | ll | <empty>
        SPEC    ::=  d | i | o | u | x | X | f | e | E | g | G | 
                         c | wc | s | ws | p

If the given format string does not contain a %, dbx automatically prepends
one. If the format string contains spaces, semicolons, or tabs, the entire
format string must be surrounded by double quotes.

Examples:

(dbx) print i
i = 31
(dbx) print -fx i       ;# the format string may be concatenated with the -f
i = 1f
(dbx) print -f 0x%12.12X 1234
0x0000000004D2
(dbx) print -f "The value of 0x1000 is %o in octal" 0x1000
The value of 0x1000 is 10000 in octal
(dbx) print x/10.0       ;# compare with following
x/10 = 12.3
(dbx) print -F"10%% of x is %.2e" x/10.0  ;# suppress printing of left side
10% of x is 1.23e+01
(dbx) print -fx struct1  ;# it even applies to members...
struct1 = {
    x = 7b
}

#
# I18N - translate this topicname to match same word in `Other Topics' message
:prettyprint (topic)
If the `-p' flag is given to `print', `rprint', or `display', dbx invokes the 
ksh function `prettyprint', which searches for a function in the target process
with the name `db_pretty_print' that takes three arguments: a pointer to the 
type of the expression, an integer, and a char *:

        char *db_pretty_print(const Foo *, int flags, char *formatstring);

If found, dbx calls the function and prints (or displays) its return value;
if not found, dbx prints (or displays) the expression itself. The dbxenv
variable `output_pretty_print', if `on', causes `-p' to be passed as the
default; use `+p' to override this behavior for one command. 

`prettyprint' is defined in the system-wide dbx startup file (see `help startup').
 The value passed in the `flags' argument is bit-wise OR one of the following:

   FVERBOSE        0x1       not currently implemented, always set
   FDYNAMIC        0x2       -d
   FRECURSE        0x4       -r
   FFORMAT         0x8       -f (if set, "formatstring" is the <fmt> part)
   FLITERAL        0x10      -l

See `help print' for the meaning of these flags.
#
# I18N - translate this topicname to match same word in `Other Topics' message
:redirection (topic)
There are two classes of commands in dbx: redirectable and non-redirectable.
The non-redirectable commands take language expressions or patterns as 
arguments. Since the I/O redirection operators are also expression operators
 in the languages that dbx supports, any command that takes an expression treats
 the I/O operators as expression operators.

Examples of non-redirectable commands are: assign, bsearch, call, display, dump,
 examine, files, funcs, hide, print, run, rerun, search, stop, stopi, trace,
 tracei, undisplay, whatis, where, whereis, which.

To redirect commands, you can put the I/O redirection before the command keyword:

        (dbx) >foo print a > b

If you wish to pipe the output of a non-redirectable command, you can
wrap the command in curly braces:

        (dbx) { print *p; } | awk '/member[0-3]/ { print }'

Only dbx output may be redirected in this manner; output produced by the
 target process (via printf(), for example) still goes to the `stdout'
 of the target process:

        (dbx) >foo print printf("hello")

causes "hello" to appear on the terminal, and the file `foo' to contain

        printf("hello") = 5

which is the return value of the printf() call.

See the `typeset' command to find out how you can cause a ksh
function to be made non-redirectable (so it can accept language
expressions as arguments).

Note: Non-redirectable commands also do not recognize `#' as the start of
a comment. To add a comment to such a command, use `;#'.

Using some dbx commands in a pipe may have undesired results. Any command
 that modifies the state of the target process (or modifies dbx's information
 concerning the state of the target process) will not behave as expected in
 a pipe. Commands which should not be used in pipes include: alias, attach,
 bsearch, call, catch, check, clear, collector, cont, dbxenv, debug, delete,
 detach, display, down, fix, frame, func, handler, hide, ignore, import,
 intercept, kill, language, next, nexti, pathmap, pop, quit, replay, rerun,
 restore, run, save, search, set, setenv, step, stepi, stop, stopi, suppress,
 trace, tracei, unalias, uncheck, undisplay, unhide, unintercept, unsuppress,
 up, use, when, wheni.

To redirect these commands, use a temp file:

        (dbx) >/tmp/xxx call foo(); cat /tmp/xxx | sed 's/foo/FOO/'
#
# I18N - translate this topicname to match same word in `Other Topics' message
:registers (topic)

Register names are machine-specific. These names are reserved and may 
not be used as ksh environment variable names.

Use the following registers names in expressions:

On SPARC:
  $g0 $g1 ... $g7
  $o0 $o1 ... $o7
  $l0 $l1 ... $l7
  $i0 $i1 ... $i7
  $f0 $f1 ... $f31
  $pc $npc $y $psr $wim $tbr $fsr $fq $fp $sp

  The following pairs of floating-point registers are treated as having
  C "double" type (normally $fN registers are treated as C "float" type):

  $f0f1  $f2f3  ...  $f30f31
or
  $d0 $d2 ... d30

  The following quad floating-point registers are treated as having
  C "long double" type. They are available on SPARC V9 hardware:

  $q0 $q4 ... $q60


  The following pairs of registers which combine the least significant
  32-bits of two registers are available on V8+ hardware: 

  $g0g1 $g2g3 $g4g5 $g6g7
  $o0o1 $o2o3 $o4o5 $o6o7


  These additional registers are available on SPARC V9 and V8+ hardware:

  $xg0 $xg1 ... $xg7
  $xo0 $xo1 ... $xo7
  $xfsr $tstate $gsr
  $f32f33 $f34f35 ... $f62f63

On Intel:
  $pc $ps $fp $sp
  $gs $fs $es $ds
  $edi $esi $ebp $esp $ebx $edx $ecx $eax
  $trapno $err $eip $cs $eflags $uesp $ss
  $di $si $bp $SP
  $bx $dx $cx $ax
  $bl $bh $dl $dh $cl $ch $al $ah
  $ip $flags
  $st0 $st1 ... $st7
  $fctrl $fstat $ftag $fip $fcs $fopoff $fopsel

To print registers as hex numbers, use one of the following:

        print -fx $pc

        print (void *)$pc

See also `help regs'.
#
:regs (command)
%regs - Print current value of registers
regs [-f] [-F]          # Print value of registers
                        # -f: include floating-point registers (single precision).
                        # -F: Include floating-point registers (double precision)
                        #     SPARC only.

Example (SPARC):
dbx[13] regs -F
current thread: t@1
current frame:  [1]
g0-g3    0x00000000 0x0011d000 0x00000000 0x00000000
g4-g7    0x00000000 0x00000000 0x00000000 0x00020c38
o0-o3    0x00000003 0x00000014 0xef7562b4 0xeffff420
o4-o7    0xef752f80 0x00000003 0xeffff3d8 0x000109b8
l0-l3    0x00000014 0x0000000a 0x0000000a 0x00010a88
l4-l7    0xeffff438 0x00000001 0x00000007 0xef74df54
i0-i3    0x00000001 0xeffff4a4 0xeffff4ac 0x00020c00
i4-i7    0x00000001 0x00000000 0xeffff440 0x000108c4
y        0x00000000
psr      0x40400086
pc       0x000109c0:main+0x4    mov     0x5, %l0
npc      0x000109c4:main+0x8    st      %l0, [%fp - 0x8]
f0f1     +0.00000000000000e+00
f2f3     +0.00000000000000e+00
f4f5     +0.00000000000000e+00
f6f7     +0.00000000000000e+00
...

See also `help registers'.
# I18N - translate this topicname to match same word in `Other Topics' message
:scope (topic)
The scope is a subset of a program defined in terms of the visibility of a
 variable or function. A symbol is said to be "in scope" if its name is
 visible at the given point of execution. In C, functions may have global
 or file-static scope; variables may have global, file-static, or block scope.

In dbx, scope also refers to the point in the program where the
search for a given symbol begins. Normally, it is the same as the current
line, but several commands can change the current scope without causing
the point of execution to move:

        func
        file
        up, down, frame
        list <procedure>

To get the fully qualified name of a symbol, use:

        which <name>

To find all declarations of a name, use:

        whereis <name>

You can also use backquotes to give the scope of a name explicitly:

        print `file.c`func1`x
        print `file.c`func2:212`y       # "y" is declared in block at line 212
        stop in `libxx.so.1`func3       # func3 is declared in dyn. library xx
        stop in `file.c`func1
        stop in `file.c`classname::func2
        stop in ``func3                 # "func3" is extern or file static
        stop in `func4                  # "func4" is extern
        stop in #fun                    # "fun" is a linker symbol; dbx
                                          looks it up in global scope
                                          exactly as it appears
        stop in `file.c`#fun            # to search in file.c static scope for
                                          linker name "fun"

To relax the scope lookup rules for static symbols and C++ member functions, use:

        dbxenv scope_look_aside on

or use the "double backquote" prefix:

        stop in ``func4                 # "func4" may be static and not in scope


If scope_look_aside is turned on, dbx looks for:

- Static variables defined in other files if not found in 
  current scope. Files from libraries in /usr/lib are not searched.
- C++ member functions without class qualification
- Instantiations of C++ inline member functions in other
  files if a member function is not instantiated in current file.

#
# I18N - translate this topicname to match same word in `Other Topics' message
:signals (topic)
SIGHUP          1               # hangup
SIGINT          2               # interrupt (rubout)
SIGQUIT         3               # quit (ASCII FS)
SIGILL          4               # illegal instruction (not reset when caught)
        ILL_ILLOPC      1       # illegal opcode
        ILL_ILLOPN      2       # illegal operand
        ILL_ILLADR      3       # illegal addressing mode
        ILL_ILLTRP      4       # illegal trap
        ILL_PRVOPC      5       # privileged opcode
        ILL_PRVREG      6       # privileged register
        ILL_COPROC      7       # co-processor
        ILL_BADSTK      8       # bad stack
SIGTRAP         5               # trace trap (not reset when caught)
        TRAP_BRKPT      1       # breakpoint trap
        TRAP_TRACE      2       # trace trap
        TRAP_RWATCH     3       # read access watchpoint trap
        TRAP_WWATCH     4       # write access watchpoint trap
        TRAP_XWATCH     5       # execute access watchpoint trap
SIGIOT          6               # IOT instruction
SIGABRT         6               # used by abort, replace SIGIOT in the future
SIGEMT          7               # EMT instruction
        EMT_TAGOVF      1       # tag overflow
SIGFPE          8               # floating-point exception
        FPE_INTDIV      1       # integer divide by zero
        FPE_INTOVF      2       # integer overflow
        FPE_FLTDIV      3       # floating-point divide by zero
        FPE_FLTOVF      4       # floating-point overflow
        FPE_FLTUND      5       # floating-point underflow
        FPE_FLTRES      6       # floating-point inexact result
        FPE_FLTINV      7       # invalid floating-point operation
        FPE_FLTSUB      8       # subscript out of range
SIGKILL         9               # kill (cannot be caught or ignored)
SIGBUS          10              # bus error
        BUS_ADRALN      1       # invalid address alignment
        BUS_ADRERR      2       # non-existent physical address
        BUS_OBJERR      3       # object specific hardware error
SIGSEGV         11              # segmentation violation
        SEGV_MAPERR     1       # address not mapped to object
        SEGV_ACCERR     2       # invalid permissions
SIGSYS          12              # bad argument to system call
SIGPIPE         13              # write on a pipe with no one to read it
SIGALRM         14              # alarm clock
SIGTERM         15              # software termination signal from kill
SIGUSR1         16              # user defined signal 1
SIGUSR2         17              # user defined signal 2
SIGCLD          18              # child status change
SIGCHLD         18              # child status change alias (POSIX)
        CLD_EXITED      1       # child has exited
        CLD_KILLED      2       # child was killed
        CLD_DUMPED      3       # child has coredumped
        CLD_TRAPPED     4       # traced child has stopped
        CLD_STOPPED     5       # child has stopped on signal
        CLD_CONTINUED   6       # stopped child has continued
SIGPWR          19              # power-fail restart
SIGWINCH        20              # window size change
SIGURG          21              # urgent socket condition
SIGPOLL         22              # pollable event occurred
        POLL_IN         1       # input available
        POLL_OUT        2       # output possible
        POLL_MSG        3       # message available
        POLL_ERR        4       # I/O error
        POLL_PRI        5       # high priority input available
        POLL_HUP        6       # device disconnected
SIGIO           22              # socket I/O possible (SIGPOLL alias)
SIGSTOP         23              # stop (cannot be caught or ignored)
SIGTSTP         24              # user stop requested from tty
SIGCONT         25              # stopped process has been continued
SIGTTIN         26              # background tty read attempted
SIGTTOU         27              # background tty write attempted
SIGVTALRM       28              # virtual timer expired
SIGPROF         29              # profiling timer expired
SIGXCPU         30              # exceeded cpu limit
SIGXFSZ         31              # exceeded file size limit
SIGWAITING      32              # process's lwps are blocked
SIGLWP          33              # special signal used by thread library
SIGFREEZE       34              # special CPR signal
SIGTHAW         35              # special CPR signal
SIGCANCEL       36              # special signal used by thread library
SIGLOST         37              # resource lost
# New signal numbers may be added here in future releases of Solaris.
SIGRTMIN        *               # First real time signal
SIGRTMIN+1      *               # Second real time signal
...             *               # other real time signals
SIGRTMAX-1      *               # Next to last real time signal
SIGRTMAX        *               # Last real time signal

The '*'s used for the range SIGRTMIN through SIGRTMAX indicate that the
actual signal numbers are dynamic and may vary from one release of Solaris
to the next.
#
# I18N - translate this topicname to match same word in `Other Topics' message
:startup (topic)
First, if no `-S' flag was given, and if the file <install-directory>/lib/dbxrc
exists and is readable, dbx reads it. (The path to the site-specific
initialization file is derived from the path to the dbx executable.)

dbx searches for the file `.dbxrc' in the current directory, then in
\$HOME.  A different startup file may be given explicitly via
the `-s' command-line option. See `help .dbxrc' for a sample .dbxrc file.

A startup file may contain any dbx command. Most commonly, it contains
alias and function definitions. It may also `source' other files using the
`source' or `.' command (see `help source' and `help .'). The startup file is also a good
place to set various options via `set -o' and `dbxenv'.

#
:tid (topic)
Thread ID. The syntax `t@<number>' is used and accepted by various
commands to specify a thread. The number refers to the ID of the
thread as returned by thr_create(). `all', or `t@all' can sometimes
be substituted to refer to all threads.
#
# I18N - translate this topicname to match same word in `Other Topics' message
:callbacks (topic)
A callback is a ksh function that is automatically invoked by dbx
at certain points in the execution of the target. You can define
your own version of any of these functions to perform desired tasks as
necessary. The default versions do nothing. Currently, the following
callbacks are supported:

        _cb_aoutchange          _cb_prompt
        _cb_fix_comp            _cb_fix_link

See the help on the individual function name for details.
#
:_cb_aoutchange (callback)
_cb_aoutchange <old_a.out_name> <new_a.out_name>

This ksh function is invoked by dbx whenever the program being debugged
changes--the full path name is different. This is a good place to set
 a.out-specific breakpoints.

For example:

        _cb_aoutchange() {
                case "$2" in
                *producer)      stop in make_some_more ;;
                *consumer)      stop in get_another_one ;;
                esac
        }
#
:_cb_prompt (callback)
_cb_prompt

This ksh function is invoked by dbx immediately before it prints the top
level prompt (PS1). This is a good place to set PS1 so that it reflects
the current state of the process. _cb_prompt receives no arguments.
#
:_cb_fix_comp (callback)
_cb_fix_comp <compilation_arguments>

This ksh function, if defined, is invoked by dbx instead of calling the 
compiler directly during a `fix'.  This is a good place to customize the
 compilation line by adding or changing options, modifying paths, etc.
 Use with caution.

For example:

        _cb_fix_comp() {
            echo $*
            eval $*
        }

This just echoes and executes the compilation line without modifications,
whereas:

        _cb_fix_comp() {
            eval "$(echo $* | sed -e 's! -g0 ! -g !')"
        }

replaces `-g0' with `-g' to turn off C++ front-end inlining when the
compiler is run.

The arguments of this function are from the original, unmodified
compilation line, plus some options added internally for use by dbx.

See also `help _cb_fix_link'.
#
:_cb_fix_link (callback)
_cb_fix_link <linker_arguments>

This ksh function, if defined, is invoked by dbx instead of calling
the linker directly during a `fix'. This is a good place to customize
the link line by adding or changing options, modifying paths, etc. Use
with caution. This link creates a shared object which is dlopen'd
into the target process. It does *not* modify the a.out.

For example:

        _cb_fix_link() {
            echo $*
            eval $*
        }

echoes and executes the link line.

See also `help _cb_fix_comp'.
#
:event
Subtopics for `help event <subtopic>':

specification           Description of all recognized event specifications.
fault                   Fault specifications.
sig                     Signal specifications.
variables               Built-in variables which are related to events.
watchpoint              Watchpoints.
resumeone               Conditional breakpoints in multi-threaded applications.

See also `help events'.
#
:resumeone (topic)
Consider the following conditional breakpoint

        stop in lookup -if strcmp(name, "troublesome") == 0

Suppose that it is set in a multithreaded application where many
threads call lookup(). When t@1 hits lookup(), dbx will attempt to
evaluate the condition and will call 'strcmp()'. When calling 'strcmp()'
dbx has two choices.

1) Resume only t@1. This is liable to cause a deadlock if 'strcmp()' tries
   to grab a lock that is owned by another thread. Now strcmp() is unlikely to
   do that but dbx can't tell, the user could've put in some other function.
   So, to avoid deadlock, dbx ...

2) Resumes all threads for the duration of the call. This is a strategy
   similar to what dbx does when 'next'ing.

The resume all approach might have some unusual side-effects if the
conditional expression is accessing global data that is being mutated
by other threads. It is assumed that the called functions are
relatively local, atomic and side-effect free and furthermore that the
user can ascertain this.

The same cannot be said with respect to a function being a deadlock risk.
Deadlocks can occur more frequently that you would expect. For example ...

- The condition might be a C++ expression with overloaded operators containing
  hidden function calls. An innocuous "-if bag[i]" might be referring to
  the STL 'map' collection which is MT safe and contains a mutex!

- The function call might contend for a common lock in the dynamic linker.
  For example, if memcmp() is used it turns around and calls a platform
  optimized memcmp() (in "libc_psr.so") through the dynamic linker.

- A signal might arrive and invoke a signal handler which might contend
  for a lock.

This is why dbx takes approach (2).

There is one drawback to the resume all strategy which is that dbx at
present cannot handle another thread, say t@2, hitting the breakpoint
at lookup(), while strcmp() is being called. It will emit a warning
like this:
        event infinite loop causes missed events in following handlers:
or
        Event reentrancy
        first event BPT(VID 6, TID 6, PC echo+0x8)
        second event BPT(VID 10, TID 10, PC echo+0x8)
        the following handlers will miss events:

In such cases if you can ascertain that the function called in the
conditional expression will not grab a mutex, you can use the -resumeone
event modifier to force dbx to use strategy (1):

        stop in lookup -resumeone -if strcmp(name, "troublesome") == 0

Only the thread that hit the breakpoint in 'lookup()' will be resumed
in order to evaluate strcmp().

Note that this will not help in all cases. For example ...
- If the second breakpoint on lookup() happens in the same thread because
  the conditional recursively calls lookup().
- If the thread on which the conditional runs yields, sleeps or in some
  manner relinquishes control to another thread.

#
:eventspec
See `help event specification'

:event$$spec
See `help event specification'

:event$$specification (topic)
An event specification is used by the event management commands stop, when,
and trace to specify an event of interest. It has the following general syntax:

        <keyword> [ <arg> ] [ <modifier> ... ]  

The keyword specifies the kind of event; the most common being `at' and `in'.
Certain events take additional arguments as demonstrated below.
Modifiers begin with a `-' and may be applied to all event types and commands.
However, some commands and or events also accept non-generic modifiers.

The following list of predefined events was introduced pre-SPARCworks 3.1:

        in <func>       # entry into <func>
        at <line>
        at <filename>:<line>
                        # <line> is about to be executed
                        # Sometimes dbx has problems setting a breakpoint
                        # at a specific line in header files (in C++ inline
                        # functions or template definitions) if debugging
                        # information has not been read for at least one
                        # instance of the function. If dbx cannot set the
                        # breakpoints, do a `func <name_of_function>' to
                        # force dbx to read the debugging information, and
                        # try to re-type the command.

        inmethod <func> # entry into any method named <func>
        inmember <func> # an alias of `inmethod'
        infunction <func>
                        # entry into any overloaded version of <func>   
        inclass <classname> [ -recurse | -norecurse ]
                        # entry into any method of <classname> where
                        # <classname> is a C++ struct, union, class, or
                        # template class. 
                        # -norecurse is the default
                        # If -recurse is given, it includes the base classes.
        inobject <object_address>  [ -recurse | -norecurse ] 
                        # entry into any non-static method of the
                        # class and all its baseclasses when called
                        # from the object. <object_address> should evaluate
                        # to the address of a C++ object.
                        # -recurse is the default.
                        # If -norecurse is given, it does not include 
                        # base classes. 

The following list of predefined events was introduced in SPARCworks 3.0:

        modify <addr-expr> [ , <byte-size-expr> ]
                        # The given address range has been written to (see   
                        # `help event watchpoint'). Any expression can be used
                        # for <addr-expr> but it has to evaluate to an address.
                        # See `help event watchpoint' for more information.
        step            # A single step has occurred
                        # Specifying this event implicitly turns on stepping.  
        next            # A next has occurred  
        sig <sig>       # The specified signal has been intercepted (see    
                        # `help event sig') 
        sig <sig> <code>
                        # The signal with the given signal sub-code has been
                        # intercepted (see `help event sig' for more info)
        fault <fault>   # The specified fault has been intercepted (see 
                        # `help event fault') 
        throw           # A C++ exception has been thrown
        throw <type>    # A C++ exception of type <type> has been thrown
                        # -unhandled or -unexpected may be used for <type>
                        # (see `help intercept' for more information)
        stop            # The process has stopped; user is about to get prompt
        attach          # An attach operation has just completed
        sync            # The target process has just execed and synchronized
                        # with dbx. `stop sync' is ineffective, although you
                        # can still use `when sync'
        syncrtld        # rtld has run and all loadobject symbols have been
                        # loaded by dbx. Same restriction regarding `stop'
                        # applies as with the `sync' event.
        lastrites       # The process is about to expire
        dlopen          # A set of loadobjects has been loaded
        dlopen [ <lib-path> ]   
                        # The specified loadobject has been loaded. The full
                        # path name of the library has to be quoted for <lib-path>.
        dlclose ...     # Similarly for dlclose.
        exit [ <exitcode> ]     
                        # The process has exited with any exit value, or
                        # the specified one. <exitcode> has to be a decimal.
        sysin           # The process has entered a system call.
        sysout          # A system call has returned.
        sysin <code>|<name>
        sysout <code>|<name>
                        # Entry to or return from the system call of the given
                        # number or name.  See <sys/syscall.h> for list of
                        # system calls.
        returns <func>  # The specified function has returned.
        returns         # The current visiting function has returned.

The following list of predefined events was introduced in dbx 4.0:

        detach          # Complements `attach'
        lwp_exit        # Notifies of the demise of any lwp. The
                        # lwp associated with the event will be given in $lwp
        proc_gone       # Fires when dbx is no longer associated with a debugged
                        # process. The event variable $reason can be: signal, 
                        # exit, kill, or detach.
        prog_new        # Fires when a new program is loaded into dbx. This
                        # occurs during the debug command or when follow-
                        # exec occurs. Since all handlers get deleted across 
                        # debug, it only makes sense to create this handler
                        # with the -perm modifier
        timer <seconds> # The debugee has been running for <seconds> realtime
                        # seconds. <seconds> is a floating-point number.
                        # dbx's single interval timer is also shared by the
                        # data visualizer and the Collector commands. Using one
                        # of these features excludes the others.
        change <variable>
                        # Value of <variable> has changed.
        cond <cond-expr># Condition has changed. Any expression can be used
                        # but it has to evaluate to an integral type.

The following list of predefined events was introduced in dbx 5.0:

        access <mode> <addr-expr> [ , <byte-size-expr> ]
                        # The given address range has been accessed.
                        # Any expression can be used for <addr-expr> but it has
                        # to evaluate to an address.
                        # <mode> can be composed of one or all of the letters
                        # `r' (read access)
                        # `w' (write access)
                        # `x' (access for the purpose of execution)
                        # <mode> can also contain one of
                        # `a' (stop after access occurred. default)
                        # `b' (stop before access occurred)
                        # See `help event watchpoint' for more information.

For backward compatibility, the following syntactical variations of
eventspecs (note that they lack the `keyword') are accepted although
they are considered anachronistic and will be eliminated in future releases.

        <variable>      # Value has changed. Use `change <variable>' instead.
        <cond-expr>     # Condition has changed. Any expression can be used
                        # but it has to evaluate to an integral type. Use
                        # `cond <cond-expr>' instead.

The following is a list of generic eventspec modifiers:

        -if <cond>      # Event only fires when the <cond> `filter' is true.
                        # Any expression can be used for <cond> as long as 
                        # it evaluates to an integral type.
        -resumeone      # A modifier for -if. Will resume only one thread if
                        # <cond> contains function calls. See `help resumeone'
                        # for further details.
        -in <func>      # Event only fires if it occurs in function <func>.
        -disable        # Create the event in the disabled state.
        -count <n>      # Count up from 0; event fires and counter is reset
                        # to 0 when <n> is reached.   
        -count infinity # Count, but don't fire.
        -temp           # A temporary event, deleted when fired.
        -instr          # Do instruction level variation. For example,
                        # `step' becomes instruction level stepping, and `at' 
                        # takes a text address for an argument instead of   
                        # a line number.    
        -perm           # Make this event "permanent" across `debug'.
                        # Certain events (like breakpoints) are not appropriate 
                        # to be made permanent. `delete all' will not delete 
                        # permanent handlers, use `delete <hid>'.
        -hidden         # Hide the event from the `status' command. Some
                        # import modules may choose to use this. Use `status -h'
                        # to see them.

        -lwp <lwpid>    # Event only fires if it occurs in the given LWP. 
        -thread <tid>   # Event only fires if it occurs in the given thread.

The following is a list of command and event specific eventspec modifiers:

        -nosrc          # Applicable to: "trace step" only.
                        # See `help trace' for specifics.
        -nocalls        # Applicable to: "trace step" only.
                        # See `help trace' for specifics.

For backward compatibility, the following syntactical variations of
eventspec modifiers are also accepted, although they are considered 
anachronistic and will be eliminated in future releases.

        if <cond>       
        in <func>       
        <lwpid>
        <tid>
#
#
#
:event$$sig (topic)
Signal specification. You can use a decimal number and the signal name in
uppercase or lowercase, optionally prefixed by `sig', such as:

        11 segv SEGV sigsegv SIGSEGV    

A signal sub-code can be added. You can use a decimal number, the sub-code
 name in uppercase or lowercase. The prefix consisting of the signal name 
and an `_' can be dropped.

        3 fltdiv FLTDIV fpe_fltdiv FPE_FLTDIV

For a list of signals and their sub-codes, use `help signals'.
:event$$fault (topic)
Hardware fault specification. You can use a decimal number, the fault name in
uppercase or lowercase, optionally prefixed by `flt', such as:

        8 izdiv IZDIV fltizdiv FLTIZDIV 
#
:watch
See `help event watchpoint'
:modify
See `help event watchpoint'
:access
See `help event watchpoint'
:event$$watchpoint (topic)

There are two generations of watchpoint mechanisms available under dbx.

1) Use:

        stop|when|trace access <mode> <addr-exp> [ , <byte-size-exp> ]

<mode> specifies what kind of access is to be watched for:
        r       read, memory loads
        w       write, memory stores
        x       execute, execution of code
At least one of the above has to be specified for <mode>.

Additionally one of the following may be used:
        b       stop _before_ the access
        a       stop _after_ the access (default)
In both cases the program counter will point to the relevant instruction.
The before or after refers to the side-effect.

<addr-exp> is any expression that can be evaluated to produce an address.
If a symbolic expression is used the size of the region to be watched is
automatically deduced, or you can override that with the `,' syntax. 
You can also use non-symbolic, typeless address expressions in which case
the size is mandatory, such as:

        stop access w 0x5678, sizeof(Complex)

This mechanism is mostly implemented in the kernel (see proc(4) under PCWATCH
for more details) and offers the following advantages over the older
mechanisms:
        * significantly faster.
        * unlimited number of watchpoints.
        * works properly with multi-threaded applications.
        * works on stack addresses.
        * a watchpoint can be set on an address that is not mapped yet.
        * can detect accesses made by system calls.
        * shared memory can be watched.

The following limitations exist:
        * No two watched regions may overlap.

The older syntax ...
        stop|when|trace modify <addr-exp> [ , <byte-size-exp> ]
Is still accepted for backward compatibility and will map to the appropriate
"stop access" command.

2) Use:

        stop|when|trace cond <cond-expr>
        stop|when|trace change <variable>

These automatically single-step the program and check for the given condition
or change.
Because of the single-stepping they are very slow and do not apply to
multi-threaded applications.

:event$$variables (topic)
The following read-only predefined variables represent the current state
of dbx. They are always valid. They follow the current LWP or thread.
        $ins            # disassembly of the current instruction        

        $lineno         # current line number in decimal
        $vlineno        # current `visiting` line number in decimal
        $line           # contents of the current line

        $func           # name of the current function
        $vfunc          # name of the current `visiting' function.
        $class          # name of the class to which $func belongs.
        $vclass         # name of the class to which $vfunc belongs.
        $file           # name of the current file
        $vfile          # name of the current file being visited.
        $loadobj        # similarly for loadable object
        $vloadobj       # ...
        $scope          # The scope of the current PC in back-quote notation.
        $vscope         # ...

        $funcaddr       # Address of $func in hex
        $caller         # name of the function calling $func

        $newhandlerid   # The event ID of the handler most recently created.
        $firedhandlers  # The list of handler ids that caused the most recent
                        # stoppage. The handlers on this list are marked with 
                        # a '*' in the `status' command.

        $proc           # The process ID of the current process being debugged.
        $lwp            # The LWP ID of the current LWP (MT only)
        $thread         # The thread ID of the current Thread (MT only)

        $prog           # The full path-name of the loaded program.
        $oprog          # Previous value of $prog. Very useful after
                        # follow-exec, when $prog reverts to "-".
        $dllist         # list of all load objects last dlopen'ed or dlclose'd.
        $exception      # a pointer to the current C++ exception, or 0 if none

        $exitcode       # The exit status from the last run of the program.
                        # This value is an empty string if the process hasn't
                        # actually exited.

        $machtype       # If a program is loaded returns its machine type:
                        # sparcv8 sparcv8+ sparcv9 intel
                        # Otherwise will return 'unknown'
        $datamodel      # If a program is loaded returns its data model:
                        # ilp32 lp64
                        # Otherwise will return 'unknown'
                        # 
                        # To find the model of the program you've just loaded
                        # use the following in your .dbxrc:
                                when prog_new -perm {
                                        echo machine: $machtype $datamodel;
                                }

The following are only valid within the body of a WHEN:

        $handlerid      # During the execution of the body $handlerid is the
                        # ID of the WHEN command to which the body belongs.

        $booting        # Is set to `true' if the event occurs during the 
                        # "boot" process. Whenever a new program is debugged,
                        # it is first booted so that the list and location of
                        # shared libraries can be ascertained. The process is
                        # then killed.
                        # While booting happens "behind the users back",
                        # contributing to the "Reading symbolic information
                        # for libc.so.1" messages, all events are still
                        # available. Use this variable to distinguish, for
                        # example, the `sync' and the `syncrtld' events 
                        # occurring during a `debug' and the ones occurring 
                        # during a normal `run'.

The following are only valid within the body of a WHEN and are event specific.

For event sig:

        $sig            # signal number that caused the event
        $sigstr         # name of $sig
        $sigcode        # subcode of $sig if applicable
        $sigcodestr     # name of $sigcode
        $sigsender      # pid of sender of the signal if relevant, 0 otherwise

For event exit:

        $exitcode       # argument passed to exit(). This value is also valid 
                        # outside a WHEN body. See above.

For event access:

        $watchaddr      # The address being written to, read from or executed.
        $watchmode      # One of "rwx" for read, write or execute
                        # followed by one of "ab" for after or before.

For events sysin and sysout:

        $syscode        # system call code
        $sysname        # system call name as defined in <sys/syscall.h>

For events dlopen and dlclose (only if a param was provided):

        $dlobj          # loadobject that cause the event

For event proc_gone:

        $reason         # reason the process went away. Can be `signal',
                        # `exit', `kill', or `detach'

#
:MT (topic)
dbx has several commands to deal with multithreaded programs.
See the following help topics for more information:

        threads thread lwps lwp

In addition, many commands take thread or LWP qualifiers.

See the following help topics for more information:

        cont step events `event specification' mtfeatures where

Or use `help -k <keyword>' to find help topics that mention the word <keyword>.
#
########################################################################
########################### Dbx Commands ###############################
########################################################################
:! (ksh command)
!!                     # Execute previous command
!<num>                 # Execute command number <num>
!-<num>                # Execute current command-number minus <num>
!<str>                 # Execute most recent command starting with <str>

Modifiers:             # Append these tokens to modify the the above commands
\:s/<l>/<r>/           # Substitute modifier: Substitute <r> for <l>
\:p                    # Print modifier: Print but do not execute the command

Abbreviations:
^<l>^<r>^              # Quick substitution: Substitute <r> for <l> then
                       # re-run the last command typed.
#
:!!
See `help !'
#
:adb (command)
%adb - Execute an `adb-style' command or enter `adb' mode
adb <adbcmd>            # Execute an `adb-style' command
adb                     # Enter `adb' mode; use `$q' to exit adb mode

                        # The first time the `adb' command is given, it
                        # dynamically loads a shared object which implements
                        # the command. For detailed help on `adb-mode',
                        # enter an adb command, then try `help' again:

                            (dbx) adb $q
                            Searching for libdbxadb.so...
                            Redefining adb
                            (dbx) help adb
                            ...
#
:alias (topic)
`alias' is an alias for either `dalias' or `kalias'. Type `alias alias' to
find out which, then see either `help kalias' or `help dalias'
as appropriate. The default is `kalias'.  `dalias' is used to provide compatibility
with older .dbxinit startup files.  See `help .dbxinit'.
#
:assign (command)
%assign - Assign a new value to a program variable
assign <var> = <exp>   # Assign the value of the <exp> to <var>
#
:attach (command)
%attach - change the program being debugged
attach <pid>                  # Begin debugging <prog> with process ID <pid>.
                              # dbx finds <prog> using /proc.
attach -p <pid> <prog>        # Begin debugging <prog> with process ID <pid>.
attach <prog> <pid>           # Begin debugging <prog> with process ID <pid>.
                                <prog> may be `-'; dbx finds it using /proc
attach -r ...                 # The `-r' option causes dbx to retain all 
                                display's, trace's, when's, and stop's.
                                With no `-r' option, an implicit `delete all'
                                and `undisplay 0' is performed.
#
:bsearch (command)
%bsearch - Search backward in the current source file
bsearch <string>       # Search backward for <string> in the current file
bsearch                # Repeat search, using the last search string
#
:button (command)
%button - Define a new button for the Custom Button window of the GUI.
button <seltype> <cmd>      # Define a software button

where selection type, <seltype>, is:

                   ignore    # Ignore the selection
                   literal   # Take the selection literally
                   lineno    # Lineno from the source window

This command is silently ignored unless dbx is running under the GUI. 

See also `help unbutton'.

#
:buttonx (command)
%buttonx - Define a new button for the Custom Button window of the GUI.
buttonx <seltype> <name> <cmd>       # Define an extended software button

where selection type, <seltype>, is:
                   ignore    # Ignore the selection
                   literal   # Take the selection literally
                   lineno    # Lineno from the source window

<name> is the name of the button. The name may contain spaces in which case you
have to quote the name. The name is used as the key searched by `unbutton'.

<cmd> is any dbx command, ksh function or even a mini-script. It should
probably be quoted if its more than one word.

This command is silently ignored unless dbx is running under the GUI. 

In order for the dbx startup script to work properly with all versions
use something like this:
        dalias goto "stop at !:1 -temp; cont"
        if [ ${versionno:-3} = "5.0" ]
        then
                buttonx lineno  "GoTo" goto
        else
                button lineno  "goto"
        fi

See also `help unbutton'.

#
:call (command)
%call - Call a procedure
call <proc>([params])  # Call the procedure

While you can also call functions, in order to see the return value use the
print command.
Occasionally the called function hits a breakpoint. You can choose to 
continue using `cont', or abort the call by using `pop -c'. The latter
is useful also if the called function causes a SEGV.
#
:cancel (command)
%cancel - Cancel the current signal
cancel                  # Cancel the current signal. Primarily used 
                        # within the body of a WHEN
Signals are normally cancelled when dbx stops because of a signal.
If a `when' command is attached to a signal event, the signal is *not*
automatically cancelled.  The `cancel' command can be used to explicitly
cancel the signal.
#
:catch (command)
%catch - Catch the given signal(s)
catch                   # Print a list of the caught signals
catch <num> <num>...    # Catch signal(s) numbered <num>
catch <sig> <sig>...    # Catch signal(s) named by <sig>
                        # SIGKILL cannot be caught or ignored.
catch $(ignore)         # Catch all signals.
Catching a given signal causes dbx to stop the program when the process
receives that signal.  If you continue the program at that point,
the signal will *not* be processed by the program.
See also `help ignore' and `help cancel' and `help cont' under the -sig option.
#
:clear (command)
%clear - Clear breakpoints
clear                  # Clear all breakpoints at the current stopping point
clear <line>           # Clear all breakpoints at <line>
clear <filename>:<line># Clear all breakpoints at <line> in <filename>

Event handlers created using "stop|trace|when inclass|inmethod|infunction ..."
create sets of breakpoints. If the line given to `clear' matches one of
these breakpoints, only that breakpoint is cleared.  Once cleared in
this manner an individual breakpoint belonging to a set cannot be
enabled again.  However, disabling and then enabling the relevant event
handler will reestablish all the breakpoints.
#
:commands (command)
%commands - List all built-in commands with one-line descriptions
commands                # List all built-in commands with one-line descriptions
#
:cont (command)
%cont - Cause the process to continue execution
cont                    # Continue execution. In an MT process all threads are
                        # resumed. Use ^C to stop executing the program.
cont ... -sig <signo>   # Continue execution with signal <signo>
cont ... <id>           # The <id> specifies which thread or LWP to continue.
cont at <line> [ <id> ] # Continue execution at line <line>. <id> is required
                        # if the application is multi-threaded.
cont ... -follow parent|child|both
                        # If $DBX_follow_fork_mode is set to `ask', and
                        # you've chosen `stop', use this option to choose 
                        # which process to follow. `both' is only applicable
                        # under the GUI.

See also `help dbxenv'.
                                        
See `help continue' for dbx command language loop control.
#
:dbxdebug (command)
%dbxdebug - Displays internal state of dbx (for dbx developers' use)
dbxdebug                # Displays various internal data structures. Not
                          available unless `debugging.so' has been imported.
#
:dbxenv (command)
%dbxenv - List or set dbx customization variables
dbxenv                          # Display the dbx customization variables

If it is necessary to deal with multiple versions of dbx which accept 
different dbxenv variables (or for any other differences between 
versions) you can use code like the following in your .dbxrc file to 
select different options for each version.

        if [ $versionno = "6.1" ]
        then
                dbxenv rtc_use_traps on
        else
                # on by default in 6.2 and 7.0
        fi


        List of dbxenv variables and their meanings:
        --------------------------------------------

dbxenv array_bounds_check <on | off> 
                                # (f77 and f90)If on, dbx checks the 
                                # array bounds. 
                                # Default: on
dbxenv core_lo_pathmap <on | off>
                                # Use pathmap settings to control where
                                # shared libraries are found for a core file.
                                # See `help core mismatch' for details.
                                # Default: off
dbxenv disassembler_version <autodetect | v8 | v9 | v9vis>
                                # SPARC:
                                # 
                                # Set the version of dbx's built-in 
                                # disassembler for SPARC V8, V9, or V9 with 
                                # the Visual Instruction set. Default:
                                # autodetect, which sets the mode
                                # dynamically depending on the type of 
                                # machine a.out is running on.
                                # 
                                # non-SPARC:
                                # 
                                # Only choice is autodetect.
                                # 
dbxenv fix_verbose <on | off>   
                                # Governs the printing of the compilation line
                                # during a `fix'. Default: off
dbxenv follow_fork_inherit <on | off>
                                # When following child ...
       follow_fork_inherit on   # ... inherit events
       follow_fork_inherit off  # ... don't inherit events.
                                # Default: off
dbxenv follow_fork_mode <parent | child | both | ask>
                                # When process executes a fork/vfork/fork1 ...
       follow_fork_mode parent  # ... stay with parent
       follow_fork_mode child   # ... follow child
       follow_fork_mode both    # ... follow both parent and child (GUI only)
       follow_fork_mode ask     # ... ask which of the above the user wants
                                # Default: parent
dbxenv follow_fork_mode_inner <unset | parent | child | both>
                                # Only of relevance after a fork has been
                                # detected and if follow_fork_mode was set to
                                # `ask', and you chose `stop'. By setting this
                                # variable you need not use `cont -follow ...'.
dbxenv input_case_sensitive <autodetect | true | false>
                                # If set to `autodetect', dbx automatically 
                                # selects case sensitivity based on the language
                                # of the file: `false' for fortran files,
                                # otherwise `true'. If true, case 
                                # matters in variable and function names; 
                                # otherwise, case is not significant.  
                                # Default: autodetect
dbxenv language_mode <autodetect | main | c | ansic | c++ | 
                                  fortran | fortran90>
                                # Governs the language used for parsing and
                                # evaluating expressions.
                                # 
                                # mode `autodetect': sets expression 
                                # evaluation language to language of current 
                                # file. Useful if debugging programs with 
                                # mixed languages (default mode).
                                # mode `main': sets expression evaluation 
                                # language to the language of the main routine 
                                # in the program. Useful if debugging 
                                # homogeneous programs.
                                # mode `c', `c++', `ansic', `c++',
                                # `fortran', `fortran90' : sets 
                                # expression language to selected language.
See also `help language'.

dbxenv mt_scalable <on | off>   # When enabled, dbx will be more conservative
                                # in its resource usage and will be able to
                                # debug processes with upwards of 300 LWPs. 
                                # The down side is significant slowdown.
                                # Default: off
dbxenv output_auto_flush <on | off>
                                # Automatically call fflush() after each `call'
                                # Default: on
dbxenv output_base <auto[matic] | 8 | 10 | 16>
                                # Default base for printing integer constants
                                # Default: automatic
dbxenv output_class_prefix <on | off>
                                # Prefix class member with classname(s)
                                # when printing its value (print -r)
                                # or declaration (whatis -t).
                                # Default: on
dbxenv output_dynamic_type <on | off>
                                # When on, `-d' is the default for printing
                                # and displaying. Default: off
dbxenv output_inherited_members <on | off>
                                # When on, `-r' is the default for printing
                                # and displaying. Default: off
dbxenv output_list_size <num>   # Governs the default number of lines to print 
                                # in the list command. Default: 10
dbxenv output_log_file_name <filename>
                                # Name of the command logfile.
                                # Records only commands, not command output.
                                # Default: /tmp/dbx.log.<uniqueID>
dbxenv output_max_string_length <num>
                                # Set # of chars printed for `char *'s.
                                # Default: 512
dbxenv output_pretty_print <on | off>
                                # When `on', `-p' is the default for printing
                                # and displaying. Default: off
                                # See `help prettyprint'.
dbxenv output_short_file_name <on | off>
                                # Display short pathnames for files.
                                # Default: on
dbxenv overload_function <on | off>
                                # If on, do automatic function overload
                                # resolution (C++ only). Default: on
dbxenv overload_operator <on | off>
                                # If on, do automatic operator overload
                                # resolution (C++ only). Default: on
dbxenv pop_auto_destruct <on | off>
                                # If on, automatically call appropriate
                                # destructors for locals when popping a frame.
                                # Default: on
dbxenv proc_exclusive_attach <on | off>
                                # If on, will keep dbx from attaching if another
                                # tool is already attached. Warning: be aware
                                # that if more than one tool attaches to a
                                # process and tries to control it chaos
                                # will ensue.
                                # Default: on
dbxenv rtc_auto_continue <on | off>
                                # Log RTC errors to rtc_error_log_file_name
                                # and continue. Default: off
dbxenv rtc_auto_suppress <on | off>
                                # If on, an RTC error at a given location is
                                # reported only once. Default: on
dbxenv rtc_biu_at_exit <on | off | verbose>
                                # Used when `check -memuse' is on explicitly or 
                                # via `check -all'. If the value is `on', a
                                # non-verbose memory use (blocks in use) report
                                # is produced at program exit.
                                # If `verbose', a verbose report is produced at
                                # program exit.
                                # If `off', no output is produced.
                                # This variable has no effect on the
                                # `showmemuse' command.
                                # Default: on
See also `help check' and `help showmemuse'.

dbxenv rtc_error_limit <num>  
                                # Number of RTC errors that will be reported.
                                # Default: 1000
dbxenv rtc_error_log_file_name <filename>
                                # Name of file where RTC errors are logged
                                # if `rtc_auto_continue' is set.
                                # Default: /tmp/dbx.errlog.<uniqueID>
dbxenv rtc_error_stack <on | off>
                                # If `on' stack traces will show frames
                                # corresponding to RTC internal mechanisms.
                                # $DBX_rtc_error_stack
dbxenv rtc_inherit <on | off>
                                # If `on' enable RTC on child processes
                                # that are exec'ed from the debugged program.
                                # `on' causes LD_PRELOAD to be inherited.
                                # Default: off
dbxenv rtc_mel_at_exit <on | off | verbose>
                                # Used when leaks checking is on.
                                # 
                                # If the value is `on', a non-verbose memory 
                                # leak report is produced at program exit.
                                # If `verbose', a verbose memory leak report is
                                # produced at program exit. If `off', no output
                                # is produced. This variable has no effect on
                                # the `showleaks' command.
                                # Default: on
dbxenv run_autostart <on | off> 
                                # If on and there is no active program, `step',
                                # `next', `stepi', and `nexti' implicitly
                                # run the program and stop at the language-
                                # dependent "main" routine, and `cont' implies
                                # `run' whenever necessary.
                                # Default: off
dbxenv run_io <stdio | pty>     
                                # Governs whether the user program's I/O is
                                # redirected to dbx's stdio or a specific pty.
                                # The pty is provided via $DBX_run_pty.
                                # Default: stdio
dbxenv run_pty <ptyname>        
                                # Sets the name of the pty to use when
                                # $DBX_run_io is set to `pty'. Ptys are
                                # mainly used by GUI wrappers for dbx.
dbxenv run_quick <on | off>     
                                # If on, no symbolic information is loaded upon
                                # `debug'. The symbolic information can be
                                # loaded on demand using "prog -readsysms".
                                # Until then dbx behaves as if the program
                                # being debugged is stripped.
                                # Default: off
dbxenv run_savetty <on | off>   
                                # Multiplexes tty settings, process group, and
                                # keyboard settings (if -kbd was used on the
                                # command line) between dbx and the debuggee;
                                # useful when debugging editors and shells. 
                                # Set it to `on' if dbx gets SIGTTIN or SIGTTOU
                                # and pops back into the shell. Setting it to 
                                # `off' to gain a slight speed advantage.
                                # The setting is irrelevant if dbx attached
                                # to the debugee or is running under the GUI.
                                # Default: on
dbxenv run_setpgrp <on | off>   
                                # If on, when a program is `run' `setgprp(2)'
                                # is called right after the fork.
                                # Default: off
dbxenv scope_global_enums <on | off>
                                # If on, enumerators are put in global scope
                                # and not in file scope. Set before
                                # debugging information is processed 
                                # (~/.dbxrc). Default: off
dbxenv scope_look_aside <on | off>
                                # Find file static symbols, even when not in
                                # scope. Default: on
dbxenv session_log_file_name <filename>
                                # Name of the file where dbx logs all 
                                # commands and their output. Output is 
                                # appended to the file.
                                # Default: "" (no session logging)
dbxenv stack_find_source <on | off> 
                                # When set to on, dbx will attempt to find and
                                # automatically 'up to a stack frame with
                                # source when the debugee comes to a stop in
                                # a function which is not compiled with -g.
                                # Default: on
dbxenv stack_max_size <num>     
                                # Set the default size for the `where' command.
                                # Default: 100
dbxenv stack_verbose <on | off> 
                                # Governs the printing of arguments and
                                # line information in `where'.
                                # Default: on
dbxenv step_events <on | off>   
                                # Allow breakpoints while step/next'ing.
                                # Default: off
dbxenv step_granularity <statement | line>
                                # Controls granularity of source line stepping.
                                # When set to `statement' the following code:
                                #       a(); b();
                                # will take two `next's to get through.
                                # When set to `line' a single `next' will do.
                                # Granularity of `line' is particularly useful
                                # when dealing with multi-line macros.
                                # Default: statement
NOTE: Granularity of `statement' might not always achieve the desired
effect because the compiler might not have emitted information about
statement boundaries.

dbxenv suppress_startup_message <num>
                                # Set the release level below which the startup
                                # message is not printed. Default: 3.01
dbxenv symbol_info_compression <on | off>
                                # Read debugging information for each include
                                # file only once, and create the common block
                                # symbol table for FORTRAN only once.
                                # Default: on
dbxenv trace_speed <num>
                                # Set the speed of tracing execution. Value is
                                # number of seconds to pause between steps.
                                # Default: 0.50

Each of the above has a corresponding ksh environment variable such as
DBX_trace_speed.  The variable may be assigned directly, or the dbxenv 
command may be used; they are equivalent.

The following obsolete names are recognized as aliases by the 
'dbxenv' command, and emit a warning.  The old names do not have
corresponding shell variables starting with $DBX_.

        Old name                New name

        autocontinue            rtc_auto_continue
        autoflush               output_auto_flush
        autosuppress            rtc_auto_suppress
        case                    input_case_sensitive
        compress_stabs          symbol_info_compression
        dynamic_type            output_dynamic_type
        errlogfile              rtc_error_log_file_name
        errstack                rtc_error_stack
        error_limit             rtc_error_limit
        func_overload           overload_function
        logfile                 output_log_file_name
        lookaside               scope_look_aside
        oper_overload           overload_operator
        pop_autodestruct        pop_auto_destruct
        setpgrp                 run_setpgrp
        savetty                 run_savetty
        shortfname              output_short_file_name
        speed                   trace_speed
        stackmaxsize            stack_max_size
        stackverbose            stack_verbose
        stepevents              step_events
        stringlen               output_max_string_length
        warnings                symbol_info_warnings
        
#
:debug (command)
%debug - List or change the program being debugged
debug                         # Print the name and arguments of the program
                                being debugged
debug <prog>                  # Begin debugging <prog> with no process or core.
debug -c <core> <prog>        # Begin debugging <prog> with core file <core>.
debug -p <pid> <prog>         # Begin debugging <prog> with process ID <pid>.
debug <prog> <core>           # Begin debugging <prog> with core file <core>.
                                <prog> may be `-'; dbx will attempt to extract
                                the name of the executable from the core file.
                                For details see `help core'.
debug <prog> <pid>            # Begin debugging <prog> with process ID <pid>.
                                <prog> may be `-'; dbx finds it using /proc
debug -f ...                  # Force loading of core file, even if it doesn't
                              # match.
debug -r ...                  # The `-r' option causes dbx to retain all 
                                display's, trace's, when's, and stop's.
                                With no `-r' option, an implicit `delete all'
                                and `undisplay 0' is performed.
debug -clone ...              # The `-clone' option causes another dbx to 
                                begin execution, permitting debugging of more
                                than one process at a time. Valid only if 
                                running under the GUI.
debug -clone                  # Starts another dbx debugging nothing. Valid
                                only if running under the GUI.
debug [<options>] -- <prog>   # Start debugging <prog>, even if <prog> begins
                                with a dash.

Note: Leaks checking and access checking will be turned off when a program
is loaded with 'debug'.  You can enable them with the 'check' command.

See also `help prog'.
#
:delete (command)
%delete - Delete breakpoints and other events
delete [-h] <number> ...    # Remove trace's, when's, or stop's of given
                            # number(s). To remove hidden handlers,
                            # -h option must be given.
delete [-h] 0 | all | -all  # Remove all trace's, when's, and stop's excluding
                            # permanent and hidden handlers. Specifying -h 
                            # removes hidden handlers as well.
delete -temp                # Remove all temporary handlers
delete $firedhandlers       # delete all the handlers that caused the latest
                            # stoppage.
#
:detach (command)
%detach - Release the target process from dbx's control
detach                  # Detach dbx from the target, and cancel any
                        # pending signals.
detach -sig <sig>       # Detach while forwarding the given signal.
#
:dis (command)
%dis - Disassemble machine instructions
dis <addr> [/ <count>]  # Disassemble <count> instructions (default is 10),
                          starting at address <addr>.
dis <addr1>, <addr2>    # Disassemble instructions from <addr1> through <addr2>.
dis                     # Disassemble 10 instructions, starting at the value
                          of `+' (see `help examine').
dis /<count>            # Disassemble <count> instructions, starting at `+'.
#
:display (command)
%display - Evaluate and print expressions at every stopping point
display                # Print the list of expressions being displayed
display <exp>, ...     # Display the value of expressions <exp>, ... at every
                         stopping point
display [-r|+r|-d|+d|-p|+p|-L|-f<fmt>|-F<fmt>|--] <exp>, ...
                         See `help print' for flags.

See also `help undisplay'.
#
:document (command)
%document - Add help information for a command or topic
document <cmdname>      # Provides the documentation for <cmdname>.  The
                        `document' command reads from standard input. To
                         add documentation for a new command named `foo', use

                         (dbx) document foo
                         foo <arg>   # Echoes the <arg> with each
                                     # letter converted to upper case.
                         ^D

                          Type Control-D to end the input.

                          To remove the documentation for command `foo', use
                         
                          (dbx) document foo </dev/null
#
:down (command)
%down - Move down the call stack (away from `main')
down                   # Move down the call stack one level
down <number>          # Move down the call stack <number> levels
down -h [<number>]     # Move down the call stack, but don't skip hidden frames
#
:dump (command)
%dump - Print all variables local to a procedure
dump                   # Print all variables local to the current procedure
dump <proc>            # Print all variables local to <proc>
#
:edit (command)
%edit - Invoke $EDITOR on a source file (GUI: display the source)
edit                   # Edit the current file
edit <filename>        # Edit the specified file <filename>
edit <proc>            # Edit the file containing function or procedure <proc>

`edit' uses $EDITOR if dbx is not running under the GUI. Otherwise,
it sends a message to the GUI to display the appropriate file.  
# If the GUI was invoked with the `-E' option, the external editor which
# handles source display is used, otherwise the source pane is
# updated to display the requested file.
#
:examine (command)
%examine - Show memory contents
examine [ <addr> ] [ / [ <count> ] [ <fmt> ] ]

        Display the contents of memory starting at <addr> for <count> items
        in format <fmt>. The default <addr> is the next one after the last
        address previously displayed. The default <count> is 1. The default
        <fmt> is the same as was used in the previous `examine' command, or
        `X' if this is the first one.

examine <addr1> , <addr2> [ / [ <fmt> ] ]

        Display the contents of memory from <addr1> through <addr2>
        inclusive, in format <fmt>.

examine <addr> = [ <fmt> ]

        Display the address (instead of the contents of the address) in the
        given format.
                
        The <addr> may be `+' which indicates the address just after the last
        one previously displayed (the same as omitting it).

        `x' is a predefined alias for `examine'.

        Legal values for <fmt> are:

            i       instruction (disassembly)
            d,D     decimal (2 or 4 bytes)
            o,O     octal (2 or 4 bytes)
            x,X     hexadecimal (2 or 4 bytes)
            b       octal (1 byte)
            c       character
            w       wide character
            s       string
            W       wide character string
            f       hex and float (4 bytes, 6 digit prec.)
            F       hex and float (8 bytes, 14 digit prec.)
            g       same as `F'
            E       hex and float (16 bytes, 14 digit prec.)
            ld,lD   decimal (4 bytes, same as D)
            lo,lO   octal (4 bytes, same as O)
            lx,lX   hexadecimal (4 bytes, same as X)
            Ld,LD   decimal (8 bytes)
            Lo,LO   octal (8 bytes)
            Lx,LX   hexadecimal (8 bytes)
#
:gdb (command)
%gdb - Support gdb command set
gdb on | off
Use `gdb on' to enter the gdb command mode under which 
dbx will understand and accept gdb commands. To exit 
the gdb command mode and return to the dbx command mode, 
enter "gdb off". Please note that the dbx commands will 
not be accepted while in gdb command mode and vice versa. 
All debugging settings such as breakpoints are preserved 
across different command modes.
The following gdb commands are not supported in the
current release:
        - commands      - define
        - handle        - hbreak
        - interrupt     - maintenance
        - printf        - rbreak
        - return        - signal
        - tcatch        - until
#
:fix (command)
%fix - Recompile and relink a source file
Use `fix' to make changes to your program given. `fix' recompiles
modified source files and dynamically links the modified functions into
the application.

fix                    # Fix the current file
fix <filename> <filename> ... 
                       # Fix files in list
fix -f                 # Force fixing the file, even if source hasn't been 
                         modified
fix -a                 # Fix all modified files
fix -g                 # Strip -O flags and add -g flag
fix -c                 # Print compilation line (may include some options
                         added internally for use by dbx)
fix -n                 # Do not execute compile/link commands (use with -v)
fix -v                 # Verbose mode (overrides dbxenv setting)
fix +v                 # Non-verbose mode (overrides dbxenv setting)

See `help _cb_fix_comp' and `help _cb_fix_link' for how to customize the
compilation and link steps. See `help fix-pitfalls' and `help dbxenv' 
under `fix_verbose' for more information.
#
:fixed (command)
%fixed - List names of all `fixed' files
fixed                  # List names of all fixed files
#
:exception (command)
%exception - Print the value of the current C++ exception
exception [-d | +d]    # Prints the value of the current C++ exception,
                         if any. See `help print' for the meaning of the `-d'
                         flag.

See also `help whocatches' and `help event specification'.
#
:exists (command)
%exists - Check for existence of a symbol name
exists <name>          # Returns 0 if <name> is found in the current
                         program, 1 if <name> is not found
#
:file (command)
%file - List or change the current file
file                   # Print the name of the current file
file <filename>        # Change the current file
#
:files (command)
%files - List file names that match a regular expression
files                  # List the names of all files that contributed
                         debugging information to the current program
                         (those which were compiled `-g')
files <regexp>         # List the names of all `-g' files which match the
                         given regular expression
For example:
   (dbx) files ^r
myprog:
  retregs.cc
  reg_sorts.cc
  reg_errmsgs.cc
  rhosts.cc
                         
For more information about the style of regular expression, see `help regexp'.
#
:frame (command)
%frame - List or change the current stack frame number
frame                  # Display the frame number of the current frame
frame [-h] <number>    # Set the current frame to frame <number>
frame [-h] +[<number>] # Go <number> frames up the stack; default is 1
frame [-h] -[<number>] # Go <number> frames down the stack; default is 1
       -h              # Go to frame, even if frame is hidden
#
:func (command)
%func - List or change the current function
func                   # Print the name of the current function
func <proc>            # Change the current function to function
                         or procedure <proc>
#
:funcs (command)
%funcs - List all function names that match a regular expression
funcs                  # List all functions in the current program
funcs [-f <filename>] [-g] [<regexp>]
      -f <filename>    # List all functions in file
      -g               # List all functions with debugging information
      <regexp>         # List all functions which match the regular
                         expression
For example:
  (dbx) funcs [vs]print
  `libc.so.1`isprint
  `libc.so.1`wsprintf
  `libc.so.1`sprintf
  `libc.so.1`vprintf
  `libc.so.1`vsprintf
                           
See `help regexp' for more about regular expressions                         
#
:handler (command)
%handler - Modify event handlers (enable, disable, etc.)
A handler is created for each event that needs to be managed in a debugging
session. The commands `trace', `stop', and `when' create handlers. Each
of these commands returns a number known as the `handler ID' (<hid>). The 
`handler', `status', and `delete' commands manipulate or
provide information about handlers in a generic fashion:

handler -enable <hid> ...       # enable given handlers, `all' for all
handler -disable <hid> ...      # disable given handlers, `all' for all
                                # Use $firedhandlers instead of <hid> to
                                # disable the handlers that caused the most
                                # recent stoppage.
handler -count <hid>            # print value of trip counter for given handler
handler -count <hid> <newlimit> # set new count limit for given event
handler -reset <hid>            # reset trip counter counter for given handler

See also `help event'.
#
:help (command)
%help - Provide more information about a command or topic
help                     # Print a summary of the builtin dbx commands
help <cmd>               # Print help about <cmd>
help <topic> <subtopic>  # Print help for topic and subtopic
help -k <keyword>        # Print name of each topic which contains <keyword>

           When dbx is not running under the GUI,
           `help' output is piped through $PAGER, if set, or
           /usr/ucb/more, if it is present and $PAGER is not
           set. (The value of $PAGER must be a full path name
           if the `path' option is not set.) To disable this
           feature, put `unalias help' in your .dbxrc file.

           Use the `commands' command to see a one-line summary
           of all commands.  See `help changes' for new and changed
           features.
#
:hide (command)
%hide - Hide stack frames that match a regular expression
hide                   # List the stack frame filters currently in effect
hide <regexp>          # Hide stack frames matching <regexp>
                         The regular expression matches either the function
                         name, or the name of the loadobject, and is a
                         sh or ksh file matching style regular expression.

See also `help unhide'.
#
:history (ksh command)
%history - Manipulate the command history list
history                # Print a list of the most recent commands
history <num>          # Resize the history list to hold <num> commands
history -              # Stop recording commands in the history
history +              # Resume recording commands
#
:ignore (command)
%ignore - Don't catch the given signal(s)
ignore                  # Print a list of the ignored signals
ignore <num>...         # Ignore signal(s) numbered <num>
ignore <sig>...         # Ignore signal(s) named by <sig>
                        # SIGKILL cannot be caught or ignored.
ignore $(catch)         # Ignore all signals.
Ignoring a signal causes dbx *not* to stop when the process receives
that kind of signal.
See also `help catch' and `help cancel' and `help cont' under the -sig option.
#
:import (command)
%import - Import commands from a dbx command library
import <pathname>    # Import commands from the dbx command library <pathname>.
#
:intercept (command)
%intercept - Intercept throws (C++ exceptions) of the given type (C++ only)
intercept <typename>       # Intercept throws of type <typename>.
intercept -a               # Intercept all throws.
intercept -x <typename>    # Do not intercept <typename>
intercept -a -x <typename> # Intercept all types except <typename>
intercept                  # List intercepted types.

<typename> may be one of -unhandled or -unexpected.
A thrown exception for which there is no matching catch is called an
"unhandled" throw. A thrown exception that doesn't match the exception
specification of the function it is thrown from is called an
"unexpected" throw.

Unhandled and unexpected throws are intercepted by default.

See also `throw' under `help event specification', `$exception' under
`help event variables', and `help unintercept'.
#
:kill (ksh/dbx command)
%kill - Send a signal to a process; kill the target process
kill -l                 # List all known signal numbers, names, and descriptions
kill                    # Kill the controlled process
kill <job>...           # Send the SIGTERM signal to the listed jobs
kill -<sig> <job>...    # Send the given signal to the listed jobs
                          <job> may be a process ID or may be specified in
                          any of the ways listed under `help fg', but the `%'
                          is not optional in this case.
#
:language (command)
%language - List or change the current source language
language               # Print the name of the current language used for
                       # parsing and evaluating expressions.
language <lang>        # Set current language to <lang>, where <lang> is
                         either `c', `ansic', `c++', `fortran', or `fortran90'.

                         Note: `c' is an alias for `ansic'.

See also `help dbxenv' under `language_mode'.
#
:line (command)
%line - List or change the current line number
line                   # Display the current line number
line <num>             # Set the current line number
line "<filename>"      # Set current line number to line 1 in <filename>
line "<filename>":<n>  # Set current line number to line <n> in <filename>
                         The `"' around the filename is optional.

Examples:
    line 100
    line "/root/test/test.cc":100
#
:list (command)
%list - Display lines of a source file
The default number of lines listed, N, is controlled by the dbxenv 
variable `output_list_size'. See `help dbxenv' under `output_list_size'
for more information.

list                # List N lines 
list <n>            # List line number <n>    
list +              # List next N lines
list +<n>           # List next <n> lines
list -              # List previous N lines
list -<n>           # List previous <n> lines
list <n1>,<n2>      # List lines from <n1> to <n2>
list <n1>,+         # List from <n1> to <n1> + N
list <n1>,+<n2>     # List from <n1> to <n1> + <n2>
list <n1>,-         # List from <n1>-N to <n1>
list <n1>,-<n2>     # List from <n1>-<n2> to <n1>
list <function>     # List the start of the source for <function>
list <filename>     # List the start of the file <filename>
list <filename>:<n> # List file <filename> from line <n>
                    # Where appropriate, the line number may be `$' which
                      denotes the last line of the file. Comma is
                      optional. `list <function>' changes the current
                      scope. See `help scope' for more information.          

Options:
-i or -instr        # Intermix source lines and assembly code
-w or -w<n>         # List N (or <n>) lines (window) around 
                      line or function. This option is not allowed in 
                      combination with the `+' or `-' syntax or when two
                      linenumbers are specified.        

Examples:
    list                      // list N lines starting at current line
    list +5                   // list next 5 lines starting at current line
    list -                    // list previous N lines
    list -20                  // list previous 20 lines
    list 1000                 // list line 1000
    list 1000,$               // list from line 1000 to last line
    list 2737 +24             // list line 2737 and next 24 lines
    list 1000 -20             // list line 980 to 1000
    list "test.cc":33         // list source line 33 in file "test.cc"
    list -w                   // list N lines around current line
    list -w8 `test.cc`func1   // list 8 lines around function func1
    list -i 500 +10           // list source and assembly code for line 500
                                 to line 510
See also `listi' for assembly-level source code listing.
#
:listi (command)
%listi - Display source and disassembled instructions
Same as `list -i'. Please see `help list' for details.
#
:loadobject (command)
%loadobject - List and manage symbolic information from loadobjects
loadobject <subcommand> <subcommand args>
(This command has a default alias `lo')

loadobject -list    <regexp>      Show currently loaded loadobjects
loadobject -load    <loadobject>  Load symbols for specified loadobject
loadobject -unload  <regexp>      Unload specified loadobjects
loadobject -hide    <regexp>      Remove loadobject from dbx's search algorithm
loadobject -use     <regexp>      Add loadobject to dbx's search algorithm
loadobject -dumpelf <regexp>      Show various ELF details of the loadobject
loadobject -exclude <ex-regexp>   Don't automatically load loadobjects
                                  matching <ex-pattern>
loadobject -exclude               Show list of exclude patterns
loadobject -exclude -clear        Clear the 'exclude' list of patterns

<regexp> is optional, and if it's not specified the command applies to all
loadobjects.

<ex-regexp> is not optional, it must be specified.

For more information about the `regexps' used here, see `help regexp'.

For a general description of how loadobjects work inside of dbx,
see `help loadobject management'.

loadobject -list <regexp>

    The full pathname for each loadobject is shown along with letters in
    the margin to show status.
    'h' : This means "hidden" (the symbols will
          not be found by symbolic queries like `whatis' or `stop in')
    'u' : If there is an active process "u" means "unmapped".
    'p' : This letter indicates an LO that is 'preloaded', that is,
          the result of a `loadobject -load' command or a dlopen
          event in the program. (See `help loadobject preloading')

    For example:
    
      (dbx) lo -list libm
         /usr/lib/64/libm.so.1
         /usr/lib/64/libmp.so.2
         
      (dbx) lo -list ld.so
       h  /usr/lib/sparcv9/ld.so.1 (rtld)

   This last example shows that the symbols for the runtime linker
   are hidden by default.  To use those symbols in dbx commands,
   see the `lo -use' command below.

loadobject -load <loadobject> ...
loadobject -load -all

    <loadobject> can be a full pathname or a library in /usr/lib or
    /usr/lib/sparcv9.  If there is a program being debugged, then only
    the proper ABI library directory will be searched.

    You can use the -all option to ask dbx to load all the loadobjects
    currently mapped by the process which are not already loaded.
    You can use this if you had started a program with some 
    `lo -exclude' commands in force, but then removed some of the
    exclusions.

loadobject -unload <regexp>

    This command unloads the symbols for any loadobjects matching the
    regexp supplied on the command line.  The main program loaded with
    'debug' can't be unloaded.  Dbx may also refuse to unload other
    loadobjects which might be currently in use, or critical to
    the proper functioning of dbx.

loadobject -dumpelf <regexp>

    This command dumps out information related to the ELF structure
    of the loadobject file on disk.   The details of this output are
    highly subject to change.  If you want to parse this output, you would
    be better off using the Solaris commands `dump' or `elfdump'.

loadobject -exclude  <ex-regexp>

    This command prevents dbx from automatically loading symbols for
    loadobjects which match the regexps given by `loadobject -exclude'
    commands.  Unlike regexps in other subcommands, this regexp
    isn't optional, and doesn't default to 'all'.
    
    Currently this functionality cannot be used to prevent loading of
    the main program, or the runtime linker.  Also, using it to prevent
    loading of C++ runtime libraries could cause C++ functionality.
    This option shouldn't be used with Runtime Checking (RTC).

loadobject -use <regexp>

    This command will place 'hidden' loadobjects into the program
    scope and allow dbx to see the types and functions in this loadobject.
    The loadobject must already be loaded, either automatically
    by dbx, or using the 'lo -load' command.

loadobject -hide <regexp>

    This command will remove a loadobject from the program scope,
    and hide it's functions and symbols from dbx.  This command
    will also reset the 'preload' bit.  (See `help loadobject preloading')

For more information about loadobjects and how dbx deals with them,
see: `help loadobject management', `help loadobject preloading',
and `help core mismatch'  

#
:loadobject$$management (topic)
Loadobject is short for "loadable object" as defined by the SVR4 ABI.
Executables ("a.out") and shared libraries ("*.so") are loadobjects.

When an executable starts, the dynamic linker pre-loads a set of loadobjects
that are in the executable's dependency list. Dbx keeps track of this and 
reads the symbol tables of these loadobjects. A very large application might
have numerous large shared libraries and occasionally this poses a significant
startup penalty. To counter this, loadobjects can be excluded from this
initial loading of symbol tables. For more information see `help loadobject'
under the `exclude' option.

Once an application is running it can dynamically load more loadobjects
by using the dlopen(3) system function. Such loadobjects can be subsequently
unloaded via dlclose(3). Dbx keeps track of such events and the user can
request notification, by using:
        stop dlopen                     # stop the process on every dlopen
        stop dlopen libjava_g.so        # stop when "libjava_g.so" has
                                        # been dlopened.
("stop in dlopen" does not quite have the same effect.)
For more information see `help event specification' and `help event variables'.

It's possible to write an event handler (using the `when' command)
which sets the breakpoints you want after the dlopen event, but that
is clumsy.  To make this easier, a loadobject's symbol table
may be pre-loaded and virtual breakpoints placed in it before it is
dlopened. For more information see `help loadobject preloading'.

Dbx, particularly when it is running under the GUI, can debug many
executables all of which re-use the same basic set of loadobjects (for
example "libc.so", "libthread.so" or "libX11.so").  The symbols for
these libraries are not re-read each time a program runs, they are
simply reused from one run to the next.

To conserve memory, dbx will unload the symbols for an executable
when a new program is debugged.  But the libraries will accumulate
and be reused when they are needed.  The symbols in a loadobject
will be 'hidden' when they are not used by the current program.
See `help loadobject' for information about 'using' and 'hiding'
loadobjects.

Related topics:

   Loading a core file when the loadobjects don't match the
   current system:   `help core mismatch'

   To prevent dbx from loading symbols for loadobjects in order
   to speed up the program load phase:  `help loadobject'
   (Under the `-exclude' option)

   To set breakpoints in a library that hasn't been dlopen()ed
   by the program yet: `help loadobject preloading'
#
:loadobject$$preloading (topic)
Dbx is unable to "browse" (through commands like whatis, func, and
list), or place breakpoints in loadobjects that haven't been loaded.
(For a general description of how dbx treats loadobjects, see
`help loadobject management' and `help loadobject'.)
For example, if a program loads a library with dlopen(3), then dbx
won't normally be able to set a breakpoint in the library until after
the dlopen() happens.  However, these capabilities can be enabled by
preloading the loadobjects using the `loadobject -load' command
(see `help loadobject').

Alternatively, you can just run the program once to cause the library
to be loaded, then set your break points, and run the program again.

Loadobjects which are either explicitly loaded or which are
dlopened by the program are flagged as 'preloaded'.  Symbols from
these loadobjects will be available even when the program doesn't
have those libraries open.  Preloaded libraries show up with a
'p' in the output of the `loadobject -list' command.
#
:loadobjects (command)
The "loadobjects" command has been replaced with a new
command called "loadobject" (or "lo").  Use "help loadobject" to
see how to use the new command.  The address mappings (the old -v
option) can be seen with "proc -map".

To list loadobjects,      use "loadobject -list"
To exclude loadobjects,   use "loadobject -exclude ..."
To load loadobjects,      use "loadobject -load ..."

For this option        Use this new command
---------------        --------------------
loadobjects -a         loadobject -list
loadobjects -v         proc -map 
loadobjects -p xxx     loadobject -load xxx
loadobjects -x xxx     loadobject -exclude xxx

The -f option:

   Some of the old loadbjects options also took a secondary
   option '-f <file>'.  There is no direct equivalent to this option
   with the new 'loadobject' command.  If you previously had a file
   with a list of loadobject pathnames, then you should simple put
   'lo -load ' at the beginning of each line, and the use the 'source'
   command to execute those commands when you want to load those files.
   Also, if you had many pathnames that can be described with a regexp
   (for example /home/foo/myapp/lib/libf.*.so) then you might be
   able to replace many lines of your previous file with a much smaller
   list of regexps.
#
:lwp (command)
%lwp - List or change the current LWP
lwp                    # Display current LWP
lwp <lwpid>            # Switch to LWP <lwpid>
#
:lwps (command)
%lwps - List all LWPs in the process
lwps                   # List all LWPs in the current process
#
:mmapfile (command)
%mmapfile - View contents of mmaped files missing from coredump
mmapfile <mmapped_file> <address> <offset> <length>
Solaris core files do not contain any memory segments that are read-only.

Executable read-only segments (i.e. text) are dealt with automatically
and dbx resolves memory accesses against these by looking into the 
executable and the relevant shared objects.

Read-only data segments typically occur when an application memory maps
some database. For example:
        caddr_t vaddr = NULL;
        off_t offset = 0;
        size_t = 10 * 1024;
        int fd;
        fd = open("../DATABASE", ...)
        vaddr = mmap(vaddr, size, PROT_READ, MAP_SHARED, fd, offset);
        index = (DBIndex *) vaddr;

If you want to be able to access the database through the debugger as memory
you should issue
        mmapfile ../DATABASE $[vaddr] $[offset] $[size]
Now you can look at your database contents in a structured way:
        print *index
#
:module (command)
%module - Read debugging information for one or more modules
module [-v]                  # Print the name of the current module
module [-f] [-v] [-q] <name> # Read in debugging info for <name>
module [-f] [-v] [-q] -a     # Read in debugging info for all modules
Flags:                        -f : Force reading of debugging info, even if 
                                   the file is newer than the executable 
                                   (use with caution!).
                              -v : Verbose mode. Prints language, file
                                   names, etc.
                              -q : Quiet mode
#
:modules (command)
%modules - List module names
modules [-v]            # List all modules
modules [-v] -debug     # list all modules containing debugging info
modules [-v] -read      # List names of modules containing debugging info
                          that have been read in already
Flags:                   -v : Verbose mode. Prints language, file
                              names, etc.
#
:next (command)
%next - Step one source line (stepping over calls)
next                   # Step one line (step OVER calls).
                       # With MT programs, when a function call is stepped
                       # over, all LWPs are implicitly resumed for the
                       # duration of that function call in order to
                       # avoid deadlock.
                       # Non-active threads cannot be stepped.
next <n>               # Step <n> lines (step OVER calls)
next ... -sig <sig>    # Deliver the given signal while nexting

The dbxenv variable `step_events' controls whether breakpoints are enabled
during a step.

next ... <tid>         # Step the given thread.
next ... <lwpid>       # Step the given LWP.

See also `nexti' for machine-level stepping over calls.         
See also `help dbxenv' under `step_granularity'.
#
:nexti (command)
%nexti - Step one machine instruction (stepping over calls)
nexti                 # Step one machine instruction (step OVER calls)
nexti <n>             # Step <n> machine instructions (step OVER calls)
nexti -sig <sig>      # deliver the given signal while nexting
nexti ... <lwpid>     # ... the given LWP.
nexti ... <tid>       # ... the LWP on which the given thread is active. Will
                        not implicitly resume all LWPs when stepping over a
                        function.
#
:pathmap (command)
%pathmap - Map one pathname to another for finding source files, etc.
pathmap [ -c ] [-<index>] <from> <to>
pathmap [ -c ] [-<index>] <to>
                        # Establish a new mapping from <from> to <to> where
                          <from> and <to> are filepath prefixes. <from>
                          refers to the filepath compiled into the executable 
                          or object file and <to> refers to the file path at
                          debug time. If `-c' is used, the mapping is 
                          applied to the current working directory as well. 
                          If <from> is empty, all paths are mapped to <to> 
                          (the functionality of the old `use' command). If an 
                          index is specified, the mapping is inserted in the 
                          list with that index, otherwise it is added to 
                          the end of the list.
pathmap                 # List all existing path mappings (by index)
pathmap -s              # The same, but the output can be read by dbx
pathmap -d <from1> <from2> ...
                        # Delete the given mapping(s) by path
pathmap -d <index1> <index2> ...
                        # Delete the given mapping(s) by index

`pathmap' creates a mapping from one pathname to another. The mapping
is applied to source paths, object file paths and the current working
directory (if `-c' is used).

`pathmap' is useful for dealing with automounted and explicit NFS mounted
filesystems with different paths on differing hosts. Use `-c' when
you're trying to correct problems arising due to the automounter since
CWD's are inaccurate on automounted filesystems as well. The `pathmap'
command is also useful if source or build trees are moved.

`pathmap /tmp_mnt /' exists by default.

`pathmap' is used to find load objects for core files when 
`dbxenv core_lo_pathmap' is set to `on'.  Other than this case,
pathmap has no effect on finding load objects (shared libraries).
See `help core mismatch' for details about how this works.

Examples:
(dbx) pathmap /export/home/work1 /net/mmm/export/home/work2
  # maps /export/home/work1/abc/test.c to /net/mmm/export/home/work2/abc/test.c
(dbx) pathmap /export/home/newproject
  # maps /export/home/work1/abc/test.c to /export/home/newproject/test.c
(dbx) pathmap
(1) -c /tmp_mnt /
(2) /export/home/work1 /net/mmm/export/home/work2
(3) /export/home/newproject

#
:pop (command)
%pop - Remove one or more frames from the callstack
pop                    # Pop current topframe from stack
pop <num>              # Pop <num> frames from stack
pop -f <num>           # Pop frames from stack until specified frame number
pop -c                 # Pop the last call made from the debugger.

You can only pop to a frame for a function function that has been compiled
with -g. The program counter is reset to the beginning of the source line
at the callsite.
You can not pop past a function call made by the debugger, use `pop -c'.
Normally a pop command will call all the C++ destructors associated with 
the popped frames; this can be overridden by setting the dbxenv
`pop_autodestruct' to `off'.
#
:print (command)
%print - Print the value of an expression
print <exp>, ...       # Print the value of the expression(s) <exp>, ...
print -r <exp>         # Print the value of the expression <exp>
                         including its inherited members (C++ only)
print +r <exp>         # Don't print inherited members when the 
                         dbxenv `output_inherited_members' is on (C++ only)
print -d [-r] <exp>    # Show dynamic type of expression <exp>
                         instead of static type (C++ only)
print +d [-r] <exp>    # Don't use dynamic type of expression <exp>
                         when the dbxenv `output_dynamic_type' is on (C++ only)
print -p <exp>         # Call `prettyprint' function
print +p <exp>         # Do not call `prettyprint' when the dbxenv
                         `output_pretty_print' is on (see `help prettyprint')
print -L <exp>         # if the printing object <exp> is larger than 4K, 
                         -L enforce the printing.
print -l <exp>         # (`Literal') Do not print the left side. If the
                         expression is a string (char *), do not print the
                         address, just print the raw characters of the string,
                         without quotes.
print -f<fmt> <exp>    # Use <fmt> as the format for integers, strings, or
                         floating-point expressions (see `help format')
print -F<fmt> <exp>    # Use the given format but do not print the left hand
                         side (the variable name or expression) (see `help format')
print -o <exp>         # Print the value of exp which must be an enumeration as
                         an ordinal value. You may also use a format string 
                         here (-f<fmt>). This  option is ignored for non 
                         enumeration expressions.
print -- <exp>         # `--' signals the end of flag arguments. This is useful
                         if <exp> may start with a plus or minus (see `help scope'
                         for scope resolution rules. See `help redirection' to
                         redirect the output of a `print' and add a trailing comment.)
#
:rprint (command)
%rprint - Print an expression using shell quoting rules
rprint [-r|+r|-d|+d|-p|+p|-L|-l|-f<fmt>|-F<fmt>|--] <exp> 
                         Print the value of the expression. No special
                         quoting rules apply, so `rprint a > b' puts the
                         value of `a' (if it exists) into file `b' (see
                         `help print' for flags)
#
:proc (command)
%proc - Display status of the current process
proc -map               # Show the list of loadobjects with addresses
proc -pid               # Show current process id (PID)
#
:prog (command)
%prog - Manage programs being debugged and their attributes
prog -readsyms          # Read symbolic information which was postponed by 
                        # having set dbxenv run_quick to `on'.
prog -executable        # Prints the full path of the executable, `-' if the
                        # program was attached to using -.
prog -argv              # Prints the whole argv, including argv[0].
prog -args              # Prints the argv, excluding argv[0].
prog -stdin             # Prints "< <filename>" or empty if stdin is used.
prog -stdout            # Prints "> <filename>" or ">> <filename>" or empty of
                        # stdout is used.
                        # The outputs of -args, -stdin, -stdout are designed
                        # so that the strings can be combined and reused
                        # with `run'.
#
:pwd (ksh command)
%pwd - Print the current working directory
pwd                    # Print the current working directory
#
:quit (command)
%quit - Exit dbx
quit                   # Exit dbx with return code 0. Same as `exit'.
quit <n>               # Exit with return code <n>. Same as `exit <n>'.
If dbx was attached to a process, the process is detached from before exiting.
If there are pending signals, they are cancelled. Use `detach' for fine control.
#
:regexp (topic)
Some commands in dbx (`funcs' `files' `loadobject') use regular expressions
to specify items on the command line.  You can find the exact syntax
for these regular expressions in the Solaris man page for `regcmp' in
section 3c of the man pages.  The details of what each command matches
the regular expression against are specified in the help description
for that command.
#
:replay (command)
%replay - Replay debugging commands since last `run'
replay [-<num>]        # Replay all or all minus <num> commands since last
                       # run/rerun/debug command.

See also `help save' and `help restore'.
#
:rerun (command)
%rerun - Run the program with no arguments
rerun                  # Begin executing the program with no arguments
rerun <args>           # Begin executing the program with new arguments
                         by the save command.

See also `help run'.
#
:run (command)
%run - Run the program with arguments
run                     # Begin executing the program with the current arguments
run <args>              # Begin executing the program with new arguments
                          Use ^C to stop executing the program.
run ... >|>> <file>     # Set the output redirection
run ... < <file>        # Set the input redirection

There is currently no way to redirect stderr using 'run' or 'runargs'.

See also `help rerun', `help runargs' and `help prog'.
#
:runargs (command)
%runargs - Change the arguments of the target process
runargs <args>          # Set the current arguments, to be used by `run'
runargs ... >|>> <file> # Set the output redirection to be used by `run'
runargs ... < <file>    # Set the input redirection to be used by `run'
runargs                 # Clear the current arguments

Use `debug' by itself to inspect the current arguments.

See also `help prog'.
#
:restore (command)
%restore - Restore dbx to a previously saved state
restore [<filename>]   # Restore dbx to the state it was in when it was saved.

See also `help save' and `help replay'.
#
:save (command)
%save - Save commands to a file
save [-<num>] [<filename>] # Save all or all minus <num> commands since last
                             run/rerun/debug command to default file or
                             <filename>.

See also `help restore' and `help replay'.
#
:scopes (command)
%scopes - Print list of active scopes
scopes                 # Print list of active scopes, including namespaces
#
:search (command)
%search - Search forward in the current source file
search <string>        # Search forward for <string> in the current file
search                 # Repeat search, using last search string        
#
:setenv (ksh command)
%setenv - Set an environment variable
setenv <name> <string> # Set environment variable <name> to <string>
#
:source (command)
%source - Execute commands from a given file
source <filename>      # Execute commands from file <filename>. $PATH is not
                         searched.

See also `help .'.
#
:status (command)
%status - List event handlers (breakpoints, etc.)
status                 # Print trace's, when's, and stop's in effect
status <hid>           # Print status for handler <hid>
status -h              # Print trace's, when's, and stop's in effect including
                       # the hidden ones.
status -s              # The same, but the output can be read by dbx

                                (dbx) status -s > bpts 
                                ...
                                (dbx) source bpts

See also the `-r' flag under `help debug'.
#
:step (command)
%step - Step one source line or statement (stepping into calls)
step                   # Single step one line (step INTO calls).
                       # Non-active threads cannot be stepped.
step <n>               # Single step <n> lines (step INTO calls)
step up                # ... and out of the current function
step ... -sig <sig>    # ... and deliver the given signal
step to [<func>]       # Attempts to step into <func> in the current
                       # source line. If <func> is not given, <func> will
                       # be the last <func> called, as determined by the
                       # assembly code for the current source line.
                       # See also `help step to'

The dbxenv variable `step_events' controls whether breakpoints are enabled
during a step.

step ... <tid>         # Step the given thread. Does not apply to `step up'.
step ... <lwpid>       # Step the given LWP. 

See also `stepi' for machine-level stepping.
See also `help dbxenv' under `step_granularity'.
#
:step$$to (subtopic)
While an attempt is made to step into the last assembly call instruction or
step into a function (if given) in current source line, it is possible that
the call is not taken (due to conditional branch). In such cases that the
call is not taken or there is no call in the current source line, step will
step over the current source line. Special consideration on user-defined
assignment operators should be taken when `step to' is used.
#
:stepi (command)
%stepi - Step one machine instruction (stepping into calls)
stepi                  # Single step one machine instruction (step INTO calls)
stepi <n>              # Single step <n> machine instructions (step INTO calls)
stepi -sig <sig>       # ... and deliver the given signal
stepi ... <lwpid>      # ... the given LWP.
stepi ... <tid>        # ... the LWP on which the given thread is active.
#
:stop (command)
%stop - Set a source-level breakpoint
stop [ -update ]        # Stop execution now. Only valid within the body of a WHEN.
stop -noupdate          # Same as -update, but does not update GUI displays.
stop at <line>          # Stop execution at the line
stop in <func>          # Stop execution when <func> is called
stop inclass <clsname>  # C++ only: set breakpoints on all member functions
                          of a class/struct/union or template class
stop inmember <name>    # C++ only: set breakpoints on all member functions
                          <name>
stop infunction <name>  # C++ only: set breakpoints on all non-member
                          functions <name>

`stop' has a general syntax as follows:

        stop <event-specification> [ <modifier> ]

When the specified event occurs, the process is stopped.
See also `stopi' for setting a machine-level breakpoint.
For a list and the syntax of all events see `help event specification'.
For a general discussion of event management commands see `help events'.
#
:stopi (command)
%stopi - Set a machine-level breakpoint
stopi at <addr>         # Stop execution at location <addr>
stopi in <func>         # Stop execution when <func> is called.

stopi is similar to `stop' except that when the program stops due to a stopi
dbx shows the location in disassembly.

`stopi' has a general syntax as follows:

        stopi <event-specification> [ <modifier> ]

When the specified event occurs, the process is stopped.
For a list and the syntax of all events see `help event specification'.
For a general discussion of event management commands see `help events'.
#
:thread (command)
%thread - List or change the current thread
thread                      # Display current thread
thread <tid>                # Switch to thread <tid>. 

In the following variations, a missing <tid> implies the current thread.    

thread -info [ <tid> ]      # Print everything known about the given thread
thread -hide [ <tid> ]      # "hide" the given (or current) thread. It will
                              not show up in the generic `threads' listing.
thread -unhide [ <tid> ]    # "unhide" the given (or current) thread.
thread -unhide all          # "unhide" all threads.
thread -suspend <tid>       # Keep the given thread from ever running. A
                              suspended thread shows up with an `S' in the
                              threads list.
thread -resume <tid>        # Undo the effect of `-suspend'.
thread -blocks [ <tid> ]    # List all locks held by the given thread which are
                            # blocking other threads.
thread -blockedby [ <tid> ] # Show which synchronization object the given
                              thread is blocked by, if any.
#
:threads (command)
%threads - List all threads
threads                   # Print the list of all known threads
threads -all              # Print threads normally not printed (zombies)
threads -mode all|filter  # Controls whether `threads' prints all threads or
                            filters them by default.
threads -mode auto|manual # Under the GUI, enables automatic updating of the
                            thread listing.
threads -mode             # Echo the current modes
#
:sync (command)
%sync - Show information about a given synchronization object
sync -info <addr>       # Show information about the synchronization object
                        # at <addr>
#
:syncs (command)
%syncs - List all synchronization objects (locks)
syncs                   # List all synchronization objects (locks)
#
:lwpid (topic)
This is the term used for the system handle on an LWP. The syntax 
`l@<number>' is used and accepted by various commands to specify an 
LWP. The number refers to the ID of the LWP as returned by lwp_create() 
and furnished by the /proc interface.  `all' can usually be substituted 
to refer to all LWPs.
#
:trace (command)
%trace - Show executed source lines, function calls, or variable changes
trace -file <filename>  # Direct all trace output to the given <filename>.
                        # To revert trace output to standard output use
                        # `-' for <filename>.
                        # trace output is always appended to <filename>.
                        # It is flushed whenever dbx prompts and when the
                        # app has exited. The <filename> is always re-opened 
                        # on a new run or resumption after an attach.
trace step              # Trace each source line
trace next -in <func>   # Trace each source line while in the given function
trace at <line#>        # Trace given source line
trace in <func>         # Trace calls to and returns from the given function
trace inmember <func>   # Trace calls to any member function named <func>
trace infunction <func> # Trace when any function named <func> is called
trace inclass <class>   # Trace calls to  any member function of <class>
trace change <var>      # Trace changes to the variable
...

`trace' has a general syntax as follows:

        trace <event-specification> [ <modifier> ]

When the specified event occurs, a "trace" is printed.
For a list and the syntax of all events see `help event specification'.
For a general discussion of event management commands see `help events'.

The speed of a trace is set using the dbxenv variable trace_speed.

Source line tracing (the 'step' event specification) can be customized
by using the non-generic modifiers -nosrc and -nocalls.
        -nocalls        Defeats the Entering/leaving trace messages.
        -nosrc          Defeats the printing of the sourceline contents.
                        Instead the trace printout is:
                                trace: "<filename>":<lineno>
Using these two modifiers will reduce the time and disk-space overhead
of traces.

See `tracei' for machine-level trace.

An older syntax of trace is no longer accepted. (see `help old trace'
for a mapping between the old and the new syntax).

#
:old$$trace (topic)
In the following each pair of lines shows the old trace syntax followed by
the new equivalent:

        trace                   # Trace each source line
        trace step

        trace in <proc>         # Trace each source line while in proc
        trace next -in <proc>

        trace <line#>           # Trace given source line
        trace at <line#>        # (Analogous to "stop at")

        trace <proc>            # Trace calls to the procedure
        trace in <proc>         # (Analogous to "stop in")

        trace var at <line#>    # Print var when <line> is reached
        when at <line#> {
            echo at line $lineno in file \"$(basename $file)\": var = $[var];
        }

        trace <var> [in <proc>] # Trace changes to the variable
        trace change <var> [ -in <proc> ]
#
:tracei (command)
%tracei - Show machine instructions, function calls, or variable changes
tracei step              # Trace each machine instruction
tracei next -in <func>   # Trace each instruction while in the given function
tracei at <address>      # Trace instruction at given address
tracei in <func>         # Trace calls to and returns from the given function
tracei inmember <func>   # Trace calls to any member function named <func>
tracei infunction <func> # Trace when any function named <func> is called
tracei inclass <class>   # Trace calls to any member function of <class>
tracei change <var>      # Trace changes to the variable
...

tracei is really a shorthand for `trace <event-specification> -instr'
where the -instr modifier causes tracing to happen at instruction 
granularity instead of source line granularity and when the event
occurs the printed information is in disassembly format as opposed
to source line format.

See `help trace' for more information.
#
:unbutton (command)
%unbutton - Remove GUI buttons
unbutton <cmd>         # Remove all GUI buttons containing <cmd>
unbutton -a            # Remove all GUI buttons
                         This command is silently ignored unless dbx is running
                         under control of the GUI.
#
:undisplay (command)
%undisplay - Undo `display' commands
undisplay <exp>, ...   # Undo a `display <exp>' command
undisplay <n>, ...     # Undo the `display' commands numbered <n>...
undisplay 0            # Undo all `display' commands
#
:unhide (command)
%unhide - Undo `hide' commands
unhide 0               # Delete all stack frame filters
unhide <regexp>        # Delete stack frame filter <regexp>
unhide <num>           # Delete stack frame filter number <num>
                         The `hide' command lists the filters with numbers.
#
:unintercept (command)
%unintercept - Undo `intercept' commands (C++ only)
unintercept <typename>    # Delete <typename> from `intercept' list
unintercept -a            # Delete all types from `intercept' list
unintercept -x <typename> # Delete <typename> from `intercept -x' list
unintercept -x -a         # Delete all types from `intercept -x' list
unintercept               # List intercepted types

<typename> may be one of -unhandled or -unexpected.

See also `help intercept'.
#
:up (command)
%up - Move up the call stack (toward `main')
up                     # Move up the call stack one level
up <number>            # Move up the call stack <number> levels
up -h [<number>]       # Move up the call stack, but don't skip hidden frames
#
:use (command)
%use - List or change the directory search path
This command is an anachronism and usage of this command is mapped to 
the following `pathmap' commands: 

    `use'  => `pathmap -s'
    `use <dir>' => `pathmap <dir>'

See `help pathmap' for more details.

The `use' command will not be accepted in future releases.
#
:whatis (command)
%whatis - Print type of expression or declaration of type
whatis [-n] [-r] <name>   # Print the declaration of the non-type <name>
whatis -t [-r] <type>     # Print the declaration of the type <type>
whatis -e [-r] [-d] <exp> # Print the type of the expression <exp>

                      -r : Print information about base classes (C++ only)
                      -d : Show dynamic type instead of static type (C++ only)
                           (See also `help c++ whatis')
#
:when (command)
%when - Execute commands on given event
when at <line> { cmd; }         # Execute command(s) when <line> reached
when in <proc> { cmd; }         # Execute command(s) when <proc> called

`when' has a general syntax as follows:

        when <event-specification> [ <modifier> ] { <cmd> ... ; }

When the specified event occurs, the <cmd>s are executed.
For a list and the syntax of all events see `help event specification'.
For a general discussion of event management commands see `help events'.
See also `wheni' for executing commands on given low-level event.
#
:wheni (command)
%wheni - Execute commands on given low-level event
wheni at <addr> { cmd; }         # Execute command(s) when <address> reached

`wheni' has a general syntax as follows:

        wheni <event-specification> [ <modifier> ] { <cmd> ... ; }

When the specified event occurs, the <cmd>s are executed.
For a list and the syntax of all events see `help event specification'.
For a general discussion of event management commands see `help events'.
#
:where (command)
%where - Print the call stack
where                  # Print a procedure traceback
where <num>            # Print the <num> top frames in the traceback
where -f <num>         # Start traceback from frame <num>
where -h               # Include hidden frames
where -l               # include library name with function name
where -q               # Quick traceback (only function names)
where -v               # Verbose traceback (include function args and line info)

Any of the above forms may be followed by a thread or LWP ID to obtain the
traceback for the specified entity.
See also the commands `hide' and `unhide'.
#
:whereami (command)
%whereami - Display the current source line
whereami                # Display the source line corresponding to the
                          current location (top of the stack), and the
                          source line corresponding to the current frame,
                          if different.
whereami -instr         # Same as above, except that the current disassembled
                          instruction is printed instead of the source line.
#
:whereis (command)
%whereis - Print all uses of a given name, or symbolic name of an address
whereis <name>         # Print all declarations of <name>
whereis -a <address>   # Print location of an address expression
#
:which (command)
%which - Print the full qualification of a given name
which [-n] <name>           # Print full qualification of <name>
which -t <type>             # Print full qualification of the type <type>
#
:whocatches (command)
%whocatches - Tell where a C++ exception would be caught
whocatches <type>       # Tell where (if at all) an exception of type <type>
                          would be caught if thrown at the current point of
                          execution. Assume the next statement to be
                          executed is a `throw x' where x is of type <type>,
                          and display the line number, function name, and frame
                          number of the `catch' clause which would catch it.

                          Will return "<type> is unhandled" if the
                          catch point is in the same function that is doing
                          the throw.
#
#
# Runtime checking stuff is here
#
:check (rtc command)
%check - Enable checking of memory access, leaks, or usage (RTC)
check

    Print current status of Runtime checking (RTC).

    Note: The features that are enabled by this command are
    reset to their initial state by the 'debug' command.

check -access

    Turn on access checking.  RTC reports the following errors:
        baf     # Bad free
        duf     # Duplicate free
        maf     # Misaligned free
        mar     # Misaligned read
        maw     # Misaligned write
        oom     # Out of memory
        rua     # Read from unallocated memory
        rui     # Read from uninitialized memory
        wro     # Write to read-only memory
        wua     # Write to unallocated memory

    The default behavior is to stop the process after detecting
    each access error, which can be changed using the `rtc_auto_continue'
    dbxenv variable. When set to `on', access errors are logged to a file
    (the file name is controlled by the `rtc_error_log_file_name'
    dbxenv variable).  See `help dbxenv'.

    By default each unique access error is only reported the first
    time it happens. Change this behavior using the `rtc_auto_suppress'
    dbxenv variable (the default setting of this variable is `on').  
    See `help dbxenv'.
    
check -leaks [-frames <n>] [-match <m>]

    Turn on leak checking.  RTC reports the following errors:
        aib     # Possible memory leak - only pointer points in the middle of
                # the block 
        air     # Possible memory leak - pointer to the block exists only
                # in register
        mel     # Memory leak - no pointers to the block

    With leak checking turned on, you get an automatic leak report when
    the program exits. All leaks including possible leaks are reported at 
    that time. By default, a non-verbose report is generated (controlled 
    by the dbxenv `rtc_mel_at_exit'). However, you can ask for a leak report
    at any time (see `help showleaks').

    -frames <n> implies that up to <n> distinct stack frames are displayed 
    when reporting leaks. -match <m> is used for combining leaks; 
    if the call stack at the time of allocation for two or more leaks 
    matches <m> frames, then these leaks are reported in a single combined 
    leak report.

    The default value of <n> is 8 or the value of <m> (whichever is larger).  
    Maximum value of <n> is 16.  The default value of <m> is 3 for C++, 2
    otherwise.

check -memuse [-frames <n>] [-match <m>]

    Turn on memory use (memuse) checking. check -memuse also implies
    check -leaks. In addition to a leak report at program exit, you also
    get a blocks in use (biu) report. By default a non-verbose blocks in
    use report is generated (controlled by the dbxenv `rtc_biu_at_exit')
    At any time during program execution you can see where the memory 
    in your program has been allocated (see `help showmemuse').  

    -frames <n> implies that upto <n> distinct stack frames
    will be displayed while reporting memuse/leaks. -match <m> is used for 
    combining these reports; if the call stack at the time of allocation 
    for two or more leaks matches <m> frames, then these are reported in a 
    single combined memuse/leak report.  

    The default value of <n> is 8 or the value of <m> (whichever is larger).  
    Maximum value of <n> is 16.  The default value of <m> is 3 for C++, 2
    otherwise.
    See check -leaks as well.

check -all [-frames <n>] [-match <m>]

    Equivalent to `check -access; check -memuse [-frames <n>] [-match <m>]'
    The value of rtc_biu_at_exit dbxenv variable is not changed with check -all.
    So by default no memory use report is generated at exit.  See 
    `help dbxenv' for the description of the rtc_biu_at_exit variable.

check [<funcs>] [<files>] [<loadobjects>]

    Equivalent to `check -all; suppress all; unsuppress all in <funcs> <files>
    <loadobjects>;'  You can use this to focus RTC on places of interest.

NOTE on errors suppressed by default:

  To detect all errors, RTC does not require the program be compiled -g.
  However, symbolic (-g) information is sometimes needed to guarantee
  the correctness of certain errors (mostly read from uninitialized memory).
  For this reason certain errors (`rui' for a.out and `rui + aib + air' for
  shared libraries) are suppressed if no symbolic information is available.
  This behavior can be changed by using `suppress' and `unsuppress'.

See `help uncheck' for information to turn off checking.
See `help suppress' for information on suppressing of errors
See `help rtc' for an introduction to RTC.

See also `help showleaks' and `help showmemuse'.
#
:uncheck (rtc command)
%uncheck - Disable checking of memory access, leaks, or usage (RTC)
uncheck                         # print current status of checking
uncheck -access                 # turn off access checking
uncheck -leaks                  # turn off leak checking
uncheck -memuse                 # turn off memuse checking (leak checking
                                # is turned off as well)
uncheck -all                    # equivalent to `uncheck -access; uncheck
                                #   -memuse'
uncheck [<funcs>] [<files>] [<loadobjects>]
                                # equivalent to `suppress all in
                                # <funcs> <files> <loadobjects>;'
See `help check' for information to turn on checking
See `help suppress' for information on suppressing of errors
See `help rtc' for an introduction to RTC.
#
:suppress (rtc command)
%suppress - Suppress reporting of memory errors (RTC)
suppress                        # History of suppress and unsuppress commands
                                # (not including "-d" and "-reset" commands)
suppress -d                     # List of errors being suppressed in functions
                                # not compiled for debugging (default
                                # suppression).  This list is per loadobject.  
                                # These errors can be unsuppressed only 
                                # by using the `unsuppress -d' command.
suppress -d <errors>            # Modify the default suppressions for all
                                # loadobjects by further suppressing <errors>
suppress -d <errors> in <loadobjects>
                                # Modify the default suppressions in the
                                # <loadobjects> by further suppressing
                                # <errors>
suppress -last                  # At error location suppress present error
suppress -reset                 # Set the default suppression to the
                                # original value (startup time)
suppress -r <id> ...            # Remove the (un)suppress events as given
                                # by the id(s) (id(s) can be obtained by
                                # doing `(un)suppress'.
suppress -r 0 | all | -all      # Remove all the (un)suppress events as given
                                # by `(un)suppress'.
suppress <errors>               # Suppress <errors> everywhere   
suppress <errors> in [<funcs>] [<files>] [<loadobjects>]
                                # Suppress <errors> in list of <funcs> and list
                                # of <loadobjects>
suppress <errors> at <line>     # Suppress <errors> at <line>
suppress <errors> at "<file>":<line> # Suppress <errors> at <line> in <file>
suppress <errors> addr <addr>   # Suppress <errors> at location <addr>

The <errors> are blank separated and can be any combination of:

all     # All errors
aib     # Possible memory leak - address in block
air     # Possible memory leak - address in register
baf     # Bad free
duf     # Duplicate free
mel     # Memory leak
maf     # Misaligned free
mar     # Misaligned read
maw     # Misaligned write
oom     # Out of memory
rua     # Read from unallocated memory
rui     # Read from uninitialized memory
wro     # Write to read-only memory
wua     # Write to unallocated memory

biu     # Block in use (allocated memory).  Though not an error, you
        # can use `biu' just like <errors> in the suppress commands.

Also note the "rtc_auto_suppress" variable:

dbxenv rtc_auto_suppress <on | off>  # If on, RTC error at a given location is
                                       reported only once.

See `help unsuppress' for information on unsuppressing errors.
See `help rtc' for an introduction to RTC.
#
:unsuppress (rtc command)
%unsuppress - Undo `suppress' commands (RTC)
unsuppress                      # History of suppress/unsuppress commands
                                # (not including "-d" and "-reset" commands)
unsuppress -d                   # List of errors being unsuppressed in functions
                                # that are not compiled for debugging.  This
                                # list is per loadobject.  Any other errors can
                                # be suppressed only by using the `suppress -d'
                                # command.
unsuppress -d <errors>          # Modify the default suppressions for all
                                # loadobjects by further unsuppressing <errors>
unsuppress -d <errors> in <loadobjects>
                                # Modify the default suppressions in the
                                # <loadobjects> by further unsuppressing
                                # <errors>
unsuppress -last                # At error location unsuppress present error
unsuppress -reset               # Set the default suppression mask to the
                                # original value (startup time)
unsuppress <errors>             # Unsuppress <errors> everywhere   
unsuppress <errors> in [<funcs>] [<files>] [<loadobjects>]
                                # Suppress <errors> in list of <funcs> and list
                                # of <loadobjects>      
unsuppress <errors> at <line>   # Unsuppress <errors> at <line>
unsuppress <errors> at "<file>":<line> # Unsuppress <errors> at <line> in <file>
unsuppress <errors> addr <addr> # Unsuppress <errors> at location <addr>

The <errors> are blank separated and can be any combination of:

all     # All errors
aib     # Possible memory leak - address in block
air     # Possible memory leak - address in register
baf     # Bad free
duf     # Duplicate free
mel     # Memory leak
maf     # Misaligned free
mar     # Misaligned read
maw     # Misaligned write
oom     # Out of memory
rua     # Read from unallocated memory
rui     # Read from uninitialized memory
wro     # Write to read-only memory
wua     # Write to unallocated memory

biu     # Block in use (allocated memory).  Though not an error, you
        # can use `biu' just like <errors> in the unsuppress commands.

See `help suppress' for information on suppressing errors.
See `help rtc' for an introduction to RTC.
#
:showleaks (rtc command)
%showleaks - Report new memory leaks since last `showleaks' command (RTC)
showleaks [-a] [-m <m>] [-n <num>] [-v]

   Report new memory leaks since the last `showleaks' command.
   In the default non-verbose case, a one line report per "leak" record is
   printed. "Actual leaks" are reported followed by the "possible leaks".
   Reports are sorted according to the combined size of the leaks. 

    -a   Show all the leaks generated so far (not just the leaks since the
         last `showleaks' command).

    -m <m>    Used for combining leaks; if the call stack at the time 
         of allocation for two or more leaks matches <m> frames, then these 
         leaks are reported in a single combined leak report.  If the -m option
         is given, it overrides the global value of <m> (specified with 
         the `check' command).

    -n <num>   Show up to <num> records in the report.  Default is to show
         all records.

    -v   Generate verbose output.  Default is to show non-verbose output.

    See `help check'.
:showmemuse (rtc command)
%showmemuse - Show memory used since last `showmemuse' command (RTC)
showmemuse [-a] [-m <m>] [-n <num>] [-v]

    showmemuse shows the memory blocks in use since the last `showmemuse'
    command.  A one line report per "block in use" record is printed.
    It sorts the reports according to the combined size of the blocks.
    Any leaked blocks since the last `showleaks' command are also included
    in the report.

    -a   Show all the blocks in use (not just the blocks since the last
         showmemuse command).

    -m <m>   Used for combining the blocks in use reports.  If the
         call stack at the time of allocation for two or more blocks
         matches <m> frames then these blocks are reported in
         a single combined report.  If the -m option is given, it overrides
         the global value of <m>.

    -n <num>   Show up to <num> records in the report.  Default is 20.

    -v   Generate verbose output.  Default is to show non-verbose output.

    The default value of <m> is 2 or (if specified) the global value
    last given with the `check' command.  The default value of <num> 
    option is 20.

    See `help check'.
:showblock (rtc command)
%showblock - Show where the particular heap block was allocated from (RTC)
showblock -a <addr>

    When memory use checking or memory leak checking is turned on, showblock
    shows the details about the heap block at address <addr>. The details 
    include the location of the blocks' allocation and its size. (see `help check')
#
#
#
# Collector data is here
#
:collector (command)
%collector - Collect performance data

collector <command>           # Specify collector command
   enable                     # Enable collector, open new experiment
   disable                    # Stop collecting performance data and
                              # close experiment
   pause                      # Stop collecting performance data but
                              # leave experiment open
   resume                     # Start performance data collection after pause
   profile <options>          # Specify profiling settings
   synctrace <options>        # Specify synctrace settings
   hwprofile <options>        # Specify hardware counter profiling settings
   heaptrace <options>        # Specify heaptrace settings
   mpitrace <options>         # Specify mpitrace settings
   sample <options>           # Specify sampling settings
   dbxsample <options>        # Specify sampling behavior when dbx stops process
   store <options>            # Experiment file control and settings
   limit <options>            # Experiment file size limit control
   show <options>             # Show current collector settings
   status                     # Inquire about status of current experiment

To start collecting data, type `collector enable'.
To turn off data collection, type `collector disable'.

Type `collector show' to see all the collector settings at any time.
Also see `help collector mt'.


#
:collector$$profile (command)
collector profile <options>     # Specify profile options
    <on|off>                    # Specify profile data collection mode
    timer <milliseconds>        # Specify profile timer period
#
:collector$$synctrace (command)
collector synctrace <options> # Specify synctrace options
    <on|off>                  # Specify synctrace data collection mode
    threshold <microseconds>  # Specify threshold value in microseconds
    threshold calibrate       # Threshold value will be automatically calculated
#
:collector$$hwprofile (command)
collector hwprofile <options>   # Specify hardware counter options
    <on|off>                    # Specify profile data collection mode
    list                        # Print out the list of available counters
    counter <name> <interval> [<name2> <interval2>]
                                # Specify hardware counter name(s) and interval(s)
#
:collector$$dbxsample (command)
collector dbxsample <options> # Specify dbx sampling behavior on stopping process
    <on|off>                  # Specify whether or not to record a sample
#
:collector$$heaptrace (command)
collector heaptrace <options> # Specify heaptrace options
    <on|off>                  # Specify heaptrace data collection mode
#
:collector$$mpitrace (command)
collector mpitrace <options>  # Specify mpitrace options
    <on|off>                  # Specify mpitrace data collection mode
#
:collector$$sample (command)
collector sample <options>        # Specify sample options
    <periodic|manual>             # Specify sampling mode
    period <seconds>              # Specify sampling period in seconds
    record <name>                 # Record a sample, with optional name
#
:collector$$show (command)
collector show <options>          # Show settings of one or more categories
    <options> absent from cmd     # Show all settings
    all                           # Show all settings
    profile                       # Show profile settings
    synctrace                     # Show synctrace settings
    hwprofile                     # Show hwprofile settings
    heaptrace                     # Show heaptrace settings
    limit                         # Show experiment size limit
    mpitrace                      # Show MPI trace settings
    sample                        # Show sample settings
    store                         # Show store settings
#
:collector$$store (command)
collector store <options>         # Specify store options
    directory <string>            # Specify directory where experiment is stored
    experiment <string>           # Specify experiment file name
    group <string>                # Specify experiment group name
#
:collector$$status (command)
collector status              # Inquire status about current experiment
#
:collector$$mt (topic)
Data collection for MT applications is supported.  There are some
restrictions and limitation about MT collection:

o You will not be able to collect information about the code which executes
        in the init sections of shared libraries (a.out is ok).

o For multithreaded applications, you can attach to the process, and start
        the collector for profiling.  You must follow the instructions
        in the collector.1 man page to do so.
        
o If you are collecting synchronization trace data, you must have LD_PRELOAD'd
        libcollector.so before starting the execution of the program.

########################################################################
#################### Language Specific Information #####################
########################################################################
#
# C++ specific help is here
#
:c++ (topic)
Use the command `help c++ <subtopic>' to get more help on one of the
subtopics.

    whatis       # finding out about class definitions
    printing     # printing or displaying inherited data members
    dynamic      # finding out dynamic information about an object pointer
    vfuncs       # information about debugging virtual functions
    rtti         # using run-time type information
    inclass      # setting breakpoints on all member functions of a class
    inmember     # setting breakpoints on all overloaded member functions
    inobject     # setting breakpoints on all member functions of a class
    infunction   # setting breakpoints on all overloaded non-member functions
    overloaded   # dealing with overloaded functions/data members

Or use `help -k <keyword>' to find help topics that mention the word <keyword>.
#
:c++$$whatis (subtopic)
The `whatis' command, when run on a C++ class or structure, provides
you with a list of all the defined member functions (undefined member
functions are not listed), the static data members, the class friends,
and the data members that are defined explicitly within that class.
Specifying the `-r' (recursive) option adds information from the
inherited classes.

The `-d' flag, when used with the `-e' flag, uses the dynamic type
of the expression.  See `help c++ dynamic' for more information.

With C++ template related identifiers are displayed as follow:
ALL template definitions are listed with "whatis -t".
Function template instantiations are listed with "whatis".
Class template instantiations are listed with "whatis -t".
#
:c++$$printing (subtopic)
When you give `print' or `display' a `-r' (recursive)
option, the GUI shows you all the data members directly
defined by a class as well as those inherited from base classes.

These three commands also take a `-d' or `+d' option that toggles the
default behavior of the dbxenv `output_dynamic_type'.  See `help c++ dynamic'
for more information.
#
:c++$$dynamic (subtopic)
In C++, an object pointer has two types: its static type (what is
defined in the source code), and its dynamic type (what an object
was before any casts were made to it). dbx can sometimes provide you
 with the information about the dynamic type of an object
when using the `print', `display', and `whatis' command
with the `-d' option or by setting the dbxenv `ouput_dynamic_type' to `on'.

In general, when an object has a virtual function table ("vtable") in it,
 dbx can use the information in the vtable to correctly figure out what
 an object's type is.

Using the `-d' flag (or setting the dbxenv `output_dynamic_type' to `on')
when there is no process running generates a "program is not
active" error message because it is not possible to access dynamic
information when there is no process.  An "illegal cast on class
pointers" error message is generated if you try to find a dynamic
type through a virtual inheritance (casting from a virtual baseclass
to a derived class is not legal in C++).
#
:c++$$vfuncs (subtopic)
Virtual functions can be called just like any other function by using
the `print' or `call' command, or any other command that executes a
function call.

NOTE: This support is only available with Sun C++ compilers 3.0 or
greater.
#
:c++$$rtti (subtopic)
dbx supports the C++ `dynamic_cast' and `typeid' operators. When evaluating
expressions with these two operators, dbx makes calls to certain rtti
functions made available by the compiler. If the source doesn't explicitly
use the operators, those functions may not have been generated by the 
compiler, and dbx will fail to evaluate the expression.
#
:c++$$inclass (subtopic)
The `inclass' event specifier allows you to set a breakpoint at all
member functions defined for a specified class.  It can be used with
the `stop', `when', and `trace' commands.  See `help event specification'.
#
:c++$$inmember (subtopic)
The `inmember' event specifier allows you to set a breakpoint at all
member functions with a specified name that are defined in any class.
It can be used with the `stop', `when', and `trace' commands.  See `help 
event specification'.  
#
:c++$$inobject (subtopic)
The `inobject' event specifier allows you to set a breakpoint at all
non-static member functions defined for a specified c++ object (pointer
to a C++ class/struct/union) and stop only if called via the object. 
It can be used with the `stop', `trace'  and `when' commands. If the
dbxenv variable `output_dynamic_type' is on, dbx will use the dynamic type
of the object. See `help c++ dynamic' and `help event specification'.
#
:c++$$infunction (subtopic)
The `infunction' event specifier allows you to set a breakpoint at all
non-member functions with a specified name that are defined.  It can
be used with the `stop' and `when' commands.  See `help event
specification'.
#
:c++$$overloaded (subtopic)
dbx should be able to determine which variable or function you
are referring to except when:

* You reference an overloaded function by name only
* You reference a function or variable with a leading ``

Consider the following example:

        int foo(double);
        int foo(int);
        int bar();
        class x {
                int bar();
        };

When you stopped at a non-member function, you can say:

        stop in foo(int)

to set a breakpoint at the global foo(int).  To set a breakpoint at
the member function you can use the command:

        stop in x::bar()

If you just say:

        stop in foo

dbx will not know if you mean the global function foo(int) or the
global function foo(double) and be forced to give you an overloaded
menu for clarification.  Lastly, if you say:

        stop in ``bar

dbx will not know if you mean the global function bar() or the member
function bar() and give you an overloaded menu.
#
:fortran90
See `help fortran'
#
:fortran77
See `help fortran'
#
:f90
See `help fortran'
#
:f77
See `help fortran'
#
:fortran (topic)

Breakpoints
-----------
In FORTRAN 77 the name of the MAIN program is MAIN, not main.
To stop in the main program, you must use `stop in MAIN'.

Expressions
-----------
There is new support for parsing FORTRAN style expressions,
handling complex numbers, and calling most FORTRAN intrinsic 
functions. It may be necessary to avoid situations such as 
"print 1.eq.1" by using "print 1 .eq. 1" due to the non-FORTRAN
nature of dbx's token scanner.
#
########################################################################
########################### KSH-specific help topics ###################
########################################################################
# I18N - translate this topicname to match same word in `Other Topics' message
:editing (ksh topic)
Use either `help editing emacs' or `help editing vi'
#
# I18N - translate this topicname (only before $$) to match previous topic
:editing$$emacs (ksh subtopic)
Use `set -o emacs' to enable the emacs-style editor.  The `bind' command
 lists the current key bindings or change the bindings.  Some of the more
 important default bindings are:

        ^A = beginning-of-line          ^B = backward-char
        ^D = eot-or-delete              ^E = end-of-line
        ^F = forward-char               ^G = abort
        ^K = kill-to-eol                ^L = redraw
        ^N = down-history               ^P = up-history
        ^R = search-history             ^^ = quote
        ^? = delete-char-backward       ^H = delete-char-backward
        ^[b = backward-word             ^[d = delete-word-forward
        ^[f = forward-word              ^[^H = delete-word-backward
        ^[^[ = complete                 ^[? = list-command

See also `help bind' and `help editing vi'
#
# I18N - translate this topicname (only before $$) to match previous topic
:editing$$vi (ksh subtopic)
Use `set -o vi' to enable the vi-style editor.  The `bind' command
lists the current key bindings and changes the bindings.  
The commands (in command mode) are:

   a = append           A = append at EOL
   c = change           d = delete
   G = goto line        h = backward char
   i = insert           I = insert at BOL
   j = next line        k = prev line
   l = forward line     n = next match
   N = prev match       p = put after 
   P = put before       r = repeat
   R = replace          s = substitute
   u = undo             x = del char
   X = del prev char    y = yank
   ~ = transpose case   _ = last arg
   * = expand           = = list expansion
   - = prev line        + = next line
   sp = forward char    # = comment out command
   ? = search history from beginning   
   / = search history from current   

In insert mode, the following keystrokes are special:
   ^? = delete char     ^H = delete char  
   ^U = kill line       ^W = delete word

See also `help editing emacs' and `help bind'.
#
:path (ksh topic)
By default, dbx searches your $PATH for commands. To disable $PATH
search, type `set +o path'. See `help ksh options' and `help ksh PATH'.
#
:PATH (ksh topic)
By default, dbx searches your $PATH for commands. To disable $PATH
search, type `set +o path'. See `help ksh options' and `help ksh PATH'.
#
:ksh (topic)
The command syntax is that of the KornShell. Branching and looping,
environment variables, history, and command-line editing are all supported.
Use the command `help ksh <subtopic>' for more information on the following:

    aliases     # the list of builtin aliases
    backslash   # the list of backslash escapes recognized by `kprint'
    builtins    # the list of builtin commands
    differences # known differences between the dbx interpreter and ksh
    environment # the list of predefined variables
    expressions # using ksh expressions, $[] language expressions,  etc.
    options     # `set -o' options
    syntax      # a simplified ksh grammar
    variables   # setting, testing, modifying ksh variables
    <varname>   # usage of specific pre-defined variables

Or use `help -k <keyword>' to find help topics that mention the word <keyword>.
#
:ksh$$aliases (subtopic)
The following aliases are predefined:

        [='\['
        alias='kalias'
        echo='kprint'
        exception='print *$exception'
        functions='typeset -f'
        integer='typeset -i'
        nohup='nohup '
        pwd='kprint -r "$PWD"'
        r='fc -e -'
        suspend='kill -STOP $$'
        type='whence -v'
        x='examine'
#
:ksh$$backslash (subtopic)
The following character sequences are treated specially by the `kprint'
command unless given the `-r' option:

        \a              alert (bell, ASCII 007)
        \b              backspace
        \c              suppresses terminating newline, like `-n' option
        \f              form feed
        \n              newline
        \r              carriage return
        \t              tab
        \v              vertical tab
        \\              backslash
        \nnn            (1 to 3 octal digits) the 8-bit character whose
                        ASCII code is nnn

Backslash is also a quoting character. To echo a form feed, one of the 
following could be used:

        (dbx) kprint -n \\f
        (dbx) kprint -n '\f'
        (dbx) kprint -n "\f"
#
:ksh$$builtins (subtopic)
The following ksh commands are built into dbx:

    :           .               [               bg              bind
    break       builtin         cd              continue        dalias
    eval        exec            exit            export          false
    fc          fg              getopts         hash            jobs
    kalias      kill            kprint          let             read
    readonly    return          set             sh              shift
    test        times           trap            true            typeset
    ulimit      umask           unalias         unset           wait
    whence

Use the command `help <cmdname>' for more specific help.
Or use `help -k <keyword>' to find help topics that mention the word <keyword>.
#
:ksh$$differences (subtopic)
The known differences between the dbx command interpreter (pdksh) and `ksh88' are:

(1) No array support.
(2) Unimplemented `set -o' options: allexport bgnice gmacs markdirs noclobber
    nolog privileged protected viraw.
(3) New `set -o' options: hashall ignoresuspend path.
(4) Unimplemented `typeset' options: -l, -u, -L, -R, -H, -Z.
(5) A new `typeset' option, -q.
(6) dbx commands are built in.
(7) The `bind' command allows rebinding of editing functions.
(8) Language expressions; i.e., $[p->x].
(9) C syntax for hex and octal numbers.
(10) Csh-like history access.
(11) Csh-like alias arguments.
(12) `print' is named `kprint'.
(13) New `kprint' and `read' option, -e.
(14) Backquote is a dbx scope-resolution operator; use $() instead.
(15) [[ expr ]] is unimplemented.
(16) New pattern operators (like `@(...)') are unimplemented.
(17) Co-processes are not implemented.
(18) `kill' without an argument kills the target process.
#
:ksh$$environment (subtopic)
The following standard ksh environment variables are predefined:
  CDPATH 
  COLUMNS 
  EXECSHELL 
  FCEDIT 
  HISTSIZE 
  HOME
  IFS 
  MAIL 
  MAILCHECK
  MAILPATH 
  OLDPWD 
  OPTARG 
  OPTIND 
  PATH 
  PPID 
  PS1 
  PS2 
  PS3 
  PS4 
  PS5 
  PWD 
  RANDOM 
  REPLY
  SECONDS 
  _ # - ? $ ! * @

See `help ksh specialvars' for the ones with non-alphanumeric names. See
`help ksh <var>' for the others.

There are several variables whose name starts with `DBX_'.  These correspond
to the `dbxenv' variables.  See `help dbxenv' for a list of these variables.

The read-only status variables are: dbxdir, havegui, mtfeatures, and version.
See `help dbxdir', `help havegui', `help mtfeatures', and `help version'
for details.

The variable `last_choice' is set automatically by overload resolution.
See `help last_choice' for details.

The following are readonly dbx state variables:

  ins lineno vlineno line
  func vfunc class vclass file vfile loadobj vloadobj scope vscope
  funcaddr caller
  newhandlerid handlerid firedhandlers
  proc prog
  lwp thread
  dllist dlobj
  exception
  sig sigstr sigcode sigcodestr
  exitcode
  falsehits
  syscode sysname

See `help event variables' for the meaning of each.

Also, the names of the registers are reserved.  See `help registers'.
#
:ksh$$expressions (subtopic)
There are two types of expressions in dbx, ksh expressions and language
expressions. The first type supports only 32-bit integer values and
the following operators (as in C):

        || && | & ^ == != > < >= <= >> << + - * / % ! ~ ()
        = += -= *= /= %= &= |= ^= <<= >>=

To evaluate a ksh expression, merely wrap it in (()). The `$' is
permitted but not required for a reference to a ksh variable. It must
not be used on the left side of an assignment.

The second type supports all the data types of the target language and
most of its operators (except the assignment operators). To evaluate a
language expression, wrap it in $[]. $[] can appear inside (()), but
not vice versa.  An expression in $[] is evaluated in the current
language (see `help language'). The `print' flags are recognized; see
`help print'.

For example:

        (dbx) typeset -i x      # x is stored internally as an integer  
        (dbx) z=3 x=5           # z is (by default) a string; (()) not required 
        (dbx)                   # for simple integer assignment
        (dbx) ((ww = z << x))   # (()) required here, spaces are permitted
        (dbx) echo $ww
        96
        (dbx) z=$[p->x[3]]      # z is assigned the (string) result; p is
        (dbx)                   # a pointer in the target process
        (dbx) ((s = z/$[sizeof double])) # $[] embedded in (())

dbx will print L LL and U as suffixes for variable values when
it knows the type of the variable (long, long long, and unsigned
respectively).  Here is an example of two ways to assign a program
variable into a ksh variable by removing this suffix.

        (dbx) whatis i
        long long i;
        (dbx) print i
        i = 8LL
        (dbx) z=$[-flld i] 
        (dbx) echo $z
        8
        (dbx) z=$[(int) i]
        (dbx) echo $z
        8
        (dbx) 

#
:ksh$$options (subtopic)
The following options are recognized by `set -o'. The one-letter
abbreviation, if any, is in parentheses.

        emacs           emacs editing mode
        errexit         (-e) exit if an error occurs
        hashall         (-h) remember full path for all UNIX commands executed
        ignoreeof       do not exit on end-of-file
        interactive     (-i) stdin is a terminal
        keyword         (-k) treat var=value as an assignment even in an
                        argument list
        monitor         (-m) run background jobs in different process group
        noexec          (-n) suppress execution of commands
        noglob          (-f) suppress expansion of wildcards
        nounset         (-u) report an error if an unset variable is referenced
        path            search the $PATH if command is not found
        stdin           (-s) take commands from stdin
        trackall        (-h) same as `hashall'
        verbose         (-v) echo each command before execution
        vi              vi editing mode
        xtrace          (-x) echo command after evaluation but before execution
#
:ksh$$specialvars (subtopic)
The following special variables are predefined:

        $_      The last argument of the previous simple command, also
                the pathname of the mailfile when checking for mail
        $#      The number of positional parameters, $1 ...
        $-      The set of options which were supplied at invocation
        $?      The return value of the last command executed, 0 to 255.
                If greater than 127, indicates that the command was terminated
                by a signal.  The signal number is equal to $? minus 128.
        $$      The process ID of this dbx process
        $!      The process ID of the last background process
        $*      The positional parameters
        $@      The positional parameters

The last two are equivalent except when quoted. "$*" yields one argument
with the positional parameters separated by spaces. "$@" yields n arguments,
each quoted with "".  If the positional parameters are:
        a
        hi there
        foo

(that is, three parameters, one containing a space), "$*" is equal to

        "a hi there foo"

whereas "$@" is

        "a" "hi there" "foo"
#
:ksh$$CDPATH (variable)
The CDPATH variable contains a colon-separated list of directories which
will be searched for the argument of a `cd' command, if the argument does
not begin with a slash. The current working directory is not searched by 
default if $CDPATH is set.  It is null by default.
#
:ksh$$COLUMNS (variable)
The COLUMNS variable should reflect the width of the terminal.  It is used
by the built-in command line editors.
#
:ksh$$EXECSHELL (variable)
The EXECSHELL variable contains the full pathname of the default shell
to use when executing scripts.  The default is `/bin/sh'.
#
:ksh$$FCEDIT (variable)
The FCEDIT variable contains the full path name of the default editor for
the `fc' command.  The implicit default is `/bin/ed'.
#
:ksh$$HISTSIZE (variable)
The HISTSIZE variable contains the number of commands which will be saved
in the history.  Larger numbers use more memory.  Default is 15.
#
:ksh$$HOME (variable)
The HOME variable is the default argument for the `cd' command, the place
that dbx looks for the startup file .dbxrc, and the result
of expanding `~' in pathnames.
#
:ksh$$IFS (variable)
The IFS variable contains the `internal field separators'.  These are the
characters which separate parameters to commands.  The default is
`space', `tab', and `newline'.
#
:ksh$$MAIL (variable)
The MAIL variable contains the full pathname of your incoming mail file.
This file is checked periodically (see `help ksh MAILCHECK') for incoming
 mail if $MAILPATH is not set (see `help ksh MAILPATH').
#
:ksh$$MAILCHECK (variable)
The MAILCHECK variable contains the minimum number of seconds that must
elapse before dbx checks for incoming mail.  The check is performed just
before printing the prompt, if $MAILCHECK seconds have elapsed since the
last check.  If $MAILCHECK is null or is zero, the check is performed
before each prompt.  If $MAILCHECK is unset, or is set to a non-numeric
value, checking for mail is disabled.  The default is 600 seconds (ten
minutes).
#
:ksh$$MAILPATH (variable)
The MAILPATH variable contains a colon-separated list of files which
will be checked for incoming mail.  Each pathname may be followed by
a question mark and a message to be printed.  The default message is
`you have mail in $_' (the $_ variable is set to the full pathname).
If MAILPATH is not set, dbx checks $MAIL.  It is not set by default.
#
:ksh$$OLDPWD (variable)
The OLDPWD variable contains the full pathname of the previous working
directory.  It is initially equal to $PWD (see `help ksh PWD').
#
:ksh$$OPTARG (variable)
The OPTARG variable is set by `getopts' when it parses an option with
an argument.  It contains the argument, but not the option letter.  For
example, if the positional arguments are

        -a -bfoo +c -de

and `getopts' is invoked as follows:

        while getopts ab:cdef opt
        do
                case $opt in
                a)      aflag=on ;;
                b)      bflag=$OPTARG ;;
                +c)     cflag=off ;;
                c)      cflag=on ;;
                d)      dflag=on ;;
                e)      eflag=on ;;
                f)      fflag=on ;;
                esac
        done

The resulting variable settings are

        aflag   on
        bflag   foo
        cflag   off
        dflag   on
        eflag   on
        fflag   (no change)
#
:ksh$$OPTIND (variable)
The OPTIND variable is set by `getopts' to the index of the next option
it will process.  It is automatically set to 1 at the beginning of any
function or script.  You can set it by hand to force getopts to process
a particular positional parameter.
#
:ksh$$PATH (variable)
The PATH variable contains a colon-separated list of directories which
will be searched for a command if the command name does not contain a
slash and the `path' options is set.  See `help path'.
#
:ksh$$PPID (variable)
The PPID variable contains the process ID of the process which spawned dbx.
#
:ksh$$PS1 (variable)
The PS1 variable contains the `primary' prompt string.  The value of
\$PS1 is expanded before printing, so that
        PS1='$PWD> '
puts the current working directory in your prompt.  A `!' is replaced
with the current history number.  Use `!!' to get an explicit exclamation
mark.  The default value for $PS1 is `($0) ' (that is, the pathname by
which dbx was invoked enclosed in parentheses).
#
:ksh$$PS2 (variable)
The PS2 variable contains the `secondary' prompt string.  This prompt is
displayed whenever you have pressed RETURN and the command is incomplete.
The default is `> '.
#
:ksh$$PS3 (variable)
The PS3 variable contains the prompt string for the `select' command.
The default is `#? '.
#
:ksh$$PS4 (variable)
The PS4 variable is currently unused by dbx.
#
:ksh$$PS5 (variable)
The PS5 variable contains the prompt string when in `adb' mode.
The default is `ADB> '.
#
:ksh$$PWD (variable)
The PWD variable contains the full pathname of the current working
directory.  The `pwd' command merely echoes the value of $PWD.
#
:ksh$$RANDOM (variable)
The RANDOM variable implements a random number generator.  Each time
the value of RANDOM is accessed, it returns an integer from 0 to
32767.  You can assign a number to RANDOM to seed the random number generator.
#
:ksh$$REPLY (variable)
The REPLY variable is assigned your response to the `select' command.
#
:ksh$$SECONDS (variable)
The SECONDS variable contains the number of seconds since dbx was invoked.
You can assign any value to SECONDS to reset the timer to 0.
#
:ksh$$syntax (subtopic)
The following rules do not constitute a formal grammar.  They merely describe
the common syntactic forms in a simplified manner.

PIPELINE        ::=     CMDLIST [ | CMDLIST ]...

CMDLIST         ::=     COMMAND
                |       CMDLIST [ && PIPELINE ]...
                |       CMDLIST [ || PIPELINE ]...
                |       CMDLIST [ ; PIPELINE ]...
                |       CMDLIST & [ PIPELINE & ]...
                |       ( CMDLIST )
                |       { CMDLIST ; }
                |       FUNCTIONDEF

FUNCTIONDEF     ::=     function IDENT { CMDLIST; }
                |       IDENT () { CMDLIST; }

COMMAND         ::=     if CMDLIST; then CMDLIST;
                        [ elif CMDLIST; then CMDLIST; ]...
                        [ else CMDLIST; ] fi
                |       case WORD in [ PATTERN ) CMDLIST ;; ]... esac
                |       for IDENT [ in WORD... ] ; do CMDLIST; done
                |       select IDENT [ in WORD... ] ; do CMDLIST; done
                |       while CMDLIST; do CMDLIST; done
                |       until CMDLIST; do CMDLIST; done
                |       when WHENARGS { CMDLIST; }
                |       (( EXPRESSION ))
                |       time PIPELINE
                |       IDENT=VALUE... COMMAND
                |       FUNCTIONCALL
                |       BUILTIN
                |       UNIXCMD
#
:ksh$$variables (subtopic)
Ksh variables may contain either strings or integers.  They are of type
`string' by default.  To declare an integer variable x, use `typeset -i x'.
Use the normal ksh syntax to reference variables:

        $x              simple reference
        ${x}            simple reference, explicit bounding of name     
        ${x-val}        substitute `val' if x is unset
        ${x:-val}       substitute `val' if x is unset or is null
        ${x=val}        assign `val' to x if x is unset
        ${x:=val}       assign `val' to x if x is unset or null
        ${x+val}        substitute `val' if x is set
        ${x:+val}       substitute `val' if x is set and non-null
        ${x?val}        generate error msg `val' if x is unset
        ${x:?val}       generate error msg `val' if x is unset or null
        ${x#pat}        value of x, less smallest left-matching pattern
        ${x##pat}       value of x, less largest left-matching pattern
        ${x%pat}        value of x, less smallest right-matching pattern
        ${x%%pat}       value of x, less largest right-matching pattern
        ${#x}           length of the (formatted) value of x

Use `typeset -i<base> x' to declare `x' an integer variable with output base
<base> (2 to 36, inclusive).  Numeric values in other bases may be entered
as `<base>#<digits>'.  For example, the number 42 (decimal) may be entered
as any of the following:

        2#101010        3#1120          4#222           5#132
        6#110           7#60            8#52            9#46
        10#42           11#39           12#36           13#33
        14#30           15#2C           16#2A           17#28
        18#26           19#24           20#22           21#20
        22#1K           23#1J           24#1I           25#1H
        26#1G           27#1F           28#1E           29#1D
        30#1C           31#1B           32#1A           33#19
        34#18           35#17           36#16
Other valid forms for `42' are `052' and `0x2a' (the `C' syntax for octal
and hex constants, respectively).  Case is not significant in any of these
forms.
#
########################################################################
########################## Ksh Commands ################################
########################################################################
:: (ksh syntax)
%: - No-op
The `:' command does nothing and returns 0 (true).
#
:. (ksh syntax)
%. - Read commands from a file
The `. <file>' command causes dbx to read commands from <file>.  Any
variable assignments and function definitions affect the current environment.
\$PATH is searched if the `path' option is set.

See also `help source' and `help ksh options'.
#
:[ (ksh syntax)
%[ - `[ <expr> ]' is shorthand for `test <expr>'
The `[ <expr> ]' command is an alternative syntax for `test <expr>'.
See `help test' for more information.
#
:bg (ksh command)
%bg - Put a job into the background
bg              # Put the current job into the background
bg %+           # Put the current job into the background
bg %-           # Put the previous job into the background
bg %<n>         # Put job number <n> into the background
bg %<str>       # Put the job which begins with <str> into the background
bg %?<str>      # Put the job which contains <str> into the background
                  The `%' is optional in all cases.
#
:bind (ksh command)
%bind - Display or modify the emacs editing key bindings
bind                    # Display the current emacs editing key bindings
bind <key>=<def>        # Bind <key> to definition <def>
bind <key>              # Display the current definition for <key>
bind <key>=             # Remove binding of <key>
bind -m <key>=<def>     # Define <key> to be a macro with definition <def>
bind -m                 # Same as `bind'        

See also `help editing emacs' and `help editing vi'.
#
:break (ksh keyword)
%break - Break out of `while', `until', or `for' loop
break                   # Break out of enclosing loop (`while', `until',
                          or `for').
break <n>               # Break out of <n> enclosing loops.
#
:builtin (ksh command)
%builtin - Use builtin version of command, ignoring functions and aliases
builtin <cmd> [<args>]  # Execute the <cmd>, suppressing the normal search
                          for a function or alias named <cmd>.  If <cmd> is
                          not a builtin, it displays an error message.
#
:cd (ksh command)
%cd - Change the working directory
cd                      # Change directory to $HOME
cd <dir>                # Change directory to <dir>.  If <dir> does not
                          contain a slash, search $CDPATH.  If <dir> contains
                          a slash, use it as-is.  In either case, if <dir>
                          begins with a tilde (`~'), replace `~/' with
                          $HOME, or `~<name>' with the HOME directory of
                          user <name>.
cd <old> <new>          # Change directory to <newdir>, where <newdir> is
                          derived by replacing the string <old> in the
                          current directory name with <new>.
cd -                    # Change directory to $OLDPWD
#
:continue (ksh keyword)
%continue - Go to next iteration of `while', `until', or `for' loop
continue                # Continue executing ksh commands with the next
                          iteration of the nearest enclosing loop (`while',
                          `until', or `for')
continue <n>            # Continue execution with the next iteration of the
                          <n>th enclosing loop.

See `help cont' for process control.
#
:dalias (command)
%dalias - Define a dbx-style (csh-style) alias
dalias                  # (Dbx alias) List all currently defined aliases
dalias <name>           # List the definition, if any, of alias <name>
dalias <name> <def>     # Define <name> to be an alias for <def>.  <def> may
                          contain white space.  A semicolon or newline
                          terminates the definition.
                          Dbx accepts the following csh history substitution
                          meta-syntax which is commonly used in aliases:
                                !:<n>
                                !-<n>
                                !^
                                !$
                                !*
                          The ! usually needs to be backslashed. For example:
                                dalias goto "stop at \!:1; cont; clear"
                          For more details consult the man page csh(1).

See also `help alias' and `help kalias'.
#
:eval (ksh command)
%eval - Evaluate text as a command
eval <cmd> [<args>]     # Evaluate the command <cmd> as if it had been
                          entered from the keyboard.  This is useful
                          when a command must be composed programmatically,
                          then executed.  Example:

                          (dbx) x='echo $$'
                          (dbx) $x
                          $$
                          (dbx) eval $x
                          1234
#
:exec (ksh command)
%exec - Execute a new program (terminate dbx)
exec <cmd> [<args>]     # Causes dbx to exec() the given command.  This
                          results in dbx being terminated and the new
                          command running with the same process ID.
#
:exit (ksh command)
%exit - Exit dbx
exit                    # Causes dbx to exit with return code 0.  Same as
                          `quit'.
exit <n>                # Exit with return code <n>.  Same as `quit <n>'.
#
:export (ksh command)
%export - Mark given environment variables to be exported
export                          # Lists all exported ksh variables
export <name>                   # Marks the variable <name> as exported
export <name>=<value>           # Marks the variable <name> as exported
                                  and assigns it a new value
export <name1> <name2>...       # Marks the given variables as exported
export <n1>=<v1> <n2>=<v2>...   # etc.
                                An exported variable has the attribute
                                `-x' (see `help typeset').
#
:false (ksh command)
%false - Does nothing and returns non-zero
false                   # Does nothing and returns non-zero (255)
#
:fc (ksh command)
%fc - (Fix Command) Manipulate history list
fc                           # (Fix Command) Invokes the editor ($FCEDIT) on
                               the most recent command.  The result is
                               executed when you leave the editor.  See
                               `help ksh FCEDIT' for more info.
fc -e <editor>               # Use <editor> instead of $FCEDIT to edit the
                               previous command
fc -l                        # Lists the last 16 commands in the history
fc -ln                       # Lists the last 16 commands without history
                               numbers
fc -lr                       # Lists the last 16 commands in reverse order
fc -e - <cmd>                # Reexecute previous command which matches <cmd>.
                               <cmd> may be a positive number (the history
                               number), a negative number (subtracted from
                               the current history number), a string (matches
                               the most recent command starting with the given
                               string), or nothing (meaning the previous
                               command).  The builtin alias `r' is set to
                               `fc -e -'.
fc -e - <old>=<new> <cmd>    # Like the above, but substitutes <new> for <old>
                               before executing the command
fc -e -g - <old>=<new> <cmd> # Globally substitute <new> for <old>
#
:fg (ksh command)
%fg - Put a job into the foreground
fg              # Put the current job into the foreground
fg %+           # Put the current job into the foreground
fg %-           # Put the previous job into the foreground
fg %<n>         # Put job number <n> into the foreground
fg %<str>       # Put the job which begins with <str> into the foreground
fg %?<str>      # Put the job which contains <str> into the foreground
                  The `%' is optional in all cases.
#
:getopts (ksh command)
%getopts - Parse positional parameters for options
getopts <opts> <name>           # Checks the positional parameters ($1, $2,
                                  etc.) for legal options, based on the value
                                  of <opts>, and assigns the result to <name>.
                                  <opts> is a string of option letters.  If an
                                  option letter is followed by a colon (`:'),
                                  it requires an argument.  See the example at
                                  `help ksh OPTARG'. 
getopts <opts> <name> <args>... # Use the given args rather than the
                                  positional parameters.
#
:hash (ksh command)
%hash - Manipulate tracked aliases (fast command lookup)
hash            # List the tracked aliases
hash <cmd>      # Make <cmd> a tracked alias
hash -r         # Unset all tracked aliases.  When a UNIX command is executed,
                  if the `hashall' option is set and the command was given as
                  a simple name (no slashes), then the name is entered as a
                  tracked alias for the pathname corresponding to the executed
                  program.
#
:jobs (ksh command)
%jobs - List all active jobs
jobs            # List all active jobs.  The list includes the job number,
                  an indicator of the current (`+') and previous (`-') job,
                  the process ID, a status indicator (`Stopped', `Running',
                  `Done', `Signal <n>'), and the first several characters
                  of the command.  See `help fg' and `help bg' for more
                  information.
#
:kalias (ksh command)
%kalias - Define a ksh-style alias
kalias                  # (ksh alias) List all currently defined aliases
kalias <name>           # List the definition, if any, of alias <name>
kalias <name>=<def>...  # Define <name> to be an alias for <def>.  <def> must
                          be quoted if it contains white space.
                          One difference from standard ksh alias semantics
                          is that `kalias' (and not just `dalias') accepts
                          the csh history substitution meta-syntax which
                          is commonly used in aliases. For example:
                                  dalias goto "stop at !:1; cont; clear"
                          Note that unlike `kalias' the ! need not
                          be backslashed.

See also `help alias' and `help dalias'.
#
:kprint (ksh command)
%kprint - (Korn print) Echo the arguments
kprint <arg>...         # (ksh print) Echo the arguments
kprint -n <arg>...      # Echo the arguments, without a trailing newline
kprint -e <arg>...      # Echo the arguments, expanding backslash escapes
                          (default setting)
kprint -r <arg>...      # Echo the arguments, without expanding backslash
                          escapes (see `help ksh backslash')
kprint -u <n> <arg>...  # Echo the arguments to file descriptor <n>
kprint - <arg>...       # Echo the arguments.  This ensures that <arg> is
                          not treated as an option, even if it starts with
                          a dash (`-').
                          The builtin alias `echo' is equal to `kprint'.
#
:let (ksh command)
%let - Evaluate ksh arithmetic expressions
let <arg>...            # Evaluate one or more arithmetic expressions. The
                          return code is 0 (true) if the last expression
                          evaluated is non-zero, 1 (false) otherwise. 
                          `let <arg>...' is equivalent to `((<arg>...))'.
                          See `help ksh expressions' for more information.
#
:read (ksh command)
%read - Read a line from a file or standard input
read <name>             # Accept a line from stdin, assign it to the ksh
                          variable <name>
read <n1> <n2>...       # Accept a line from stdin, assign the first word
                          to <n1>, the second word to <n2>, etc.  The last
                          name receives all of the remainder of the line
                          if there are more words in the input than names.
read <name>?<prompt>    # Print <prompt> on stderr, then accept a line from
                          stdin and assign it to <name>
read -e ...             # Treat backslash at the end of a line as a line
                          continuation character (default)
read -r ...             # Do not treat backslash specially
read -u <n> ...         # Read from file descriptor <n> rather than stdin       
#
:readonly (ksh command)
%readonly - Mark environment variables unchangeable
readonly                   # List all ksh variables with the `-r' attribute
readonly <name>...         # Set the `-r' attribute for the given variables
readonly <name>=<val>...   # Assign a new value and then set the `-r'
                             attribute for the given variables.  See
                             `help typeset' for more information.
#
:return (ksh keyword)
%return - Return from a ksh function
return                  # Causes a ksh function to return the exit code
                          of the last command executed
return <n>              # Causes a ksh function to return with exit code <n>
#
:set (ksh command)
%set - Set ksh options or positional parameters
set                     # Lists all ksh variables and their values
set <arg>...            # Sets the positional parameters to <arg>...
set -- <arg>...         # Sets the positional parameters, even if <arg>
                          starts with a dash
set -o <opt>            # Sets option <opt>
set +o <opt>            # Clears option <opt>
set -o                  # Lists all currently set options
set +o                  # Lists all currently set options
set -<opt>              # Sets the option with abbreviation <opt>
set +<opt>              # Clears the option with abbreviation <opt>.
                          See `help ksh options' for more information.
#
:sh (ksh command)
%sh - Execute a command explicitly from $PATH
sh <cmd> [<arg>...]     # Execute <cmd>, suppressing the usual search of
                          aliases, functions, and builtins.
#
:shift (ksh command)
%shift - Shift the positional parameters
shift                   # Shift the positional parameters one position to the
                          left, dropping $1
shift <n>               # Shift the positional parameters <n> positions to the
                          left, dropping the first <n> arguments
#
:test (ksh command)
%test - Check various file attributes, string comparison, etc.
test <expr>
     # Returns true (0) if <expr> evaluates to true,
       false (1) otherwise.  The following operators are
       recognized:
                          
            -r <file>       <file> is readable
            -w <file>       <file> is writable
            -x <file>       <file> is executable
                            (searchable, if <file> is
                            a directory)
            -f <file>       <file> is a regular file
            -d <file>       <file> is a directory
            -c <file>       <file> is a character special
                            file
            -b <file>       <file> is a block special file
            -p <file>       <file> is a named pipe (FIFO)
            -u <file>       <file> has its set-uid-bit set
            -g <file>       <file> has its set-gid-bit set
            -k <file>       <file> has its sticky bit set
            -s <file>       <file> is greater than 0 bytes
            -O <file>       <file> is owned by this user
            -G <file>       <file> has same group ID as
                            this user
            -L <file>       <file> is a symbolic link
            -S <file>       <file> is a socket special file
            -t <fd>         <fd> is an open file descriptor
                            which is associated with a tty
            -z <string>     <string> is zero length
            -n <string>     <string> is non-zero length
            -o <opt>        option <opt> is set
            !               negates following expression
            -o              binary `or'
            -a              binary `and'
            (<expr>)        grouping (must be quoted)

     Note: The `-o' operator is taken to mean `option' only 
     if the word following it is one of the options accepted
     by the `set' command.  See `help ksh options' for the
     list.
#
:times (ksh command)
%times - Print accumulated user and system times for dbx and children
times           # Prints the accumulated user and system times for dbx and
                  for all of its child processes
#
:trap (ksh command)
%trap - Associate ksh commands with signals or process exit
trap                      # Displays currently set traps and actions
trap <action> <cond>...   # Causes dbx to execute <action> whenever any
                            <cond> occurs.  The possible values for <action>
                            are:

                              null      ignore the condition
                              -         reset the handling to the default
                              omitted   same as `-'
                              <cmd>     execute the command when the condition
                                        is triggered
$<newline>        
                            Valid values for the <cond> are:

                              0         occurs when dbx exits
                              <n>       a signal number
                              <name>    a signal name; `kill -l' lists the
                                        valid names
                              EXIT      same as 0
#
:true (ksh command)
%true - Does nothing and returns zero
true                    # Does nothing and returns zero
#
:typeset (ksh command)
%typeset - Set attributes of environment variables
typeset                 # Displays the names of all ksh variables and their
                          attributes
typeset -f              # Displays the names of all ksh functions
typeset -x              # Same as `export' (see `help export')
typeset -r              # Same as `readonly' (see `help readonly')
typeset -i              # Displays the names and values of all ksh variables
                          with the `-i' (integer) attribute
typeset -t              # Displays the names and values of all ksh variables
                          with the `-t' (traced) attribute
typeset -q              # Displays the names of all ksh functions with the
                          `-q' (quote) attribute
typeset -[xritq] <name> # Sets the attribute for the named variable or function
typeset +[xritq] <name> # Clears the attribute
typeset -i<n> <var>     # Sets the integer attribute and the output base for
                          variable <var>.  <n> must be from 2 to 36, inclusive.
#
:ulimit (ksh command)
%ulimit - List or change various resource limits
ulimit                  # Displays the current file size limit (same as `-f')
ulimit -[cdmstf]        # Displays the current hard limit for the following:
                        #       -c      core file size in blocks
                        #       -d      size of the data segment (kilobytes)
                        #       -m      maximum mapped memory (kilobytes)
                        #       -s      size of the stack segment (kilobytes)
                        #       -t      time limit (seconds)
                        #       -f      size of file written (blocks)
ulimit -[CDMSTF]        # Displays the current soft limit for each of the above
ulimit -[cdmstf] <n>    # Sets the hard limit (must be super user to raise a
                        # hard limit)
ulimit -[CDMSTF] <n>    # Sets the soft limit (cannot be made greater than the
                        # current hard limit)
#
:umask (ksh command)
%umask - Restrict read/write/execute permissions for new files
umask           # Displays the current umask as a three-digit octal number
umask <n>       # Sets the umask to the given value (interpreted as an octal
                  number).  The umask specifies the bits which will be set
                  to zero in the file permissions of any file created by
                  this process.  Typical values are 022 (not writable by
                  the group or the world), and 027 (not writable by the
                  group, no access for the world).
#
:unalias (dbx/ksh command)
%unalias - Remove alias definition
unalias <name>...       # Remove the alias definition of the given names,
                          if any.
#
:unset (ksh command)
%unset - Remove definition of environment variables
unset <var>...          # Remove the definition of the given ksh variables,
                          if any.
unset -f <func>...      # Remove the definition of the given ksh functions,
                          if any.
#
:vitem (command)
%vitem - Data Visualization interface
   The vitem command is the interface to the Data Visualizer GUI.
   
vitem -new <array-expr>          # create new visualization item
vitem <id> -replace <array-expr> # replace an existing item
vitem <id>|all ... -update ontimer|onstop|ondemand
                                 # set the update mode for the given item
vitem <id>|all ... -update now   # refresh all `ondemand' items
vitem <id>|all ... -enable       # enable refreshes if given item
vitem <id>|all ... -disable      # disable refreshes if given item
vitem <id>|all -list             # list all know items
vitem <id>|all -list -s          # list all know items in a way that they
                                 # can be re-read using the `source' cmd.
vitem <id>|all -delete           # delete the given item
vitem -timer <seconds>           # set the interval timer.
                                 # dbxs single interval timer is also shared by
                                 # the `timer', `event specification', and the
                                 # collector command. Using one of these
                                 # features will exclude the others.
#
:wait (ksh command)
%wait - Wait for background jobs to terminate
wait            # Wait for the current background job to terminate
wait <job>      # Wait for the specified background job to terminate.
                  See `help fg' for the valid syntax for <job>.  The
                  `%' is optional.
#
:whence (ksh command)
%whence - Display meaning of name (alias, function, builtin, command)
whence <name>...        # Displays the meaning of the given names.  If
                          the name is a keyword or ksh function, displays
                          just the name.  If the name is a builtin command,
                          displays `builtin' and the command name.  If the name
                          is an alias, displays the definition of the alias.
                          If the name is a tracked alias or UNIX command,
                          displays the full pathname to the command.
whence -v <name>...     # Verbose display.  For functions, includes the
                          definition.
########################################################################
######################## ksh keywords  #################################
########################################################################
%case - Multiway branching: case <string> in <cases> esac
%do - Command grouping: while <test> do <cmds> done
%done - Command grouping: while <test> do <cmds> done
%elif - Conditional execution: if then elif else fi
%else - Conditional execution: if then elif else fi
%esac - Multiway branching: case <string> in <cases> esac
%fi - Conditional execution: if then elif else fi
%for - Loop over a list: for <var> in <list> do <cmds> done
%function - Define a ksh function:  function <name> { <cmds> }
%if - Conditional execution: if then elif else fi
%in - for ... in ... do ... done  or  case ... in ... esac
%select - Selection loop: select <var> in <list> do <cmds> done
%then - Conditional execution: if then elif else fi
%time - Report user and system times: time <cmd>
%until - Loop until condition is true: until <test> do <cmds> done
%while - Loop while condition is true: while <test> do <cmds> done
%{ - Command grouping:  { <cmd>; <cmd>; }
%} - Command grouping:  { <cmd>; <cmd>; }
########################################################################
######################## Miscellaneous #################################
########################################################################
:dbxdir (dbx variable)
This predefined read-only variable has the full pathname of the directory
which contains the dbx executable.
#
:havegui (dbx variable)
If dbx is running under the GUI, `$havegui' has the value `true'; 
otherwise it is `false'.
#
:mtfeatures (dbx variable)
If thread or LWP commands are enabled (if the target process uses
MT), then `$mtfeatures' has the value `true'; otherwise it is `false'.
Even if thread commands aren't available, LWP commands might be,
in which case `mtfeatures' is still `true'.
#
:version (dbx variable)
This predefined read-only variable contains the current dbx version string.
See also `help invocation' under the -V option.
#
:last_choice (dbx variable)
This variable remembers the last choice made from an overload-resolution menu.
It is useful primarily in scripts:

        function myprint {
                # print it twice, once in octal, then in hex
                # reuse same overload choice, if any
                DBX_output_base=8 builtin print $*
                DBX_output_base=16 builtin print $* <<-EOF
                $last_choice
                EOF
        }
#
# Obsolete commands/syntax go here...
#
:/
The `/' command is obsolete; please see `help changes301'.
#
:?
The `?' command is obsolete; please see `help changes301'.
#
:=
The `=' command is obsolete; please see `help changes301'.
#
#########################################################
##################  RTC help topics #####################
#########################################################
:rtc (topic)

Help about Runtime Checking (RTC) is organized into various subtopics.
and commands.  Here are the various help topics relating to RTC.

Help on subject areas:

    introduction    # brief introduction to RTC
    commands        # brief description of RTC related commands
    dbxenvs         # description of RTC related dbx environment variables
    api             # An interface to support user-defined heap allocators
    8M              # discussion and workarounds for RTC limitations
                    # encountered in some programs
    attach          # tips about using RTC on an attached program
    batch           # note about batch mode for RTC
    mt              # tips about using RTC on multi-threaded application
    errors          # brief description of the error opcodes used by RTC
    showmap         # displays a map of instrument types sorted by address

Help on RTC commands:
 
    check           # Enable checking of memory access, leaks, or usage
    uncheck         # Disable checking of memory access, leaks, or usage
    suppress        # Suppress reporting of memory errors
    showleaks       # Report new memory leaks since last `showleaks' command
    showmemuse      # Show memory used since last `showmemuse' command
    showblock       # Disable checking of memory access, leaks, or usage
    rtc -showmap    # displays a map of instrumentation types by address

:rtc$$introduction (subtopic)
Runtime Checking (RTC) is a dbx feature that consists of two parts: memory
access checking and memory use/leaks checking. Memory access checking is
available only on SPARC.

Access checking checks for improper use of memory by the debugged application. 
RTC monitors memory accesses (loads, stores, and free operations) and
also detects memory leaks (allocations of malloc() [heap] space which
are not freed and which have no pointers referencing them).

Access checking enables you to find loads or stores to out-of-range memory 
(operations that might show up unpredictably as a BUS errors or segmentation
violations); loads and stores using in-range memory that has been 
deallocated (either through a free() call, for heap memory, or through a
function return, for stack memory); loads from in-range memory that 
has not been initialized; and improper free() calls such as duplicate
free()'s or free()'s of non-malloc() space.

Memory use/leak checking involves keeping track of all the outstanding 
heap space and then on demand or at termination of the program, scanning
the available data spaces and identifying the space that has no references.

Fortran users should consider using the -stackvar option to 
take full advantage of RTC.  See the Fortran manuals for how to use -stackvar.

See `help rtc' for further help topics pertaining to RTC.

#
#
:rtc$$commands (subtopic)

dbx commands related to RTC fall into three categories:

1. Turning RTC on/off.  
  
   This is controlled by the use of `check' and `uncheck' commands.
  `check' can be used to turn on memory access checking (SPARC only),
   memory leaks and memory use checking (see `help check' and `help uncheck') 

2. Controlling the scope and the amounts of errors reported by RTC.

   This is controlled by the use of `suppress' and `unsuppress' commands.
   These commands provide a powerful means for you to control your
   RTC session.  See `help suppress' and `help unsuppress' for details.

3. Getting memory leaks and memory use reports.

   Once the memory use (or leaks) checking is turned on by using `check'
   command, you can use `showleaks' command to get the leaks report and 
   `showmemuse' commands to get the memory use report.  You can also get
   details about allocation of a heap block by using `showblock' command.
   To display a map of instrumented instructions, use `rtc -showmap' command.
   See `help showblock', `help showleaks', `help showmemuse' and `help
   rtc showmap' for details. 

See `help rtc' for further help topics pertaining to RTC. 

#
:rtc$$dbxenvs (subtopic)

Certain behavior of RTC can be controlled by the use of dbx environment
variables (see `help dbxenv').  The dbxenvs pertaining to RTC are listed:

dbxenv rtc_auto_continue <on | off>
        Log RTC errors to rtc_error_log_file_name
        and continue.  Default: off

dbxenv rtc_auto_suppress <on | off>
        If on, an RTC error at a given location is
        reported only once.  Default: on

dbxenv rtc_biu_at_exit <on | off | verbose>
        Used when memory use checking is on (either via 
        `check -memuse' or via `check -all'). If the value of the variable 
        is `on', a non-verbose memory use (blocks in use) report will be 
        produced at program exit. If the value is `verbose', a verbose
        memory use report will be produced at program exit.  The value 
        `off' causes no output.  This variable has no effect on the
        interactive `showmemuse' command.  Default: on

See also `help check' and `help showmemuse'.

dbxenv rtc_error_limit <num>
        Number of RTC errors that will be reported.
        Default: 1000

dbxenv rtc_error_log_file_name <filename>
        Name of file where RTC errors will be logged if `rtc_auto_continue' 
        is set.  Default: /tmp/dbx.errlog.<uniqueID>

dbxenv rtc_mel_at_exit <on | off | verbose>
        This variable is used when leaks checking is on.
        If the value of the variable is `on', a non-verbose memory leak 
        report will be produced at program exit.  If the value is `verbose',
        a verbose memory leak report will be produced at program exit.  The 
        value `off' causes no output.  This variable has no effect on the
        interactive`showleaks' command.  Default: on

See `help rtc' for further help topics pertaining to RTC. 

#
:rtc$$api (subtopic)

    The RTC Functions for tracking application specific memory allocators.

Both leak detection and access checking require that the standard heap
management routines in the shared library libc.so be used.  This is so that
RTC can keep track of all the allocation/deallocations in the program.  Many 
applications write their own memory management routines either on top of 
malloc-free or from scratch.  When you use your own allocators (referred to 
as "private allocators" by RTC), RTC cannot automatically track them, thus 
you do not get leaks and memory access errors resulting from their 
improper use.

However, RTC provides an API for the use of "private allocators".  This API
allows the private allocators to get the same treatment as the standard
heap allocators.  The API itself is provided in a header file "rtc_api.h" and
is distributed as a part of the product.  The man page rtc_api(3x) details the
RTC API entry points.

Some minor differences may exist with RTC error reporting when
private allocators do not use the program heap.  When memory access 
error referring a standard heap block occurs, RTC error report typically 
includes the location of the heap block allocation.  This may not be 
reported in such cases.

See `help rtc' for further help topics pertaining to RTC. 

:rtc$$8M (subtopic)

This applies to SPARC only.

The 8M problem described below should no longer occur on UltraSparc-based
hardware where dbx has a new ability to invoke a trap handler instead of
using a branch.  The transfer of control to a trap handler is significantly
slower (up to 10x), but it does not suffer from the 8M limit. Traps are
used automatically (as necessary) as long as the hardware is UltraSparc.
You can check this by using the system command "isalist" and checking that
the result contains "sparcv8plus". The `rtc -showmap' command displays a
map of instrument types sorted by address. 

To do access checking, dbx/RTC replaces each load and store instruction
with a branch instruction that branches to a patch area. This branch 
instruction has an 8Mb range. This means that if the debugged program 
has used up all the address space within 8Mb of the particular load/store 
instruction being replaced, there is no place to put the patch area. 
If RTC can't intercept ALL loads and stores to memory it cannot provide 
accurate information and so disables access checking completely.  Leaks
checking is unaffected by this.

Dbx internally applies some strategies when it runs into this limitation
and continues if it can rectify this problem.  In some cases dbx cannot
proceed; when this happens it will turn off access checking after printing 
an error message.

What to do if you run into this 8Mb limit:

1. Try using 32bit/sparcv8 instead of 64bit/sparcv9

    If you run into the 8M problem with an application that is 
    compiled with -xarch=v9, then you might try doing your memory 
    testing on a 32-bit version of the app.  Because the 64-bit 
    addresses require longer patch instruction sequences, using 
    32 bit addresses can alleviate the 8M problem.  If this is
    not a good workaround, the following methods can be used on 
    both 32-bit and 64-bit programs.

2. Try adding patch area object files.

    The "rtc_patch_area" shell script can be used to create
    special .o files that can be linked into the middle of
    a large executable or shared library to provide more
    patch space.  The man page for the script is rtc_patch_area(1).

    When dbx hits the 8M limit, it tells you which load object was
    too large (the main program, or a shared library) and it prints
    out the total patch space needed for that load object.

    For the best results, the special patch object files should be
    evenly spaced throughout the executable or shared library, and
    the default size (8 Megabytes) or smaller should be used.  Also, 
    do not add more than 10-20% more patch space than dbx says it 
    requires.  Example:  If dbx says that 31 Megabytes for a.out, 
    then add 4 object files created with the rtc_patch_area script, 
    each one 8 Megabytes in size, and roughly evenly space them 
    throughout the executable.

    When dbx finds explicit patch areas in an executable, it will
    print the address ranges spanned by the patch areas, so this
    can help to place them correctly on the link line.
    

3. Try dividing the large load object into smaller load objects.

    Split up the object files in your executable or your large library
    into smaller groups of object files.  Then link them into
    smaller parts.  If the large file is the executable then split it up
    into a smaller executable and a series of shared libraries.  If
    the large file is a shared library then rearrange it into a set 
    of smaller libraries.

    This will allow dbx to find room for patch code in between the 
    different shared objects.

4. Try adding a 'pad' .so file.

    This case should only be necessary if you're attaching
    to a process after it's started up.

    It is possible that the runtime linker will place libraries
    so close together that patch space cannot be created
    in the gaps between the libraries.  When dbx starts up the
    executable with RTC turned on, it will ask the runtime linker
    to place an extra gap between the shared libraries, but when
    attaching to a process that wasn't started up by dbx with
    RTC enabled, it's possible the libraries might be too close together.

    If this is happening to you, (and if it's not possible to start the
    program up using dbx) then you can try creating a shared library 
    using the rtc_patch_area script and linking it into your program 
    between the other shared libraries.  You can see the man page:
    rtc_patch_area(1) for more details.

See `help rtc' for further help topics pertaining to RTC. 

#
:rtc$$attach (subtopic)

RTC supports following a child as well as exec() (see `help follow-fork').
RTC also works on an attached process with the exception that RUI cannot
be detected if the affected memory has already been allocated. Also the
process must have librtc.so preloaded when it starts. If the process you
attaching to is a 64-bit sparcv9 process, use the sparcv9 librtc.so.  If
the product is installed in /opt, that would be:
      for sparcv9 use:     /opt/SUNWspro/lib/v9/librtc.so
      for all others use:  /opt/SUNWspro/lib/librtc.so
To preload librtc.so do:
      setenv LD_PRELOAD <...path-to-librtc...>/librtc.so (csh syntax)
NOTE: It is a good idea to set preload of librtc only when needed (as 
      with attach) and not have it on all the time.  For example,
      setenv LD_PRELOAD ... ; start-your-application; unsetenv LD_PRELOAD

In case the program you want to attach to gets forked/execed from some other
program, you need to set LD_PRELOAD for the main program (which will fork).
LD_PRELOAD setting gets inherited across fork/exec.  This may not work
if a 32-bit program forks/execs a 64-bit program or vice-versa.

See `help rtc' for further help topics pertaining to RTC. 

#
:rtc$$batch (subtopic)

Batch interface to Runtime Checking (RTC) allows the use of
RTC outside the interactive mode of dbx possible.  This simplifies 
the use of RTC in shell scripts.  A separate utility called `bcheck' is 
provided for this purpose.  `bcheck' is simply a shell script which runs 
the program under dbx with Runtime Checking enabled.  See the man page for 
bcheck(1) for the details.

See `help rtc' for further help topics pertaining to RTC. 

#
:rtc$$mt (subtopic)
Runtime Checking (RTC) supports multi-threaded applications.

Along with each access checking error report (SPARC only), RTC prints 
the ID of the thread on which the error occurred.  The leak report generated 
by RTC includes the leaks from all the threads in the program.   

See `help rtc' for further help topics pertaining to RTC. 

#
:rtc$$errors (subtopic)

Errors reported by RTC generally fall in two categories.  Access errors and
leaks.  

When access checking is turned on, RTC detects and reports the following
kinds of errors:
        baf     # Bad free
        duf     # Duplicate free
        maf     # Misaligned free
        mar     # Misaligned read
        maw     # Misaligned write
        oom     # Out of memory
        rua     # Read from unallocated memory
        rui     # Read from uninitialized memory
        wro     # Write to read-only memory
        wua     # Write to unallocated memory

With leak checking, RTC will report the following kinds of errors:
        aib     # Possible memory leak - only pointer points in the middle of
                # the block
        air     # Possible memory leak - pointer to the block exists only
                # in register
        mel     # Memory leak - no pointers to the block

Memory use report uses the opcode biu (Block in use).

See `help rtc' for further help topics pertaining to RTC. 
:rtc$$showmap (subtopic)
%showmap - Show address range of branches and traps (RTC)

    This command is intended for expert users, and internal debugging
    of dbx. RTC instruments program text for access checking. The
    instrumentation type can be a branch or a trap instruction based
    on available resources.  `rtc -showmap' reports the address range of
    program text categorized by instrumentation type. This map can be used
    to find an optimical location for adding patch area object files, and
    to avoid the automatic use of traps. See `help rtc 8M' for details.

#
:FAQ (topic)
                Frequently Asked Questions About dbx
                ====================================

A. General questions:
 A.1  Gdb does <something>; how do I do it in dbx?
 A.2  Dbx doesn't read my .dbxinit file anymore!  Why not?
 A.3  How do I enable command-line editing?
 A.4  Why doesn't "alias" work?
 A.5  Why does dbx keep saying "foo is not defined in the current scope"?
         What is a scope, anyway?
 A.6  Why doesn't "set" work?
 A.7  Dbx can't find my source files!
 A.8  My program behaves differently when under dbx.
 A.9  I put in a breakpoint and it's not reached.
 A.10 Why is type of a C++ member sometimes missing in the output of `whatis'?
 A.11 Why does Runtime Checking have this 8Mb limit?
 A.12 How do I use dbx to locate floating-point exceptions?
 A.13 Where does dbx create any needed temporary files?
 A.14 How do I run a command with a very long list or arguments?

B. MT-related questions:
 B.1  Where do I get the MT dbx?
 B.2  What are the major MT features of dbx?
 B.3  Can you limit your scope to a specific thread?
 B.4  What are the major MT features of the GUI?
 B.5  How does thread numbering work?
 B.6  How does LWP numbering work?
 B.7  Can you have a breakpoint on a specific thread?
 B.8  What happens when a thread hits a breakpoint? Do all threads stop, 
         or only the thread that hit the breakpoint stops?
 B.9  How does dbx know that an application is multi-threaded?
 B.10 What pitfalls should I watch for?
 B.11 Can I "force" a sleeping thread to run?
 B.12 How can I tell which other thread a particular thread is waiting for?
         (i. e., via thr_join).
         Starting from the threads list in the Process/Thread Inspector, how can
         I determine which thread id came from which thr_create() call?
 B.13 Starting from the threads list in the Process/Thread Inspector,
         how can I determine which thread id came from which start function?
 B.14 When I attach to an existing multithreaded process, which thread becomes
         the active thread?
 B.15 When the active thread does a thr_create, which thread becomes the
         active thread? (i. e., the one that did the  thr_create() or the 
         one that was thr_create'd?) (Another way to phrase this might be,
         is there a "follow_thread_mode" analogous to "follow_fork_mode"?)
 B.16 When the active thread does a thr_exit, which thread (if any) becomes
         the active thread?

--------------------------------------------------------------------------------

(A.1) Gdb does <something>; how do I do it in dbx?

The following table list approximately equivalent dbx commands for some
common gdb commands:

GDB                     DBX                       for more information
===                     ===                       ====================

break <line>            stop at <line>            `help stop'
break <func>            stop in <func>            `help stop'
break *<addr>           stopi at <addr>           `help stopi'
break ... if <expr>     stop ... -if <expr>       `help event specification'
cond <n>                stop ... -if <expr>       `help event specification'
tbreak                  stop ... -temp            `help event specification'
watch <expr>            stop <expr>  [slow]       `help event specification'
watch <var>             stop modify &<var> [fast] `help event watchpoint'
catch <x>               intercept <x>             `help intercept'
info break              status                    `help status'
info watch              status                    `help status'
clear                   clear                     `help clear'
clear <fun>             delete <n>                `help delete'
delete                  delete all                `help delete'
disable                 handler -disable all      `help handler'
disable <n>             handler -disable <n>      `help handler'
enable                  handler -enable all       `help handler'
enable <n>              handler -enable <n>       `help handler'
ignore <n> <cnt>        handler -count <n> <cnt>  `help handler'
commands <n>            when ... { <cmds>; }      `help when'

backtrace <n>           where <n>                 `help where'
frame <n>               frame <n>                 `help frame'
info reg <reg>          print $<reg>              `help registers'

finish                  step up                   `help step'
signal <num>            cont sig <num>            `help cont'
jump <line>             cont at <line>            `help cont'
set <var>=<expr>        assign <var>=<expr>       `help assign'

x/<fmt> <addr>          x <addr>/<fmt>            `help examine'
disassem <addr>         dis <addr>                `help dis'

shell <cmd>             sh <cmd> [if needed]      `help sh'

info func <regex>       funcs <regexp>            `help funcs'
ptype <type>            whatis -t <type>          `help whatis'

define <cmd>            function <cmd>            `help ksh syntax'

handle <sig>            stop sig <sig>            `help event specification'
info signals            status; catch             `help status', `help catch'

attach <pid>            debug - <pid>             `help debug'
attach <pid>            debug <a.out> <pid>       `help debug'
file <file>             [unnecessary]
exec <file>             debug <file>              `help debug'
core <file>             debug <a.out> <file>      `help debug'

set editing on          set -o emacs              `help editing'
set language <x>        language <x>              `help language'
set prompt <x>          PS1=<x>                   `help ksh PS1'
set history size <x>    HISTSIZE=<x>              `help ksh HISTSIZE'

set print object on     dbxenv output_dynamic_type on `help c++ dynamic'

show commands           history                   `help history'
dir <name>              pathmap <name>            `help pathmap'
show dir                pathmap                   `help pathmap'
info line <n>           listi <n>                 `help listi'
info source             file                      `help file'
info sources            files; modules            `help files', `help modules'
forw <regex>            search <regex>            `help search'
rev <regex>             bsearch <regex>           `help bsearch'

--------------------------------------------------------------------------------

(A.2) Dbx doesn't read my .dbxinit file anymore!  Why not?

Dbx no longer supports compatibility mode for old .dbxinit files.
See `help .dbxinit' for more details.

--------------------------------------------------------------------------------

(A.3) How do I enable command-line editing?

You can enable command-line editing in several ways.  First, if $FCEDIT,
\$EDITOR, or $VISUAL is set, its value is checked.  If the last component
(i.e., after the last slash) contains the string "emacs", then emacs-mode
is enabled.  If it contains "vi", then vi-mode is enabled.  If none of the
three environment variables are set, or if the first one in the list that
is set does not contain "emacs" or "vi", then emacs-mode is enabled.

You can enable emacs mode from the command line (or in your .dbxrc file)
by typing

        set -o emacs

Vi mode is similar:

        set -o vi

To disable command-line editing,

        set +o emacs +o vi

is sufficient.

--------------------------------------------------------------------------------

(A.4) Why doesn't "alias" work?

"alias" is now a pre-defined alias for either "dalias" or "kalias".  See
`help alias', `help dalias', `help kalias', and `help startup'.

--------------------------------------------------------------------------------

(A.5) Why does dbx keep saying "foo is not defined in the current scope"?
    What is a scope, anyway?

That message means that no symbol named `foo' is accessible from the
current point of execution.  See `help scope' for details.

--------------------------------------------------------------------------------

(A.6) Why doesn't "set" work?

"set" is now the KornShell "set" command; it is no longer an alias for
"assign".  See `help assign' and `help set'.

--------------------------------------------------------------------------------

(A.7) Dbx can't find my source files!

If your source files are not where they were when they were compiled,
or if you compiled on a different machine than you are debugging on
and the compile directory is not mounted as the same pathname, dbx
will have trouble finding them.  See `help pathmap' for a solution.

--------------------------------------------------------------------------------

(A.8) My program behaves differently when under dbx.

Dbx can typically affect the behavior of a program
in the following ways:

        The first available file descriptor at exec time might not
        be 3. This is a bug and we're trying to plug all the holes.
        So if you depend on pre-existing fd's or use them for indexing
        tables, etc., things might change.
        
        You might have forgotten to take out a -C or have left RTC on.

        Your dbx initialization scripts might have some environment
        variables set that you've forgotten about.  The stack base
        starts at a different address when running under dbx. 
        This also will be different based on your environment
        and contents of argv[].  This will force local variables to be
        allocated a bit differently and if they're not initialized, they
        will be getting different random numbers. This problem can be
        detected via Runtime Checking.  See `help check'.

        The program does not initialize malloc()ed memory before use.
        This situation is similar to the previous one.  The same
        suggestions apply.

        The program references an uninitialized memory location via a
        bad pointer.  This is similar to the previous two situations.
        The same suggestions apply.

        Dbx has to catch LWP creation and dlopen events. This
        might seriously affect the timings of things. Dbx also does
        context switching on signals, so if you have heavy use of
        signals which are timing sensitive, things might work differently.

        The program expects that mmap() will always return the same base
        address for mapped segments.  Running under dbx perturbs the
        address space sufficiently to make it unlikely that mmap() will
        return the same address as when the program is run without dbx.
        To determine if this is a problem in your program, look at all
        uses of mmap() and ensure that the address returned is actually
        used by the program, rather than a hard-coded address.

        If the program is multi-threaded, it may contain data races or
        be otherwise dependent upon thread scheduling.  Running under
        dbx perturbs thread scheduling somewhat and may cause the
        program to execute threads in a different order than it normally
        would.  To detect such conditions, try `lock_lint'.

        See if running outside `GUI' (i.e. use `dbx'), or with
        `adb' or `truss' causes the same problems.

Dbx should impose minimal perturbation when it attaches 
to a running process; give that a try.  See `help debug'.

--------------------------------------------------------------------------------

(A.9) I put in a breakpoint and it's not reached.

Consider the following possibilities:
        
        If you've placed a bpt on a function, it might not be the function
        you think. Use `whereis <funcname>' to find out how many functions
        of a given name exist. Then use the exact syntax as presented
        by the output of `whereis' in your `stop' command.

        See the answer to (10).

        If the breakpoint is on a while loop you might run into trouble
        stemming from the fact that the compiler converts code of the
        form:

                while (<cond> )
                        <stmt>

        to

                if (<cond>) {
                again:
                    <stmt>
                    if <cond>
                        goto again;
                }

        in which case putting a bpt on the `while' amounts to putting a bpt 
        only on the outer `if'. This is because dbx cannot deal with 
        source lines that map to two (or more) different addresses.

--------------------------------------------------------------------------------

(A.10) Why is type of a C++ member sometimes missing in the output of `whatis'?

In the following whatis command, the type of member `stackcount' is
missing:

        (dbx) whatis stack
        class stack {
        ...
            static stackcount; /* Never defined or allocated */
        ...
        };

When a class member is not defined or allocated, dbx cannot determine
its type.  There is no type to print.

--------------------------------------------------------------------------------

(A.11) Why does Runtime Checking have this 8Mb limit?

Only access checking has this limit.  Leaks checking is not affected
by this.
 
To do access checking dbx/RTC replaces each load and store instruction
with a branch instruction that branches to a patch area. This branch
instruction has an 8Mb range. This means that if the debugged program
has used up all the address space within 8Mb of the particular load/store
instruction being replaced, there is no place to put the patch area.
If RTC can't intercept ALL loads and stores to memory it cannot provide
accurate information and so disables access checking completely.
 
Dbx internally applies some strategies when it runs into this limitation
and continues if it can rectify this problem.  In some cases dbx cannot
proceed; when this happens it will turn off access checking after printing
an error message (see `help rtc 8M' for possible workarounds).

--------------------------------------------------------------------------------
(A.12) How do I use dbx to locate floating-point and integer exceptions?

You need to do two things:

In dbx say "catch FPE". This will stop the process whenever an FP
exception happens. Note that some integer exception, like integer
divide by 0 and integer overflow also show up under SIGFPE.

But this isn't enough. The f77 ieee software typically sets all errors to
be silent (not raising signals). You'll have to add the following to
your FORTRAN 77 application:

        integer ieeer, ieee_handler, myhandler
        ieeer = ieee_handler('set', 'all', myhandler)
        ...
        
        integer function myhandler(sig, code, context)
        integer sig, code(5)
        call abort()
        end

This will cause _all_ ieee exceptions to generate a SIGFPE as appropriate,
which might be a bit too much.

For Fortran95 all errors are non-silent and will raise signals so you
need not take any additional action.

For a C or C++ program you can do this:
        #include <ieeefp.h>

        main() 
        {
            fpsetmask(FP_X_INV|FP_X_OFL|FP_X_UFL|FP_X_DZ|FP_X_IMP);
            ...

See the respective man pages for more information on these functions.
        
You can further tailor which exceptions you see by tweaking the parameters
of ieee_handler()/fpsetmask() or by using an alternative to the dbx
catch command:
        stop sig FPE
which acts just like "catch FPE", or
        stop sig FPE <subcode>
for finer control.  <subcode> can be one of 
        FPE_INTDIV      1       # integer divide by zero
        FPE_INTOVF      2       # integer overflow
        FPE_FLTDIV      3       # floating-point divide by zero
        FPE_FLTOVF      4       # floating-point overflow
        FPE_FLTUND      5       # floating-point underflow
        FPE_FLTRES      6       # floating-point inexact result
        FPE_FLTINV      7       # invalid floating-point operation
        FPE_FLTSUB      8       # subscript out of range
        
which you can also see by saying `help signals'.     

Note that "stop" and "catch" are independent and that if you use
"stop FPE" you should also "ignore FPE".

See also the "Debugging" appendix of your Fortran documentation.

--------------------------------------------------------------------------------

(A.13) Where does dbx create any needed temporary files?

    Dbx will use the directory /tmp (or the value of the environment
    variable TMPDIR if it is set) for all it's temporary files.
    All the dbx temporary files with start with "dbx." and be unique
    to that dbx session. All dbx temporary files are removed when
    dbx terminates.

--------------------------------------------------------------------------------

(A.14) How do I run a command with a very long list or arguments?

    The right way to do this is to put the "run" command into a
    separate file and do

        $ dbx a.out
        (dbx) stop at 100
        (dbx) source foo
    Yes, there is a hard limit on the length of the input lines. It is 10k.

--------------------------------------------------------------------------------

(B.1) Where do I get the MT dbx?

    You don't need to get a specific MT dbx. MT features are an inherent
    part of the standard dbx.  With the 4.0 dbx release you do not need
    to have a separate license to use the MT functionality.

--------------------------------------------------------------------------------

(B.2) What are the major MT features of dbx?

    The `threads' command will give a list of all known threads, with
    their current state, base functions, current functions etc.
    You can examine stack traces of each thread.
    You can resume (`cont') a specific or all threads.
    You can `step' or `next' a specific thread.
    The `thread' command helps navigating between threads.

--------------------------------------------------------------------------------

(B.3) Can you limit your scope to a specific thread?

   `dbx' maintains a cursor to the "current" or "active" thread.
    It is manipulable by the `thread' command. About the only
    commands which uses the current thread as the default thread are
    `where' and `thread -info'.

--------------------------------------------------------------------------------

(B.4) What are the major MT features of the GUI?

    A GUI interface to the `threads' command which shows an up-to-date
    list of threads in the "Process/Thread Inspector".
    The Process/Thread Inspector is linked to the "Stack Inspector"
    So you can quickly and efficiently look at all threads' stacks.

--------------------------------------------------------------------------------

(B.5) How does thread numbering work?

    dbx knows the id of each thread (the type thread_t) as
    returned by `thr_create()'. The syntax is `t@<number>'.

--------------------------------------------------------------------------------

(B.6) How does LWP numbering work?

    dbx knows the  id of each LWP (the type lwpid_t) as presented by
    the /proc (man procfs(4)) interface. The syntax is `l@<number>'.

--------------------------------------------------------------------------------

(B.7) Can you have a breakpoint on a specific thread?

    Yes, by filtering a regular breakpoint as follows:
        stop in foo -thread t@4
    Where the `t@4' refers to the thread with id 4.

--------------------------------------------------------------------------------

(B.8) What happens when a thread hits a breakpoint?
    Do all threads stop, or only the thread that hit the breakpoint stops? 

    All threads stop. This is knows as "sympathetic stop", or "stop
    the world". from the point of view of /proc and LWPs this is
    "synchronous" debugging.

--------------------------------------------------------------------------------

(B.9) How does dbx know that an application is multi-threaded?

    If an application is linked with -lthread, dbx assumes it is 
    multi-threaded. 

--------------------------------------------------------------------------------

(B.10) What pitfalls should I watch for with MT?

    It is very easy to get your program to deadlock by resuming only
    a specific thread while other threads are still blocked and hold a
    resource that the resumed thread might need.

    libthread data structures are in user space and might get corrupted
    by bugs involving rogue pointers. In such cases one suggestion is to
    work at the LWP level with commands like `lwps' and `lwp' which 
    are analogous to their thread equivalents.

--------------------------------------------------------------------------------

(B.11) Can I "force" a sleeping thread to run?

    You cannot. In future version you might be able to, but in general
    when debugging MT applications it is recommended that you take a
    "stand back and watch" approach rather than trying to force your
    will on the program's natural execution flow.

--------------------------------------------------------------------------------

(B.12) How can I tell which other thread a particular thread is waiting for?
    (i. e., via thr_join).
    Starting from the threads list in the Process/Thread Inspector, how can
    I determine which thread id came from which thr_create() call?

    You currently cannot. We're waiting for a more sophisticated interface
    to help dbx query the state of threads.

--------------------------------------------------------------------------------

(B.13) Starting from the threads list in the Process/Thread Inspector,
    how can I determine which thread id came from which start function?

    The "base function" as it is known, is printed in the thread listing.

--------------------------------------------------------------------------------

(B.14) When I attach to an existing multithreaded process, which thread becomes
    the active thread?

    It's non-deterministic.

--------------------------------------------------------------------------------

(B.15) When the active thread does a thr_create, which thread becomes the
    active thread? (i. e., the one that did the  thr_create() or the 
    one that was thr_create'd?) (Another way to phrase this might be,
    is there a "follow_thread_mode" analogous to "follow_fork_mode"?)

    The current threads stays with the "creating thread". In the 
    follow_fork analogy, it would be `parent'.
    Note that the Sun MT model doesn't have true `fork' semantics 
    for threads. There is no thread tree, and no parent-child relationships
    like with processes. thr_join() is only a simplified veneer.

--------------------------------------------------------------------------------

(B.16) When the active thread does a thr_exit, which thread (if any) becomes
    the active thread?

    Dbx makes a dummy "dead" thread the active thread. This thread
    is represented as `t@X'.

#
# We don't want to insert tabs so we don't have to worry about 
# people's stty settings 
# Local Variables:
# indent-tabs-mode: nil 
# End:
#
