+++ /dev/null
-#!/bin/bash
-# Copyright (C) 2019 Ian Kelling
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-# Commentary: Print stack trace and exit/return on errors, or use
-# functions below for for more details and manual error handling. See
-# end of file for credits etc.
-
-#######################################
-# err-catch: Setup trap on ERR to print stack trace and exit (or return
-# if the shell is interactive). This is the most common use case so we
-# run it after defining it, you can call err-allow to undo that.
-#
-# This also sets pipefail because it's a good practice to catch more
-# errors.
-#
-# Note: In interactive shell, stack calling line number is not
-# available, so we print function definition lines.
-#
-# Globals
-#
-# err_catch_ignore Array containing glob patterns to test against
-# filenames to ignore errors from in interactive
-# shell. Initialized to ignore bash-completion
-# scripts on debian based systems.
-#
-# err-cleanup If set, this command will run just before exiting.
-#
-# _err_func_last Used internally in err-bash-trace-interactive
-#
-#######################################
-err-catch() {
- set -E;
- if [[ $- == *i* ]]; then
- if ! test ${err_catch_ignore+defined}; then
- err_catch_ignore=(
- '/etc/bash_completion.d/*'
- '*/bash-completion/*'
- )
- fi
- declare -i _err_func_last=0
- shopt -s extdebug
- # shellcheck disable=SC2154
- trap '_err-bash-trace-interactive $? "$BASH_COMMAND" ${BASH_ARGC[0]} "${BASH_ARGV[@]}" || return $?' ERR
- else
- # Man bash on exdebug: "If set at shell invocation, arrange to
- # execute the debugger". We want to avoid that, but I want this file
- # to be sourceable from bash startup files. noninteractive ssh and
- # sources .bashrc on invocation. login_shell sources things on
- # invocation.
- #
- # extdebug allows us to print function arguments in our stack trace.
- if ! shopt login_shell >/dev/null && [[ ! $SSH_CONNECTION ]]; then
- shopt -s extdebug
- fi
- trap err-exit ERR
- fi
- set -o pipefail
-}
-# This is the most common use case so run it now.
-err-catch
-
-#######################################
-# Undo err-catch/err-catch-interactive
-#######################################
-err-allow() {
- shopt -u extdebug
- set +E +o pipefail
- trap ERR
-}
-
-#######################################
-# err-exit: Print stack trace and exit
-#
-# Use this instead of the exit command to be more informative.
-#
-# usage: err-exit [-EXIT_CODE] [MESSAGE]
-#
-# EXIT_CODE Default: $? if it is nonzero, otherwise 1.
-# MESSAGE Print MESSAGE to stderr. Default:
-# ${BASH_SOURCE[1]}:${BASH_LINENO[0]}: `$BASH_COMMAND' returned $?
-#
-# Globals
-#
-# err-cleanup If set, this command will run just before exiting.
-#
-#######################################
-err-exit() {
- local err=$?
- # This has to come before most things or vars get changed
- local msg="${BASH_SOURCE[1]}:${BASH_LINENO[0]}: \`$BASH_COMMAND' returned $err"
- set +x
- if [[ $1 == -* ]]; then
- err=${1#-}
- shift
- elif (( ! err )); then
- err=1
- fi
- if [[ $1 ]]; then
- msg="$1"
- fi
- printf "%s\n" "$msg" >&2
- err-bash-trace 2
- set -e # err trap does not work within an error trap
- if type -t err-cleanup >/dev/null; then
- err-cleanup
- fi
- printf "%s: exiting with status %s\n" "$0" "$err" >&2
- exit $err
-}
-
-#######################################
-# Print stack trace
-#
-# usage: err-bash-trace [FRAME_START]
-#
-# This function is called by the other functions which print stack
-# traces.
-#
-# It does not show function args unless you first run:
-# shopt -s extdebug
-# which err-catch does for you.
-#
-# FRAME_START Optional variable to set before calling. The frame to
-# start printing on. default=1. If ${#FUNCNAME[@]} <=
-# FRAME_START + 1, don't print anything because we are at
-# the top level of the script and better off printing a
-# general message, for example see what our callers print.
-#
-#######################################
-err-bash-trace() {
- local -i argc_index=0 frame i frame_start=${1:-1}
- local source_loc
- if (( ${#FUNCNAME[@]} <= frame_start + 1 )); then
- return 0
- fi
- for ((frame=0; frame < ${#FUNCNAME[@]}; frame++)); do
- argc=${BASH_ARGC[frame]}
- argc_index+=$argc
- if ((frame < frame_start)); then continue; fi
- if (( ${#BASH_SOURCE[@]} > 1 )); then
- source_loc="${BASH_SOURCE[frame]}:${BASH_LINENO[frame-1]}:"
- fi
- printf " from %sin \`%s" "$source_loc" "${FUNCNAME[frame]}" >&2
- if shopt extdebug >/dev/null; then
- for ((i=argc_index-1; i >= argc_index-argc; i--)); do
- printf " %s" "${BASH_ARGV[i]}" >&2
- done
- fi
- echo \' >&2
- done
- return 0
-}
-
-#######################################
-# Internal function for err-catch. Prints stack trace from interactive
-# shell trap.
-#
-# Usage: see err-catch-interactive
-#######################################
-_err-bash-trace-interactive() {
- if (( ${#FUNCNAME[@]} <= 1 )); then
- return 0
- fi
-
- for pattern in "${err_catch_ignore[@]}"; do
- # shellcheck disable=SC2053
- if [[ ${BASH_SOURCE[1]} == $pattern ]]; then
- return 0
- fi
- done
-
- local ret bash_command argc pattern i last
- last=$_err_func_last
- _err_func_last=${#FUNCNAME[@]}
- # We have these passed to us because they are lost inside the
- # function.
- ret=$1
- bash_command="$2"
- argc=$(( $3 - 1 ))
- shift 3
- argv=("$@")
- # The trap returns a nonzero, then gets called again. This condition
- # tells us if we are the first.
- if (( _err_func_last > last )); then
- printf "ERR: \`%s\' returned %s\n" "$bash_command" $ret >&2
- fi
- printf " from \`%s" "${FUNCNAME[1]}" >&2
- if shopt extdebug >/dev/null; then
- for ((i=argc; i >= 0; i--)); do
- printf " %s" "${argv[i]}" >&2
- done
- fi
- printf "\' defined at %s:%s\n" "${BASH_SOURCE[1]}" "$(declare -F "${FUNCNAME[1]}"|awk "{print \$2}")" >&2
- if [[ -t 1 ]]; then
- return $ret
- else
- # Part of an outgoing pipe, avoid getting get us stuck in a weird
- # subshell if we returned nonzero, which would happen in a situation
- # like this:
- #
- # tf() { while read -r line; do :; done < <(asdf); };
- # tf
- #
- # Note: exit $ret also avoids the stuck subshell problem, and I
- # can't notice any difference, but this seems more proper.
- return 0
- fi
-}
-
-# Credits etc:
-#
-# Related: see my bash script template repo at https://iankelling.org/git.
-#
-#
-# Please email me if you have a patches, bugs, feedback, or if you use
-# it or republish it since I'm not aware of any users yet
-# Ian Kelling <ian@iankelling.org>.
-#
-# Tested on bash 4.4.20(1)-release (x86_64-pc-linux-gnu). If you test