return

Exit a function prematurely

$ [func_name]() { [echo "This is reached"]; return; [echo "This is not"]; }

$ [func_name]() { return [exit_code]; }

return [n]

n
    An integer between 0 and 255, representing the exit status of the function. By convention, 0 signifies success, while any non-zero value indicates an error or a specific condition. If omitted, the return status is the exit status of the last command executed within the function.

The return command is a shell built-in used exclusively within shell functions to terminate their execution and return control to the calling script or function. It allows a function to signal its success or failure by providing an optional integer argument, which serves as the function's exit status.

When return is called with an argument n, that value becomes the function's exit status, which can be retrieved by the caller using the special shell variable $?. If n is omitted, the function's exit status will be that of the last command executed within the function.

It's important to note that if return is invoked outside the context of a shell function (i.e., directly in a script or interactive shell), it behaves identically to the exit command, terminating the current shell or script entirely.

Shell Built-in: It is a shell built-in command, not an external executable. Its behavior is consistent across most POSIX-compliant shells (e.g., Bash, Zsh, Dash), but specific shell versions might have minor nuances.

Function Context: The return command is primarily designed for use inside shell functions. If executed directly in a script or interactive shell (i.e., outside a function), it behaves identically to the exit command, terminating the current shell process.

Exit Status, Not Value: Unlike some programming languages, return in shell scripting returns an exit status (an integer), not a complex data value or object. To return data, one typically echoes it to standard output and captures it using command substitution (`$(...)`).

Scope: While return exits a function, it does not automatically stop the entire script unless it was called from the main script body (acting as exit).

The exit status returned by a function (either explicitly via return or implicitly) can be captured using the special shell variable $? immediately after the function call.
my_function() {
echo "Hello from function";
return 10;
}

my_function
status=$?
echo "Function exited with status: $status"
This will output:
Hello from function
Function exited with status: 10

If a function completes its execution without an explicit return command, its exit status will be the exit status of the last command executed within that function. This is a common and often utilized feature in shell scripting.
another_function() {
ls /non_existent_path # This command will fail
}

another_function
echo "Function exited with status: $?"
This will typically output:
ls: cannot access '/non_existent_path': No such file or directory
Function exited with status: 2 (assuming 2 is ls's exit code for 'no such file')

The concept of functions and the ability to explicitly return from them with an exit status became standardized in Unix shells with the evolution towards POSIX compliance. While early shells like the Bourne Shell had limited function support, shells like KornShell (ksh) and later Bash significantly enhanced function capabilities, making return a fundamental part of structured shell scripting. It provides a standardized way for functions to communicate their outcome to the caller, similar to how commands communicate their status to the shell.

exit(1), bash(1), sh(1), local(1), declare(1)