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