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