bashdb.texi

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

\input texinfo      @c -*-texinfo-*-
@c Copyright 2002, 2003, 2004, 2006, 2007
@c Rocky Bernstein for the Free Software Foundation
@c
@c TODO: 
@c   - add examples for commands
@c   - clean up/improve sample session
@c   - help text is inaccurate and formatted too much to right.
@c 

@c Sets version and release names and dates. Frees us from changing
@c this file when a new release comes along.

@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars.  However, you can override filename with makeinfo -o.
@setfilename bashdb.info
@c 
@c Name of Bash program.  Used in running text.

@c
@c Name of debugger program.  Used also for prompt string.
@set BASH @acronym{BASH}
@set DBG the @value{BASH} debugger
@set dBGP The @value{BASH} debugger
@set DDD @acronym{DDD}
@set Emacs @sc{gnu} Emacs

@settitle @value{BASH} Debugger
@setchapternewpage odd
@c %**end of header

@include version.texi
@include macros.texi

@iftex
@c @smallbook
@c @cropmarks
@end iftex

@finalout

@c readline appendices use @vindex, @findex and @ftable,
@c annotate.texi and gdbmi use @findex.
@c @syncodeindex vr cp
@c @syncodeindex fn cp

@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.

@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.
@dircategory Programming & development tools.
@direntry
* @value{DBG}: (bashdb).                     The @sc{bash} debugger.
@end direntry

@ifinfo
This file documents the @sc{bash} debugger @value{BASH}.


This is the @value{EDITION} Edition, @value{UPDATED},
of @cite{Debugging with BASHDB: the @sc{gnu} Source-Level Debugger}
for BASH

Copyright (C) 2002, 2003, 2004, 2006, 2007 Rocky Bernstein for the Free Software Foundation.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@ifset DEBIANHASBECOMEREASONABLE
@c From Matthias Klose <[e-mail]> a Debian maintainer on
@c Sat, 23 Aug 2003 14:24:44 +0200
@c
@c  I personally see the invariant sections as the thing in the
@c  GFDL, which hinders me in uploading the package to the archives.
@c  I don't have any problem, if some other Debian developer makes a
@c  bashdb package built from separate sources.
@c
@c  I am aware that Debian ships other packages containing documentation
@c  covered by the GFDL (and one of them for which I do the packaging as
@c  well), but I won't add a new package, which I maintain. So before an
@c  upload of a bashdb package built from the bash sources either
@c
@c
@c  - Debian has a position on the GFDL, which allows inclusion
@c
@c  - the bashdb manual does not have invariant sections, or is
@c    relicensed, or dual licensed.
@c
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below.

(a) The Free Software Foundation's Back-Cover Text is: ``You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development.''
@end ifset
@ifclear DEBIANHASBECOMEREASONABLE
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@end ifclear
@end ifinfo

@titlepage
@title Debugging with BASHDB
@sp 1
@subtitle @value{EDITION} Edition, for BASH
@subtitle @value{UPDATED-MONTH}
@author Rocky Bernstein
@page
@tex
{\parskip=0pt
\hfill (Send bugs and comments on bashdb to bug-bashdb\@sourceforge.net.)\par
\hfill {\it Debugging with BASH}\par
\hfill \TeX{}info \texinfoversion\par
}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 2002, 2003, 2004, 2006, 2007 Rocky Bernstein for the Free Software
Foundation.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@ifset DEBIANHASBECOMEREASONABLE
@c From Matthias Klose <[e-mail]> a Debian maintainer on
@c Sat, 23 Aug 2003 14:24:44 +0200
@c
@c  I personally see the invariant sections as the thing in the
@c  GFDL, which hinders me in uploading the package to the archives.
@c  I don't have any problem, if some other Debian developer makes a
@c  bashdb package built from separate sources.
@c
@c  I am aware that Debian ships other packages containing documentation
@c  covered by the GFDL (and one of them for which I do the packaging as
@c  well), but I won't add a new package, which I maintain. So before an
@c  upload of a bashdb package built from the bash sources either
@c
@c
@c  - Debian has a position on the GFDL, which allows inclusion
@c
@c  - the bashdb manual does not have invariant sections, or is
@c    relicensed, or dual licensed.
@c
@c
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.

(a) The Free Software Foundation's Back-Cover Text is: ``You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development.''
@end ifset
@ifclear DEBIANHASBECOMEREASONABLE
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@end ifclear
@end titlepage
@page

@ifnottex
@node Top, Summary, (dir), (dir)

@top Debugging with @DBG

This file describes @value{DBG}, the @sc{bash} symbolic debugger.

This is the @value{EDITION} Edition, @value{UPDATED}, for BASH.

Copyright (C) 2002, 2003, 2004, 2006, 2007 Rocky Bernstein

@menu
* Summary::                     Overview of Debugger with a sample session

* Invocation::                  Getting in and out
* Running::                     Script setup inside the BASH debugger
* Debugger Command Reference::  BASH debugger command reference

* Front Ends::                  Using the Debugger from a front-end user interface

