---
name: "zshdb"
section: "1"
platform: "linux"
package: "zshdb"
version: "1.1.4-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/zshdb"
---

# zshdb(1)

zsh debugger

## NAME

zshdb - zsh debugger

## SYNOPSIS

**zshdb** \[*options*\] \[--\] *script-name* \[*script options*\]

**zshdb** \[*options*\] -c *execution-string*

## DESCRIPTION

`"zshdb"` is a zsh script to which arranges for another zsh script to be debugged. The debugger has a similar command interface as `gdb(1)`.

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

## 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 \| --no-init

  Normally the debugger will read debugger commands in `"~/.zshdbinit"` if that file exists before accepting user interaction. `".zshdbinit"` 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 `".zshdbinit"` profile.

- \-c \| --command *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.

- \-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 \| --eval-command *debugger-cmdfile*

  Run the debugger commands *debugger-cmdfile* before accepting user input.  These commands are read however after any `".zshdbinit"` 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 zshdb script: `"../lib/zshdb"`.

- \-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 or stdin 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.

- \-V \| --version

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

## BUGS

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 not be 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 `"zshdb"`.

The `"zshdb"` script option assume a version of zsh with debugging support, zsh 4.3.6-dev-2 or later.

The debugger slows things down a little because the debugger has to intercept every statement and check to see if some action is to be taken.

## SEE ALSO

- •

  \<http://bashdb.sourceforge.net/bashdb.html\> - Until a full manual is written, this manual for a similar bash debugger may give some guidance. The two debuggers have similar command interfaces (and code).

- •

  \<http://bashdb.sourceforge.net\> - the homepage for the project for the family of debugger, zshdb, bashdb.

## AUTHOR

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

## COPYRIGHT

```
  Copyright (C) 2009 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
```