(Synopsis): Document tar exit codes.

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index ed1dba92c0252947c2fc23c2825b0170aa7cc430..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
@@ -8800,8 +8820,8 @@ that precedes an archive member and contains a set of
 stored in the standard @code{ustar} header.  While optional for
 expanding sparse version 1.0 members, use of extended headers is
 mandatory when expanding sparse members in older sparse formats: v.0.0
-and v.0.1 (The sparse formats are described in detail in @pxref{Sparse
-Formats}).  So, for this format, the question is: how to obtain
+and v.0.1 (The sparse formats are described in detail in @ref{Sparse
+Formats}.)  So, for this format, the question is: how to obtain
 extended headers from the archive? 
 
 If you use a @command{tar} implementation that does not support PAX