Lesson 9. Functions, local, and Return Status vs Output

Mission link: This is stage 7's capstone. Lesson 8 gave the shell a vocabulary for holding and branching on values; this lesson is how a script organizes repeated work into a function, and the single sharpest surprise waiting there for anyone coming from another language: a shell function's return is an exit status, not a value.
Primary source: Docs: "Bash Reference Manual", GNU
Prerequisites: Lesson 8, Word splitting

Warm-up

1. ▢ count=$(grep -c "ERROR" logfile.txt). What does count hold afterward, and what would a script need to check separately to know whether grep itself succeeded?

2. ▢ Why does while read -r line; do ... done < file avoid the word-splitting problem a for f in $(cat file) loop would have on a file whose lines contain spaces?

Know this

Defining a function: a name, a body, and arguments exactly like a script's own

name() { commands; } defines a function (the POSIX-portable form; bash also accepts function name { ... }, a bash-only alternative worth calling out per lesson 5's discipline rather than mixing the two). Calling it, name arg1 arg2, hands the function its own $1, $2, $@, and $#, exactly the same positional-parameter mechanism a script gets from its own command-line arguments; a function is, from the inside, a mini-script that happens to run in the calling shell's process rather than a new one.

local: without it, every variable a function touches is global

Assign a variable inside a function with a plain name=value, and it is global by default: it persists after the function returns and can silently clobber a variable of the same name the caller was already using. local name=value scopes the assignment to the current function call; the variable reverts to whatever it was (or disappears entirely) once the function returns. This is the single most common shell-function surprise for anyone used to a language where a function's local variables are local by default: count=0 inside process_file() is not a local counter, it is count in whatever scope called process_file, silently overwritten. local is not part of POSIX sh (dash and other portable shells commonly support it as a widely-adopted extension, but the POSIX specification itself does not define it), so a strictly portable script either accepts the extension explicitly, the same way lesson 5 treats arrays and [[ ]], or works around it by using distinctly-named variables instead.

Return status vs output: the surprise this lesson is named for

return N sets the function's own exit status to N (0-255), checked by the caller exactly the way any command's exit status is checked, via $? or directly in an if. It does not hand a value back to the caller the way return does in most other languages; return "some string" either errors or gets silently coerced into a number, never the string itself. To get an actual value out of a function, the function prints it to standard output, and the caller captures that output with lesson 8's command substitution: result=$(compute_thing "$input"). A function can do both at once, printing its answer and separately returning a real status, 0 for success or a specific nonzero code for a specific failure the caller might want to branch on: if result=$(compute_thing "$input"); then use "$result"; else handle_failure; fi.

Practice

1. ▢ A function parse_config() does count=0 (no local) inside a loop, incrementing it as it parses. The calling script also happens to use a variable named count for an unrelated purpose, before and after calling parse_config. What breaks?

2. ▢ A function is written as add() { return $(($1 + $2)); }, intended to add two numbers and hand back the sum. Called as sum=$(add 3 4), what does sum actually hold, and why doesn't this work the way it looks like it should?

3. ▢ Why is local worth flagging explicitly in a script meant to be POSIX sh-portable, the same way lesson 5 flags bash arrays and [[ ]]?

4. ▢ Write, in words, a function to_upper() that both prints its input converted to uppercase and returns a nonzero status if no argument was given at all.

5. ▢ Which claim correctly describes what a shell function's return does?

   • a) return hands a value of any type back to the caller, the same way return works in Python or JavaScript
   • b) return N sets the function's exit status to N (checked via $? or if); a value has to be printed to stdout and captured separately via command substitution
   • c) A function cannot both print output and return a meaningful status in the same call
   • d) local is part of the POSIX sh specification and behaves identically across every shell without exception

Real-world reps

• [ ] Find a function in a script you have access to that assigns a variable without local. Check whether that variable's name could plausibly collide with something the caller uses, and add local if it's missing.
• [ ] Find (or write) a function meant to compute and hand back a value. Confirm it does so by printing to stdout and being called via command substitution, not via return.
• [ ] Tomorrow: read the primary source's section on shell functions in full, and note what it says about a function's exit status when no explicit return is given at all.

Going further

• Docs: "Bash Reference Manual", GNU
• Docs: "Shell Command Language", POSIX.1-2017, The Open Group
• Resources

Not landing? Reread the primary source at the top, since this lesson compresses it and compression is where understanding leaks. Check the glossary for any term that felt slippery.

If the lesson itself is unclear rather than the material, that is a defect: open an issue.