> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bash RETURN Trap
The `RETURN` trap in Bash is an event-driven mechanism that executes a specified command list whenever a shell function or a sourced script terminates. It is triggered either by an explicit `return` statement or by the implicit completion of the execution flow (reaching the end of the function or script block).
## Syntax
```bash theme={"dark"}
# Define a RETURN trap
trap 'command_list' RETURN
# Unset a RETURN trap
trap - RETURN
```
## Execution Mechanics
* **Trigger Timing:** The trap executes immediately after the function or sourced script finishes, but strictly *before* control is handed back to the calling environment.
* **Exit Status (`$?`):** The exit status evaluated immediately prior to the trap's execution is the exit status of the returning function or script. The commands executed within the trap do not alter the final return value of the function unless the trap explicitly executes a new `return` command.
* **Sourced Scripts vs. Subprocesses:** The trap fires when a script is executed via the `source` or `.` builtins. It does *not* trigger when a script is executed as a standard child process (e.g., `./script.sh`), as that constitutes an `EXIT` condition, not a `RETURN`.
## Scope and Inheritance (`functrace`)
By default, the `RETURN` trap (along with the `DEBUG` trap) is not inherited by shell functions, command substitutions, or subshell environments. A `RETURN` trap defined in the global scope will not automatically trigger when a child function returns.
To propagate the `RETURN` trap to these environments, the `functrace` attribute must be enabled using the `set` builtin:
```bash theme={"dark"}
# Enable RETURN/DEBUG trap inheritance
set -T
# Alternatively: set -o functrace
# Disable RETURN/DEBUG trap inheritance
set +T
# Alternatively: set +o functrace
```
When `functrace` is enabled, any invoked function will inherit the `RETURN` trap from its calling environment, causing the trap to fire upon the termination of every function in the execution tree.
## Contextual Variables
When a `RETURN` trap is triggered, Bash preserves the execution context of the returning entity. The following internal arrays remain accessible and reflect the state of the function or script that just returned:
* `FUNCNAME`: Contains the execution call stack. `${FUNCNAME[0]}` holds the name of the function that triggered the trap.
* `BASH_SOURCE`: Contains the source filenames corresponding to the `FUNCNAME` stack.
* `BASH_LINENO`: Contains the line numbers in the source files where each function in the stack was invoked.
Tired of Poor Bash Skills? Fix That With Deep Grasping!
Learn More
