summaryrefslogtreecommitdiff
path: root/pod
diff options
context:
space:
mode:
authorCraig A. Berry <craig.a.berry@gmail.com>2012-09-18 23:24:56 -0700
committerFather Chrysostomos <sprout@cpan.org>2012-09-18 23:24:56 -0700
commitdd766832e653b99bd7a3b57d049f81e9d8c000fe (patch)
tree4e83be11daa01c3296d666ff2a01fc8d8732339a /pod
parent37ccf918afde3d9f88f7955b043e8ecc5158caaa (diff)
downloadperl-dd766832e653b99bd7a3b57d049f81e9d8c000fe.tar.gz
[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:
Diffstat (limited to 'pod')
-rw-r--r--pod/perlfunc.pod6
1 files changed, 4 insertions, 2 deletions
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 08743ed499..5a2eb71da0 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -7401,8 +7401,10 @@ meanings of the fields:
8 atime last access time in seconds since the epoch
9 mtime last modify time in seconds since the epoch
10 ctime inode change time in seconds since the epoch (*)
- 11 blksize preferred block size for file system I/O
- 12 blocks actual number of blocks allocated
+ 11 blksize preferred I/O size in bytes for interacting with the
+ file (may vary from file to file)
+ 12 blocks actual number of system-specific blocks allocated
+ on disk (often, but not always, 512 bytes each)
(The epoch was at 00:00 January 1, 1970 GMT.)