new repository

1 files changed, 27 insertions, 0 deletions

diff --git a/devdocs/bash/shell-functions.html b/devdocs/bash/shell-functions.html
new file mode 100644
index 00000000..ed230d3e
--- /dev/null
+++ b/devdocs/bash/shell-functions.html
@@ -0,0 +1,27 @@
+<h1 class="section">Shell Functions</h1>   <p>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. </p> <p>Functions are declared using this syntax:  </p>
+<div class="example"> <pre class="example">fname () compound-command [ redirections ]
+</pre>
+</div> <p>or </p> <div class="example"> <pre class="example">function fname [()] compound-command [ redirections ]
+</pre>
+</div> <p>This defines a shell function named <var>fname</var>. The reserved word <code>function</code> is optional. If the <code>function</code> reserved word is supplied, the parentheses are optional. The <em>body</em> of the function is the compound command <var>compound-command</var> (see <a href="compound-commands">Compound Commands</a>). That command is usually a <var>list</var> enclosed between { and }, but may be any compound command listed above. If the <code>function</code> reserved word is used, but the parentheses are not supplied, the braces are recommended. <var>compound-command</var> is executed whenever <var>fname</var> is specified as the name of a simple command. When the shell is in <small>POSIX</small> mode (see <a href="bash-posix-mode">Bash POSIX Mode</a>), <var>fname</var> must be a valid shell name and may not be the same as one of the special builtins (see <a href="special-builtins">Special Builtins</a>). In default mode, a function name can be any unquoted shell word that does not contain ‘<samp>$</samp>’. Any redirections (see <a href="redirections">Redirections</a>) associated with the shell function are performed when the function is executed. A function definition may be deleted using the <samp>-f</samp> option to the <code>unset</code> builtin (see <a href="bourne-shell-builtins">Bourne Shell Builtins</a>). </p> <p>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. </p> <p>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 <code>blank</code>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 <var>list</var> must be terminated by a semicolon, a ‘<samp>&amp;</samp>’, or a newline. </p> <p>When a function is executed, the arguments to the function become the positional parameters during its execution (see <a href="positional-parameters">Positional Parameters</a>). The special parameter ‘<samp>#</samp>’ that expands to the number of positional parameters is updated to reflect the change. Special parameter <code>0</code> is unchanged. The first element of the <code>FUNCNAME</code> variable is set to the name of the function while the function is executing. </p> <p>All other aspects of the shell execution environment are identical between a function and its caller with these exceptions: the <code>DEBUG</code> and <code>RETURN</code> traps are not inherited unless the function has been given the <code>trace</code> attribute using the <code>declare</code> builtin or the <code>-o functrace</code> option has been enabled with the <code>set</code> builtin, (in which case all functions inherit the <code>DEBUG</code> and <code>RETURN</code> traps), and the <code>ERR</code> trap is not inherited unless the <code>-o errtrace</code> shell option has been enabled. See <a href="bourne-shell-builtins">Bourne Shell Builtins</a>, for the description of the <code>trap</code> builtin. </p> <p>The <code>FUNCNEST</code> 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. </p> <p>If the builtin command <code>return</code> is executed in a function, the function completes and execution resumes with the next command after the function call. Any command associated with the <code>RETURN</code> trap is executed before execution resumes. When a function completes, the values of the positional parameters and the special parameter ‘<samp>#</samp>’ are restored to the values they had prior to the function’s execution. If a numeric argument is given to <code>return</code>, that is the function’s return status; otherwise the function’s return status is the exit status of the last command executed before the <code>return</code>. </p> <p>Variables local to the function may be declared with the <code>local</code> builtin (<em>local variables</em>). Ordinarily, variables and their values are shared between a function and its caller. These variables are visible only to the function and the commands it invokes. This is particularly important when a shell function calls other functions. </p> <p>In the following description, the <em>current scope</em> is a currently- executing function. Previous scopes consist of that function’s caller and so on, back to the "global" scope, where the shell is not executing any shell function. Consequently, a local variable at the current local scope is a variable declared using the <code>local</code> or <code>declare</code> builtins in the function that is currently executing. </p> <p>Local variables "shadow" variables with the same name declared at previous scopes. For instance, a local variable declared in a function hides a global variable of the same name: references and assignments refer to the local variable, leaving the global variable unmodified. When the function returns, the global variable is once again visible. </p> <p>The shell uses <em>dynamic scoping</em> to control a variable’s visibility within functions. With dynamic scoping, visible variables and their values are a result of the sequence of function calls that caused execution to reach the current function. The value of a variable that a function sees depends on its value within its caller, if any, whether that caller is the "global" scope or another shell function. This is also the value that a local variable declaration "shadows", and the value that is restored when the function returns. </p> <p>For example, if a variable <code>var</code> is declared as local in function <code>func1</code>, and <code>func1</code> calls another function <code>func2</code>, references to <code>var</code> made from within <code>func2</code> will resolve to the local variable <code>var</code> from <code>func1</code>, shadowing any global variable named <code>var</code>. </p> <p>The following script demonstrates this behavior. When executed, the script displays </p> <div class="example"> <pre class="example">In func2, var = func1 local
+</pre>
+</div> <div class="example"> <pre class="example">func1()
+{
+    local var='func1 local'
+    func2
+}
+
+func2()
+{
+    echo "In func2, var = $var"
+}
+
+var=global
+func1
+</pre>
+</div> <p>The <code>unset</code> builtin also acts using the same dynamic scope: if a variable is local to the current scope, <code>unset</code> will unset it; otherwise the unset will refer to the variable found in any calling scope as described above. If a variable at the current local scope is unset, it will remain so (appearing as unset) until it is reset in that scope or until the function returns. Once the function returns, any instance of the variable at a previous scope will become visible. If the unset acts on a variable at a previous scope, any instance of a variable with that name that had been shadowed will become visible (see below how <code>localvar_unset</code>shell option changes this behavior). </p> <p>Function names and definitions may be listed with the <samp>-f</samp> option to the <code>declare</code> (<code>typeset</code>) builtin command (see <a href="bash-builtins">Bash Builtin Commands</a>). The <samp>-F</samp> option to <code>declare</code> or <code>typeset</code> will list the function names only (and optionally the source file and line number, if the <code>extdebug</code> shell option is enabled). Functions may be exported so that child shell processes (those created when executing a separate shell invocation) automatically have them defined with the <samp>-f</samp> option to the <code>export</code> builtin (see <a href="bourne-shell-builtins">Bourne Shell Builtins</a>). </p> <p>Functions may be recursive. The <code>FUNCNEST</code> 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. </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.<br>Licensed under the GNU Free Documentation License.<br>
+    <a href="https://www.gnu.org/software/bash/manual/html_node/Shell-Functions.html" class="_attribution-link">https://www.gnu.org/software/bash/manual/html_node/Shell-Functions.html</a>
+  </p>
+</div>