From dd766832e653b99bd7a3b57d049f81e9d8c000fe Mon Sep 17 00:00:00 2001 From: "Craig A. Berry" Date: Tue, 18 Sep 2012 23:24:56 -0700 Subject: [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 ) 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 | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'pod') 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.) -- cgit v1.2.1