This service will be undergoing maintenance at 00:00 UTC, 2016-08-01. It is expected to last about 1 hours
Bug 446294 - incorrect exit from 'ls'
incorrect exit from 'ls'
Status: CLOSED NEXTRELEASE
Product: Fedora
Classification: Fedora
Component: coreutils (Show other bugs)
8
i386 Linux
low Severity medium
: ---
: ---
Assigned To: Ondrej Vasik
Fedora Extras Quality Assurance
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2008-05-13 18:56 EDT by Greg Metcalfe
Modified: 2008-10-16 03:49 EDT (History)
4 users (show)

See Also:
Fixed In Version: coreutils-6.9-19.fc8
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2008-10-13 14:21:22 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:


Attachments (Terms of Use)

  None (edit)
Description Greg Metcalfe 2008-05-13 18:56:52 EDT
Description of problem:
'ls' does not exit in accordance with info page.

Version-Release number of selected component (if applicable):
coreutils-6.9-9.fc7

How reproducible:
Always

Steps to Reproduce:
1. ls no_dir
2. echo $?

Actual results:
2

Expected results:
1, according to info page, which specifically states that an ls on a missing dir returns 1. 
man page just says 1 for minor, 2 for major.

Additional info:
Makes it impossible to know when to either attempt to handle it, or bail. I think the 
problem exists on RH5, as well.
Comment 1 Ondrej Vasik 2008-05-14 03:11:01 EDT
Thanks for report, the same is for upstream, rawhide and RHEL-5 coreutils. In
source code relevant to that situation is comment 

/* Failure to stat a command line argument leads to
   an exit status of 2.  For other files, stat failure
   provokes an exit status of 1.  */

so it does mean that current behaviour is intentional. Will check a bit more
about that - maybe change of info pages would be the best solution.

Comment 2 Bug Zapper 2008-05-14 11:30:30 EDT
This message is a reminder that Fedora 7 is nearing the end of life. Approximately 30 (thirty) days from now Fedora will stop maintaining and issuing updates for Fedora 7. It is Fedora's policy to close all bug reports from releases that are no longer maintained. At that time this bug will be closed as WONTFIX if it remains open with a Fedora 'version' of '7'.

Package Maintainer: If you wish for this bug to remain open because you plan to fix it in a currently maintained version, simply change the 'version' to a later Fedora version prior to Fedora 7's end of life.

Bug Reporter: Thank you for reporting this issue and we are sorry that we may not be able to fix it before Fedora 7 is end of life. If you would still like to see this bug fixed and are able to reproduce it against a later version of Fedora please change the 'version' of this bug. If you are unable to change the version, please add a comment here and someone will do it for you.

Although we aim to fix as many bugs as possible during every release's lifetime, sometimes those efforts are overtaken by events. Often a more recent Fedora release includes newer upstream software that fixes bugs or makes them obsolete. If possible, it is recommended that you try the newest available Fedora distribution to see if your bug still exists.

Please read the Release Notes for the newest Fedora distribution to make sure it will meet your needs:
http://docs.fedoraproject.org/release-notes/

The process we are following is described here: http://fedoraproject.org/wiki/BugZappers/HouseKeeping
Comment 3 Greg Metcalfe 2008-05-14 15:33:17 EDT
(In reply to comment #1)
> Thanks for report, the same is for upstream, rawhide and RHEL-5 coreutils. In
> source code relevant to that situation is comment 
>
I won't have a Fedora > 7 for another week, but I've confirmed upstream and RHEL-5 as 
well. If we don't wrap this before F7 goes off support, I'll either change the product ID to 
RHEL, or confirm on a later Fedora and change to that.

> /* Failure to stat a command line argument leads to
>    an exit status of 2.  For other files, stat failure
>    provokes an exit status of 1.  */
> 
> so it does mean that current behaviour is intentional. Will check a bit more
> about that - maybe change of info pages would be the best solution.
> 

OK, looking at ls.c from the GNU coreutils-6.9 tarball, I think you're right about the the 
coder's intent, and changing the info page being perhaps the best solution (with a 
possible proviso below). Here's another example, using the specific case of a missing 
subdirectory mentioned example used in info:
$ mkdir ls_test; echo $?; ls ls_test/no_dir; echo $?
0
ls: ls_test/no_dir: No such file or directory
2

