(Synopsis): Document tar exit codes.

diff --git a/doc/tar.texi b/doc/tar.texi
index 35e3959c3cbe3ec39d2e26842da6c8f973e27658..279d7d9f6f73075bf283d6d1a967ca10e5485bd8 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -1894,13 +1894,33 @@ All abnormal exits, whether immediate or delayed, should always be
 clearly diagnosed on @code{stderr}, after a line stating the nature of
 the error.
 
-@GNUTAR{} returns only a few exit statuses.  I'm really
-aiming simplicity in that area, for now.  If you are not using the
-@option{--compare} @option{--diff}, @option{-d}) option, zero means
-that everything went well, besides maybe innocuous warnings.  Nonzero
-means that something went wrong. Right now, as of today, ``nonzero''
-is almost always 2, except for remote operations, where it may be
-128.
+Possible exit codes of @GNUTAR{} are summarized in the following
+table:
+
+@table @asis
+@item 0
+@samp{Successful termination}.
+
+@item 1
+@samp{Some files differ}.  If tar was invoked with @option{--compare}
+(@option{--diff}, @option{-d}) command line option, this means that
+some files in the archive differ from their disk counterparts
+(@pxref{compare}).  If tar was given @option{--create},
+@option{--append} or @option{--update} option, this exit code means
+that some files were changed while being archived and so the resulting
+archive does not contain the exact copy of the file set.
+
+@item 2
+@samp{Fatal error}.  This means that some fatal, unrecoverable error
+occurred.
+@end table
+
+If @command{tar} has invoked a subprocess and that subprocess exited with a
+nonzero exit code, @command{tar} exits with that code as well.
+This can happen, for example, if @command{tar} was given some
+compression option (@pxref{gzip}) and the external compressor program
+failed.  Another example is @command{rmt} failure during backup to the
+remote device (@pxref{Remote Tape Server}).
 
 @node using tar options
 @section Using @command{tar} Options