Man Linux: Main Page and Category List


       bashdb - bash debugger script


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

       bashdb [options] -c execution-string

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


       "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 <>
       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.


       -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

           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
           artifical 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

       -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

       -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:

       -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 or
           stdin 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.

       -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").


       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.


       ·   <> - an extensive
           reference manual.

       ·   <> - the homepage for the project

       ·   <> - bash
           reference manual


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


         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
         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 $