Subject: Re: bug#9939: Problems with the SIZE description in man pages for <ls> and <du>

From: abdallah clark <[email-masked]>
Date: Thu, 3 Nov 2011 12:51:56 -0500

Dear Paul,

Thanks and more thanks must begin my message. I never expected this
much support and encouragement. So much of what I have heard about
Linux and UNIX shops is that they're closed-up environment where techs
are not helpful and "you've got to pay your dues" is the daily mantra
for new hires. Refreshing to see that the general community is
generous. Thanks.

In particular, your explanation of long options and short options was
an epiphany, since I had learned the hard way that I couldn't combine
options that have single hyphens and those with double hyphens.
Further, I'd seen that options with only one character used only one
hyphen and those with two characters, a full word or a hyphenated word
used two hyphens. Your explanation gave me more material to confirm
and expand upon that empirical denotation. Thanks again.

I started off in computing by taking an Honors class (there was no AP
back then) that taught us programming in Fortran III, so I understand
the long-standing traditions of keeping things short. Variable names
could only be one or two characters, so <dd>, <du> and <ls> are "old
friends"! However, modern memory and hard drive storage capacities are
such that descriptions in the man pages could be more helpful.

Succinctness is good for folks who slip into "discourses" (unlike
Voltaire  ;-)  ), but it would be great for newbies and those looking
at a command for the first time to give just a little more in some
cases. Also, as my instructor exemplifies, there are people who just
believe in playing with the system and others who "use the book." Man
pages and Internet searches are frustrating for a guy like me, then,
as the quality of info is irregular. Almost no one tells you whether a
command is root-level of authority only, or for general users. ??!

One aspect of what I'm trying to say is that the man pages include
examples in some cases, but in many cases they do not. Even when
examples are given, many are complex and not illustrative of how to
"just get it done." A simple example and a complex one would be best,
but it's rare to see.

For instance, the <man tee> pages only show one complex example. I
have never been successful using <tee> on my own for the simple cases,
so I gave up on it. Why should it be that way?? Internet results were
mostly verbatim copies of the man pages, so I was stuck.

I can only spend a certain amount of time researching, as there is so
much I need to learn and the Linux filesystems, admin tasks, other
commands, vi/vim, RPM, GRUB, shell programming, etc., for the RHELSA
certification exam. I figure that <ls> ought to one command that I
understand fully, otherwise I would have never expended the effort of
contacting [email-masked].

So, yes, I really wish the <ls --block-size> command was one of those
cases with examples, any examples at all. Let me show you some of my
attempts at "hacking" and "playing around" with <ls>, although it's
going to demonstrate my confusion, not my understanding.

First, consider the actual <man ls> extracted statement, as cited here:

   SIZE may be (or may be an integer optionally followed by) one of
   following: KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on
   for G, T, P, E, Z, Y.

So, I tried to use an integer followed by a character. That's what I
meant when I said
               >>  an implied evaluation as the description of SIZE
starts off by saying

Failure every time I tried to use the pattern:
--block-size=number+space+suffix

Trying the command with numerical values and suffixes:

<ls -alsi --block-size=1024KB>          Success, but no suffixes on the sizes
<ls -alsi --block-size=1KB>                 Success, but no suffixes
on the sizes
<ls -alsi --block-size=1MB>                Success, but no suffixes on the sizes
<ls -alsi --block-size=10K>                 Success, but no suffixes
on the sizes
<ls -alsi --block-size=10kB>               Success, but no suffixes on the sizes
<ls -alsi --block-size=10kb>                Fails; Invalid suffix in
--blocksize argument '10kb'

Also, when I run <ls -alsi --si>, the results have <K> or <M> or <G>
as a suffix on the filesize amounts, but the similar command <ls
-alsih> gives <k> or <m> or <g>. This is just one group of the cases
behind my statement: "I can see no rhyme or reason why I get lowercase
K, or KB or kB, etc. for the <ls> command, either." Another is given
later, with the "hackings" that had suffixes without numerical values.

Trying the command without any suffixes:

<ls -alsi --block-size=10>                    Success, but no suffixes
on the sizes
<ls -alsi --block-size=100>                  Success, but no suffixes
on the sizes
<ls -alsi --block-size=1024>                Success, but no suffixes
on the sizes
<ls -alsi --block-size=1000000>         Success, but no suffixes on the sizes

Trying the command with suffixes and no numerical values:

