Day 4: Functions and a Library
Goal: Write functions, return results via exit code and output, protect variables with
local, build a shared librarylib.shfor the toolbox and examine scripts withbash -x. · Duration: approx. 75 min · Prerequisite: Day 3
Briefing
- A function is a mini script inside your script: its
own arguments (
$1,$@), its own exit code (return). It returns results via its output, which the caller captures with$(…). - Without
local, variables in functions are global – a common bug that is hard to find. - Whatever several scripts need goes into a library
that every script loads with
source: logging, aborting with a message, checking for required programs. bash -xshows every line before it runs – the most important debugging tool.
bin/notes-ping ─┐
bin/notes-add ─┼─ source ─► lib/lib.sh: log · info · warn · die · need · notes_url
bin/notes-last ─┘
Drill 1: Functions
source ~/sh-lab/setup/env.sh
mkdir -p ~/sh-lab/tag04 && cd ~/sh-lab/tag04
cat > funktionen <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
ist_zahl() {
[[ $1 =~ ^[0-9]+$ ]]
}
verdoppeln() {
echo $(($1 * 2))
}
for x in 21 abc; do
if ist_zahl "$x"; then
echo "$x verdoppelt: $(verdoppeln "$x")"
else
echo "$x ist keine Zahl"
fi
done
EOF
bash funktionenExpected:
21 verdoppelt: 42
abc ist keine Zahl
ist_zahlprints nothing. Its result is the exit code of the last command – just like with a script. That is why it works directly afterif.verdoppelnreturns its result as output.return 42would not work: exit codes are only 0 to 255 and mean success or failure, not data.
Save your progress? Sign up for free
Drill 2: local
cat > global <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
zaehle_dateien() {
n=$(find "$1" -maxdepth 1 -type f | wc -l)
echo "$n"
}
n="Notiz Nr. 7"
echo "vorher: $n"
echo "Dateien: $(zaehle_dateien /etc/apt)"
zaehle_dateien /etc/apt >/dev/null
echo "nachher: $n"
EOF
bash globalExpected:
vorher: Notiz Nr. 7
Dateien: 1
nachher: 1
The first call in $(…) runs in a subshell and cannot
change n. The second runs directly – and overwrites
n. With local, that doesn’t happen:
sed -i 's/^ n=\$(find/ local n\n n=$(find/' global
sed -n '3,6p' global
bash globalExpected:
zaehle_dateien() {
local n
n=$(find "$1" -maxdepth 1 -type f | wc -l)
echo "$n"
vorher: Notiz Nr. 7
Dateien: 1
nachher: Notiz Nr. 7
local n is on a line of its own:
local n=$(…) would swallow the exit code of
find, because local itself always reports
success (ShellCheck SC2155).
Save your progress? Sign up for free
Drill 3: lib.sh
cat > ~/sh-lab/werkzeug/lib/lib.sh <<'EOF'
# lib.sh – shared functions for the toolbox. Load with: source …/lib.sh
# shellcheck shell=bash
[[ -n "${_LIB_SH:-}" ]] && return 0
_LIB_SH=1
PROG="${0##*/}"
log() { printf '%s %s: %s\n' "$(date +%H:%M:%S)" "$PROG" "$*" >&2; }
info() { log "INFO $*"; }
warn() { log "WARN $*"; }
die() {
log "FEHLER $1"
exit "${2:-1}"
}
# need prog… – aborts with exit code 3 if a program is missing
need() {
local p
for p in "$@"; do
command -v "$p" >/dev/null || die "Programm fehlt: $p" 3
done
}
notes_url() { printf '%s\n' "${NOTES_URL:-http://127.0.0.1:8080}"; }
EOF
shellcheck ~/sh-lab/werkzeug/lib/lib.sh && echo sauber
printf 'source-path=SCRIPTDIR\n' > ~/sh-lab/werkzeug/.shellcheckrcExpected:
sauber
- The library has no shebang and no
set -euo pipefail– it runs inside the script that loads it.# shellcheck shell=bashtells ShellCheck which language applies. - The guard
_LIB_SHprevents it from being loaded twice. - Messages go to stderr. That way stdout stays free for the actual result.
How does a script find the library, no matter where it is called from? Through its own path:
cat > ~/sh-lab/werkzeug/bin/notes-ping <<'EOF'
#!/usr/bin/env bash
# notes-ping – checks whether notes responds. Exit code 0 = ok
set -euo pipefail
source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/../lib/lib.sh"
need curl
url="$(notes_url)"
curl -fsS --max-time 3 "$url/healthz" >/dev/null 2>&1 || die "nicht erreichbar: $url"
echo "notes ok"
EOF
shellcheck -x ~/sh-lab/werkzeug/bin/notes-ping && echo sauber
cd / && notes-ping
NOTES_URL=http://127.0.0.1:9 notes-ping; echo "Exit: $?"Expected:
sauber
notes ok
12:20:14 notes-ping: FEHLER nicht erreichbar: http://127.0.0.1:9
Exit: 1
readlink -f resolves links, BASH_SOURCE[0]
is the path of the running file. shellcheck -x follows the
source and checks the library as well. ShellCheck cannot
work out the computed path; source-path=SCRIPTDIR in
.shellcheckrc tells it that ../lib/lib.sh is
meant relative to the script’s folder. ShellCheck looks for the file in
every parent folder of the script being checked.
Save your progress? Sign up for free
Drill 4: Debugging with bash -x
NOTES_URL=http://127.0.0.1:9 bash -x ~/sh-lab/werkzeug/bin/notes-ping 2>&1 \
| grep -v '^++* date' | head -12Expected (shortened):
+ set -euo pipefail
+++ readlink -f /home/ubuntu/sh-lab/werkzeug/bin/notes-ping
++ dirname /home/ubuntu/sh-lab/werkzeug/bin/notes-ping
+ source /home/ubuntu/sh-lab/werkzeug/bin/../lib/lib.sh
++ [[ -n '' ]]
++ _LIB_SH=1
++ PROG=notes-ping
+ need curl
+ local p
+ for p in "$@"
+ command -v curl
++ notes_url
Every line starts with +, one level deeper (subshell,
source) with ++. You see the values
after substitution – exactly what gets executed. In a
script, you turn tracing on with set -x and off again with
set +x.
Save your progress? Sign up for free
Drill 5: notes-add with lib.sh
cat > ~/sh-lab/werkzeug/bin/notes-add <<'EOF'
#!/usr/bin/env bash
# notes-add – creates a note: notes-add text of the note
set -euo pipefail
source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/../lib/lib.sh"
need curl
(($# > 0)) || die "Aufruf: $PROG Text der Notiz" 2
key="${NOTES_API_KEY:?fehlt – source ~/sh-lab/setup/env.sh}"
text="$*"
curl -fsS -X POST -H "X-API-Key: $key" -H 'Content-Type: application/json' \
-d "{\"text\":\"$text\"}" "$(notes_url)/notes"
echo
EOF
shellcheck -x ~/sh-lab/werkzeug/bin/notes-add && echo sauber
notes-add; echo "Exit: $?"
notes-add mit Bibliothek | grep -o '"text":"[^"]*"'Expected:
sauber
12:21:02 notes-add: FEHLER Aufruf: notes-add Text der Notiz
Exit: 2
"text":"mit Bibliothek"
Save your progress? Sign up for free
Checkpoint
grep -c '^source .*/lib/lib.sh"$' ~/sh-lab/werkzeug/bin/notes-ping \
~/sh-lab/werkzeug/bin/notes-addExpected:
/home/ubuntu/sh-lab/werkzeug/bin/notes-ping:1
/home/ubuntu/sh-lab/werkzeug/bin/notes-add:1
bash -c 'source ~/sh-lab/werkzeug/lib/lib.sh; need curl gibtsnicht'; echo "Exit: $?"Expected:
12:22:40 bash: FEHLER Programm fehlt: gibtsnicht
Exit: 3
shellcheck -x ~/sh-lab/werkzeug/bin/* && echo "alles sauber"Expected:
alles sauber
Challenge
Add retry count command… to lib.sh: it runs
the command until it succeeds, at most count times with a
one-second pause, reports every failed attempt with warn,
and ends with the exit code of the last attempt.
Note: "$@" after a shift
are exactly the words of the command.
Solution
cat >> ~/sh-lab/werkzeug/lib/lib.sh <<'EOF'
# retry count command… – repeats a command until it succeeds
retry() {
local max=$1 versuch=1 rc
shift
while true; do
rc=0
"$@" || rc=$?
((rc == 0)) && return 0
((versuch >= max)) && return "$rc"
warn "Versuch $versuch/$max: $* (Exit $rc)"
versuch=$((versuch + 1))
sleep 1
done
}
EOF
shellcheck ~/sh-lab/werkzeug/lib/lib.sh && echo sauber
bash -c 'source ~/sh-lab/werkzeug/lib/lib.sh; retry 3 false; echo "Exit: $?"'
bash -c 'source ~/sh-lab/werkzeug/lib/lib.sh; retry 3 notes-ping'Expected:
sauber
12:24:01 bash: WARN Versuch 1/3: false (Exit 1)
12:24:02 bash: WARN Versuch 2/3: false (Exit 1)
Exit: 1
notes ok
"$@" || rc=$? captures the exit code without
set -e aborting – after all, strict mode applies in the
script that uses retry.
Save your progress? Sign up for free
Enterprise Note
- One library, versioned: Shared functions live once in the repository and are distributed along with it. Copies in every script drift apart.
- Uniform logging: Timestamp, program name and level on stderr – then journald, cron mail or a log collector understands every line the same way.
set -xin production only selectively: tracing also shows secrets that are stored in variables.