-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcommoncodes1.7
278 lines (265 loc) · 10 KB
/
commoncodes1.7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
.\" generated: 2021-11-13T17:54:50Z
.TH COMMONCODES 7 "2021-11-13" "1.2.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]\fR\fB(\fRmay\fB|\fRmust\fB)\fR 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>