The info page:
0 success
     1 minor problems (e.g., a subdirectory was not found)
     2 serious trouble (e.g., memory exhausted)

The man page is nonspecific enough to not be wrong. A change there would be nice, as 
well, as it's currently 'not even wrong' in a literal sense. :)

I think I (and the info page author?) may have been misled by the following comment in 
enum{}:
/* "ls" had a minor problem (e.g., it could not stat a directory entry).  */

Consider that in the context of this last example. I'd advocate tweaks to both enum{} 
comments, but I'd call it a fix if the info and man pages were changed.

Just for the sake of completeness: The Open Group Base Specifications Issue 6 (IEEE Std 
1003.1, 2004 Edition) provides no guidance. All they want is exit > 0 on an error:
http://www.opengroup.org/onlinepubs/009695399/utilities/ls.html
Comment 4 Ondrej Vasik 2008-05-15 03:25:59 EDT
I'm changing the product version to rawhide(as the behaviour is still same for
rawhide and the issue is not so severe(just partially misleading ls
documentation)). Change happened after release of RHEL-4 but before RHEL-5,
therefore RHEL-4 returns 1 and RHEL-5 returns 2 for missing dir. Just FYI, this
is the upstream commit with the change of ls exit code behaviour:
http://git.savannah.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=3a208b14048121755eb01377f985372561a4b953
Comment 5 Greg Metcalfe 2008-05-15 04:40:10 EDT
(In reply to comment #4)
> I'm changing the product version to rawhide(as the behaviour is still same for
> rawhide and the issue is not so severe(just partially misleading ls
> documentation)). Change happened after release of RHEL-4 but before RHEL-5,
> therefore RHEL-4 returns 1 and RHEL-5 returns 2 for missing dir. Just FYI, this
> is the upstream commit with the change of ls exit code behaviour:
> 
http://git.savannah.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=3a208b14048121755eb01377f985372561a4b953

Ondrej, thanks for the Savannah git link and RHEL-4 to -5 info. I have some internal 
things to check, based on that, and you've probably saved me a problem or two. Also 
thanks for confirming on rawhide, and changing Product ID, so I don't have to remember 
to keep this alive in a week or two, when things will likely be a bit crazy, and this might 
have fallen through the cracks. Much appreciated, both cases.
Comment 6 Greg Metcalfe 2008-08-18 22:36:40 EDT
It's been three months. Any progress, or should I just assume it may not be fixed for many more months, internally document, and add to the test case matrix? I know RH and GNU folk are busy, but I am too. After three months, I have to get off the dime.

Changed version to 8, as that's verified here, and I don't want this thought of as some future thing about rawhide. The problem is right here, right now, as a verifiable flaw in RHEL 5 and Fedora 8.

Would it speed the process in the future if I reported problems with the GNU userland via Savannah? I just want the fastest means to resolve the problem. Perhaps upstream should have been the way to go. I assumed (yes, I know that stale joke) that you guys had streamlined channels into the GNU org.

Guidance would be appreciated.
Comment 7 Ondrej Vasik 2008-08-19 02:52:35 EDT
I asked Jim Meyering (upstream maintainer of coreutils, employed in Red Hat - so that's the direct channel) in May about that issue. He said that the behaviour is correct and will not change and the only change could be in documentation - to clarify what missing subdir means or to choose different example of exit code 1 - and that he is not going to change it but will accept documentation patch to clarify that behaviour. I was not sure how to improve the documentation to make it clear and short and had some other issues with higher priority. Red Hat Bugzilla is usually the best way - as some things are a bit different in Red Hat version of coreutils (most differences in PAM and SELinux). I'm always informing Jim about new bugzillas which are relevant for upstream. You are right that three months are quiet a long time. I will try to find out proper formulation and possibly add this manpage improvement into upcoming RHEL-5 coreutils update (which should be in RHEL 5.3). If you have any wish/idea about the proper formulation for documentation, feel free to add it.
Comment 8 Greg Metcalfe 2008-08-19 05:22:03 EDT
I was fine with changing only the doc three months ago. That shouldn't be something we're discussing. I'll see what sort of verbiage I can come up with, and get back to you by Thursday or Friday. If you look at the time stamp on this, you can probably guess that it's a crazy week in Oregon.
Comment 9 John Poelstra 2008-08-19 10:43:07 EDT
This bug is open against FEDORA so we would hope/expect that it will be fixed here where non-RHEL subscribers can get the fix too :)

