From 024e1bcc0eefae1353c41e30abc36453b4425c53 Mon Sep 17 00:00:00 2001 From: flokoe Date: Wed, 5 Jul 2023 11:06:16 +0200 Subject: [PATCH] Convert files under dict to Markdown --- docs/dict/directory.md | 15 ++++ docs/dict/end_of_options.md | 31 +++++++ docs/dict/exit_status.md | 140 +++++++++++++++++++++++++++++ docs/dict/file.md | 24 +++++ docs/dict/filetimes.md | 23 +++++ docs/dict/globbing.md | 31 +++++++ docs/dict/hardlink.md | 51 +++++++++++ docs/dict/interpreter_directive.md | 35 ++++++++ docs/dict/parameter.md | 67 ++++++++++++++ docs/dict/posix.md | 16 ++++ docs/dict/shell.md | 19 ++++ docs/dict/special_file.md | 19 ++++ docs/dict/symlink.md | 15 ++++ 13 files changed, 486 insertions(+) create mode 100644 docs/dict/directory.md create mode 100644 docs/dict/end_of_options.md create mode 100644 docs/dict/exit_status.md create mode 100644 docs/dict/file.md create mode 100644 docs/dict/filetimes.md create mode 100644 docs/dict/globbing.md create mode 100644 docs/dict/hardlink.md create mode 100644 docs/dict/interpreter_directive.md create mode 100644 docs/dict/parameter.md create mode 100644 docs/dict/posix.md create mode 100644 docs/dict/shell.md create mode 100644 docs/dict/special_file.md create mode 100644 docs/dict/symlink.md diff --git a/docs/dict/directory.md b/docs/dict/directory.md new file mode 100644 index 0000000..aaff034 --- /dev/null +++ b/docs/dict/directory.md @@ -0,0 +1,15 @@ +# Directory + +In terms of UNIX(r), a directory is a special file which contains a list +of [hardlinks](/dict/terms/hardlink) to other files. These other files +also can be directories of course, so it\'s possible to create a +\"hierarchy of directories\" - the UNIX(r)-typical filesystem structure. + +The structure begins at the special directory `/` (root directory) and +all other directory entries are **subdirectories** of it. + +## See also + +- [hardlink](/dict/terms/hardlink) +- [file](/dict/terms/file) +- [special file](/dict/terms/special_file) diff --git a/docs/dict/end_of_options.md b/docs/dict/end_of_options.md new file mode 100644 index 0000000..146a3fd --- /dev/null +++ b/docs/dict/end_of_options.md @@ -0,0 +1,31 @@ +# End of Options + +The options of UNIX(r) utilities usually are introduced with a dash +(`-`) character. + +This is problematic when a non-option argument has to be specified that +begins with a dash. A common example for this are filenames. + +Many utilities use the convention to specify two consecutive dashes +(`--`) to signal \"end of options at this point\". Beyond this tag, no +options are processed anymore, even if an argument begins with a dash. + +Example: You want to list (`ls`) the file with the name `-hello`. With +common option processing, this could end up in the ls-options `-h`, +`-e`, `-l` and `-o` and probably in an error message about invalid +options. You use this to avoid the wrong option processing: + + ls -- -hello + +POSIX(r) specifies that every utility should follow this rule (see ch. +[12.2 Utility Syntax +Guidelines](https://pubs.opengroup.org/onlinepubs/9699919799.2013edition/basedefs/V1_chap12.html)), +except + +- `echo` (historical reasons) +- `test` (obvious parsing reasons) + +## See also + +- Scripting article, internal: + [getopts_tutorial](/howto/getopts_tutorial) diff --git a/docs/dict/exit_status.md b/docs/dict/exit_status.md new file mode 100644 index 0000000..6242ea4 --- /dev/null +++ b/docs/dict/exit_status.md @@ -0,0 +1,140 @@ +# Exit Status + +- exit code +- return status + +## Purpose + +The exit status is a numeric value that is returned by a program to the +calling program or shell. In C programs, this is represented by the +return value of the `main()` function or the value you give to +`exit(3)`. The only part of the number that matters are the least +significant 8 bits, which means there are only values from 0 to 255. + +In the shell, every operation generates an exit status (return status), +even if no program is called. An example for such an operation is a +redirection. + +The parameter to the + +- `exit` (exit the shell/script) +- `return` (return from a function) + +builtin commands serve the purpose of giving the exit status to the +calling component. + +This - and only this - makes it possible to determinate the success or +failure of an operation. For scripting, always set exit codes. + +## Values + +The code is a number between 0 and 255, where the part from 126 to 255 +is reserved to be used by the Bash shell directly or for special +purposes, like reporting a termination by a signal: + + Code Description + --------- ------------------------------------------------------------------------------------------------------------------------------------------------------------ + 0 success + 1-255 failure (in general) + 126 the requested command (file) can\'t be executed (but was found) + 127 command (file) not found + 128 according to ABS it\'s used to report an invalid argument to the exit builtin, but I wasn\'t able to verify that in the source code of Bash (see code 255) + 128 + N the shell was terminated by the signal N (also used like this by various other programs) + 255 wrong argument to the exit builtin (see code 128) + +The lower codes 0 to 125 are not reserved and may be used for whatever +the program likes to report. A value of **0 means successful** +termination, a value **not 0 means unsuccessful** termination. This +behavior (== 0, != 0) is also what Bash reacts on in some code flow +control statements like `if` or `while`. + +## Portability + +Tables of shell behavior involving non-portable side-effects or common +bugs with exit statuses. Note heirloom doesn\'t support pipeline +negation (`! pipeline`). + +### Misc + + -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + test bash\ bash\ zsh 5.0.2\ ksh93\ mksh\ posh\ dash\ busybox\ heirloom\ + 4.2.45 (POSIX) (emulate ksh) 93v- 2013-03-18 R44 2013/02/24 0.11 0.5.7.3 1.2.1 050706 + ----------------------------------------------------------------------------------------------------- -------- --------- --------------- ----------------- ---------------- ------- --------- ---------- ----------- + `` :; : `false` `echo $? >&2` `` 1 1 1 1 0 0 0 0 1 + + `false; eval; echo $?` 0 0 0 0 0 1 0 1 0 + + `` x=`false` eval echo \$? `` 1 1 1 1 0 0 0 0 1 + + `` eval echo \$? <&0`false` `` 1 1 1 1 0 0 0 0 1 + + `while :; do ! break; done; echo $?` 1 1 1 1 0 0 1 1 \- + + [discussion](https://lists.gnu.org/archive/html/bug-bash/2010-09/msg00009.html)`false; : | echo $?` 1 1 1 0 1 1 1 1 0 + + `` (exit 2); for x in "`exit 3`"; do echo $?; done `` 3 3 3 3 2 2 0 0 3 + -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + +### functions + +Measuring side-effects during the function call, during return, and +transparency of the return builtin. + + ------------------------------------------------------------------------------------------------------------------------------------------- + test bash bash\ zsh\ ksh93 mksh posh dash busybox heirloom + (POSIX) (emulate ksh) + -------------------------------------------------------- ------ --------- --------------- ------- ------ ------ ------ --------- ---------- + `` f() { echo $?; }; :; f `false` `` 1 1 1 1 0 0 0 0 1 + + `f() { return; }; false; f; echo $?` 1 1 1 0 1 1 1 1 1 + + `f() { return $?; }; false; f; echo $?` 1 1 1 1 1 1 1 1 1 + + `f() { ! return; }; f; echo $?` 0 0 1 0 0 0 1 1 \- + + `f() { ! return; }; false; f; echo $?` 1 1 0 0 1 1 0 0 \- + + `` f() { return; }; x=`false` f; echo $? `` 1 1 1 1 0 0 0 0 0 + + `` f() { return; }; f <&0`false`; echo $? `` 1 1 1 1 0 0 0 0 1 + + `` f() { x=`false` return; }; f; echo $? `` 1 1 1 0 0 0 0 0 1 + + `` f() { return <&0`false`; }; f; echo $? `` 1 1 1 0 0 0 0 0 1 + + `` f() { x=`false` return <&0`false`; }; f; echo $? `` 1 1 1 1 0 0 0 0 1 + ------------------------------------------------------------------------------------------------------------------------------------------- + +### case..esac + +Statuses measured within the command and after, with matching and +non-matching patterns. + + ------------------------------------------------------------------------------------------------------------------------------------------------- + test bash bash\ zsh\ ksh93 mksh posh dash busybox heirloom + (POSIX) (emulate ksh) + -------------------------------------------------------------- ------ --------- --------------- ------- ------ ------ ------ --------- ---------- + `(exit 2); case x in x) echo $?;; esac` 2 2 0 2 2 2 0 0 2 + + `` (exit 2); case `exit 3`x in x) echo $?;; esac `` 3 3 0 3 2 2 0 0 3 + + `` (exit 2); case x in `exit 4`x) echo $?;; esac `` 4 4 4 4 2 2 0 0 4 + + `` (exit 2); case `exit 3`x in `exit 4`x) echo $?;; esac `` 4 4 4 4 2 2 0 0 4 + + `(exit 2); case x in x);; esac; echo $?` 0 0 0 0 0 0 0 0 2 + + `(exit 2); case x in "");; esac; echo $?` 0 0 0 0 0 0 0 0 2 + + `` (exit 2); case `exit 3`x in x);; esac; echo $? `` 0 0 0 3 0 0 0 0 3 + + `` (exit 2); case `exit 3`x in "");; esac; echo $? `` 0 0 0 3 0 0 0 0 3 + + `` (exit 2); case x in `exit 4`x);; esac; echo $? `` 0 0 0 4 0 0 0 0 4 + + `` (exit 2); case x in `exit 4`);; esac; echo $? `` 0 0 4 4 0 0 0 0 4 + + `` (exit 2); case `exit 3`x in `exit 4`);; esac; echo $? `` 0 0 4 4 0 0 0 0 4 + + `` (exit 2); case `exit 3`x in `exit 4`x);; esac; echo $? `` 0 0 0 4 0 0 0 0 4 + ------------------------------------------------------------------------------------------------------------------------------------------------- diff --git a/docs/dict/file.md b/docs/dict/file.md new file mode 100644 index 0000000..d83d86e --- /dev/null +++ b/docs/dict/file.md @@ -0,0 +1,24 @@ +# File + +A file is a pool of data in the [filesystem](/dict/terms/filesystem). On +userlevel, it\'s referenced using a name, a +[hardlink](/dict/terms/hardlink) to the file. + +If a file is not referenced anymore (number of hardlinks to it drops to +0) then the space allocated for that file is re-used, unless it\'s still +used by some process. + +The file-data splits into actual payload (file contents) and some +metadata like filesize, filemode or timestamps. The metadata is stored +in the [inode](/dict/terms/inode). + +Strictly spoken, a [hardlink](/dict/terms/hardlink) (also called +\"filename\") points to the [inode](/dict/terms/inode) which organizes a +file, not to the file itself. + +## See also + +- [filesystem](/dict/terms/filesystem) +- [filetimes](/dict/terms/filetimes) +- [hardlink](/dict/terms/hardlink) +- [inode](/dict/terms/inode) diff --git a/docs/dict/filetimes.md b/docs/dict/filetimes.md new file mode 100644 index 0000000..00c8a44 --- /dev/null +++ b/docs/dict/filetimes.md @@ -0,0 +1,23 @@ +# File timestamp + +## atime + +This timestamp indicates when a file was last accessed (read). `cat`ing +a file or executing a shellscript will set it, for example. + +## ctime + +This timestamp is set, whenever the metadata of a file (stored in the +responsible inode) is set. The metadata includes for example: + +- file name +- fize size +- file mode (permissions) + +and some other things. `ctime` will also be updated when a file is +written to (when `mtime` is updated. + +## mtime + +The mtime is set, whenever a file\'s contents are changed, for example +by editing a file. diff --git a/docs/dict/globbing.md b/docs/dict/globbing.md new file mode 100644 index 0000000..698767b --- /dev/null +++ b/docs/dict/globbing.md @@ -0,0 +1,31 @@ +# Globbing + +Globbing is the procedure of + +- matching all filenames against a given pattern +- expanding to all matching filenames + +Unlike MSDOS, where the called program had to interpret the patterns, +the globbing on UNIX(r) is done by the shell, the matched filenames are +given as parameters to a called command: + + $ cat *.txt + +really executes + + $ cat 1.txt 3.txt foobar.txt XXX.txt + +The term \"glob\" originates back in the UNIX(r) days where an +executable `glob` (from \"global\") existed which was used to expand +pattern-matching characters. Later, this functionality was built into +the shell. There\'s still a library function called `glob()` (POSIX(r)), +which serves the same purpose. + +## See also + +- [shell](/dict/terms/shell) +- [hardlink](/dict/terms/hardlink) + +## See also (article) + +- [pathname expansion](/syntax/expansion/globs) diff --git a/docs/dict/hardlink.md b/docs/dict/hardlink.md new file mode 100644 index 0000000..d355ca9 --- /dev/null +++ b/docs/dict/hardlink.md @@ -0,0 +1,51 @@ +# Hardlink + +Also the article for: + +- filename + +A hardlink associates a *filename* with a [file](/dict/terms/file). That +name is an entry in a directory listing. Of course a file can have more +hardlinks to it (usually the number of hardlinks to a file is limited), +but all hardlinks to a file must reside on the same +[filesystem](/dict/terms/filesystem) as the file itself! + +What you usually call a file is just a name for that file, and thus, a +hardlink. + +The difference between a [symbolic link](/dict/terms/symlink) and a hard +link is that there is no easy way to differentiate between a \'real\' +file and a hard link, let\'s take a look at the example: + +\* create an empty file + + $ touch a + +\* create a hard link \'b\' and sym link \'c\' to empty file + + $ ln a b + $ ln -s a c + +as you can see file(1) can\'t differentiate between a real file \'a\' +and a hard link \'b\', but it can tell \'c\' is a sym link + + $ file * + a: empty + b: empty + c: symbolic link to `a' + +`ls -i` prints out the inode numbers of files, if two files have the +same inode number AND are on the same file system it means they are +**hardlinked**. + + $ ls -i * + 5262 a 5262 b 5263 c + +hard links don\'t consume additional space on the filesystem, the space +is freed when the last hard link pointing to it is deleted. + +## See also + +- [file](/dict/terms/file) +- [filesystem](/dict/terms/filesystem) +- [symlink](/dict/terms/symlink) diff --git a/docs/dict/interpreter_directive.md b/docs/dict/interpreter_directive.md new file mode 100644 index 0000000..a81a27a --- /dev/null +++ b/docs/dict/interpreter_directive.md @@ -0,0 +1,35 @@ +# Interpreter Directive + +- shebang + +The interpreter directive, usually called shebang, is the character +sequence starting with `#!` (hash, exclamation-point) at the beginning +of the very first line of an executable text file on unixoid operating +systems. + +The program loader of the operating system may use this line to load an +interpreter for this file when executed. This makes it a self-executable +script. + +A shebang will typically look like + + #!/bin/bash + +Since the line starting with `#` is a comment for the shell (and some +other scripting languages), it\'s ignored. + +Regarding the shebang, there are various, differences between operating +systems, including: + +- may require a space after `#!` and before the pathname of the + interpreter +- may be able to take arguments for the interpreter +- \... + +POSIX(r) doesn\'t specify the shebang, though in general it\'s commonly +supported by operating systems. + +## See also + +- [#!-magic](http://www.in-ulm.de/~mascheck/various/shebang/) - a nice + overview of the differences between various operating systems diff --git a/docs/dict/parameter.md b/docs/dict/parameter.md new file mode 100644 index 0000000..9778bfc --- /dev/null +++ b/docs/dict/parameter.md @@ -0,0 +1,67 @@ +# Parameter + +Also the article for: [variable]{.underline}, [positional +parameter]{.underline}, [special parameter]{.underline} + +In Bash, a parameter is simply an entity that stores values and can be +referenced. Depending on the type, the parameters can be set directly, +only indirectly, or only automatically by the shell. + +Bash knows 3 types of parameters: + +- variables +- positional parameters +- special parameters + +## variables + +A shell variable is a parameter denoted by a *variable name*: + +- containing only alphanumeric characters and underscores +- beginning with an alphabetic character or an underscore + +A value can be assigned to a variable, using the variable\'s name and an +equal-sign: + + NAME=VALUE + +Once a variable is set, it exists and can only be unset by the `unset` +builtin command. + +The nullstring is a valid value: + + NAME= + NAME="" + +## positional parameters + +A positional parameter is denoted by a number other than `0` (zero). + +Positional parameters reflect the shell\'s arguments that are not given +to the shell itself (in practise, the script arguments, also the +function arguments). You can\'t directly assign to the positional +parameters, however, [the set builtin command](/commands/builtin/set) +can be used to indirectly set them. + +The first to ninth positional parameter is referenced by `$1` to `$9`. +All following positional parameters (tenth and above) must be referenced +by the number given in curly braces, i.e., `${10}` or `${432}`. + +Unlike popular belief, `$0` is *not a positional parameter*. + +See also the [scripting article about handling positional +parameters](/scripting/posparams). + +## special parameters + +There are a bunch of special parameters, which are set by the shell. +Direct assignment to them is not possible. These parameter names are +formed of one character. + +Please see [shellvars](/syntax/shellvars). + +## See also + +- Syntax article, internal: [pe](/syntax/pe) +- Syntax article, internal: [shellvars](/syntax/shellvars) +- Scripting article, internal: [posparams](/scripting/posparams) diff --git a/docs/dict/posix.md b/docs/dict/posix.md new file mode 100644 index 0000000..5d699a4 --- /dev/null +++ b/docs/dict/posix.md @@ -0,0 +1,16 @@ +# POSIX + +POSIX(r) is a family of standards defined by the IEEE to give a minimum +API and interface standardization across the variants of UNIX(r) +operating systems. + +One part of it is the standardization of minimum functionality and +behaviour of the system shell and some utilities (commands). + +- UNIX is a registered trademark of The Open Group in the US and other + countries. +- POSIX is a registered trademark of the IEEE Inc. + +## See also + +- Dictionary, internal: [shell](/dict/terms/shell) diff --git a/docs/dict/shell.md b/docs/dict/shell.md new file mode 100644 index 0000000..d416b80 --- /dev/null +++ b/docs/dict/shell.md @@ -0,0 +1,19 @@ +# Shell + +On UNIX(r), the shell is the main interaction tool between the +user-level and the system. That doesn\'t necessarily mean the user +always sits infront of a shell, but it\'s integral part of the system, +not only an \"optional commandline interpreter\". + +The main job of a shell is to execute commands as a user requests them. +This behaviour alone doesn\'t help much. A shell knits some intelligence +and flow control around the possibility to execute commands - it\'s a +complete commandline-oriented user-interface (UI). + +FIXME + +## See also + +## See also (external) + +- Wikipedia: [UNIX shell](http://en.wikipedia.org/wiki/Unix_shell) diff --git a/docs/dict/special_file.md b/docs/dict/special_file.md new file mode 100644 index 0000000..b7d168d --- /dev/null +++ b/docs/dict/special_file.md @@ -0,0 +1,19 @@ +# Special file + +Unlike a regular file (a bunch of accessible data organized on a +filesystem), it\'s a special filename that points to a ressource or +similar: + +- character special files +- block special files +- named pipes +- socket files + +Since a directory also is only a file, you can count it as special file, +too. + +## See also + +- [file](/dict/terms/file) +- [filename](/dict/terms/hardlink) +- [directory](/dict/terms/directory) diff --git a/docs/dict/symlink.md b/docs/dict/symlink.md new file mode 100644 index 0000000..6b1a7d0 --- /dev/null +++ b/docs/dict/symlink.md @@ -0,0 +1,15 @@ +# Symlink + +A symlink (symbolic link) is a \"normal\" file, which contains a pointer +to another filename. Since it really only points to another **filename** +it can + +- reference filenames on other filesystems +- reference filenames that don\'t actually exist +- save a reference to the name of a directory + +## See also + +- [hardlink](/dict/terms/hardlink) +- [filesystem](/dict/terms/filesystem) +- [directory](/dict/terms/directory)