bashdb.texi

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

You can abbreviate the long name of @DBG command to the first
few letters of the command name, if that abbreviation is unambiguous;
and you can repeat the @code{next} o r@code{step} commands by typing
just @key{RET}. Some commands which require a parameter, such as 
@code{print} remember the argument that was given to them. 

@menu
* Command Syntax::       How to give commands to the BASH debugger
* Help::                 How to ask for help (help)
* Quit::                 Leaving the debugger (quit, kill)
* Information::          Status and Debugger settings (info, show)
* Stopping::             Stopping and continuing (break, watch, step, cont...)
* Stack::                Examining the stack frame (where, up, down, frame)
* List::                 Printing source files (list)
* Search::               Searching source files (/pat/ ?pat?)
* Data::                 Examining data (print, examine, info variables)
* Evaluation/Execution:: Arbitrary execution (eval, shell)
* Interfacing to the OS:: Interfacing to the OS (cd, pwd)
* Auto Display::         Executing expressions on stop (display, undisplay)
* Controlling bashdb::   Controlling bashdb (annotate, file, prompt, history...)
@end menu

@node Command Syntax
@section Command syntax

A @acronym{BASH} debugger command is a single line of input.  There is
no limit on how long it can be.  It starts with a command name, which
is followed by arguments whose meaning depends on the command name.
For example, the command @code{step} accepts an argument which is the
number of times to step, as in @samp{step 5}.  You can also use the
@code{step} command with no arguments.  Some commands do not allow any
arguments.

@cindex repeating next/step commands
@kindex RET @r{(repeat last command)}
A blank line as input to @DBG (typing just @key{RET}) means to
repeat the previous next or step command.  

