Bash Functions
Internal
Defintion
Syntax
[function] function-name() { ... }
The "function" keyword is optional.
If the function declaration is specified on a single line, then the final command of the function must be followed by a semicolon:
function one-liner() { echo "something"; echo "something else"; }
The function definition must precede the first call to it. Function bodies may not be empty.
Arguments
The function does not declare its arguments in the signature. They are available in the function's body as $1, $2, etc.
Important: For more than 9 arguments, always refer to arguments using ${}: ${10} not $10. If you use $10, you'll actually get the first argument ($1) with a "0" appended to it.
The number of arguments, including the empty strings specified as "" when the function was invoked, may be obtained with $#.
The shift keyword "shifts" to the left the argument list, discarding $1 and assigning to $1 the value that was previously assigned to $2, to $2 the value that was previously assigned to $3, and so on. shift's exit code is 0 if there were still arguments to shift, 1 otherwise.
The correct way to iterate through a function's arguments, including the empty strings, is:
function my-function() {
while [ $# -gt 0 ]; do
[ "$1" = "" ] && echo "got empty string" || echo "got $1"
shift
done
}
Exit Status
A bash function does not return a value, it only allows to set an exit status, which is a numerical value. 0 indicates success and a non-zero value indicates failure. The exit status is declared with the "return" keyword:
function f() {
...
return 0
}
If there is no explicit "return" keyword, the function's exit status is the exit status of last executed statement.
The function's caller can retrieve the exist status with $?.
Returning Values
As mentioned above, functions do not return values. However, we may send content to stdout or stderr from the body of the function, and that content can be captured by the caller as follows:
function callee() {
echo "we send this to stdout"
echo "we send this to stderr" 1>&2
}
function caller() {
local content
content=$(callee)
echo "${content}"
}
Command substitution demonstrated above will capture the content that is being sent to stdout into the local variable "content". The content sent to stderr will be sent to the stderr of the executing shell.
Function Info
- Names of declared functions: typeset -F
- The function body: typeset -f, type <function-name>
The FUNCNAME Array
A function has a "FUNCNAME" built-in array, which is an array variable containing the names of all shell functions currently in the execution call stack. The element with index 0 is the name of any currently-executing shell function. The bottom-most element is "main". This variable exists only when a shell function is executing. Assignments to FUNCNAME have no effect and return an error status. If FUNCNAME is unset, it loses its special properties, even if it is subsequently reset.
The Name of the Function
The name of the function may be obtained inside the function with:
${FUNCNAME[0]}
Recommended Style
# Function documentation
# Returns to stdout: ...
# Returns to stderr: ...
function some-function() {
local arg1=$1 # arg1 documentation
local arg2=$2 # arg1 documentation
...
}
Executing a Function in Background
Functions can be executed in background with & as follows:
function callee() {
...
}
function caller() {
callee &
}
When a function is invoked in background within the context of a shell (callee() in this case), a completely new sub-shell is started and begins to execute the code of function. The shell that invoked the function in background is the parent of the newly created sub-shell. Both processes have the same name in the process table:
501 4058 3941 0 9:07PM ttys004 0:00.01 /bin/bash ./main.sh 501 4059 4058 0 9:07PM ttys004 0:00.01 /bin/bash ./main.sh
The sub-shell's stdout and stderr are directed to the parent shell's stdout and stderr.
When the function exits: