From 3e5ce3ce3140476f77731bf708240b0afa43e48c Mon Sep 17 00:00:00 2001 From: Rawiri Blundell Date: Sun, 16 Apr 2023 20:04:24 +1200 Subject: [PATCH] First pandoc conversion --- bash4.md | 219 +++++ commands/builtin/caller.md | 80 ++ commands/builtin/continuebreak.md | 139 +++ commands/builtin/declare.md | 160 +++ commands/builtin/echo.md | 88 ++ commands/builtin/eval.md | 170 ++++ commands/builtin/exec.md | 85 ++ commands/builtin/exit.md | 46 + commands/builtin/export.md | 52 + commands/builtin/false.md | 139 +++ commands/builtin/kill.md | 70 ++ commands/builtin/let.md | 110 +++ commands/builtin/local.md | 44 + commands/builtin/mapfile.md | 220 +++++ commands/builtin/printf.md | 465 +++++++++ commands/builtin/read.md | 269 +++++ commands/builtin/readonly.md | 44 + commands/builtin/return.md | 35 + commands/builtin/set.md | 81 ++ commands/builtin/shift.md | 87 ++ commands/builtin/shopt.md | 51 + commands/builtin/source.md | 139 +++ commands/builtin/times.md | 139 +++ commands/builtin/trap.md | 72 ++ commands/builtin/true.md | 139 +++ commands/builtin/unset.md | 179 ++++ commands/builtin/wait.md | 44 + commands/classictest.md | 571 +++++++++++ dict/index.md | 10 + howto/calculate-dc.md | 276 ++++++ howto/collapsing_functions.md | 99 ++ howto/conffile.md | 105 ++ howto/dissectabadoneliner.md | 124 +++ howto/edit-ed.md | 386 ++++++++ howto/getopts_tutorial.md | 358 +++++++ howto/mutex.md | 202 ++++ howto/pax.md | 347 +++++++ howto/redirection_tutorial.md | 686 +++++++++++++ howto/start.md | 1 + howto/testing-your-scripts.md | 94 ++ internals/shell_options.md | 509 ++++++++++ misc/bashphorisms.md | 52 + misc/readthesourceluke.md | 68 ++ misc/shell_humor.md | 35 + scripting/bashbehaviour.md | 360 +++++++ scripting/bashchanges.md | 333 +++++++ scripting/basics.md | 351 +++++++ scripting/debuggingtips.md | 371 +++++++ scripting/newbie_traps.md | 278 ++++++ scripting/nonportable.md | 265 +++++ scripting/obsolete.md | 0 scripting/posparams.md | 396 ++++++++ scripting/processtree.md | 175 ++++ scripting/style.md | 404 ++++++++ scripting/terminalcodes.md | 403 ++++++++ scripting/tutoriallist.md | 467 +++++++++ snipplets/start.md | 24 + start.md | 584 +++++++++++ syntax/arith_expr.md | 374 +++++++ syntax/arrays.md | 718 ++++++++++++++ syntax/basicgrammar.md | 329 +++++++ syntax/ccmd/arithmetic_eval.md | 30 + syntax/ccmd/c_for.md | 236 +++++ syntax/ccmd/case.md | 161 +++ syntax/ccmd/classic_for.md | 186 ++++ syntax/ccmd/grouping_plain.md | 71 ++ syntax/ccmd/grouping_subshell.md | 35 + syntax/ccmd/if_clause.md | 91 ++ syntax/ccmd/intro.md | 34 + syntax/ccmd/until_loop.md | 38 + syntax/ccmd/user_select.md | 56 ++ syntax/ccmd/while_loop.md | 41 + syntax/expansion/arith.md | 73 ++ syntax/expansion/brace.md | 266 +++++ syntax/expansion/cmdsubst.md | 137 +++ syntax/expansion/globs.md | 113 +++ syntax/expansion/intro.md | 91 ++ syntax/expansion/proc_subst.md | 184 ++++ syntax/expansion/tilde.md | 109 +++ syntax/expansion/wordsplit.md | 47 + syntax/grammar/parser_exec.md | 124 +++ syntax/keywords/coproc.md | 266 +++++ syntax/pattern.md | 160 +++ syntax/pe.md | 1044 ++++++++++++++++++++ syntax/quoting.md | 271 ++++++ syntax/redirection.md | 247 +++++ syntax/shellvars.md | 1507 +++++++++++++++++++++++++++++ syntax/words.md | 164 ++++ user/thebonsai/imprint.md | 20 + 89 files changed, 18923 insertions(+) create mode 100644 bash4.md create mode 100644 commands/builtin/caller.md create mode 100644 commands/builtin/continuebreak.md create mode 100644 commands/builtin/declare.md create mode 100644 commands/builtin/echo.md create mode 100644 commands/builtin/eval.md create mode 100644 commands/builtin/exec.md create mode 100644 commands/builtin/exit.md create mode 100644 commands/builtin/export.md create mode 100644 commands/builtin/false.md create mode 100644 commands/builtin/kill.md create mode 100644 commands/builtin/let.md create mode 100644 commands/builtin/local.md create mode 100644 commands/builtin/mapfile.md create mode 100644 commands/builtin/printf.md create mode 100644 commands/builtin/read.md create mode 100644 commands/builtin/readonly.md create mode 100644 commands/builtin/return.md create mode 100644 commands/builtin/set.md create mode 100644 commands/builtin/shift.md create mode 100644 commands/builtin/shopt.md create mode 100644 commands/builtin/source.md create mode 100644 commands/builtin/times.md create mode 100644 commands/builtin/trap.md create mode 100644 commands/builtin/true.md create mode 100644 commands/builtin/unset.md create mode 100644 commands/builtin/wait.md create mode 100644 commands/classictest.md create mode 100644 dict/index.md create mode 100644 howto/calculate-dc.md create mode 100644 howto/collapsing_functions.md create mode 100644 howto/conffile.md create mode 100644 howto/dissectabadoneliner.md create mode 100644 howto/edit-ed.md create mode 100644 howto/getopts_tutorial.md create mode 100644 howto/mutex.md create mode 100644 howto/pax.md create mode 100644 howto/redirection_tutorial.md create mode 100644 howto/start.md create mode 100644 howto/testing-your-scripts.md create mode 100644 internals/shell_options.md create mode 100644 misc/bashphorisms.md create mode 100644 misc/readthesourceluke.md create mode 100644 misc/shell_humor.md create mode 100644 scripting/bashbehaviour.md create mode 100644 scripting/bashchanges.md create mode 100644 scripting/basics.md create mode 100644 scripting/debuggingtips.md create mode 100644 scripting/newbie_traps.md create mode 100644 scripting/nonportable.md create mode 100644 scripting/obsolete.md create mode 100644 scripting/posparams.md create mode 100644 scripting/processtree.md create mode 100644 scripting/style.md create mode 100644 scripting/terminalcodes.md create mode 100644 scripting/tutoriallist.md create mode 100644 snipplets/start.md create mode 100644 start.md create mode 100644 syntax/arith_expr.md create mode 100644 syntax/arrays.md create mode 100644 syntax/basicgrammar.md create mode 100644 syntax/ccmd/arithmetic_eval.md create mode 100644 syntax/ccmd/c_for.md create mode 100644 syntax/ccmd/case.md create mode 100644 syntax/ccmd/classic_for.md create mode 100644 syntax/ccmd/grouping_plain.md create mode 100644 syntax/ccmd/grouping_subshell.md create mode 100644 syntax/ccmd/if_clause.md create mode 100644 syntax/ccmd/intro.md create mode 100644 syntax/ccmd/until_loop.md create mode 100644 syntax/ccmd/user_select.md create mode 100644 syntax/ccmd/while_loop.md create mode 100644 syntax/expansion/arith.md create mode 100644 syntax/expansion/brace.md create mode 100644 syntax/expansion/cmdsubst.md create mode 100644 syntax/expansion/globs.md create mode 100644 syntax/expansion/intro.md create mode 100644 syntax/expansion/proc_subst.md create mode 100644 syntax/expansion/tilde.md create mode 100644 syntax/expansion/wordsplit.md create mode 100644 syntax/grammar/parser_exec.md create mode 100644 syntax/keywords/coproc.md create mode 100644 syntax/pattern.md create mode 100644 syntax/pe.md create mode 100644 syntax/quoting.md create mode 100644 syntax/redirection.md create mode 100644 syntax/shellvars.md create mode 100644 syntax/words.md create mode 100644 user/thebonsai/imprint.md diff --git a/bash4.md b/bash4.md new file mode 100644 index 0000000..fe213bc --- /dev/null +++ b/bash4.md @@ -0,0 +1,219 @@ +# Bash 4 - a rough overview + +:V4: + +\Attention: Since Bash 4 has been around for quite some time now +(4.3 will come soon), I consider it to be "standard". This page is not +maintained anymore and is left here to keep your links working. See the +[bashchanges](/scripting/bashchanges) page for new stuff +introduced.\ + +Besides many bugfixes since Bash 3.2, Bash 4 will bring some interesting +new features for shell users and scripters. See also +[bashchanges](/scripting/bashchanges) for a small general overview with +more details. + +Not all of the changes and news are included here, just the biggest or +most interesting ones. The changes to completion, and the readline +component are not covered. **Though, if you're familiar with these parts +of Bash (and Bash 4), feel free to write a chapter here.** + +The complete list of fixes and changes is in the CHANGES or NEWS file of +your Bash 4 distribution. + +\ The current available **stable** +version is 4.4.18 release (February 03, 2018): + +- +- + +\ + +## New or changed commands and keywords + +### The new "coproc" keyword + +Bash 4 introduces the concepts of coprocesses, a well known feature of +other shells. The basic concept is simple: It will start any command in +the background and set up an array that is populated with accessible +files that represent the filedescriptors of the started process. + +In other words: It lets you start a process in background and +communicate with its input and output data streams. + +See [The coproc keyword](/syntax/keywords/coproc) + +### The new "mapfile" builtin + +The `mapfile` builtin is able to map the lines of a file directly into +an array. This avoids having to fill an array yourself using a loop. It +enables you to define the range of lines to read, and optionally call a +callback, for example to display a progress bar. + +See: [mapfile](/commands/builtin/mapfile) + +### Changes to the "case" keyword + +The `case` construct understands two new action list terminators: + +The `;&` terminator causes execution to continue with the next action +list (rather than terminate the `case` construct). + +The `;;&` terminator causes the `case` construct to test the next given +pattern instead of terminating the whole execution. + +See [case](/syntax/ccmd/case) + +### Changes to the "declare" builtin + +The `-p` option now prints all attributes and values of declared +variables (or functions, when used with `-f`). The output is fully +re-usable as input. + +The new option `-l` declares a variable in a way that the content is +converted to lowercase on assignment. For uppercase, the same applies to +`-u`. The option `-c` causes the content to be capitalized before +assignment. + +`declare -A` declares associative arrays (see below). + +### Changes to the "read" builtin + +The `read` builtin command has some interesting new features. + +The `-t` option to specify a timeout value has been slightly tuned. It +now accepts fractional values and the special value 0 (zero). When +`-t 0` is specified, `read` immediately returns with an exit status +indicating if there's data waiting or not. However, when a timeout is +given, and the `read` builtin times out, any partial data recieved up to +the timeout is stored in the given variable, rather than lost. When a +timeout is hit, `read` exits with a code greater than 128. + +A new option, `-i`, was introduced to be able to preload the input +buffer with some text (when Readline is used, with `-e`). The user is +able to change the text, or press return to accept it. + +See [read](/commands/builtin/read) + +### Changes to the "help" builtin + +The builtin itself didn't change much, but the data displayed is more +structured now. The help texts are in a better format, much easier to +read. + +There are two new options: `-d` displays the summary of a help text, +`-m` displays a manpage-like format. + +### Changes to the "ulimit" builtin + +Besides the use of the 512 bytes blocksize everywhere in POSIX mode, +`ulimit` supports two new limits: `-b` for max socket buffer size and +`-T` for max number of threads. + +## Expansions + +### Brace Expansion + +The brace expansion was tuned to provide expansion results with leading +zeros when requesting a row of numbers. + +See [brace](/syntax/expansion/brace) + +### Parameter Expansion + +Methods to modify the case on expansion time have been added. + +On expansion time you can modify the syntax by adding operators to the +parameter name. + +See [Case modification on parameter +expansion](/syntax/pe#case_modification) + +### Substring expansion + +When using substring expansion on the positional parameters, a starting +index of 0 now causes \$0 to be prepended to the list (if the positional +parameters are used). Before, this expansion started with \$1: + + # this should display $0 on Bash v4, $1 on Bash v3 + echo ${@:0:1} + +### Globbing + +There's a new shell option `globstar`. When enabled, Bash will perform +recursive globbing on `**` -- this means it matches all directories and +files from the current position in the filesystem, rather than only the +current level. + +The new shell option `dirspell` enables spelling corrections on +directory names during globbing. + +See [globs](/syntax/expansion/globs) + +## Associative Arrays + +Besides the classic method of integer indexed arrays, Bash 4 supports +associative arrays. + +An associative array is an array indexed by an arbitrary string, +something like + + declare -A ASSOC + + ASSOC[First]="first element" + ASSOC[Hello]="second element" + ASSOC[Peter Pan]="A weird guy" + +See [arrays](/syntax/arrays) + +## Redirection + +There is a new `&>>` redirection operator, which appends the standard +output and standard error to the named file. This is the same as the +good old `>>FILE 2>&1` notation. + +The parser now understands `|&` as a synonym for `2>&1 |`, which +redirects the standard error for a command through a pipe. + +See [redirection](/syntax/redirection) + +## Interesting new shell variables + +| Variable | Description | +|----------------------------------------------------|--------------------------------------------------------------------------------| +| [BASHPID](/syntax/shellvars#BASHPID) | contains the PID of the current shell (this is different than what `$$` does!) | +| [PROMPT_DIRTRIM](/syntax/shellvars#PROMPT_DIRTRIM) | specifies the max. level of unshortened pathname elements in the prompt | +| [FUNCNEST](/syntax/shellvars#FUNCNEST) | control the maximum number of shell function recursions | + +See [shellvars](/syntax/shellvars) + +## Interesting new Shell Options + +The mentioned shell options are **off by default** unless otherwise +mentioned. + +| Option | Description | +|-------------|--------------------------------------------------------------------------------------------------------| +| `checkjobs` | check for and report any running jobs at shell exit | +| `compat*` | set compatiblity modes for older shell versions (influences regular expression matching in `[[ ... ]]` | +| `dirspell` | enables spelling corrections on directory names during globbing | +| `globstar` | enables recursive globbing with `**` | +| `lastpipe` | (4.2) to execute the last command in a pipeline in the current environment | + +See [shell_options](/internals/shell_options) + +## Misc + +- If a command is not found, the shell attempts to execute a shell + function named `command_not_found_handle`, supplying the command words + as the function arguments. This can be used to display userfriendly + messages or perform different command searches +- The behaviour of the `set -e` (`errexit`) mode was changed, it now + acts more intuitive (and is better documented in the manpage). +- The output target for the `xtrace` (`set -x`/`set +x`) feature is + configurable **since Bash 4.1** (previously, it was fixed to + `stderr`): a variable named + [BASH_XTRACEFD](/syntax/shellvars#BASH_XTRACEFD) can be set to the + filedescriptor that should get the output +- Bash 4.1 is able to log the history to syslog (only to be enabled at + compile time in `config-top.h`) diff --git a/commands/builtin/caller.md b/commands/builtin/caller.md new file mode 100644 index 0000000..20dd277 --- /dev/null +++ b/commands/builtin/caller.md @@ -0,0 +1,80 @@ +# The caller builtin command + +## Synopsis + + caller [FRAMENUMBER] + +## Description + +The `caller` builtin command is used to print execution frames of +subroutine calls. Without giving a framenumber, the topmost execution +frame information is printed ("who called me") wile linenumber and +filename. + +When an execution frame number is given (0 - topmost), the linenumber, +the subroutine (function) and the filename is printed. When an invalid +execution frame number is given, it exists `FALSE`. This way it can be +used in a loop (see the examples section below). + +## Examples + +### Simple stack trace + +The code below defines a function `die` that is used to exit the +program. It prints a list of execution frames, starting with the topmost +frame (0). The topmost frame is the "caller of the die function", in +this case function "f1". + +This way, you can print a "stack trace" for debugging or logging +purposes. + +The code is made very simple, just to show the basic purposes. + +``` bash +#!/bin/bash + +die() { + local frame=0 + while caller $frame; do + ((++frame)); + done + echo "$*" + exit 1 +} + +f1() { die "*** an error occured ***"; } +f2() { f1; } +f3() { f2; } + +f3 +``` + +**Output** + + 12 f1 ./callertest.sh + 13 f2 ./callertest.sh + 14 f3 ./callertest.sh + 16 main ./callertest.sh + *** an error occured *** + +## Notes + +- `caller` produces no output unless used within a script that's run + from a real file. It isn't particularly useful for interactive use, + but can be used to create a decent `die` function to track down errors + in moderately complex scripts. + `{ bash /dev/stdin; } <<<$'f(){ g; }\ng(){ h; }\nh(){ while caller $((n++)); do :; done; }\nf'` +- For more sophisticated debugging, Bash extended debugging features are + available and a number of special parameters that give more detail + than caller (e.g. BASH_ARG{C,V}). Tools such as + [Bashdb](http://bashdb.sourceforge.net/) can assist in using some of + Bash's more advanced debug features. +- The Bash manpage and help text specifies that the argument to `caller` + is an "expr" (whatever that means). Only an integer is actually + allowed, with no special interpretation of an "expression" as far as + we can tell. + +## Portability considerations + +- `caller` is not specified by POSIX(R) +- the `caller` builtin command appeared in Bash version 3.0 diff --git a/commands/builtin/continuebreak.md b/commands/builtin/continuebreak.md new file mode 100644 index 0000000..b46fdd7 --- /dev/null +++ b/commands/builtin/continuebreak.md @@ -0,0 +1,139 @@ +\