Designing Functions with Local Scope and Return Codes

In Bash, variables are global by default. A variable set inside a function leaks out into the caller's scope unless you explicitly declare it local. This is a common source of subtle bugs in shell scripts.

• Functions without local can silently overwrite caller variables.
• local variables are destroyed when the function returns.
• Clean scope boundaries make functions reusable and testable in isolation.

This lesson teaches you to write functions that are self-contained: they use local variables, communicate results through exit codes and printf, and never rely on implicit global state.

Here is a concrete example of a global variable leak. The function set_name sets a variable called result, which quietly overwrites the caller's own result variable.

Run this script and observe the unexpected output — the caller's result is gone after the function call.

The local built-in restricts a variable's scope to the enclosing function and any functions it calls. Outside the function, the variable is either unset or retains its previous value.

• local varname — declares without assigning.
• local varname="value" — declares and assigns in one step.
• local -i count=0 — declares an integer-typed local variable.
• local -r PI=3.14159 — declares a read-only local constant.

Best practice: declare every variable inside a function as local unless you intentionally need it to be global.

Bash functions cannot return strings — return only sets an integer exit status (0–255). By convention:

• return 0 — success
• return 1 (or any non-zero) — failure

The caller reads the exit status via $? immediately after the call, or uses the function directly in an if condition. Exit codes are the idiomatic way to signal success or failure from a function.

When a function needs to return a string result, the standard pattern is to print to stdout and capture it with command substitution $(). Using printf instead of echo is preferred because:

• printf does not append a trailing newline by default (unless you include \n).
• printf behaviour is consistent and POSIX-defined; echo varies across shells.
• Command substitution strips trailing newlines, so printf '%s' "$value" is precise.

A well-designed function can both print a result (on success) and signal failure (via exit code) at the same time. The caller decides what to do based on the exit code before trusting the output.

The pattern below is used extensively in real Bash libraries:

• On success: printf the result and return 0.
• On failure: write a diagnostic to stderr (not stdout) and return 1.
• Writing errors to stderr keeps stdout clean for piping.

Recursion is one of the clearest demonstrations of why local is essential. Each recursive call gets its own independent copy of every local variable on the call stack. Without local, each call would overwrite the same global variable and produce wrong results.

The factorial function below is safe because n and sub are local to each stack frame.

Command substitution $() runs in a subshell. Any variable assignments inside it are invisible to the parent shell. When you need a function to write into a caller-provided variable without a subshell, use a nameref (local -n), available in Bash 4.3+.

• local -n ref="$1" makes ref an alias for the variable whose name is stored in $1.
• Assigning to ref inside the function changes the caller's variable directly.
• This avoids a subshell while still keeping the implementation details local.

Real-world Bash projects split reusable functions into library files that are sourced by scripts with source (or the dot operator .). Good library design rules:

• Every variable inside a library function must be local.
• Library functions never exit — they return, so the caller stays alive.
• Use a consistent namespace prefix (e.g., str_, log_) to avoid name collisions.
• Guard against double-sourcing with a sentinel variable.

Below is a minimal string utility library following these conventions.

Functions that receive arguments should validate them early and return a specific exit code on bad input. This is called a guard clause pattern — fail fast, fail clearly.

• Check argument count with $#.
• Validate types or formats before doing any work.
• Print diagnostic messages to stderr only, never to stdout.
• Use distinct non-zero return codes (e.g., 1 = wrong args, 2 = file not found) so callers can react differently to different failure modes.

Here is a complete, self-contained script that demonstrates all the concepts from this lesson working together:

• local variables in every function.
• Exit codes to signal success/failure.
• printf to communicate string results.
• Errors written to stderr, results to stdout.
• Guard clauses for argument validation.

Study the flow: parse_version extracts data, version_ge compares it, and main uses both cleanly.

Consider the following Bash function. What is the correct way to capture its string result in the caller, and which statement about the variable tmp is true?

transform() {
    local tmp="${1,,}"   # lowercase
    printf '%s' "$tmp"
    return 0
}

In this lesson you learned how to write Bash functions that are clean, composable, and safe:

• Always use local for variables inside functions to prevent polluting the caller's scope.
• Use exit codes (return 0/1/N) to signal success or failure — they integrate naturally with if, &&, and ||.
• Use printf to stdout to communicate string results; capture them with $() in the caller.
• Write errors to stderr (>&2) so stdout stays clean for data flow and piping.
• Use local -n (nameref) when you need to write into a caller-provided variable without the overhead of a subshell.
• Guard clauses (validate arguments early, return immediately on bad input) make functions robust and self-documenting.
• Library files should be sourced, use namespace prefixes, never call exit, and guard against double-sourcing.

Mastering these patterns is the difference between fragile one-off scripts and professional, maintainable Bash codebases.