bashdb.texi

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

program doesn't trap @code{SIGINT}).

@node Free Software
@unnumberedsec Free software

@DBG is @dfn{free software}, protected by the @sc{gnu}
General Public License
(GPL).  The GPL gives you the freedom to copy or adapt a licensed
program---but every person getting a copy also gets with it the
freedom to modify that copy (which means that they must get access to
the source code), and the freedom to distribute further copies.
Typical software companies use copyrights to limit your freedoms; the
Free Software Foundation uses the GPL to preserve these freedoms.

Fundamentally, the General Public License is a license which says that
you have these freedoms and that you cannot take these freedoms away
from anyone else.

@unnumberedsec Free Software Needs Free Documentation

The biggest deficiency in the free software community today is not in
the software---it is the lack of good free documentation that we can
include with the free software.  Many of our most important
programs do not come with free reference manuals and free introductory
texts.  Documentation is an essential part of any software package;
when an important free software package does not come with a free
manual and a free tutorial, that is a major gap.  We have many such
gaps today.

Consider Perl, for instance.  The tutorial manuals that people
normally use are non-free.  How did this come about?  Because the
authors of those manuals published them with restrictive terms---no
copying, no modification, source files not available---which exclude
them from the free software world.

That wasn't the first time this sort of thing happened, and it was far
from the last.  Many times we have heard a GNU user eagerly describe a
manual that he is writing, his intended contribution to the community,
only to learn that he had ruined everything by signing a publication
contract to make it non-free.

Free documentation, like free software, is a matter of freedom, not
price.  The problem with the non-free manual is not that publishers
charge a price for printed copies---that in itself is fine.  (The Free
Software Foundation sells printed copies of manuals, too.)  The
problem is the restrictions on the use of the manual.  Free manuals
are available in source code form, and give you permission to copy and
modify.  Non-free manuals do not allow this.

The criteria of freedom for a free manual are roughly the same as for
free software.  Redistribution (including the normal kinds of
commercial redistribution) must be permitted, so that the manual can
accompany every copy of the program, both on-line and on paper.

Permission for modification of the technical content is crucial too.
When people modify the software, adding or changing features, if they
are conscientious they will change the manual too---so they can
provide accurate and clear documentation for the modified program.  A
manual that leaves you no choice but to write a new manual to document
a changed version of the program is not really available to our
community.

Some kinds of limits on the way modification is handled are
acceptable.  For example, requirements to preserve the original
author's copyright notice, the distribution terms, or the list of
authors, are ok.  It is also no problem to require modified versions
to include notice that they were modified.  Even entire sections that
may not be deleted or changed are acceptable, as long as they deal
with nontechnical topics (like this one).  These kinds of restrictions
are acceptable because they don't obstruct the community's normal use
of the manual.

However, it must be possible to modify all the @emph{technical}
content of the manual, and then distribute the result in all the usual
media, through all the usual channels.  Otherwise, the restrictions
obstruct the use of the manual, it is not free, and we need another
manual to replace it.

Please spread the word about this issue.  Our community continues to
lose manuals to proprietary publishing.  If we spread the word that
free software needs free reference manuals and free tutorials, perhaps
the next person who wants to contribute by writing documentation will
realize, before it is too late, that only free manuals contribute to
the free software community.

If you are writing documentation, please insist on publishing it under
the GNU Free Documentation License or another free documentation
license.  Remember that this decision requires your approval---you
don't have to let the publisher decide.  Some commercial publishers
will use a free license if you insist, but they will not propose the
option; it is up to you to raise the issue and say firmly that this is
what you want.  If the publisher you are dealing with refuses, please
try other publishers.  If you're not sure whether a proposed license
is free, write to @email{licensing@@gnu.org}.

You can encourage commercial publishers to sell more free, copylefted
manuals and tutorials by buying them, and particularly by buying
copies from the publishers that paid for their writing or for major
improvements.  Meanwhile, try to avoid buying non-free documentation
at all.  Check the distribution terms of a manual before you buy it,
and insist that whoever seeks your business must respect your freedom.
Check the history of the book, and try to reward the publishers that
have paid or pay the authors to work on it.