@kindex # @r{(a comment)}
@cindex comment
Any text from a @kbd{#} to the end of the line is a comment; it does
nothing.  This is useful mainly in command files (@pxref{Command
Files,,Command files}).

@node Help
@section Getting help (@samp{help})
@cindex online documentation

Once inside the @acronym{BASH} debugger, you can always ask it for
information on its commands, using the command @code{help}.

@table @code
@kindex h @r{(@code{help})}
@item help
@itemx h
You can use @code{help} (abbreviated @code{h}) with no arguments to
display a short list of named classes of commands:
@end table 

@flushleft
@smallexample
bashdb<0> @b{help}
bashdb commands:
List/search source lines:                 Control script execution:
-------------------------                 -------------------------
 l [start|.] [cnt] List cnt lines         T [n]        Stack trace
                   from line start        s [n]        Single step [n times]
 l sub       List source code fn          n [n]        Next, steps over subs
 - or .      List previous/current line   <CR>/<Enter> Repeat last n or s 
 w [line]    List around line             c [linespec] Continue [to linespec]
 f filename  View source in file          L            List all breakpoints
 /pat/       Search forward for pat       b linespec   Set breakpoint
 ?pat?       Search backward for pat      del [n].. or D Delete a/all breaks
                                                         by entry number
Debugger controls:                        skip         skip execution of cmd
-------------------------                 cl linespec  Delete breakpoints by
 H [num]         Show last num commands                line spec
 q [exp] or ^D   Quit returning exp       R [args]     Attempt a restart
 info [cmd]      Get info on cmd.         u [n]        Go up stack by n or 1.
 !n or hi n      Run debugger history n   do [n]       Go down stack by n or 1.
 h or ? [cmd]    Get help on command      W [var]      Add watchpoint. If no
 info [cmd]      Get info on cmd                       no expr, delete all
 show [cmd]      Show settings            We [expr]    Add Watchpoint arith 
                                                       expr
 so file         read in dbg commands     t            Toggle trace
                                          en/di n      enable/disable brkpt,
 set x y         set a debugger variable               watchpoint, or display
 e bash-cmd      evaluate a bash command  tb linespec  Add one-time break
 disp expr       add a display expr       a linespec cmd eval "cmd" at linespec
 M               Show module versions     A            delete all actions
 x expr          evaluate expression      ret          jump out of fn or source
                 (via declare, let, eval) finish       execute until return
 deb             debug into another       cond n exp   set breakpoint condition
                 shell script
 !! cmd [args]   execute shell command "cmd" with "args"
 file filename   Set script filename to read for current source.

Data Examination: also see e, t, x
-------------------------                 
 p variable      Print variable 
 V [[!]pat]      List variable(s) matching or not (!) matching pattern pat
 S [[!]pat]      List subroutine names [not] matching pattern pat

Readline command line editing (emacs/vi mode) is available.
For more help, type h <cmd> or consult online-documentation.
@end smallexample
@end flushleft
@c the above line break eliminates huge line overfull...

@table @code
@item help @var{command}
With a command name as @code{help} argument, the @acronym{BASH}
debugger displays short information on how to use that command.

@example
bashdb<0> @b{help list}
l linespec      List window lines starting at linespec.
l min incr      List incr lines starting at 'min' linespec.
l               List next window of lines.
l .             Same as above.
                Long command name: list.
@end example

In addition to @code{help}, you can use the debugger command
@code{info} to inquire about the state of your script, or the state of
@DBG itself.  The listings under @code{info} in the Index
point to all the sub-commands.  @xref{Command Index}.
@end table

@c @group
@table @code
@kindex info
@kindex i @r{(@code{info})}
@item info
This command (abbreviated @code{i}) is for describing the state of
your program.  For example, you can list the arguments given to your
script with @code{info args}, or list the breakpoints you have set
with @code{info breakpoints}.  You can get a complete list of the
@code{info} sub-commands with @w{@code{help info}}.

@example
bashdb<0> @b{help info}
List of info subcommands:

info args -- Argument variables (e.g. $1, $2, ...) of the current stack frame.
info breakpoints -- Status of user-settable breakpoints
info display -- Show all display expressions
info files -- Source files in the program
info functions -- All function names
info line -- list current line number and and file name
info program -- Execution status of the program.
info signals -- What debugger does when program gets various signals
info source -- Information about the current source file
info stack -- Backtrace of the stack
info terminal -- Print terminal device
info variables -- All global and static variable names
info warranty -- Various kinds of warranty you do not have
bashdb<1> @b{info source}
Current script file is parm.sh
Contains 34 lines.
@end example
@end table


@node Quit
@section Quitting the BASH debugger (@samp{quit}, @samp{kill})

@table @code
@kindex quit @r{[}@var{expression} @ovar{subshell-levels}@r{]}
@kindex q @r{(@code{quit})}
@item quit @ovar{expression}
@item quit @r{[}@var{expression} @ovar{subshell-levels}@r{]}
@itemx q

To exit @value{DBG}, use the @code{quit} command (abbreviated
@code{q}), or type an end-of-file character (usually @kbd{C-d}).  If
you do not supply @var{expression}, @DBG will try to terminate
normally or with exit code 0. Otherwise it will terminate using the
result of @var{expression} as the exit code. 

A simple @code{quit} tries to terminate all nested subshells that may
be in effect.  If you are nested a subshell, this is normally
indicated in a debugger prompt by the number of parentheses that the
history number is inside --- no parenthesis means there is no subshell
in effect. The dynamic variable @env{BASH_SUBSHELL} also contains the
number of subshells in effect. 

If you want only to terminate some number of subshells but not all of
them, you can give a count of the number of subshells to leave after
the return-code expression. To leave just one level of subshell
@code{return} does almost the same thing. (See @pxref{Returning,
,Returning}) There is a subtle difference between the two though:
@code{return} will leave you at the beginning of the next statement
while @code{quit} may leave you at the place the subshell was invoked
which may be in the middle of another command such as an assingment
statement or condition test.

If the environment variable @code{BASHDB_QUIT_ON_QUIT} is set, when the
program terminates, the debugger will also terminate too. This may be
useful if you are debugging a script which calls another script and
you want this inner script just to return to the outer script.

@item kill
@kindex k @r{(@code{kill})}
@itemx k
In situations where @code{quit} doesn't work we provide an alternative
and more forceful quit command: @code{kill}. This sends to the OS
non-maskable KILL signal with the debugger process number. No cleanup
of temporary files is done by the program.
@end table

@node Stopping
@section Stopping and Resuming Execution

One important use of a debugger is to stop your program @emph{before} it
terminates so that if your script might run into trouble, you can
investigate and find out why. However should your script accidently
continue to termination, @DBG has arranged for it not to leave the
debugger without your explicit instruction. That way, you can restart
the program using the same command arguments.

Inside @value{DBG}, your script may stop for any of several reasons,
such as a signal, a breakpoint, or reaching a new line after a
debugger command such as @code{step}.  You may then examine and
change variables, set new breakpoints or remove old ones, and then
continue execution.  

@menu
* Breakpoints::          Breakpoints, watchpoints (break, tbreak, watch, watche, clear)
* Resuming Execution::   Resuming execution (continue, step, next, skip, finish, return, debug)
* Signals::              Signals
@end menu

@node Breakpoints
@subsection Breakpoints, watchpoints (@samp{break}, @samp{tbreak}, @samp{watch}, @samp{watche}...)

@cindex breakpoints
A @dfn{breakpoint} makes your script stop whenever a certain point in
the program is reached.  For each breakpoint, you can add conditions to
control in finer detail whether your script stops.  

You can set breakpoints specify the place where your script should
stop the @code{break} command and its variants (@pxref{Set Breaks,
,Setting breakpoints}). These commands allow own to specify the
location by line number and file name or function name.

@cindex watchpoints
@cindex breakpoint on variable modification
A @dfn{watchpoint} is a special breakpoint that stops your script when
the value of an expression changes.  There is a different command to
set watchpoints (@pxref{Set Watchpoints, ,Setting watchpoints}). 

But aside from that, you can manage a watchpoint like any other
breakpoint: you delete enable, and disable both breakpoints and
watchpoints using the same commands.

You can arrange to have values from your program displayed automatically
whenever @value{BASH} stops at a breakpoint.  @xref{Auto Display,,
Automatic display}.

@cindex breakpoint numbers
@cindex numbers for breakpoints
@value{dBGP} assigns a number to each breakpoint when you create it;
these numbers are successive integers starting with one.  In many of
the commands for controlling various features of breakpoints you use
the breakpoint number to say which breakpoint you want to change.
Each breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled,
it has no effect on your script until you enable it again.

@cindex watchpoints numbers
@cindex numbers for watchpoints
Watchpoint numbers however are distinguished from breakpoint numbers by
virtue of their being suffixed with the either an upper- or lower-case
`W'.  For example, to enable breakpoint entry 0 along with watchpoint
entry 1 you would write @samp{enable 1 2w}, the ``2w'' refers to the
watchpoint; ``2W'' would work just as well.

@ifset FINISHED
@cindex breakpoint ranges
@cindex ranges of breakpoints
Some @DBG commands accept a range of breakpoints on which to
operate.  A breakpoint range is either a single breakpoint number, like
@samp{5}, or two such numbers, in increasing order, separated by a
hyphen, like @samp{5-7}.  When a breakpoint range is given to a command,
all breakpoint in that range are operated on.
@end ifset

@menu
* Set Breaks::                      Setting breakpoints (break, tbreak)
* Set Watchpoints::                 Setting watchpoints (watch, watche)
* Break Commands::                  Breakpoint command lists (command)
* Delete Breaks::                   Deleting breakpoints (delete, clear)
* Disabling::                       Disabling breakpoints (disable, enable)
* Conditions::                      Break conditions (condition)
@end menu

@node Set Breaks
@subsubsection Setting breakpoints (@samp{break} @samp{tbreak})

@kindex break
@kindex b @r{(@code{break})}
@cindex latest breakpoint
Breakpoints are set with the @code{break} command (abbreviated
@code{b}).  

@table @code
@item break @var{function}
Set a breakpoint at entry to function @var{function}.

@item break @var{linenum}
Set a breakpoint at line @var{linenum} in the current source file.
The current source file is the last file whose source text was printed.
The breakpoint will stop your script just before it executes any of the
code on that line.

@item break @var{filename}:@var{linenum}
Set a breakpoint at line @var{linenum} in source file @var{filename};
@var{filename} has to be one of the files previously read in and has
to be specified exactly as the name used when read in. For a list of
read-in files, use the @samp{info files} command.

@ifset FINISHED
@item break
When called without any arguments, @code{break} sets a breakpoint at
the next instruction to be executed in the selected stack frame
(@pxref{Stack, ,Examining the Stack Frame}).  In any selected frame but the
innermost, this makes your script stop as soon as control returns to
that frame.  If you use @code{break} without an argument in the
innermost frame, @DBG stops the next time it reaches the
current location; this may be useful inside loops.
@end ifset

@item break @dots{} if @var{cond}
Set a breakpoint with condition @var{cond}; evaluate the expression
@var{cond} each time the breakpoint is reache