man: Document and improve C/C++ programs exit codes

debian/changelog

@@ -16,6 +16,7 @@ dpkg (1.18.5) UNRELEASED; urgency=medium
     - Add missing quotes in man pages.
     - Document Source field version in deb-control(5).
     - Add new deb822(5) man page.
+    - Document and improve C/C++ programs exit codes in man pages.
 
  -- Guillem Jover <guillem@debian.org>  Fri, 25 Dec 2015 14:20:16 +0100
 

man/dpkg-deb.1

@@ -289,6 +289,16 @@ This currently only affects \fB\-\-extract\fP making it behave like
 .BR \-D ", " \-\-debug
 Enables debugging output. This is not very interesting.
 .
+.SH EXIT STATUS
+.TP
+.B 0
+The requested action was successfully performed.
+.TP
+.B 2
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+.
 .SH ENVIRONMENT
 .TP
 .B TMPDIR

man/dpkg-divert.1

@@ -97,6 +97,16 @@ Show the usage message and exit.
 .B \-\-version
 Show the version and exit.
 .
+.SH EXIT STATUS
+.TP
+.B 0
+The requested action was successfully performed.
+.TP
+.B 2
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+.
 .SH ENVIRONMENT
 .TP
 .B DPKG_ADMINDIR

man/dpkg-query.1

@@ -292,9 +292,15 @@ conversion nor error checking is done on them. To get the name of the
 The requested query was successfully performed.
 .TP
 .B 1
-Problems were encountered while parsing the command line or performing the
-query, including no file or package being found (except for
-\fB\-\-control\-path\fP).
+The requested query failed either fully or partially, due to no file or
+package being found (except for \fB\-\-control\-path\fP,
+\fB\-\-control\-list\fP and \fB\-\-control\-show\fP were such errors are
+fatal).
+.TP
+.B 2
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
 .
 .SH ENVIRONMENT
 .TP

man/dpkg-split.1

@@ -209,9 +209,10 @@ and indicates that the
 file was not a binary package part.
 .TP
 .B 2
-Some kind of trouble happened, such as a system
-call failure, a file that looked like a package part file but was
-corrupted, a usage error or some other problem.
+Fatal or unrecoverable error due to invalid command-line usage,
+a file that looked like a package part file but was corrupted, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
 .
 .SH FILES
 .TP

man/dpkg-statoverride.1

@@ -58,8 +58,7 @@ unchanged by this command.
 .TP
 .BR \-\-list " [\fIglob-pattern\fP]"
 List all overrides. If a glob pattern is specified restrict the output
-to overrides which match the glob. If there are no overrides or none
-match the glob \fBdpkg\-statoverride\fR will exit with an exitcode of 1.
+to overrides which match the glob.
 .TP
 .B \-\-help
 Show the usage message and exit.
@@ -84,6 +83,20 @@ exists.
 .B \-\-quiet
 Be less verbose about what we do.
 .
+.SH EXIT STATUS
+.TP
+.B 0
+The requested action was successfully performed.
+.TP
+.B 1
+For \fB\-\-list\fP, if there are no overrides or none match the supplied
+glob.
+.TP
+.B 2
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+.
 .SH ENVIRONMENT
 .TP
 .B DPKG_ADMINDIR

man/dpkg-trigger.1

@@ -78,6 +78,20 @@ It is currently the default behavior.
 .BR \-\-no\-act
 Just test, do not actually change anything.
 .
+.SH EXIT STATUS
+.TP
+.B 0
+The requested action was successfully performed.
+Or a check or assertion command returned true.
+.TP
+.B 1
+A check or assertion command returned false.
+.TP
+.B 2
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+.
 .SH ENVIRONMENT
 .TP
 .B DPKG_ADMINDIR

man/dpkg-vendor.1

@@ -32,12 +32,12 @@ information about the current vendor.
 .TP
 .BI \-\-is " vendor"
 Exits with \fB0\fP if the current vendor is \fIvendor\fP. Otherwise exits
-with non-zero.
+with \fB1\fP.
 .TP
 .BI \-\-derives\-from " vendor"
 Exits with \fB0\fP if the current vendor distribution is a derivative of
-\fIvendor\fP, otherwise exits with non-zero. It uses the \fBParent\fP field
-to browse all ancestors of the current vendor.
+\fIvendor\fP, otherwise exits with \fB1\fP.
+It uses the \fBParent\fP field to browse all ancestors of the current vendor.
 .TP
 .BI \-\-query " field"
 Print on standard output the value of the vendor-specific \fIfield\fP for

man/dpkg.1

@@ -370,8 +370,8 @@ Supports versioned \fBProvides\fP (since dpkg 1.17.11).
 .TP
 .B \-\-compare\-versions \fIver1 op ver2\fP
 Compare version numbers, where \fIop\fP is a binary operator. \fBdpkg\fP
-returns success (zero result) if the specified condition is satisfied,
-and failure (nonzero result) otherwise. There are
+returns true (\fB0\fP) if the specified condition is satisfied,
+and false (\fB1\fP) otherwise. There are
 two groups of operators, which differ in how they treat an empty
 \fIver1\fP or \fIver2\fP. These treat an empty version as earlier than any
 version: \fBlt le eq ne ge gt\fP. These treat an empty version as later
@@ -792,6 +792,20 @@ may leave packages in the improper \fBtriggers\-awaited\fP and
 \fB\-\-triggers\fP
 Cancels a previous \fB\-\-no\-triggers\fP (since dpkg 1.14.17).
 .
+.SH EXIT STATUS
+.TP
+.B 0
+The requested action was successfully performed.
+Or a check or assertion command returned true.
+.TP
+.B 1
+A check or assertion command returned false.
+.TP
+.B 2
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+.
 .SH ENVIRONMENT
 .SS External environment
 .TP

man/dselect.1

@@ -446,6 +446,16 @@ but provides a more obvious panic button in cases where the user
 pressed \fBenter\fP by accident.
 .sp
 .
+.SH EXIT STATUS
+.TP
+.B 0
+The requested command was successfully performed.
+.TP
+.B 2
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+.
 .SH ENVIRONMENT
 .TP
 .B HOME