<ls -alsi --block-size=M>          Success, <M> suffix on the sizes
<ls -alsi --block-size=m>          Success, <M> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=kb>         Fails;  Invalid suffix in
--blocksize argument 'kb'
<ls -alsi --block-size=kB>        Success, <kB> suffix on the sizes
<ls -alsi --block-size=KB>        Success, <kB> suffix on the sizes  (
<KB> suffix expected, tho)
<ls -alsi --block-size=MB>       Success, <MB> suffix on the sizes
<ls -alsi --block-size=K>          Success, <K> suffix on the sizes
<ls -alsi --block-size=k>          Success, <K> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=mb>        Fails;  Invalid suffix in
--blocksize argument 'mb'
<ls -alsi --block-size=g>          Success, <G> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=t>            Success, <T> suffix on the sizes
(case is opposite of suffix)
<ls -alsi --block-size=EB>       Success, <K> suffix on the sizes
<ls -alsi --block-size=eb>        Failed; Invalid suffix in
--blocksize argument 'eb'
<ls -alsi --block-size=eB>        Failed; Invalid suffix in
--blocksize argument 'eB'  (differs from kB)

G, GB, T, TB, E, EB, P and PB worked. However, Z, ZB, Y and YB all
failed, despite what I see above. Error message said, "--block-size
argument . . . too large" where the ellipses are the suffixes.

Another set of issues revolve around the accuracy/precision of the
filesizes. <ls -alh> and <ls -al --block-size=k> were different only
in the number of decimal places shown to the right of the decimal
point, <ls -alh> showing one place and the other command showing none.
I tried a lot of combinations here, but I'll let this suffice for now.

Oh, you should know that I'm running CentOS 6 at home (Kernel is
2.6.32-71.el6.i686 on my laptop and the 64-bit on my desktop) and Red
Hat 6 at school. Bash is the default at both.

Also, I found that the <man dd> had a very different wording for the
SIZE argument. Also, there was an equals sign given between each
suffix and each numeric value.
Now things got really weird, when I tried to use a suffix and a
number, to attempt to understand the segment "may be one of the
following:  KB 1000, K 1024, MB 1000*1000, . . . "

Failure every time I used the pattern:      --block-size=suffix+space+number.
Failure every time I used the pattern:      --block-size=suffix+number
Failure every time I used the pattern:
--block-size=suffix+number+asterisk+number
Failure every time I used the pattern:      --block-size=number+asterisk+number
Failure every time I used the pattern:
--block-size=suffix+space+number+asterisk+number
            (Error message: "ls: cannot access 1024*1024: No such file
or directory")
Failure every time I used the pattern
--block-size=suffix=number+asterisk+number
                   (This last attempt was based on the <man dd> material.)

Since the number+suffix "sequence" worked in so many earlier cases, I
tried that here, too, but every attempt to do so failed:

Failure every time I used the pattern:
--block-size=number+asterisk+number+suffix
Failure every time I used the pattern:
--block-size=number+asterisk+number+suffix

The following attempt to evaluate the asterisk expression had
absolutely disastrous results:

<ls -alsi --block-size=`1000*1000`>  where the back-tick/grave accent
encloses the value.

Now, I saw a greater-than symbol on the next line as a prompt that
accepted characters until <exit> was supplied. Then the following
error message was presented:

>  -bash: unexpected EOF while looking for matching ``'
-bash: syntax error: unexpected end of file

Newbie me was very frustrated, to say the least. No smoke coming out
of my ears after all of this, but enough midnight oil was consumed
that I just went to bed, trying to forget about it all. Three lines of
text really caused me a lot of grief and I still don't understand it
any better than when I started, except for a few "no no, not that"s.

I await your response to these situations and thank you in advance for
your patience and consideration.

               All the best to you and yours,

                       Mr. Abdallah Clark

ls -alsi

On Thu, Nov 3, 2011 at 1:24 AM, Paul Eggert <[email-masked]> wrote:
> On 11/02/11 19:33, abdallah clark wrote:
>
>> am I to be able to use <1000*1000> or <1024*1024> in
>> either one of those commands?
>
> Not those exact strings, no.  At least, not as far as I know.
> But "MB" is short for 1000*1000, and "M" for 1024*1024.
>
>> I saw that I could use other numerics,
>> even odd amounts, but nothing with an implied evaluation as the
>> description of SIZE starts off by saying.
>
> Sorry, don't follow.  Perhaps an example would clarify?
>
>> I can see no rhyme or reason why I get lowercase K, or KB or
>> kB, etc. for the <ls> command, either.
>
> Again, I'm lost.  Got a specific example?
>
>> The same goes for the statement on mandatory options. Just what is a
>> long option as compared to a short option?
>
> A long option is something like --ignore='*.x'.
> A short option is something like -I '*.x'.
> Typically, for every short option there's an equivalent long
> option, but the reverse is not necessarily true.
>
>> How do I know what is
>> mandatory from what isn't?
>
> Optional arguments are written in square brackets in the
> documentation, e.g., --color[=WHEN].  This isn't written
> down in the man page, unfortunately.  It is described (not
> all that well) in the full manual, here:
>
> http://www.gnu.org/s/coreutils/manual/html_node/General-output-formatting.html#index-g_t_002d_002dcolor-791
>
>