Skip to content
Hands-on IT IT Drills

Day 4: Functions and a Library

Goal: Write functions, return results via exit code and output, protect variables with local, build a shared library lib.sh for the toolbox and examine scripts with bash -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 -x shows 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 funktionen

Expected:

21 verdoppelt: 42
abc ist keine Zahl
  • ist_zahl prints nothing. Its result is the exit code of the last command – just like with a script. That is why it works directly after if.
  • verdoppeln returns its result as output. return 42 would 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 global

Expected:

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 global

Expected:

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/.shellcheckrc

Expected:

sauber
  • The library has no shebang and no set -euo pipefail – it runs inside the script that loads it. # shellcheck shell=bash tells ShellCheck which language applies.
  • The guard _LIB_SH prevents 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 -12

Expected (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-add

Expected:

/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 -x in production only selectively: tracing also shows secrets that are stored in variables.