Also keep in mind that F8 will only be maintained until 1 month after the GA of Fedora 10.  If this bug is present in 'rawhide' change the version to 'rawhide'
Comment 10 Ondrej Vasik 2008-08-20 02:03:32 EDT
(In reply to comment #9)
> This bug is open against FEDORA so we would hope/expect that it will be fixed
> here where non-RHEL subscribers can get the fix too :)

I would not call it a bug, it is just a bit confusing documentation. This behaviour is expected - but we agreed to improve documentation. Documentation improvement will of course get into Fedora... but as it could be good to clarify it for RHEL-5 as well, I mentioned RHEL-5.3 update as well.

> Also keep in mind that F8 will only be maintained until 1 month after the GA of
> Fedora 10.  If this bug is present in 'rawhide' change the version to 'rawhide'

I guess we could keep it F8 at the moment as it is an easy and fast thing - IMHO adding one line should be enough. I guess there will be at least one F8 coreutils update until it's EOL.
Comment 11 Greg Metcalfe 2008-08-21 14:40:34 EDT
Current man page says:
Exit status is 0 if OK, 1 if minor problems, 2 if serious trouble.
Current info page says:
0 success
1 minor problems (e.g., a subdirectory was not found)
2 serious trouble (e.g., memory exhausted)

How about:
Exit status is 0 if OK. 1 if minor problems, e.g. failure to stat a non-command line file or directory. 2 if serious trouble, e.g. failure to stat a command line argument, an out of memory failure, etc.

Both info and man pages would have to changed.

I still think that the comments in the source are misleading, as per my comment #3. Not fixing comments is an invitation to regression, *clearly* makes reporting bugs more difficult, etc. But I have to pick my battles, and I'm hoping to get another submission in on man(5) yum.conf. Rather more extensive, though nothing like http://rhn.redhat.com/errata/RHBA-2008-0388.html.
Comment 12 Greg Metcalfe 2008-08-21 15:19:15 EDT
Reply to Comment #10, "I would not call it a bug, it is just a bit confusing documentation."

That's a philosophical distinction. To me, an important measure of software quality lies in whether it runs as it's documented to run. A flaw in docs, whether external to the sources, such as man pages, or internal, such as comments, can cause a lot of man-hour wastage. You can't quantify that, as you can have no idea of some random end-user's circumstances.

I regard any flaw in a shipping package as a bug, as it's a potentially serious disservice to that random end-user. If you want to have that discussion, we'd best take it off-line. We seem to have very different ideas about quality.
Comment 13 Jim Meyering 2008-10-13 03:12:37 EDT
Thanks for the report.
Fixed upstream with this patch:
  http://thread.gmane.org/gmane.comp.gnu.coreutils.bugs/14764/focus=14813