The Free Software Foundation maintains a list of free documentation
published by other publishers, at
@url{http://www.fsf.org/doc/other-free-books.html}.

@node Invocation
@chapter Getting in and out

This chapter discusses how to start @value{DBG}, and how to get out of it.
The essentials are:
@itemize @bullet
@item
type @samp{bash --debugger @emph{script-name}} or @samp{bashdb
@emph{script-name}} to start @value{DBG}. Or...
@item 
type @samp{bashdb -c @emph{command string}} to give a string to run 
under the debugger. Or ..
@item 
modify your program to enter the debugger at a particular point:
@code{source ../bashdb-trace} and @code{_Dbg_debugger}.
@item
type @kbd{quit} or @kbd{C-d} inside the debugger to exit.
@end itemize

There are also two front-ends available as well. One can also
enter the debugger inside emacs via the command @code{M-x bashdb}
after loading Emacs' Grand Unified Debugger, @code{gud}. See
@ref{Emacs,,Using the BASH debugger from @value{Emacs}}. And there is
support in a @value{DDD} for bash.

@menu
* Starting the BASH debugger::    How to enter the BASH debugger
* Quitting the BASH debugger::    How to leave the BASH debugger
* Calling from Program::          Calling the debugger from inside your program
@end menu

@node Starting the BASH debugger
@section Starting the BASH debugger

@emph{Note: it is important to use a debugger-enabled bash. You will
get an error message if the debugger is run under a version of BASH
that does not have debugging support.}

As mentioned above, one can enter @DBG via Emacs or
DDD. However you don't have to use either of these. And these still
need a way on their own to get things started.

There are in fact two @emph{other} ways to start @value{DBG}.  The
first way is to pass the @samp{--debugger} option to bash with the
name of your script the scripts arguments following that, or with a
command string (@code{-c}).

@example
bash --debugger @var{script} @var{script-arguments...}
bash --debugger -c @var{command-string}...
@end example

This calls a debugger initialization script. It works much like a
@acronym{BASH} login profile which may set variables and define
functions. But this shell profile is customized for debugging and as
such arranges for itself to get called before each statement is
executed. Although there are some problems at present in I/O
redirection that the method described next doesn't have, it is
expected that over time more features will be enabled in bash when the
@samp{--debugger} option is in effect. By default, both debugging in
Emacs via GUD (@ref{Emacs,,Using the BASH debugger under Emacs}) and
debugging via @value{DDD} work via this method.

The form @samp{bash --debugger -c ...} can be used to get into the
debugger without having to give a script name to debug. Sometimes you
may want to do this just to see how the debugger works: try some
debugger commands or maybe get online help. If you run @code{ddd
--bash} without giving a script name, it in fact uses this form.

In order for the @samp{--debugger} option to work however, you must
have the debugger scripts installed in a place where @DBG can find
them. For this reason, in developing @value{DBG}, I use a second
method more often; it doesn't require the bash debugger to be
installed. This method uses another script called @code{bashdb} which
allows for giving its own options, the final option is signaled by
adding @code{--}). After this, the name of the script to debugged and
any the arguments to pass to that script are given. Using this method,
one would start the debugger like this:

@example
bash @var{path-to-bashdb}/bashdb @var{bashdb-options} -- @var{script} @var{script-arguments...}
@end example

If you don't need to pass dash options to your program which might get
confused with the debugger options, then you don't need to add the
@code{--}.@footnote{And in the interest of full disclosure, although
this was not shown in the example it is possible to add the @code{--}
@emph{after} the script name to be debugged but before the first
program option with a dash.}

