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.
name() {
commands
}
function name { commands; } # Bash-only form
Try it
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.
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
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 aslocalto 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.
returnonly 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 nameto bypass the function orunset -f nameto remove it. - Functions can have redirections applied at definition (
log() { ...; } >&2) and be exported to child Bash processes withexport -f. set -einteracts oddly with functions used in conditions: inside anif f; then, errors infdo not stop the script.
Related
- Indexed arrays
- if statements
- Command lists
- Tutorial: Functions