DEBUG.SH(8)             FreeBSD System Manager's Manual            DEBUG.SH(8)

NAME

     debug.sh - selectively debug scripts

SYNOPSIS

     $_DEBUG_SH . debug.sh

     DebugOn [-eo] tag ...
     DebugOff [-eo] [rc=rc] tag ...
     Debugging
     DebugAdd tag
     DebugEcho [message]
     DebugLog [message]
     DebugShell tag ...
     DebugTrace message
     Debug tag ...

DESCRIPTION

     debug.sh provides the following functions to facilitate flexible run-time
     tracing of complicated shell scripts.

     DebugOn [-eo] tag ...
           turns tracing on if any tag is found in DEBUG_SH (a comma separated
           list of tags).

           It turns tracing off if !tag is found in DEBUG_SH.

           It sets DEBUG_ON to the tag that caused tracing to be enabled, or
           DEBUG_OFF if we matched !tag.

           If -e option is present, returns 1 if no tag matched.

           If -o option is present, tracing is turned off unless there was a
           matched tag, useful for functions too noisy to tace.

     DebugOff [-eo] [rc=rc] tag ...
           turns tracing on if any tag matches DEBUG_OFF or off if any tag
           matches DEBUG_ON.  This allows nested functions to not interfere
           with each other.

           The flags -e and -o are ignored, they just allow for symmetry with
           calls to DebugOn().

           The optional rc value will be returned rather than the default of
           0.  Thus if DebugOff() is the last operation in a function, rc will
           be the return code of the function.

     Debugging
           returns true if tracing is enabled.  It is useful for bounding
           complex debug actions, rather than using lots of $DEBUG_DO lines.

     DebugAdd tag
           Add tag to DEBUG_SH to influence later output, possibly in a child
           process.

     DebugEcho
           is just shorthand for:

                 $DEBUG_DO echo "$@"

     DebugLog [message]
           If debugging is enabled, output message prefixed with a time-stamp.

     DebugShell tag ...
           runs an interactive shell if any tag is found in DEBUG_INTERACTIVE,
           and there is a tty available.  The shell used is defined by
           DEBUG_SHELL or SHELL and defaults to /bin/sh.

     DebugTrace message
           Debug output can be very noisy, and it can be tricky to align with
           the script.  This function outputs a very noticeable banner
           indicating the value of DEBUG_ON, and message is passed to
           DebugLog(), finally the banner is repeated.

     Debug tag ...
           For backwards compatibility, calls DebugOn() and if that does not
           turn tracing on, it calls DebugOff() to turn it off.

     The variables DEBUG_SKIP and DEBUG_DO are set so as to enable/disable
     code that should be skipped/run when debugging is turned on.  DEBUGGING
     is the same as DEBUG_SKIP for backwards compatibility and is only set by
     Debug().

     The use of $_DEBUG_SH is to prevent multiple inclusion, though it does no
     harm in this case.

BUGS

     Does not work with some versions of ksh(1).  If a function turns tracing
     on, ksh turns it off when the function returns - useless.

     PD ksh works ok ;-)

AUTHOR

     debug.sh was written by Simon J Gerraty <sjg@crufty.net>.

FreeBSD 15.1-STABLE-HBSD       October 22, 2024                    DEBUG.SH(8)