Provided by: bashdb_4.3.0.91+ds-4_amd64 bug

NAME

       bashdb - bash debugger script

SYNOPSIS

       bashdb [options] [--] script-name [script options]

       bashdb [options] -c execution-string

       bash --debugger [bash-options...] script-name [script options]

DESCRIPTION

       "bashdb" is a bash script to which arranges for another bash script to be debugged.  The
       debugger has a similar command interface as gdb(1).

       The way this script arranges debugging to occur is by including (or actually "source"-ing)
       some debug-support code and then sourcing the given script or command string.

       One problem with sourcing a debugged script is that the program name stored in $0 will be
       "bashdb" rather than the name of the script to be debugged. The debugged script will
       appear in a call stack not as the top item but as the item below "bashdb". If this is of
       concern, use the last form given above, "bash --debugger" script-name [script-options].

       If you used bashdb script and need to pass options to the script to be debugged, add "--"
       before the script name. That will tell bashdb not to try to process any further options.

       See the reference manual <http://bashdb.sourceforge.net/bashdb.html> for how to to call
       the debugger from inside your program or arrange for the debugger to get called when your
       program is sent a signal.

OPTIONS

       -h | --help
           Print a usage message on standard error and exit with a return code of 100.

       -A | --annotation level
           Sets to output additional stack and status information which allows front-ends such as
           emacs to track what's going on without polling.

           This is needed in for regression testing. Using this option is equivalent to issuing:

             set annotation LEVEL

           inside the debugger.

       -B | --basename
           In places where a filename appears in debugger output give just the basename only.
           This is needed in for regression testing. Using this option is equivalent to issuing:

             set basename on

           inside the debugger.

       -n | nx
           Normally the debugger will read debugger commands in "~/.bashdbinit" if that file
           exists before accepting user interaction.  ".bashdbinit" is analogus to Perl's
           ".perldb" or GNU gdb's ".gdbinit": a user might want to create such a debugger profile
           to add various user-specific customizations.

           Using the "-n" option this initialization file will not be read. This is useful in
           regression testing or in tracking down a problem with one's ".bashdbinit" profile.

       -c command-string
           Instead of specifying the name of a script file, one can give an execution string that
           is to be debugged. Use this option to do that.

           If you invoke the debugger via "bash --debugger", the filename that will appear in
           source listing or in a call stack trace will be the artificial name *BOGUS*.

       -q | --quiet
           Do not print introductory version and copyright information. This is again useful in
           regression testing where we don't want to include a changeable copyright date in the
           regression-test matching.

       -x debugger-cmdfile
           Run the debugger commands debugger-cmdfile before accepting user input.  These
           commands are read however after any ".bashdbinit" commands. Again this is useful
           running regression-testing debug scripts.

       -L | --library debugger-library
           The debugger needs to source or include a number of functions and these reside in a
           library. If this option is not given the default location of library is relative to
           the installed bashdb script: "../lib/bashdb".

       -T | --tempdir temporary-file-directory
           The debugger needs to make use of some temporary filesystem storage to save persistent
           information across a subshell return or in order to evaluate an expression. The
           default directory is "/tmp" but you can use this option to set the directory where
           debugger temporary files will be created.

       -t | --tty tty-name
           Debugger output usually goes to a terminal rather than STDOUT which the debugged
           program may use. Determination of the tty or pseudo-tty is normally done
           automatically. However if you want to control where the debugger output goes, use this
           option.

           If you want output to go to STDOUT use &1. Note: the '&' may have to be escaped or
           quoted to avoid shell interpretation with forking.

       -V | --version
           Show version number and no-warranty and exit with return code 1.

       -X | --trace
           Similar to ""set -x"" line tracing except that by default the location of each line,
           the bash level, and subshell level are printed. You might be able to get something
           roughly similar if you set "PS4" as follows

               export PS4='(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]}\n'

           In contrast however to ""set -x"" tracing, indentation of the original program is also
           preserved in the source output. And if you interrupt the program with a break (a
           "SIGINT" signal), you will go into the debugger (assuming your program doesn't trap
           "SIGINT").

BUGS

       The "bashdb" script and "--debugger" option assume a version of bash with debugging
       support. That is you can't debug bash scripts using the standard-issue version 2.05b bash
       or earlier versions. In versions after 3.0, debugging should have been enabled when bash
       was built. (I think this is usually the case though.) If you try to run the bashdb script
       on such as shell, may get the message:

         Sorry, you need to use a debugger-enabled version of bash.

       Debugging startup time can be slow especially on large bash scripts. Scripts created by
       GNU autoconf are at thousands of lines line and it is not uncommon for them to be tens of
       thousands of lines.

       There is a provision to address this problem by including a fast file-to-array read
       routine (readarray), but the bashdb package has to be compiled in a special way which
       needs access to the bash source code and objects.

       Another reason of the debugger slowness is that the debugger has to intercept every line
       and check to see if some action is to be taken for this and this is all in bash code. A
       better and faster architecture would be for the debugger to register a list of conditions
       or stopping places inside the bash code itself and have it arrange to call the debugger
       only when a condition requiring the debugger arises. Checks would be faster as this would
       be done in C code and access to internal structures would make this more efficient.

SEE ALSO

       •   <http://bashdb.sourceforge.net/bashdb.html> - an extensive reference manual.

       •   <http://bashdb.sourceforge.net> - the homepage for the project

       •   <http://www.gnu.org/software/bash/manual/bashref.html> - bash reference manual

AUTHOR

       The current version is maintained (or not) by Rocky Bernstein.

COPYRIGHT

         Copyright (C) 2003, 2006, 2007 Rocky Bernstein
         This program is free software; you can redistribute it and/or modify
         it under the terms of the GNU General Public License as published by
         the Free Software Foundation; either version 2 of the License, or
         (at your option) any later version.

         This program is distributed in the hope that it will be useful,
         but WITHOUT ANY WARRANTY; without even the implied warranty of
         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
         GNU General Public License for more details.

         You should have received a copy of the GNU General Public License
         along with this program; if not, write to the Free Software
         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

       $Id: bashdb-man.pod,v 1.10 2009/06/22 22:41:10 rockyb Exp $