Release v2.1.0 and v1.1.0

.gitignore

@@ -1,2 +1,2 @@
-node_modules
-commoncodes.7
+/commoncodes*.7
+/node_modules

CHANGELOG.md

@@ -6,6 +6,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2021-11-01 ##
+
+[2.1.0]: https://github.com/mfederczuk/commoncodes/compare/v2.0.0...v2.1.0
+
+### Changed ###
+
+* status 101 (`not enough memory`) message and description
+  * message: `not enough [heap ]memory` → `not enough [(heap|kernel) ]memory`
+  * description: _"**[...]** free memory on the heap to allocate a block of data."_ →
+     _"**[...]** free memory (either heap or kernel memory) to perform an operation."_
+
 ## [2.0.0] - 2020-04-13 ##
 
 [2.0.0]: https://github.com/mfederczuk/commoncodes/compare/v1.0.0...v2.0.0
@@ -53,6 +64,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * status 30: `divided by 0 error`
 * status 31: `(overflow|underflow) error`
 
+## [1.1.0] - 2021-11-01 ##
+
+[1.1.0]: https://github.com/mfederczuk/commoncodes/compare/v1.0.0...v1.1.0
+
+### Changed ###
+
+* status 100 (`not enough memory`) message and description
+  * message: `not enough [heap ]memory` → `not enough [(heap|kernel) ]memory`
+  * description: _"**[...]** free memory on the heap to allocate a block of data."_ →
+     _"**[...]** free memory (either heap or kernel memory) to perform an operation."_
+
 ## [1.0.0] - 2019-05-11 ##
 
 [1.0.0]: https://mfederczuk.github.io/commoncodes/v/0.3.0...1.0.0.html

README.md

@@ -1,8 +1,8 @@
 # CommonCodes #
 
-[version_shield]: https://img.shields.io/badge/version-2.0.0-blue.svg
+[version_shield]: https://img.shields.io/badge/version-2.1.0-blue.svg
 [latest_release]: https://mfederczuk.github.io/commoncodes "Latest Release"
