---
name: "debug.sh"
section: "8"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/debug.sh"
---

# debug.sh(8)

selectively debug scripts

## 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.

## FILES

- */libexec/debug.sh*

  Source code of the debugging facilities.

## BUGS

Does not work with some versions of [ksh(1)](/ksh/1.md). 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*⟩.