hyperreal/bash-hackers-wiki
1
0
Fork 0
mirror of https://github.com/flokoe/bash-hackers-wiki.git synced 2024-11-01 06:53:05 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Convert files under dict to Markdown

Browse Source
This commit is contained in:
flokoe 2023-07-05 11:06:16 +02:00
parent 1406408dff
commit 024e1bcc0e
13 changed files with 486 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/dict/directory.md Normal file
View File

@ -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)

31
docs/dict/end_of_options.md Normal file
View File

@ -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)

140
docs/dict/exit_status.md Normal file
View File

@ -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
-------------------------------------------------------------------------------------------------------------------------------------------------

24
docs/dict/file.md Normal file
View File

@ -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)

23
docs/dict/filetimes.md Normal file
View File

@ -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.

31
docs/dict/globbing.md Normal file
View File

@ -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)

51
docs/dict/hardlink.md Normal file
View File

@ -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)

35
docs/dict/interpreter_directive.md Normal file
View File

@ -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

67
docs/dict/parameter.md Normal file
View File

@ -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)

16
docs/dict/posix.md Normal file
View File

@ -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)

19
docs/dict/shell.md Normal file
View File

@ -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)

19
docs/dict/special_file.md Normal file
View File

@ -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)

15
docs/dict/symlink.md Normal file
View File

@ -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)