(bash.info) Shell Functions
Info Catalog
(bash.info) Shell Commands
(bash.info) Basic Shell Features
(bash.info) Shell Parameters
3.3 Shell Functions
===================
Shell functions are a way to group commands for later execution using a
single name for the group. They are executed just like a "regular"
command. When the name of a shell function is used as a simple command
name, the list of commands associated with that function name is
executed. Shell functions are executed in the current shell context;
no new process is created to interpret them.
Functions are declared using this syntax:
NAME () COMPOUND-COMMAND [ REDIRECTIONS ]
or
function NAME [()] COMPOUND-COMMAND [ REDIRECTIONS ]
This defines a shell function named NAME. The reserved word
`function' is optional. If the `function' reserved word is supplied,
the parentheses are optional. The BODY of the function is the compound
command COMPOUND-COMMAND ( Compound Commands). That command is
usually a LIST enclosed between { and }, but may be any compound
command listed above. COMPOUND-COMMAND is executed whenever NAME is
specified as the name of a command. When the shell is in POSIX mode
( Bash POSIX Mode), NAME may not be the same as one of the
Redirections::) associated with the shell function are performed when
the function is executed.
A function definition may be deleted using the `-f' option to the
`unset' builtin ( Bourne Shell Builtins).
The exit status of a function definition is zero unless a syntax
error occurs or a readonly function with the same name already exists.
When executed, the exit status of a function is the exit status of the
last command executed in the body.
Note that for historical reasons, in the most common usage the curly
braces that surround the body of the function must be separated from
the body by `blank's or newlines. This is because the braces are
reserved words and are only recognized as such when they are separated
from the command list by whitespace or another shell metacharacter.
Also, when using the braces, the LIST must be terminated by a semicolon,
a `&', or a newline.
When a function is executed, the arguments to the function become
the positional parameters during its execution ( Positional
Parameters). The special parameter `#' that expands to the number of
positional parameters is updated to reflect the change. Special
parameter `0' is unchanged. The first element of the `FUNCNAME'
variable is set to the name of the function while the function is
executing.
All other aspects of the shell execution environment are identical
between a function and its caller with these exceptions: the `DEBUG'
and `RETURN' traps are not inherited unless the function has been given
the `trace' attribute using the `declare' builtin or the `-o functrace'
option has been enabled with the `set' builtin, (in which case all
functions inherit the `DEBUG' and `RETURN' traps), and the `ERR' trap
is not inherited unless the `-o errtrace' shell option has been enabled.
Bourne Shell Builtins, for the description of the `trap'
builtin.
The `FUNCNEST' variable, if set to a numeric value greater than 0,
defines a maximum function nesting level. Function invocations that
exceed the limit cause the entire command to abort.
If the builtin command `return' is executed in a function, the
function completes and execution resumes with the next command after
the function call. Any command associated with the `RETURN' trap is
executed before execution resumes. When a function completes, the
values of the positional parameters and the special parameter `#' are
restored to the values they had prior to the function's execution. If
a numeric argument is given to `return', that is the function's return
status; otherwise the function's return status is the exit status of
the last command executed before the `return'.
Variables local to the function may be declared with the `local'
builtin. These variables are visible only to the function and the
commands it invokes.
Function names and definitions may be listed with the `-f' option to
the `declare' (`typeset') builtin command ( Bash Builtins). The
`-F' option to `declare' or `typeset' will list the function names only
(and optionally the source file and line number, if the `extdebug'
shell option is enabled). Functions may be exported so that subshells
automatically have them defined with the `-f' option to the `export'
builtin ( Bourne Shell Builtins). Note that shell functions and
variables with the same name may result in multiple identically-named
entries in the environment passed to the shell's children. Care should
be taken in cases where this may cause a problem.
Functions may be recursive. The `FUNCNEST' variable may be used to
limit the depth of the function call stack and restrict the number of
function invocations. By default, no limit is placed on the number of
recursive calls.
Info Catalog
(bash.info) Shell Commands
(bash.info) Basic Shell Features
(bash.info) Shell Parameters
automatically generated byinfo2html