[perl #99382] 'stat' call documentation is poorly worded

# New Ticket Created by  Linda Walsh 
# Please include the string:  [perl #99382]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org:443/rt3/Ticket/Display.html?id=99382 >



This is a bug report for perl from perl-diddler@tlinx.org,
generated with the help of perlbug 1.39 running under perl 5.12.3.


-----------------------------------------------------------------
[Please describe your issue here]

In the 'perlfunc' manpage, under 'stat', it says:

stat DIRHANDLE
  stat    Returns a 13-element list giving the status info for a file,
          either the file opened via FILEHANDLE or DIRHANDLE, or named by
          EXPR.  If EXPR is omitted, it stats $_.  Returns the empty list
          if "stat" fails.  Typically used as follows:

              ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
                 $atime,$mtime,$ctime,$blksize,$blocks)
                     = stat($filename);

          Not all fields are supported on all filesystem types.  Here are
          the meanings of the fields:

            0 dev      device number of filesystem
            ....
            7 size     total size of file, in bytes
            ....
           11 blksize  preferred block size for file system I/O
           12 blocks   actual number of blocks allocated


I printed out sizes, blocksize and #blocks allocated 
(for multiple files, actually)... of files needing to be examined:

   "Need to examine 318.5GB bytes (taking 479.5TB space) in 226640 files."

(on a 1TB disk -- neat trick!).


The 2nd number (in parens) was the total of the 'preferred block size'
 * # blocks allocated for each file.

Makes sense from the above description no?   Nep!

upon  further examination .. param#12 is # of 512-byte blocks -- NOTHING
to do with param 11, but certainly not something someone would get
from the perl manpage.

Im...maybe instead of 'actual number of blocks allocated', it should
say 'number of 512-byte blocks allocated' ???





[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags:
    category=docs
    severity=medium
---
This perlbug was built using Perl 5.12.3 - Fri May  6 13:31:41 UTC 2011
It is being executed now by  Perl 5.12.3 - Fri May  6 13:26:30 UTC 2011.

Site configuration information for perl 5.12.3:

Configured by abuild at Fri May  6 13:26:30 UTC 2011.

Summary of my perl5 (revision 5 version 12 subversion 3) configuration:
   
  Platform:
    osname=linux, osvers=2.6.36, archname=x86_64-linux-thread-multi
    uname='linux build33 2.6.36 #1 smp 2011-02-21 10:34:10 +0100 x86_64 x86_64 x86_64 gnulinux '
    config_args='-ds -e -Dprefix=/usr -Dvendorprefix=/usr -Dinstallusrbinperl -Dusethreads -Di_db -Di_dbm -Di_ndbm -Di_gdbm -Duseshrplib=true -Doptimize=-fmessage-length=0 -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -Wall -pipe -Accflags=-DPERL_USE_SAFE_PUTENV'
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=define, usemultiplicity=define
    useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
    use64bitint=define, use64bitall=define, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -DPERL_USE_SAFE_PUTENV -DDEBUGGING -fno-strict-aliasing -pipe -fstack-protector -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
    optimize='-fmessage-length=0 -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -Wall -pipe',
    cppflags='-D_REENTRANT -D_GNU_SOURCE -DPERL_USE_SAFE_PUTENV -DDEBUGGING -fno-strict-aliasing -pipe -fstack-protector'
    ccversion='', gccversion='4.5.1 20101208 [gcc-4_5-branch revision 167585]', gccosandvers=''
    intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
    ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
    alignbytes=8, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -L/usr/local/lib64 -fstack-protector'
    libpth=/lib64 /usr/lib64 /usr/local/lib64
    libs=-lm -ldl -lcrypt -lpthread
    perllibs=-lm -ldl -lcrypt -lpthread
    libc=/lib64/libc-2.11.3.so, so=so, useshrplib=true, libperl=libperl.so
    gnulibc_version='2.11.3'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E -Wl,-rpath,/usr/lib/perl5/5.12.3/x86_64-linux-thread-multi/CORE'
    cccdlflags='-fPIC', lddlflags='-shared -L/usr/local/lib64 -fstack-protector'

Locally applied patches:
    

---
@INC for perl 5.12.3:
    /usr/lib/perl5/site_perl/5.12.3/x86_64-linux-thread-multi
    /usr/lib/perl5/site_perl/5.12.3
    /usr/lib/perl5/vendor_perl/5.12.3/x86_64-linux-thread-multi
    /usr/lib/perl5/vendor_perl/5.12.3
    /usr/lib/perl5/5.12.3/x86_64-linux-thread-multi
    /usr/lib/perl5/5.12.3
    .

---
Environment for perl 5.12.3:
    HOME=/home/law
    LANG=en_US.UTF-8
    LANGUAGE (unset)
    LC_CTYPE=en_US.UTF-8
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=.:/sbin:/usr/local/sbin:/opt/lsb/bin:/home/law/bin:/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:/usr/games:/opt/kde3/bin:/usr/lib/mit/bin:/usr/lib/mit/sbin:/usr/lib/qt3/bin:/usr/sbin
    PERL_BADLANG (unset)
    SHELL=/bin/bash

• [perl #99382] 'stat' call documentation is poorly worded by Linda Walsh
• Re: [perl #99382] 'stat' call documentation is poorly worded by Craig A. Berry