Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Bash Syntax

Bash functions

Reference for Bash functions: define them, pass arguments with $1 and $@, return a status or output, use local variables, nameref and recursion.

A function gives a name to a block of commands so you can run it again with different arguments. Inside the function the arguments appear as $1, $2, $@ and $#, just like a script's. A function runs in the current shell, so it can change variables and the working directory of the caller.

Functions can only "return" a small number (an exit status 0โ€“255). To hand back data, print it and capture it with command substitution, or set a global variable or a nameref.

Terminal
name() {
  commands
}

function name { commands; }     # Bash-only form

Try it

Bash Arguments, status and output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Scope, return and recursion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
name () compound-command [redirection]
function name [()] compound-command [redirection]
return [n]
local [option] name[=value] ...
Part Description
$1...$9, ${10} Positional parameters of the call.
$#, $@, $* Number of arguments; all arguments (quote "$@").
$0 Still the script name (the function name is in FUNCNAME[0]).
return [n] Leave the function with status n (default: status of the last command).
local Declare a variable that exists only in the function and the functions it calls (dynamic scope).
local -n ref=name Name reference to another variable (Bash 4.3+).
declare -F, declare -f name List function names, or print the definition.
unset -f name Remove a function.

Returns: the status given to return, or the status of the last command executed.

Usage notes

  • Define a function before you call it; the shell reads a script top to bottom.
  • Variables are global unless declared local. Always declare loop counters and temporaries as local to avoid clobbering the caller's variables.
  • Bash scope is dynamic: a function called from another sees the caller's locals. This is different from most languages.
  • return only accepts 0โ€“255; larger values wrap around. Use output ($(func)) for data and the status for success or failure.
  • Capturing output with $(func) runs the function in a subshell, so variable changes inside it are lost and forks cost time in tight loops. A nameref or a global variable avoids that.
  • A function with the same name as an external command shadows it. Use command name to bypass the function or unset -f name to remove it.
  • Functions can have redirections applied at definition (log() { ...; } >&2) and be exported to child Bash processes with export -f.
  • set -e interacts oddly with functions used in conditions: inside an if f; then, errors in f do not stop the script.