bashdb.texi

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

command number, starting with 3, or the third command entered, now
appears in parenthesis. Each subshell nesting adds a set of
parenthesis.

The first @kbd{step} command steps the script one instruction; it
didn't advance the line number, 9, at all. That is because we were
stopping before the command substitution or backtick is to take
place. The second command we entered was just hitting the return key;
bashdb remembers that you entered @code{step} previously, so it runs
the step rather than @kbd{next}, the other alternative when you hit
@key{RET}. Step one more instruction and we are just before running
the first statement of the function.

Next, we print the value of the variable @kbd{n}. Notice we need to add
a preceding dollar simple to get the substitution or value of n. As we
will see later, if the @kbd{pe} command were used this would not be
necessary. 

We now modify the file to add an assignment to local variable @kbd{n} and
restart.

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

@noindent
This time we use the @code{list} debugger command to list the lines in
the file. From before we know it takes three @code{step} commands
before we get into the fact() function, so we add a count onto the
@code{step} command. Notice we abbreviate @code{step} with @code{s};
we could have done likewise and abbreviated @code{list} with @code{l}.

@smallexample
@cartouche
bashdb<(4)> @b{@key{RET}}
(/tmp/fact.sh:4):
4:	((n==0)) && echo 1 && return
echo 1
bashdb<(5)> @b{@key{RET}}
(/tmp/fact.sh:4): 
4:	((n==0)) && echo 1 && return
return
@end cartouche
@end smallexample 

@noindent
Again we just use @key{RET} to repeat the last @code{step}
commands. And again the fact that we are staying on the same line 4
means that the next condition in the line is about to be
executed. Notice that we see the command (@code{echo 1} or
@code{return}) listed when we stay on the same line which has multiple
stopping points in it. Given the information above, we know that the
value echo'ed on return will be 1.

@smallexample
@cartouche
bashdb<(6)> @b{@key{RET}}
fact 0 is: 1
(/tmp/fact.sh:12): 
12:	echo fact 3 is: $(fact 3)
bashdb<(7)> @b{break 5}
Breakpoint 1 set in file fact.sh, line 5.
bashdb<(8)> @b{continue}
@end cartouche
@end smallexample 

@noindent
We saw that we could step with a count into the function
fact(). However above took another approach: we set a stopping point or
``breakpoint'' at line 5 to get us a little ways into the fact()
subroutine. Just before line 5 is to executed, we will get back into
the debugger. The @code{continue} command just resumes execution until
the next stopping point which has been set up in some way.

