bashdb.texi

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

down your program quite a bit, and addressing this better would mean
some serious changes to @value{BASH} internals.  If you have a
@code{configure} script generated by autoconf, and you want to stop in
the middle of the script, it can take quite a while.

Furthermore, by necessity, debuggers change the operation of the
program they are debugging. And this can lead to unexpected and
unwanted differences. It has happened so often that the term
``Heisenbugs'' (see @url{http://en.wikipedia.org/wiki/Heisenbug}) was
coined to describe the situation where the addition of the use of a
debugger (among other possibilities) changes behavior of the program
so that the bug doesn't manifest itself anymore.

Another way to get into the debugger which adds no overhead or
slowdown until you reach the point at which you want to start
debugging. However here you must change the script and make an
explicit call to the debugger. Because the debugger isn't involved
before the first call, there is no overhead and the script will run at
the same speed as if there were no debugger.

There are two parts to calling the debugger from inside the script,
``sourcing'' in the debugger code and then making the call calling the
debugger to issue a ``step'' command. The name of file in
@code{source} command is @code{bashdb-trace} and it is located in the
directory where the other bash debugger files live. For example on
GNU/Linux if it is in directory @code{/usr/local/share/bashdb}, you
would first add to a @value{BASH} script the line:

@smallexample
    source /usr/local/share/bashdb/bashdb-trace
@end smallexample 

Although I said that running under the debugger adds overhead which
slows down you program, the above command in of itself will @emph{not}
cause any slowdown. If possible, it's best to put this somewhere in
the main-line code rather than in a function or in a subshell. If it
is put in a function of subshell and you step outside of that,
some of the global variables set up in @code{bashdb-trace} may be
lost. One the other hand if you know your debugging will be confined
to just the scope of the @code{source} command there is no problem.

The second thing that needs to be done is put add statements to start
stepping code, and this line looks like this:
@smallexample
     _Dbg_debugger ; : ; :
@end smallexample 

(For reasons that are a mystery to me, the stepping seems to kick in
only two statements after the call.)

Putting these two components together, here's an example:
@smallexample
@cartouche
  # Lots of stuff here. ...
  x=2
  source <path-to-program>/_Dbg_debugger
  echo There can be lots of other statements between the above
  echo and below line.
  _Dbg_debugger ; : ; :
  y=3
@end cartouche
@end smallexample 

You will be stopped before @code{y=3} in the debugger. 

You can also supply options to @code{_Dbg_debugger} just as you would to
the debugger itself. All of the options listed in @ref{Options for the
bashdb script} can be used with the exception of @code{-c} (run a
command) and of course you don't supply the name of a @value{BASH} script.

For example to suppress the banner you could use @code{_Dbg_debugger
-q} in the above example.

@node Program-Controlled Line Tracing
@subsection Program-Controlled Line Tracing

You can also turn on and off line tracing. Here's an example

@smallexample
@cartouche
  source <path-to-program>/bashdb-trace
   ...
  _Dbg_linetrace_on
  for i in `seq 10` ; do
     echo $i
  done
  _Dbg_linetrace_off
   BASHDB_QUIT_ON_QUIT=1  
@end cartouche
@end smallexample 

The @code{BASHDB_QUIT_ON_QUIT}  variable make sure the program doesn't
stay inside the debugger after it quits. It can also be set earlier in
the program.

Again @code{<path-to-program>} is whatever path needed to located
@code{<bashdb-trace>}. For example it might be @code{</usr/local/share>}
on some GNU/Linux installations.

@node Having the debugger intercept signals
@subsection Having the debugger intercept signals

You can also use the debugger's signal handler to print signals or go
into the debugger when geting a specific signal. 

Here are some examples: 
@smallexample
@cartouche
    _Dbg_handler INT print showstack nostop  # this is the default
    _Dbg_handler INT                         # same thing
    _Dbg_hander                              # same thing
    _Dbg_handler HUP print stop              # stop in debugger when getting
@end cartouche
@end smallexample 

@node Running
@chapter Script Setup inside the BASH Debugger

@menu
* Starting::                    Starting your script
* Command Files::               Command files
* Arguments::                   Your script's arguments
* Input/Output::                Your script's input and output
* Script/Debugger Interaction::   Keeping out of each other's harm
@end menu

@need 2000
@node Starting
@section Starting your script
@cindex starting
@cindex running

After invoking the debugger you should be on the first stoppable line
of your program to be debugged. At this point you can issue debugger
commands to set breakpoints (@pxref{Set Breaks, ,Setting
breakpoints}), or watchpoints (@pxref{Set Watchpoints, ,Setting
watchpoints}), or start continue the execution of the program
(@pxref{Resuming Execution, ,Resuming Execution}).

@table @code
@kindex restart @ovar{args}
@kindex run @r{(@code{restart})}
@kindex R @r{(@code{restart})}
@item restart @ovar{args}
@itemx run @ovar{args}
@itemx R @ovar{args}
Use the @code{restart} command to restart your script under
@value{DBG}. Without any arguments, the script name and parameters
from the last invocation are used. @value{dBGP} tries to maintain the
settings, watchpoints, breakpoints, actions and so on. Internally it
uses line numbers and filenames to record he position of interesting
places in your porgram; so if your program changes some or all of
these numbers may be off. Environment variable
@code{BASHDB_RESTART_FILE} is and a temporary file are used to signal
a restart, so you shouldn't uset @code{BASHDB_RESTART_FILE} (or any
environment variable starting with @code{BASHDB_}.

@end table

@node Command Files
@section Command files

@cindex command files
A command file for @DBG is a file of lines that are @DBG
commands.  Comments (lines starting with @kbd{#}) may also be included.
An empty line in a command file does nothing; it does not mean to repeat
the last command, as it would from the terminal.

@cindex init file
@cindex @file{.bashdbinit}
@cindex @file{bashdb.ini}
When you start @value{DBG}, it automatically executes commands from its
@dfn{init files}, normally called @file{.bashdbinit}@footnote{The DJGPP
port of @DBG uses the name @file{bashdb.ini} instead, due to the
limitations of file names imposed by DOS filesystems.}.
During startup, @DBG does the following:

@enumerate
@item
Reads the init file (if any) in your home directory@footnote{On
DOS/Windows systems, the home directory is the one pointed to by the
@code{HOME} environment variable.}.

@item
Processes command line options and operands.

@item
Reads the init file (if any) in the current working directory.

@item
Reads command files specified by the @samp{-x} option.
@end enumerate

The init file in your home directory can set options (such as @samp{set
complaints}) that affect subsequent processing of command line options
and operands.  Init files are not executed if you use the @samp{-x}
option (@pxref{Options for the bashdb script, ,bashdb script options}).

@cindex init file name
On some configurations of @value{DBG}, the init file is known by a
different name (these are typically environments where a specialized
form of @DBG may need to coexist with other forms, hence a
different name for the specialized version's init file).  These are the
environments with special init file names:

You can also request the execution of a command file with the
@code{source} command:

@table @code
@kindex source
@item source @var{filename}
Execute the command file @var{filename}.
@end table

The lines in a command file are executed sequentially.  They are not
printed as they are executed.  If there is an error, execution
proceeds to the next command in the file.

@node Arguments
@section Your script's arguments

@cindex arguments (to your script)
The arguments to your script can be specified by the arguments of the
@code{restart} command.
They are passed to a shell, which expands wildcard characters and
performs redirection of I/O, and thence to your script.  

@code{restart} with no arguments uses the same arguments used by the previous
@code{restart}, or those set by the @code{set args} command.. 

@table @code
@kindex set args
@item set args
Specify the arguments to be used if your program is rerun. If
@code{set args} has no arguments, @code{restart} executes your program
with no arguments.  Once you have run your program with arguments,
using @code{set args} before the next @code{restart} is the only way to run
it again without arguments.

@kindex show args
@item show args
Show the arguments to give your program when it is started.
@end table

@node Input/Output
@section Your script's input and output

@cindex redirection
@cindex I/O
@cindex terminal
By default, the script you run under the @acronym{BASH} debugger does
input and output to the same terminal that @acronym{BASH} uses.
Before running the script to be debugged, the debugger records the tty
that was in effect. All of its output is then written to that.
However you can change this when using the @samp{bashdb} script using
the @samp{-t} option.


@table @code
@kindex info terminal
@item info terminal
Displays information recorded by @DBG about the terminal modes your
program is using.
@end table

@kindex tty
@cindex controlling terminal
Another way to specify where your script should do input and output is
with the @code{tty} command.  This command accepts a file name as
argument, and causes this file to be the default for future @code{restart}
commands.  It also resets the controlling terminal for the child
process, for future @code{restart} commands.  For example,

@example
tty /dev/ttyb
@end example

@noindent
directs that processes started with subsequent @code{restart} commands
default to do input and output on the terminal @file{/dev/ttyb} and have
that as their controlling terminal.

An explicit redirection in @code{restart} overrides the @code{tty} command's
effect on the input/output device, but not its effect on the controlling
terminal.

When you use the @code{tty} command or redirect input in the @code{restart}
command, only the input @emph{for your script} is affected.  The input
for @DBG still comes from your terminal.

@node Script/Debugger Interaction
@section Script/Debugger Interaction

@value{dBGP} and your program live in the same variable space so to
speak. @acronym{BASH} does not have a notion of module scoping or
lexical hiding (yet) as is found in modern programming langauges and
in modern versions of the Korn shell. This then imposes some
additional care and awareness.

Most of the variables and functions used inside @DBG start
@code{_Dbg_}, so please don't use variables or functions with these
names in your program. 

@emph{Note: there are some other variables that begin with just an
underscore (@code{_}); over time these will be phased out. But until
then, avoid those or consult what is used by the debugger. Run
@samp{bashdb --debugger -c "declare -p"} to list all the variables in
use including those used by the debugger.}

A number of environment variables are also reserved for use; these
start with @code{BASHDB_}. For example: @env{BASHDB_INPUT},
@env{BASHDB_LEVEL} and, @env{BASHDB_QUIT_ON_QUIT} (@pxref{Debug,
,Debug}), @env{BASHDB_RESTART_FILE} (@pxref{Starting, ,Starting}), to
name a few.  Finally, there are some @acronym{BASH} environment
dynamic variables and these start with @env{BASH_}. For example
@env{BASH_SUBSHELL} (@pxref{Debug, ,Debug}), @env{BASH_COMMAND}
(@pxref{Command Display, ,Command Display}), @env{BASH_LINENO}, and
@env{BASH_SOURCE} to name a few.

Inside the debugger some variables may be redefined. In particular
@code{IFS} and @code{PS4}, and various dollar variables @code{$?},
@code{$1}, @code{$2}, etc. The values before entering the debugger are
saved and those variables have their old values restroed when leaving
the debugger. However you may notice these difference in various
debugger commands. For example @code{examine PS4} might not return the
same value as @code{eval declare -p PS4}. The former is picking the debugger
value while the @code{eval} is careful to restore the value to what
it was before entering the debugger.

In order to do its work @value{dBGP} sets up a @code{DEBUG}
trap. Consequently a script shouldn't reset this or the debugger will
lose control. @value{dBGP} also sets up an @code{EXIT} handler so that
it can gain control after the script finishes. Another signal
intercepted is the an interrupt or @code{INT} signal. For more
information about signal handling, @pxref{Signals, ,Signals} 

@node Debugger Command Reference
@chapter BASH Debugger Command Reference