Re: [PATCH] : ls: clarify documentation of exit statuses

[Jim Meyering]

Ondřej Vašík <address@hidden> wrote:
> as reported in rh bz#446294 , ls is not very clear with it's exit status
> documentation. This patch should clarify it a bit.

Re: <http://thread.gmane.org/gmane.comp.gnu.coreutils.bugs/14764>

Thanks, Ondřej.  I've reworded things to be more accurate,
mentioned Greg and the buzilla URL in the commit log,
and added Greg's name/email to THANKS:

>From 50654566c77d1335870206f657507a2d1c23f628 Mon Sep 17 00:00:00 2001
From: =?utf-8?q?Ond=C5=99ej=20Va=C5=A1=C3=ADk?= <address@hidden>
Date: Thu, 9 Oct 2008 10:56:54 +0200
Subject: [PATCH] doc: ls: clarify exit status description

* src/ls.c (exit_status): Clarify comments.
(usage): Clarify exit status description in --help output.
* doc/coreutils.texi (ls invocation): Clarify exit status documentation
Reported by Greg Metcalfe in <http://bugzilla.redhat.com/446294>.
---
 THANKS             |    1 +
 doc/coreutils.texi |    7 +++++--
 src/ls.c           |   16 ++++++++++++----
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/THANKS b/THANKS
index e6e48b3..d06f755 100644
--- a/THANKS
+++ b/THANKS
@@ -201,6 +201,7 @@ Guochun Shi                         address@hidden
 GOTO Masanori                       address@hidden
 Greg Louis                          address@hidden
 Greg McGary                         address@hidden
+Greg Metcalfe                       address@hidden
 Greg Schafer                        address@hidden
 Greg Troxel                         address@hidden
 Greg Wooledge                       address@hidden
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index a0d2202..b7e044d 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -6073,8 +6073,11 @@ ls invocation

 @display
 0 success
-1 minor problems (e.g., a subdirectory was not found)
-2 serious trouble (e.g., memory exhausted)
+1 minor problems  (e.g., failure to access a file or directory not
+  specified as a command line argument.  This happens when listing a
+  directory in which entries are actively being removed or renamed.)
+2 serious trouble (e.g., memory exhausted, invalid option or failure
+  to access file or directory specified as a command line argument)
 @end display

 Also see @ref{Common options}.
diff --git a/src/ls.c b/src/ls.c
index e107162..108d669 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -715,11 +715,14 @@ static int exit_status;
 /* Exit statuses.  */
 enum
   {
-    /* "ls" had a minor problem (e.g., it could not stat a directory
-       entry).  */
+    /* "ls" had a minor problem.  E.g., while processing a directory,
+       ls obtained the name of an entry via readdir, yet was later
+       unable to stat that name.  This happens when listing a directory
+       in which entries are actively being removed or renamed.  */
     LS_MINOR_PROBLEM = 1,

-    /* "ls" had more serious trouble.  */
+    /* "ls" had more serious trouble (e.g., memory exhausted, invalid
+       option or failure to stat a command line argument.  */
     LS_FAILURE = 2
   };

@@ -4527,7 +4530,12 @@ colors, and can be set easily by the dircolors 
command.\n\
 "), stdout);
       fputs (_("\
 \n\
-Exit status is 0 if OK, 1 if minor problems, 2 if serious trouble.\n\
+Exit status:\n\
+0 if OK,
+1 if minor problems (e.g., failure to access a file or directory not\n\
+  specified as a command line argument\n\
+2 if serious trouble (e.g., memory exhausted, invalid option or failure\n\
+  to access a file or directory specified as a command line argument).\n\
 "), stdout);
       emit_bug_reporting_address ();
     }
--
1.6.0.2.514.g23abd3