-[![version: 2.0.0][version_shield]][latest_release]
+[![version: 2.1.0][version_shield]][latest_release]
 [![Changelog](https://img.shields.io/badge/-Changelog-blue.svg)](./CHANGELOG.md "Changelog")
 
 ## About ##

commoncodes1.7

@@ -0,0 +1,278 @@
+.\" generated: 2021-11-01T20:09:33Z
+.TH COMMONCODES 7 "2021-11-01" "1.1.0" "CommonCodes man page"
+
+.SH NAME
+.P
+CommonCodes \- Standardized list of commonly used exit statuses
+
+.SH DESCRIPTION
+.P
+\fBCommonCodes\fR is an attempt to standardize the meaning of exit statuses of programs written for \fBUnix\fR like systems.
+
+.P
+\fBCommonCodes\fR includes the 15 exit codes defined by \fBBSD\fR in \fI\,sysexits.h\/\fR that range from 64 to 78.
+
+.P
+\fBGNU\fR \fBBash\fR uses the exit status 2 to indicate incorrect usage of shell builtins. \fBBash\fR also uses codes above 125 for special exit statuses like termination by a sent signal.
+.br
+\fBCommonCodes\fR adopts both of these rules, using 2 as a generic usage error and not defining any codes above 125.
+
+.P
+If you're going to use the \fBCommonCodes\fR standard in your program, be sure to document it. A good place would be both the \fI\,\-\-help\/\fR summary and the programs manpage.
+.br
+It is recommended to always add which exact version is being used.
+
+.P
+Some ranges have been kept empty so that developers may add error messages of their own, tailored to the program that they are writing.
+.br
+If statuses in these ranges are defined then they should also always be documented. Again in the \fI\,\-\-help\/\fR summary and in the manpage.
+
+.P
+In the following table, these rules apply for the status messages:
+
+.IP \[bu] 2
+Italic and/or underlined symbols are placeholders for other text that should get replaced for real messages.
+.IP \[bu]
+Text and symbols in bold square brackets may be ommitted in real messages.
+.IP \[bu]
+Text and symbols followed by bold ellipsis may be repeated one or more times in real messages.
+.IP \[bu]
+In real messages, only one field of text and symbols may be displayed if they are separated by bold vertical bars(|).
+.P
+
+.P
+Some status messages have the suffix \fB[\fR: \fI\,info\/\fR\fB]\fR appendend to them and a lot of usage errors about arguments also contain the placeholder \fI\,option\/\fR.
+.br
+\fI\,info\/\fR may be more information on what the error represents and why it happened.
+.br
+\fI\,option\/\fR may be either a \fBPOSIX\fR short option or a \fBGNU\fR long option, if that option received the argument that is invalid except the program itself.
+
+.SH EXIT STATUS TABLE
+.IP "\fBExit Code\fR" 12
+\fBMessage\fR
+.br
+\fBDescription\fR
+.IP "0"
+success
+.br
+The program executed successfully or the \fI\,\-\-help\/\fR or the \fI\,\-\-version\/\fR options were specified.
+.IP "1"
+generic error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+Any other error that doesn't fit in any other category.
+.IP "2"
+generic usage error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+Any other program usage error that doesn't fit in any other category.
+.IP "3"
+\fB[\fR\fI\,option\/\fR: \fB]\fRmissing argument\fB[\fRs\fB]\fR\fB[\fR: \fI\,arguments\/\fR\fB...\fR\fB]\fR
+.br
+Not enough arguments have been passed down to the program or to an option of the program.
+.br
+\fI\,arguments\/\fR may be the placeholder name of the missing arguments.
+.IP "4"
+\fB[\fR\fI\,option\/\fR: \fB]\fRtoo many arguments\fB[\fR: \fI\,n\/\fR\fB]\fR
+.br
+Too many arguments have been passed down to the program or to an option of the program.
+.br
+\fI\,n\/\fR may be the amount of arguments that are not needed.
+.IP "5"
+\fI\,option\/\fR: invalid option
+.br
+The entered option is not specified in the program.
+.IP "6"
+\fI\,option\/\fR: unexpected option
+.br
+The seen option at this position with the set combination and order of arguments and other options is invalid.
+.IP "7"
+\fB[\fR\fI\,option\/\fR: \fB]\fR\fI\,argument\/\fR: invalid argument\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+The argument is invalid and cannot be used.
+.IP "8"
+\fI\,argument\/\fR: unknown \fB[\fRsub\fB]\fRcommand
+.br
+The entered (sub)command of the program is not known.
+.IP "9"
+\fB[\fR\fI\,option\/\fR: \fB]\fRargument \fB[\fR\fI\,n\/\fR: \fB]\fRmay not be \fB(\fRempty\fB|\fRblank\fB)\fR
+.br
+Program can not work with empty or blank argument.
+.br
+"Blank" means none or only whitespace characters.
+.br
+\fI\,n\/\fR is the position of the argument that is empty/blank and is only really needed when the program/option needs multiple arguments.
+.IP "10"
+\fB[\fR\fI\,option\/\fR: \fB]\fR\fI\,argument\/\fR: not a\fB[\fRn\fB]\fR \fB(\fRnumber\fB|\fRinteger\fB)\fR
+.br
+The argument is not a valid number or is not a valid integer.
+.IP "11"
+\fB[\fR\fI\,option\/\fR: \fB]\fR\fI\,argument\/\fR: out of range\fB[\fR (\fI\,relational_op\/\fR \fI\,limit\/\fR)\fB]\fR
+.br
+The numerical argument is out of the given range.
+.br
+\fI\,relational_op\/\fR may be the four relational operators: \fI\,<=\/\fR, \fI\,<\/\fR, \fI\,>\/\fR or \fI\,>=\/\fR
+.br
+\fI\,limit\/\fR may either be the minumum, floor, maximum or ceiling value.
+.IP "12"
+\fB[\fR\fI\,option\/\fR: \fB]\fR\fI\,argument\/\fR: does not match: \fI\,pattern\/\fR
+.br
+The argument does not match the pattern provided. The pattern can be glob, regex or any other pattern matching system.
+.IP "13 - 23"
+\fB(custom usage errors)\fR
+.br
+Usage errors defined by the developer of the program. These should always be documented.
+.IP "24"
+\fI\,item\/\fR: no such \fI\,itemtype\/\fR\fB[\fR\fB[\fR, \fI\,itemtype\/\fR\fB]\fR\fB...\fR or \fI\,itemtype\/\fR\fB]\fR
+.br
+The item in question could not be found.
+.br
+\fI\,item\/\fR can be things like paths, etc. and \fI\,itemtype\/\fR can be things like regular files, directories, etc.
+.IP "25"
+\fI\,item\/\fR: not a\fB[\fRn\fB]\fR \fI\,itemtype\/\fR\fB[\fR\fB[\fR, \fI\,itemtype\/\fR\fB]\fR\fB...\fR or \fI\,itemtype\/\fR\fB]\fR
+.br
+The item in question is of the wrong type.
+.IP "26"
+network error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+A general network error occurred.
+.IP "27"
+no network connection
+.br
+No network connection is established.
+.IP "28"
+connection timed out
+.br
+A network request took too long and timed out.
+.IP "29"
+arithmetic error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+A general arithmetic error occurred.
+.IP "30"
+divided by 0 error
+.br
+A division by 0 was tried to be executed and there was no fallback option.
+.IP "31"
+\fB(\fRoverflow\fB|\fRunderflow\fB)\fR error
+.br
+An overflow or underflow happened and it has critical effects on the program.
+.IP "32 - 47"
+\fB(custom feedback statuses)\fR
+.br
+Custom exit codes defined by the developer that aren't actually errors, but rather, feedback for the program user.
+.br
+For example, the program \fBgrep\fR exits with code 1 when it couldn't match an entered pattern.
+.IP "48 - 63"
+\fB(custom errors)\fR
+.br
+General custom errors defined by the developer. These should always be documented.
+.IP "64"
+command line usage error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+The command was used incorrectly, e.g., with the wrong number of arguments, a bad flag, a bad syntax in a parameter, or whatever.
+.IP "65"
+data format error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+The input data was incorrect in some way.
+.IP "66"
+cannot open input\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+An input file (not a system file) did not exist or was not readable. This could also include errors like "No message" to a mailer (if it cared to catch it).
+.IP "67"
+addressee unknown\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+The user specified did not exist.
+.IP "68"
+host name unknown\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+The host specified did not exist.
+.IP "69"
+service unavailable\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+A service is unavailable. This can occur if a support program or file does not exist.
+.IP "70"
+internal software error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+An internal software error has been detected.
+.IP "71"
+system error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+An operating system error has been detected.
+.IP "72"
+critical OS file missing\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+Some system file (e.g., /etc/passwd, /etc/utmp, etc.) does not exist, cannot be opened, or has some sort of error (e.g., syntax error).
+.IP "73"
+can't create \fB(\fRuser\fB)\fR output file\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+A (user specified) output file cannot be created.
+.IP "74"
+input/output error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+An error occurred while doing I/O on some file.
+.IP "75"
+temp failure\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+Temporary failure, indicating something that is not really an error.
+.IP "76"
+remote error in protocol\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+The remote system returned something that was "not possible" during a protocol exchange.
+.IP "77"
+permission denied\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+You did not have sufficient permission to perform the operation.
+.IP "78"
+configuration error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+Something was found in an unconfigured or misconfigured state.
+.IP "79 - 98"
+\fB(custom configuration errors)\fR
+.br
+Configuration, property and setting errors defined by the developer. These should always be documented.
+.IP "99"
+memory error\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+A general memory error occurred.
+.IP "100"
+not enough \fB[\fR\fB(\fRheap\fB|\fRkernel\fB)\fR \fB]\fRmemory
+.br
+There was not enough free memory (either heap or kernel memory) to perform an operation.
+.IP "101"
+stack overflow error
+.br
+A stack overflow occurred.
+.IP "102"
+generic internal fault\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+General internal fault.
+.br
+An internal fault happens when preconditions prevent the program to advance to a next stage of execution.
+.IP "103 - 122"
+\fB(custom internal faults)\fR
+.br
+Different internal faults, defined by the developer. These should always be documented.
+.IP "123"
+emergency stop\fB[\fR: \fI\,info\/\fR\fB]\fR
+.br
+The program was intentionally halted by the developer because a value is invalid and can't be worked with.
+.IP "124"
+script was \fB[\fRnot \fB]\fRcalled interactively
+.br
+The shell script can either only be executed interactively (using command "." or "source"), or not interactively (executing via "./").
+.IP "125"
+unknown error
+.br
+Cause of error is not known, not even to the developer.
+.P
+
+.SH FOOTNOTES
+.P
+Since exit code 2 (generic usage error) and exit code 64 (command line usage error) are basically the same, it is recommended to use code 2 when distributing for \fBGNU/Linux\fR systems and code 64 when distributing for \fBBSD\fR systems.
+
+.SH SEE ALSO
+.P
+<https://github.com/mfederczuk/commoncodes>, grep(1)
+
+.SH AUTHORS
+.P
+Michael Federczuk
+<federczuk.michael@protonmail.com>

commoncodes.7 → commoncodes2.7

@@ -1,6 +1,5 @@
-.\" generated: 2020-04-13T15:24:11Z
-
-.TH commoncodes 7 "2.0.0" "April 13, 2020" "CommonCodes man page"
+.\" generated: 2021-11-01T20:09:33Z
+.TH COMMONCODES 7 "2021-11-01" "2.1.0" "CommonCodes man page"
 
 .SH NAME
 .P
@@ -252,9 +251,9 @@ memory error\fB[\fR: \fI\,info\/\fR\fB]\fR
 .br
 A general memory error occurred.
 .IP "101"
-not enough \fB[\fRheap \fB]\fRmemory
+not enough \fB[\fR\fB(\fRheap\fB|\fRkernel\fB)\fR \fB]\fRmemory
 .br
-There was not enough free memory on the heap to allocate a block of data.
+There was not enough free memory (either heap or kernel memory) to perform an operation.
 .IP "102"
 stack overflow error
 .br