@smallexample
@cartouche
(/tmp/fact.sh:5):
5:      ((nm1=n-1))
Breakpoint 1 hit(1 times).
bashdb<(8)> @b{x n-1}
2
bashdb<(9)> @b{s}
(/tmp/fact.sh:5):
6:     ((result=n*`fact $nm1`))
bashdb<(10)> @b{c}
fact.sh: line 6: ((: result=n*: syntax error: operand expected (error token is "*")
bashdb<(7)> @b{R}
Restarting with: bash --debugger fact.sh 
11:	echo fact 0 is: `fact 0`
bashdb<0> @b{l fact}
 2:    fact () 
 3:    @{ 
 4:       local -i n=$@{1:0@};
 5:       (( "n==0" )) && echo 1 && return;
 6:       (( nm1=n-1 ));
 7:       ((fact_nm1=`fact $nm1`))
 8:       (( "result=n*fact_nm1" ));
 9:       echo $result
10:    @}
@end cartouche
@end smallexample

@noindent
In addition to listing by line numbers, we can also list giving a
function name. Below, instead of setting a breakpoint at line 5 and
running ``@code{continue}'' as we did above, we try something slightly
shorter and slightly different. We give the line number on the
``continue'' statement. This is a little different in that a one-time
break is made on line 5. Once that statement is reached the breakpoint
is removed.

@smallexample
@cartouche
bashdb<1> @b{continue 5}
One-time breakpoint 1 set in file fact.sh, line 5.
fact 0 is: 1
(/tmp/fact.sh:5):
5:	((nm1=n-1))
bashdb<(2)> @b{s}
6:	((fact_nm1=`fact $nm1`))
bashdb<(3)> @b{s}
2:	fact() @{
bashdb<(4)> @b{T}
->0 in file `fact.sh' at line 2
##1 fact("3") called from file `fact.sh' at line 12
##2 source("fact.sh") called from file `/usr/local/bin/bashdb' at line 154
##3 main("fact.sh") called from file `/usr/local/bin/bashdb' at line 0
bashdb<(5)> @b{c}
fact 3 is: 6
Debugged program terminated normally. Use q to quit or R to restart.
@end cartouche
@end smallexample

@noindent
When we stop at line 5 above, we have already run fact(0) and output
the correct results. The output from the program ``fact 0 is: 1'' is
intermixed with the debugger output. The @code{T} command above
requests call stack output and this confirms that we are not in the
fact(0) call but in the fact(3) call. There are 4 lines listed in the
stack trace even though there is just one call from the main
program. The top line of the trace doesn't really represent a call,
it's just where we currently are in the program. That last line is an
artifact of invoking bash from the bashdb script rather than running
@code{bash --debugger}.

The last message in the output above @samp{Debugged program exited
normally.} is from @value{DBG}; it indicates script has finished
executing.  We can end our bashdb session with the bashdb
@code{quit} command.

Above we did our debugging session on the command line. If you are a
GNU Emacs user, you can do your debugging inside that. Also there is
a(nother) GUI interface called DDD that supports @value{DBG}.

@node Interactive Line Tracing Session
@section Interactive Line Tracing Session

One of the things I had found annoying about ``@code{set -x}'' tracing is
that no position information given in the trace output, in particular
the line number and the file name.  However I learn in
@url{http://raz.cx/blog/2005/08/handy-bash-debugging-trick.html} that
one can set @code{$PS4} to rectify this.

Here's what I use:

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

This can be set in one's @code{.bashrc}, or added as a line in your
script before ``@code{set -x}''.

There is also facility inside the bash debugger showing position
information when tracing a script. Here's a simple session.

@example
@cartouche
@b{/usr/local/bin/bashdb /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:11):
11:	echo fact 0 is: `fact 0`
bashdb<0> @b{set linetrace on}
bashdb<1> @b{cont}
(/tmp/fact.sh:11):
level 1, subshell 1, depth 0:	echo fact 0 is: `fact 0`
fact 0
(/tmp/fact.sh:2):
level 1, subshell 1, depth 1:	fact() @{
(/tmp/fact.sh:3):
level 1, subshell 1, depth 1:	    local -i n=$@{1:0@}
(/tmp/fact.sh:4):
level 1, subshell 1, depth 1:	    ((n==0)) && echo 1 && return
(/tmp/fact.sh:4):
level 1, subshell 1, depth 1:	    ((n==0)) && echo 1 && return
echo 1
(/tmp/fact.sh:4):
level 1, subshell 1, depth 1:	    ((n==0)) && echo 1 && return
return
fact 0 is: 1
(/tmp/fact.sh:13):
level 1, subshell 0, depth 0:	echo fact 3 is: $(fact 3)
(/tmp/fact.sh:13):
level 1, subshell 1, depth 0:	echo fact 3 is: $(fact 3)
fact 3
(/tmp/fact.sh:2):
level 1, subshell 1, depth 1:	fact() @{
(/tmp/fact.sh:3):
level 1, subshell 1, depth 1:	    local -i n=$@{1:0@}
(/tmp/fact.sh:4):
level 1, subshell 1, depth 1:	    ((n==0)) && echo 1 && return
(/tmp/fact.sh:5):
level 1, subshell 1, depth 1:	    ((nm1=n-1))
(/tmp/fact.sh:6):
level 1, subshell 1, depth 1:	    ((fact_nm1=`fact $nm1`))
(/tmp/fact.sh:6):
level 1, subshell 2, depth 1:	    ((fact_nm1=`fact $nm1`))
fact $nm1
(/tmp/fact.sh:2):
level 1, subshell 2, depth 2:	fact() @{
...
level 1, subshell 4, depth 4:	fact() @{
(/tmp/fact.sh:3):
level 1, subshell 4, depth 4:	    local -i n=$@{1:@}
(/tmp/fact.sh:4):
level 1, subshell 4, depth 4:	    ((n==0)) && echo 1 && return
(/tmp/fact.sh:4):
level 1, subshell 4, depth 4:	    ((n==0)) && echo 1 && return
echo 1
(/tmp/fact.sh:4):
level 1, subshell 4, depth 4:	    ((n==0)) && echo 1 && return
return
(/tmp/fact.sh:7):
level 1, subshell 3, depth 3:	    ((result=n*fact_nm1))
(/tmp/fact.sh:8):
level 1, subshell 3, depth 3:	    echo $result
(/tmp/fact.sh:7):
level 1, subshell 2, depth 2:	    ((result=n*fact_nm1))
(/tmp/fact.sh:8):
level 1, subshell 2, depth 2:	    echo $result
(/tmp/fact.sh:7):
level 1, subshell 1, depth 1:	    ((result=n*fact_nm1))
(/tmp/fact.sh:8):
level 1, subshell 1, depth 1:	    echo $result
fact 3 is: 6
(/usr/local/bin/bashdb:260):
level 1, subshell 0, depth -1:	
Debugged program terminated normally. Use q to quit or R to restart.
bashdb<2> 
@end cartouche
@end example

An explanation of the output. The @emph{level} is how many invocations
of @value{BASH} are in effect before the statement shown is
executed. The @emph{subshell} is how many subshells you are nested
in. Subshells are used by command substitution---@code{`..'} and
@code{$(...)}---as well as arithmetic expressions @code{((...))}. The
@emph{depth} is the function depth or how many calls you are nested
in. A ``source'' command also increases this depth.

Notice also that in contrast to @code{set -x} tracing, the line shown
is exactly as you entered it in the source. So if you indented
statements in a meaningful way, it will help you understand the
statement nesting level. But as before, if a line contains multiple
statements, you are @emph{not} executing the first statement in the
line and @code{set showcommand} is not turned off (by default it is
on), that statement is shown in addition below the multi-statement
line. Such an example can be seen right at the beginning where
@code{fact 0} is shown.

If what you want to do is trace the @emph{entire} script as was done
above (and not stop in the debugger when the script is over), you can
get the same effect by using the @code{-X} or @code{--trace} option on
the @code{bashdb} command:

@example
@cartouche
@b{/usr/local/bin/bashdb -X /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.

(/usr/local/bin/bashdb:272):
level 1, subshell 0, depth -1:	  . $_source_file
(/tmp/fact.sh:11):
level 1, subshell 0, depth 0:	echo fact 0 is: `fact 0`
(/tmp/fact.sh:11):
level 1, subshell 1, depth 0:	echo fact 0 is: `fact 0`
fact 0
(/tmp/fact.sh:2):
level 1, subshell 1, depth 1:	fact() @{
(/tmp/fact.sh:3):
level 1, subshell 1, depth 1:	    local -i n=$@{1:0@}
...
level 1, subshell 2, depth 2:	    echo $result
(/tmp/fact.sh:7):
level 1, subshell 1, depth 1:	    ((result=n*fact_nm1))
(/tmp/fact.sh:8):
level 1, subshell 1, depth 1:	    echo $result
fact 3 is: 6
(/usr/local/bin/bashdb:285):
level 1, subshell 0, depth -1:	
@end cartouche
@end example

If you issue a break (e.g. send a @code{SIGINT} signal) while the
program is running you will go into the debugger (assuming your