ls -s documentation misleading

[vcaputo]

Hello,

The ls -s argument is documented as such:

 ls --help output: 
  -s, --size                 print the size of each file, in blocks

 LS(1) man page:
       -s, --size
              print the size of each file, in blocks


This leads one to expect some sort of relationship between the size
colum in ls -l output, perhaps with rounding to the nearest block, but
this is not the case.

The -s argument causes ls to print the st_blocks member of the stat
structure shifted, which is:

               blkcnt_t  st_blocks;  /* number of blocks allocated */

..

        The st_blocks field indicates the number of blocks allocated to
        the  file,  512-byte units.  (This may be smaller than st_size/512
        when the file has holes.)

Clearly the ls help and manual should instead say:
"Size of space allocated for each file, in blocks"

Perhaps with a notice in the manual further explaining potential for
difference between the file size and size in blocks?

Cheers,
Vito Caputo