* BASH Debugger Bugs::          Reporting bugs
* History and Acknowledgments:: History and Acknowledgments

Appendices
* Copying::			GNU General Public License says
                                how you can copy and share bashdb
* GNU Free Documentation License::  The license for this documentation

Indexes (nodes containing large menus)
* Function Index::            An item for each function name.
* Command Index::             An item for each command name.
* Variable Index::            An item for each documented variable.
* General Index::             An item for each concept.
@end menu

@end ifnottex

@contents

@node Summary
@chapter Summary of the BASH Debugger

The purpose of a debugger such as @DBG is to allow you to see what is
going on ``inside'' a bash script while it executes.

@DBG can do four main kinds of things (plus other things in support of
these) to help you catch bugs in the act:

@itemize @bullet
@item
Start your script, specifying anything that might affect its behavior.

@item
Make your script stop on specified conditions.

@item
Examine what has happened, when your script has stopped.

@item
Change things in your script, so you can experiment with correcting the
effects of one bug and go on to learn about another.
@end itemize

Although you can use the @acronym{BASH} debugger to debug scripts
written in @acronym{BASH}, it can also be used just as a front-end
for learning more about programming in @acronym{BASH}. As an
additional aid, the debugger can be used within the context of an
existing script with its functions and variables that have already
been initialized; fragments of the existing can be experimented with
by entering them inside the debugger.

@menu
* Sample Session::                    A Sample BASH Debugger session
* Interactive Line Tracing Session::  Interactive Line Tracing Session
* Free Software::                     Freely redistributable software
@end menu

@node Sample Session
@section A Sample BASH Debugger Session

You can use this manual at your leisure to read all about @value{DBG}.
However, a handful of commands are enough to get started using the
debugger.  This chapter illustrates those commands.

@iftex
In this sample session, we emphasize user input like this: @b{input},
to make it easier to pick out from the surrounding output.
@end iftex

Below we will debug a script that contains a function to compute the
factorial of a number: fact(0) is 1 and fact(n) is n*fact(n-1).

@smallexample
@cartouche
$ @b{bashdb -L .  /tmp/fact.sh}
Bourne-Again Shell Debugger, release bash-@value{VERSION}
Copyright 2002, 2003, 2004, 2006, 2007 Rocky Bernstein
This is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.

(/tmp/fact.sh:9):
  9:	echo fact 0 is: `fact 0`
bashdb<0> @b{-}
  1:    #!/usr/local/bin/bash
  2:    fact() @{
  3:    ((n==0)) && echo 1 && return
  4:    ((nm1=n-1))
  5:    ((result=n*`fact $nm1`))
  6:    echo $result
  7:    @}
  8:    
  9:==> echo fact 0 is: `fact 0`
bashdb<1> @b{list}
 10:   echo fact 3 is: $(fact 3)
@end cartouche
@end smallexample 

@noindent

The command invocation uses the option ``-L .'' Here we assume that
the @command{bashdb} script and the debugger files are in the same
location. If you are running from the source code, this will be the
case. However if bashdb has been installed this probably won't be true
and here you probably don't need to use ``-L .'' Instead you would
type simply @code{bashdb /tmp/fact.sh}.

Position information consists of a filename and line number,
e.g. @code{(/tmp/fact.sh:9)} and is given parenthesis. This position
format is similar to that used by the Perl debugger and is also in the
same format used by my GNU make debugger (
@url{http://bashdb.sourceforge.net/remake} and the Extended Python
Debugger @url{http://remake.sourceforge.net/pydb}. GNU Emacs and DDD
can parse this and in fact the same regular expression is used on the
3 debuggers.

The first debugger command we gave @kbd{-}, we listed a window of
lines @emph{before} where we were executing. Because the window, 10
lines, is larger than the number of lines to the top of the file we
printed only 9 lines here. The next command, @code{list}, starts from
the current line and again wants to print 10 lines but because there
are only one remaining line, that is what is printed.

@smallexample
@cartouche
bashdb<2> @b{step}
(/tmp/fact.sh:9):
fact 0
9:	echo fact 0 is: `fact 0`
bashdb<(3)> @b{@key{RET}}
2:	fact() @{
bashdb<(4)> @b{@key{RET}}
3:	((n==0)) && echo 1 && return
bashdb<(5)> @b{print $n}

bashdb<(6)>
@end cartouche
@end smallexample

Ooops... The variable @kbd{n} isn't initialized.@footnote{Recall that
variables in @value{BASH} don't need to be declared before they are
referred to and that the default value would be the a null value which
here prints as an empty string.}

The first @kbd{step} command steps the script one instruction. It may
seem odd that the line printed is exactly the same one as before. What
has happened though is that we've ``stepped'' into the subshell needed
to run @kbd{`fact 0`}; we haven't however started running anything
inside that subshell yet though.

To indicate that which piece of the multi-part line @code{echo fact 0
is: `fact 0`} we show that part all by itself @kbd{fact 0}. If nothing
is shown then it means we are running the beginning statement or in
this case the outermost statement.

To indicate that we are now nested in a subshell, notice that the