As with the first method, @code{bash} should be a debugger-enabled
bash. If @code{bashdb} has the path to bash in it at the top (e.g. via
@code{#!}), and @code{bashdb} can be found in your program-search
path, then this might be equivalent to the above:

@example
bashdb @var{bashdb-options} -- @var{script} @var{script-arguments...}
@end example

There are two or three disadvantages however of running a debugger
this way. First @code{$0} will have the value @code{bashdb} rather
than the script you are trying to run. For some scripts this may
change the behavior of the debugged script. Second a traceback will
contain additional lines showing the ``source''-ing of the debugged
script from @code{bashdb}. And third, although this way works better
than the first method, over time this way may come into disuse. 

An option that you'll probably need to use if bashdb isn't installed
but run out of the source code directory is @samp{-L} which specifies
the directory that contains the debugger script files.

You can further control how bashdb starts up by using command-line
options. bashdb itself can remind you of the options available.

@noindent
Type

@example
bashdb -h
@end example

@noindent
to display all available options and briefly describe their use.

When the bash debugger is invoked either by the @code{bashdb}
front-end script or @code{bash --debugging}, the first argument that
does not have an associated option flag for @code{bashdb} or
@code{bash} (as the case may be) is used as the name a the script file
to be debugged, and any following options get passed the debugged
script.

Options for the @code{bashdb} front-end are shown in the
following list.  

@menu
* Options for the bashdb script::   Options you can pass in starting bashdb
@end menu

@node Options for the bashdb script
@subsection Command-line options for @code{bashdb} script

You can run @DBG in various alternative modes---for example, in batch
mode or quiet mode. If @code{getopts} support is available the script
also allows long-form command options.

@table @code
@item -h | --help
@cindex @code{-h}
@cindex @code{--help}
This option causes @value{DBG} to print some basic help and exit.

@item -V
@cindex @code{-V}
This option causes @DBG to print its version number,
no-warranty blurb, and exit.

@item -c | --command @var{cmd}
@cindex @code{-c}
@cindex @code{--command}
Run the string instead of running a script

@item -B | --basename
@cindex @code{-B}
@cindex @code{--basename}
This option causes @DBG to print its version number and
no-warranty blurb, and exit.

@item -n | --nx | --no-init
@cindex @code{-n}
@cindex @code{--nx}
@cindex @code{--no-init}
Do not execute commands found in any initialization files.  Normally,
@acronym{BASH} executes the commands in these files after all the command
options and arguments have been processed.  @xref{Command Files,,Command
files}.

@item -q | --quiet
@cindex @code{-q}
@cindex @code{--quiet}
``Quiet''.  Do not print the introductory and copyright messages.  These
messages are also suppressed in batch mode.

@item -t | --terminal | --tty @var{tty}
@cindex @code{-t}
@cindex @code{--terminal}
@cindex @code{--tty}
``Terminal output''.  Set the file or terminal that you want debugger command
output to go to. Note that the debugger output is independent of the
debugged script output.

o@item -L | --library @var{directory}
@cindex @code{-L}
@cindex @code{--library}
Set directory where debugger files reside to @var{directory}. The
default location is @code{../lib/bashdb} relative to the place that
the bashdb script is located. For example if bashdb is located in
@code{@value{bindir}/bashdb}, the default library location will be
@code{@value{libdir}/bashdb} which may or may not exist. If it doesn't
you'll get an error when you run bashdb. Only if the default location
is incorrect, should you need to use the @code{-L} option.

@item -T | --tempdir @var{directory}
@cindex @code{-T}
@cindex @code{--tempdir}
Set directory to use for writing temporary files.

@end table

@node Quitting the BASH debugger
@section Quitting the BASH debugger

@cindex interrupt
An interrupt (often @kbd{C-c}) does not exit from @value{DBG}, but
rather terminates the action of any @DBG command that is in
progress and returns to @value{DBG} command level.  Inside a debugger
command interpreter, use @code{quit} command (@pxref{Quit, ,Quitting
the BASH debugger}).

There way to terminate the debugger is to use the @code{kill}
command. This does more forceful @code{kill -9}. It can be used in
cases where @code{quit} doesn't work.

@node Calling from Program
@section Calling the BASH debugger from inside your program
@menu
* Program-Controlled Line Tracing::
* Having the debugger intercept signals::
@end menu

Running a program from the debugger adds a bit of overhead and slows