Comment 14 Fedora Update System 2008-10-13 06:07:16 EDT
coreutils-6.9-19.fc8 has been submitted as an update for Fedora 8.
http://admin.fedoraproject.org/updates/coreutils-6.9-19.fc8
Comment 15 Greg Metcalfe 2008-10-13 14:21:22 EDT
(In reply to comment #13)
> Thanks for the report.
> Fixed upstream with this patch:
>   http://thread.gmane.org/gmane.comp.gnu.coreutils.bugs/14764/focus=14813

I prefer your wording to mine in the info page. The man page hasn't been changed:

$ man ls | col -b | tail -n 27 | head -n 1
       Exit status is 0 if OK, 1 if minor problems, 2 if serious trouble.

I'd obviously prefer it to have been fixed in the man page as well, but this is good enough.
Comment 16 Jim Meyering 2008-10-13 15:08:53 EDT
Greg,

The man page should be updated, since it is generated from the output of ls --help, and since the patch updated ls's usage function, maybe your man page is out of date:

$ ./ls --help|tail -8
Exit status:
0 if OK,
1 if minor problems (e.g., failure to access a file or directory not
  specified as a command line argument
2 if serious trouble (e.g., memory exhausted, invalid option or failure
  to access a file or directory specified as a command line argument).

so you should definitely have the right content.
Hmm... but looking at the generated man page, I saw ugly formatting.
So I've just checked in another change to fix that.  Here's what I see now:

$ nroff -man man/ls.1|grep -B1 -A7 'if OK'
   Exit status:
       0      if OK,

       1      if  minor  problems (e.g., failure to access a file or directory
              not specified as a command line argument,

       2      if serious trouble (e.g., memory exhausted,  invalid  option  or
              failure  to  access  a  file or directory specified as a command
              line argument).
Comment 17 Greg Metcalfe 2008-10-13 15:58:24 EDT
Well, I rebooted before my last post, to give the best test I could. Just did it again, same result. Grabbed the -19 pkg again, but it has the same sha1sum as the first one I tested. So I don't know what to say.
Comment 18 Greg Metcalfe 2008-10-13 18:32:34 EDT

(In reply to comment #16)
> Greg,
> 
> The man page should be updated, since it is generated from the output of ls
> --help, and since the patch updated ls's usage function, maybe your man page is
> out of date:
> 
<snip>

$ ll /usr/share/man/man1/ls.1.gz
-rw-r--r-- 1 root root 3001 2008-10-13 02:50 /usr/share/man/man1/ls.1.gz
and it contains the "Exit status is 0 if OK, 1 if minor problems, 2 if serious trouble." that I expected it to.

If it helps:
$ md5sum coreutils-6.9-19.fc8.i386.rpm
aea0729a05cb600a8ccae1b173617691  coreutils-6.9-19.fc8.i386.rpm
$ sha1sum coreutils-6.9-19.fc8.i386.rpm
018ea277a6ef2ba7437b098a92a7dd1ebabf6cfe  coreutils-6.9-19.fc8.i386.rpm
$ ll coreutils-6.9-19.fc8.i386.rpm
-rw-rw-r-- 1 gregm gregm 3489698 2008-10-13 12:43 coreutils-6.9-19.fc8.i386.rpm
Comment 19 Greg Metcalfe 2008-10-13 19:27:31 EDT
Probably should have mentioned, since I sent you an 'll' output: I'm in Oregon. -7 hrs, PDT through 11/2/08.

I've unpacked the pending RPM:
https://admin.fedoraproject.org/updates/coreutils-6.9-19.fc8
which links to:
http://koji.fedoraproject.org/koji/buildinfo?buildID=66148
and verified that your man page changes aren't in it.

I grabbed a fresh copy, right at 1600 PDT, and verified the sha1 hash again. Same file. Nothing more I can test, without a fresh RPM. Perhaps I foxed the Fedora update system by closing the bug? If so, that would be a useful thing to know, as in, "Doctor, it hurts when I do this." "Then don't do that."

If you're satisfied that it's fixed, and your fixes actually will migrate through the system, then I'm satisfied as well. Heh, it's a holiday. Columbus day, when we should have all been off doing Columbus-y things, whatever those might be. Instead we're all chasing bug fixes.
Comment 20 Ondrej Vasik 2008-10-14 02:55:57 EDT
Jim is right that manpages should be generated from modified ls --help output, but it looks like they are not due to patching ls.1 by later RedHat patches. Therefore timestamp of manpage is newer than timestamp of the ls.c change and manpage is not updated. I will patch ls.1 manpage manually, but at the moment only in rawhide - I guess correct help and info page should be enough. In the case of the next update for F-8/F-9, I'll improve it there as well.
Comment 21 Greg Metcalfe 2008-10-14 15:14:28 EDT
Thanks Ondrej and Jim. It's been an interesting five month journey. Not complaining--I completely get meaning of severity: medium, pri: low. 

I'm interested in learning how the man pages are generated from 'ls --help' output. Is there a doc or example code either of you guys can send me to?
Comment 22 Fedora Update System 2008-10-15 22:07:51 EDT
coreutils-6.9-19.fc8 has been pushed to the Fedora 8 stable repository.  If problems still persist, please make note of it in this bug report.
Comment 23 Jim Meyering 2008-10-16 03:49:47 EDT
> I'm interested in learning how the man pages are generated

A good starting point is "man help2man".  That's the script that runs each program with the --help option, reads the output, then takes that and possibly other inputs and outputs troff for the man page.  For actual code, see the rule in man/Makefile.am that creates prog.1 from prog.x (.x.1:).

Note You need to log in before you can comment on or make changes to this bug.