[perl #99382] 'stat' call documentation is poorly worded
authorCraig A. Berry <craig.a.berry@gmail.com>
Wed, 19 Sep 2012 06:24:56 +0000 (23:24 -0700)
committerFather Chrysostomos <sprout@cpan.org>
Wed, 19 Sep 2012 06:24:56 +0000 (23:24 -0700)
commitdd766832e653b99bd7a3b57d049f81e9d8c000fe
tree4e83be11daa01c3296d666ff2a01fc8d8732339a
parent37ccf918afde3d9f88f7955b043e8ecc5158caaa
[perl #99382] 'stat' call documentation is poorly worded

The use of "block" to describe both the file-or-device-specific sweet
spot for I/O operations and the number of file-system-specific chunks
(not necessarily 512-byte chunks) is unfortunate.  I think we came by
it honestly because Perl just provides a wrapper around:

http://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/stat.h.html

which says:

blksize_t st_blksize A file system-specific preferred I/O block size for
                     this object. In some file system types, this may
                     vary from file to file.
blkcnt_t  st_blocks  Number of blocks allocated for this object.

and in the "Rationale" section they say:

"The unit for the st_blocks member of the stat structure is not
defined within IEEE Std 1003.1-2001. In some implementations it is 512
bytes. It may differ on a file system basis. There is no correlation
between values of the st_blocks and st_blksize, and the f_bsize (from
<sys/statvfs.h>) structure members."

The existing piece in perlfunc.pod was written in 1997 for Perl 5.003.
 Screens were smaller then.  Perhaps we could afford to wrap to a
second line now and say something like:
pod/perlfunc.pod