bashdb.1

bash debugger. You can use this tool to debug bash shell script

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BASHDB-MAN 1"
.TH BASHDB-MAN 1 "2007-03-02" "3.1-0.09cvs" "GNU Tools"
.SH "NAME"
bashdb \- bash debugger script
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBbashdb\fR [\fIoptions\fR] [\-\-] \fIscript-name\fR [\fIscript options\fR]
.PP
\&\fBbashdb\fR [\fIoptions\fR] \-c \fIexecution-string\fR
.PP
\&\fBbash \-\-debugger\fR [\fIbash-options\fR...] \fIscript-name\fR [\fIscript options\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`bashdb\*(C'\fR is a bash script to which arranges for another bash script
to be debugged. 
The debugger has a similar command interface as \f(CWgdb(1)\fR.

.PP
The way this script arranges debugging to occur is by including (or
actually \*(L"source\*(R"\-ing) some debug-support code and then sourcing the
given script or command string.
.PP
One problem with sourcing a debugged script is that the program name
stored in \f(CW$0\fR will be \f(CW\*(C`bashdb\*(C'\fR 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 \f(CW\*(C`bashdb\*(C'\fR. If this is of concern,
use the last form given above, \f(CW\*(C`bash \-\-debugger\*(C'\fR \fIscript-name\fR
[\fIscript-options\fR].
.PP
If you used bashdb script and need to pass options to the script to be
debugged, add \f(CW\*(C`\-\-\*(C'\fR before the script name. That will tell bashdb not
to try to process any further options.
.PP
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.
.SH "OPTIONS"
.IX Header "OPTIONS"
The long options listed befow are available if the \f(CW\*(C`getopt\*(C'\fR command
is installed on your system. The short options can always be used.
.IP "\-h | \-\-help" 4
.IX Item "-h | --help"
Print a usage message on standard error and exit with a return code
of 100.
.Sp
\&\&
.IP "\-B | \-\-basename" 4
.IX Item "-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:
.Sp
.Vb 1
\&  set basename on
.Ve
.Sp
inside the debugger.
.Sp
\&\&
.IP "\-n | nx" 4
.IX Item "-n | nx"
Normally the debugger will read debugger commands in \f(CW\*(C`~/.bashdbinit\*(C'\fR
if that file exists before accepting user interaction.
\&\f(CW\*(C`.bashdbinit\*(C'\fR is analogus to Perl's \f(CW\*(C`.perldb\*(C'\fR or \s-1GNU\s0 gdb's
\&\f(CW\*(C`.gdbinit\*(C'\fR: a user might want to create such a debugger profile to
add various user-specific customizations.
.Sp
Using the \f(CW\*(C`\-n\*(C'\fR option this initialization file will not be read. This
is useful in regression testing or in tracking down a problem with
one's \f(CW\*(C`.bashdbinit\*(C'\fR profile. 
.Sp
\&\&
.IP "\-c \fIcommand-string\fR" 4
.IX Item "-c command-string"
Instead of specifying the name of a bash script file, one can give an
execution string that is to be debugged. Use this option to do that.
.Sp
If you invoke the debugger via \f(CW\*(C`bash \-\-debugger\*(C'\fR, the filename that will
appear in source listing or in a call stack trace will be the artifical name
*BOGUS*.
.Sp
\&\&
.IP "\-q | \-\-quiet" 4
.IX Item "-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.
.Sp
\&\&
.IP "\-x \fIdebugger-cmdfile\fR" 4
.IX Item "-x debugger-cmdfile"
Run the debugger commands \fIdebugger-cmdfile\fR before accepting user
input.  These commands are read however after any \f(CW\*(C`.bashdbinit\*(C'\fR
commands. Again this is useful running regression-testing debug
scripts.
.Sp
\&\&
.IP "\-L | \-\-library \fIdebugger-library\fR" 4
.IX Item "-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: \f(CW\*(C`../lib/bashdb\*(C'\fR.
.Sp
\&\&
.IP "\-T | \-\-tempdir \fItemporary-file-directory\fR" 4
.IX Item "-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 \f(CW\*(C`/tmp\*(C'\fR but you can
use this option to set the directory where debugger temporary files
will be created.
.Sp
\&\&
.IP "\-t | \-\-tty \fItty-name\fR" 4
.IX Item "-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.
.Sp
\&\&
.IP "\-V | \-\-version" 4
.IX Item "-V | --version"
Show version number and no-warranty and exit with return code 1.
.IP "\-X | \-\-trace" 4
.IX Item "-X | --trace"
Similar to "\f(CW\*(C`set \-x\*(C'\fR" 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 \f(CW\*(C`PS4\*(C'\fR as follows
.Sp
.Vb 1
\&    export PS4='(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]}\en'
.Ve
.Sp
In contrast however to "\f(CW\*(C`set \-x\*(C'\fR" tracing, indentation of the original
program is also preserved in the source output. And if you interrupt
the program with a break (a \f(CW\*(C`SIGINT\*(C'\fR signal), you will go into the
debugger (assuming your program doesn't trap \f(CW\*(C`SIGINT\*(C'\fR).
.Sp
\&\&
.SH "BUGS"
.IX Header "BUGS"
The \f(CW\*(C`bashdb\*(C'\fR script and \f(CW\*(C`\-\-debugger\*(C'\fR 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:
.PP
.Vb 1
\&  Sorry, you need to use a debugger-enabled version of bash.
.Ve
.PP
Debugging startup time can be slow especially on large bash
scripts. Scripts created by \s-1GNU\s0 autoconf are at thousands of lines
line and it is not uncommon for them to be tens of thousands of lines.
.PP
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.
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
<http://bashdb.sourceforge.net/bashdb.html> \- an extensive reference manual. 
.IP "\(bu" 4
<http://bashdb.sourceforge.net> \- the homepage for the project
.IP "\(bu" 4
<http://www.gnu.org/software/bash/manual/bashref.html> \- bash
reference manual
.SH "AUTHOR"
.IX Header "AUTHOR"
The current version is maintained (or not) by Rocky Bernstein.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 5
\&  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.
.Ve
.PP
.Vb 4
\&  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.
.Ve
.PP
.Vb 3
\&  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
.Ve
.PP
\&\fI$Id: bashdb\-man.pod,v 1.9 2007/03/02 05:42:46 rockyb Exp $\fR