Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
bashdb(1)			   GNU Tools			     bashdb(1)

NAME
       bashdb -	bash debugger script

SYNOPSIS
       bashdb [options]	script-name [--] [script options]

       bashdb [options]	-c execution-string

       bash --debugger [bash-options...] script-name [[--] script options]

DESCRIPTION
       "bashdb"	is a bash script to which arranges for another bash script to
       be debugged.  The debugger has a	similar	command	interface as gdb(1).

       The way this script arranges debugging to occur is by including (or
       actually	"source"-ing) some debug-support code and then sourcing	the
       given script or command string.

       One problem with	sourcing a debugged script is that the program name
       stored in $0 will be "bashdb" rather than the name of the script	to be
       debugged. The debugged script will appear in a call stack not as	the
       top item	but as the item	below "bashdb".	If this	is of concern, use the
       last form given above, "bash --debugger"	script-name [script-options].

       If you used bashdb script and need to pass options to the script	to be
       debugged, add "--" after	the script name. That will tell	bashdb not to
       try to process any further options.

       See the reference manual	<http://bashdb.sourceforge.net/bashdb.html>
       for how to to call the debugger from inside your	program	or arrange for
       the debugger to get called when your program is sent a signal.

OPTIONS
       -h | --help
	   Print a usage message on standard error and exit with a return code
	   of 100.

       -A | --annotation level
	   Sets	to output additional stack and status information which	allows
	   front-ends such as emacs to track what's going on without polling.

	   This	is needed in for regression testing. Using this	option is
	   equivalent to issuing:

	     set annotation LEVEL

	   inside the debugger.

       -B | --basename
	   In places where a filename appears in debugger output give just the
	   basename only. This is needed in for	regression testing. Using this
	   option is equivalent	to issuing:

	     set basename on

	   inside the debugger.

       -n | nx
	   Normally the	debugger will read debugger commands in
	   "~/.bashdbinit" if that file	exists before accepting	user
	   interaction.	 ".bashdbinit" is analogus to Perl's ".perldb" or GNU
	   gdb's ".gdbinit": a user might want to create such a	debugger
	   profile to add various user-specific	customizations.

	   Using the "-n" option this initialization file will not be read.
	   This	is useful in regression	testing	or in tracking down a problem
	   with	one's ".bashdbinit" profile.

       -c command-string
	   Instead of specifying the name of a script file, one	can give an
	   execution string that is to be debugged. Use	this option to do
	   that.

	   If you invoke the debugger via "bash	--debugger", the filename that
	   will	appear in source listing or in a call stack trace will be the
	   artificial name *BOGUS*.

       -q | --quiet
	   Do not print	introductory version and copyright information.	This
	   is again useful in regression testing where we don't	want to
	   include a changeable	copyright date in the regression-test
	   matching.

       -x debugger-cmdfile
	   Run the debugger commands debugger-cmdfile before accepting user
	   input.  These commands are read however after any ".bashdbinit"
	   commands. Again this	is useful running regression-testing debug
	   scripts.

       -L | --library debugger-library
	   The debugger	needs to source	or include a number of functions and
	   these reside	in a library. If this option is	not given the default
	   location of library is relative to the installed bashdb script:
	   "../lib/bashdb".

       -T | --tempdir temporary-file-directory
	   The debugger	needs to make use of some temporary filesystem storage
	   to save persistent information across a subshell return or in order
	   to evaluate an expression. The default directory is "/tmp" but you
	   can use this	option to set the directory where debugger temporary
	   files will be created.

       -t | --tty tty-name
	   Debugger output usually goes	to a terminal rather than STDOUT which
	   the debugged	program	may use. Determination of the tty or pseudo-
	   tty is normally done	automatically. However if you want to control
	   where the debugger output goes, use this option.

	   If you want output to go to STDOUT use &1. Note: the	'&' may	have
	   to be escaped or quoted to avoid shell interpretation with forking.

       -V | --version
	   Show	version	number and no-warranty and exit	with return code 1.

       -X | --trace
	   Similar to ""set -x"" line tracing except that by default the
	   location of each line, the bash level, and subshell level are
	   printed. You	might be able to get something roughly similar if you
	   set "PS4" as	follows

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

	   In contrast however to ""set	-x"" tracing, indentation of the
	   original program is also preserved in the source output. And	if you
	   interrupt the program with a	break (a "SIGINT" signal), you will go
	   into	the debugger (assuming your program doesn't trap "SIGINT").

BUGS
       The "bashdb" script and "--debugger" option assume a version of bash
       with debugging support. That is you can't debug bash scripts using the
       standard-issue version 2.05b bash or earlier versions. In versions
       after 3.0, debugging should have	been enabled when bash was built. (I
       think this is usually the case though.) If you try to run the bashdb
       script on such as shell,	may get	the message:

	 Sorry,	you need to use	a debugger-enabled version of bash.

       Debugging startup time can be slow especially on	large bash scripts.
       Scripts created by GNU autoconf are at thousands	of lines line and it
       is not uncommon for them	to be tens of thousands	of lines.

       There is	a provision to address this problem by including a fast	file-
       to-array	read routine (readarray), but the bashdb package has to	be
       compiled	in a special way which needs access to the bash	source code
       and objects.

       Another reason of the debugger slowness is that the debugger has	to
       intercept every line and	check to see if	some action is to be taken for
       this and	this is	all in bash code. A better and faster architecture
       would be	for the	debugger to register a list of conditions or stopping
       places inside the bash code itself and have it arrange to call the
       debugger	only when a condition requiring	the debugger arises. Checks
       would be	faster as this would be	done in	C code and access to internal
       structures would	make this more efficient.

SEE ALSO
       o   <http://bashdb.sourceforge.net/bashdb.html> - an extensive
	   reference manual.

       o   <http://bashdb.sourceforge.net> - the homepage for the project

       o   <http://www.gnu.org/software/bash/manual/bashref.html> - bash
	   reference manual

AUTHOR
       The current version is maintained (or not) by Rocky Bernstein.

COPYRIGHT
	 Copyright (C) 2003, 2006-2007,	2016 Rocky Bernstein
	 This program is free software;	you can	redistribute it	and/or modify
	 it under the terms of the GNU General Public License as published by
	 the Free Software Foundation; either version 2	of the License,	or
	 (at your option) any later version.

	 This program is distributed in	the hope that it will be useful,
	 but WITHOUT ANY WARRANTY; without even	the implied warranty of
	 MERCHANTABILITY or FITNESS FOR	A PARTICULAR PURPOSE.  See the
	 GNU General Public License for	more details.

	 You should have received a copy of the	GNU General Public License
	 along with this program; if not, write	to the Free Software
	 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

       $Id: bashdb-man.pod 2016/08/13 16:30:00 rockyb Exp $

4.4-0.94			  2017-04-30			     bashdb(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | BUGS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bashdb&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help