- publishing free software manuals
GNU Bash Reference Manual
by Chet Ramey and Brian Fox
Paperback (6"x9"), 180 pages
ISBN 0954161777
RRP £19.95 ($29.95)

"An essential resource .... the most detailed coverage available for all aspects of Bash" --- Linux User and Developer Magazine (Issue 37, Mar 2004) Get a printed copy>>>

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:

[ 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 (see section 3.2.4 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. Any redirections (see section 3.6 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 (see section 4.1 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 blanks or newlines. This is because the braces are reserved words and are only recognized as such when they are separated by whitespace. Also, when using the braces, the list must be terminated by a semicolon, an ampersand ‘&’, or a newline.

When a function is executed, the arguments to the function become the positional parameters during its execution (see section 3.4.1 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 the exception that 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). See section 4.1 Bourne Shell Builtins, for the description of the trap builtin.

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 or typeset builtin commands (see section 4.2 Bash Builtin Commands). 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 (see section 4.1 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. No limit is placed on the number of recursive calls.

ISBN 0954161777GNU Bash Reference ManualSee the print edition