function

Define a function with the specified name

$ function [func_name] { [echo "Function contents here"]; }

$ func_name

$ [func_name]() { [echo "Function contents here"]; }

$ help function

function name [()] { commands ; }
or
function name [()] compound-command

name
    The identifier chosen for the function. This name will be used to invoke the function later.

commands
    The body of the function, consisting of one or more shell commands. These commands are typically enclosed within curly braces { }, forming a compound command.

The function keyword is a shell builtin primarily found in Bash and KornShell (ksh) for defining shell functions. Unlike the POSIX-compliant name() { commands; } syntax, the function keyword provides an alternative, often considered more readable, way to declare a function. When used, the parentheses () after the function name become optional, though they can still be included.

Functions allow you to encapsulate a sequence of commands into a reusable block, which can be executed simply by typing the function's name. This improves script modularity, readability, and reduces redundancy. Variables can be made local to a function using the local keyword, preventing interference with global variables. Functions also accept positional parameters, similar to scripts, enabling dynamic behavior based on input. They execute within the current shell environment, meaning they can modify the shell's state (e.g., change directories, set environment variables) without launching a subshell.

The function keyword is a Bash and KornShell extension and is not part of the POSIX shell standard. Scripts using it may not be portable to shells like Dash or pure POSIX shells. Always use the local keyword for variables intended to be scoped only within the function, to prevent unintended side effects on global variables. The return status of a function is determined by the exit status of the last command executed within its body, or explicitly set using the return command.

Inside a function, arguments passed to it are accessible via positional parameters, just like in a script: $1 for the first argument, $2 for the second, $@ for all arguments, and $# for the number of arguments. These are distinct from any positional parameters of the script itself.

A function's exit status is crucial for error handling and flow control. By default, it's the exit status of the last command executed within its body. You can explicitly set the return status using the return command, followed by an integer value (0 for success, non-zero for failure). For example: return 1.

The function keyword syntax originated in the KornShell (ksh) to provide a more explicit way to declare functions, distinct from the traditional Bourne shell (and later POSIX) name() { commands; } syntax. Bash adopted this syntax to offer compatibility and an alternative style. While the POSIX-compliant syntax remains widely used and is more portable, the function keyword is popular in Bash scripts for its clarity.

bash(1), local(1), return(1), declare(1), source(1)