1bashdb(1) GNU Tools bashdb(1)
2
6 bashdb - bash debugger script
7
9 bashdb [options] [--] script-name [script options]
10 bashdb [options] -c execution-string
12 bash --debugger [bash-options...] script-name [script options]
14
16 "bashdb" is a bash script to which arranges for another bash script to
17 be debugged. The debugger has a similar command interface as gdb(1).
18 The way this script arranges debugging to occur is by including (or
20 actually "source"-ing) some debug-support code and then sourcing the
21 given script or command string.
22 One problem with sourcing a debugged script is that the program name
24 stored in $0 will be "bashdb" rather than the name of the script to be
25 debugged. The debugged script will appear in a call stack not as the
26 top item but as the item below "bashdb". If this is of concern, use the
27 last form given above, "bash --debugger" script-name [script-options].
28 If you used bashdb script and need to pass options to the script to be
30 debugged, add "--" before the script name. That will tell bashdb not to
31 try to process any further options.
32 See the reference manual <http://bashdb.sourceforge.net/bashdb.html>
34 for how to to call the debugger from inside your program or arrange for
35 the debugger to get called when your program is sent a signal.
36
38 -h | --help
39 Print a usage message on standard error and exit with a return code
40 of 100.
41 -A | --annotation level
45 Sets to output additional stack and status information which allows
46 front-ends such as emacs to track what's going on without polling.
47 This is needed in for regression testing. Using this option is
49 equivalent to issuing:
50 set annotation LEVEL
52 inside the debugger.
54 -B | --basename
58 In places where a filename appears in debugger output give just the
59 basename only. This is needed in for regression testing. Using this
60 option is equivalent to issuing:
61 set basename on
63 inside the debugger.
65 -n | nx
69 Normally the debugger will read debugger commands in
70 "~/.bashdbinit" if that file exists before accepting user
71 interaction. ".bashdbinit" is analogus to Perl's ".perldb" or GNU
72 gdb's ".gdbinit": a user might want to create such a debugger
73 profile to add various user-specific customizations.
74 Using the "-n" option this initialization file will not be read.
76 This is useful in regression testing or in tracking down a problem
77 with one's ".bashdbinit" profile.
78 -c command-string
82 Instead of specifying the name of a script file, one can give an
83 execution string that is to be debugged. Use this option to do
84 that.
85 If you invoke the debugger via "bash --debugger", the filename that
87 will appear in source listing or in a call stack trace will be the
88 artifical name *BOGUS*.
89 -q | --quiet
93 Do not print introductory version and copyright information. This
94 is again useful in regression testing where we don't want to
95 include a changeable copyright date in the regression-test
96 matching.
97 -x debugger-cmdfile
101 Run the debugger commands debugger-cmdfile before accepting user
102 input. These commands are read however after any ".bashdbinit"
103 commands. Again this is useful running regression-testing debug
104 scripts.
105 -L | --library debugger-library
109 The debugger needs to source or include a number of functions and
110 these reside in a library. If this option is not given the default
111 location of library is relative to the installed bashdb script:
112 "../lib/bashdb".
113 -T | --tempdir temporary-file-directory
117 The debugger needs to make use of some temporary filesystem storage
118 to save persistent information across a subshell return or in order
119 to evaluate an expression. The default directory is "/tmp" but you
120 can use this option to set the directory where debugger temporary
121 files will be created.
122 -t | --tty tty-name
126 Debugger output usually goes to a terminal rather than stdout or
127 stdin which the debugged program may use. Determination of the tty
128 or pseudo-tty is normally done automatically. However if you want
129 to control where the debugger output goes, use this option.
130 -V | --version
134 Show version number and no-warranty and exit with return code 1.
135 -X | --trace
137 Similar to ""set -x"" line tracing except that by default the
138 location of each line, the bash level, and subshell level are
139 printed. You might be able to get something roughly similar if you
140 set "PS4" as follows
141 export PS4='(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]}\n'
143 In contrast however to ""set -x"" tracing, indentation of the
145 original program is also preserved in the source output. And if you
146 interrupt the program with a break (a "SIGINT" signal), you will go
147 into the debugger (assuming your program doesn't trap "SIGINT").
148
152 The "bashdb" script and "--debugger" option assume a version of bash
153 with debugging support. That is you can't debug bash scripts using the
154 standard-issue version 2.05b bash or earlier versions. In versions
155 after 3.0, debugging should have been enabled when bash was built. (I
156 think this is usually the case though.) If you try to run the bashdb
157 script on such as shell, may get the message:
158 Sorry, you need to use a debugger-enabled version of bash.
160 Debugging startup time can be slow especially on large bash scripts.
162 Scripts created by GNU autoconf are at thousands of lines line and it
163 is not uncommon for them to be tens of thousands of lines.
164 There is a provision to address this problem by including a fast file-
166 to-array read routine (readarray), but the bashdb package has to be
167 compiled in a special way which needs access to the bash source code
168 and objects.
169 Another reason of the debugger slowness is that the debugger has to
171 intercept every line and check to see if some action is to be taken for
172 this and this is all in bash code. A better and faster architecture
173 would be for the debugger to register a list of conditions or stopping
174 places inside the bash code itself and have it arrange to call the
175 debugger only when a condition requiring the debugger arises. Checks
176 would be faster as this would be done in C code and access to internal
177 structures would make this more efficient.
178
180 · <http://bashdb.sourceforge.net/bashdb.html> - an extensive
181 reference manual.
182 · <http://bashdb.sourceforge.net> - the homepage for the project
184 · <http://www.gnu.org/software/bash/manual/bashref.html> - bash
186 reference manual
187
189 The current version is maintained (or not) by Rocky Bernstein.
190
192 Copyright (C) 2003, 2006, 2007 Rocky Bernstein
193 This program is free software; you can redistribute it and/or modify
194 it under the terms of the GNU General Public License as published by
195 the Free Software Foundation; either version 2 of the License, or
196 (at your option) any later version.
197 This program is distributed in the hope that it will be useful,
199 but WITHOUT ANY WARRANTY; without even the implied warranty of
200 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
201 GNU General Public License for more details.
202 You should have received a copy of the GNU General Public License
204 along with this program; if not, write to the Free Software
205 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
206 $Id: bashdb-man.pod,v 1.10 2009/06/22 22:41:10 rockyb Exp $
2084.0-0.4 2010-06-24 bashdb(1)