what are st_blksize and st_blocks exactly?

[Guy Harris]

>The stat(2) documentation for SunOS 4.0.3 says:
>
>	  long	    st_blksize;	   /* preferred	blocksize for file system I/O*/
>	  long	    st_blocks;	   /* actual number of blocks allocated	*/

And the 4.3-tahoe documentation - those two fields originally appeared
in 4.2BSD (well, maybe 4.1c or something if you want to be *really*
picky) - says:

	long	st_blksize;	/* optimal blocksize for file system i/o ops */
	long	st_blocks;	/* actual number of blocks allocated */

which isn't any better.

>It doesn't mention what units st_blocks is measured in, but those
>units don't look like they're the value of st_blksize.
>How are these two fields related, if at all?
>Is st_blocks always measured in 512 byte units, or is there a value
>somewhere that indicates the block size for it?

The answer is "st_blocks is measured in 512-byte units, at least on
systems with a DEV_BSIZE of 512 - this includes all Suns, and VAXes, and
probably most other systems - or running System V Release 4."

The System V Release 4 documentation could either be considered worse
than, or better than, the BSD/S5 documentation in this regard.

Better, because it does say what the units are.

Worse, because it says it in both the comment on the "st_blocks" field
in the list of fields *and* in the description of the field, and the two
descriptions disagree with one another!

The correct description is almost certainly the one in the description
of the field:

	st_blocks
		The total number of physical blocks of size 512 bytes
		actually allocated on disk.

because that's what it is in 4.[23]BSD, SunOS, and probably all the
systems that picked it up from 4.[23]BSD.  The description in the
comment in the S5R4 manual page says it's in units of "st_blksize",
which makes no sense - "st_blksize" is the optimal size for I/O, and in
UFS (4.[23]BSD) file systems is typically larger (by factors of 8 or
more) than the allocation quantum for disk blocks in the file system.

As I remember, the AT&T folk originally thought that "st_blocks" was
supposed to be in units of "st_blksize", but were convinced otherwise;
the comments in the code may not have been fixed in time to get the fix
into the man page, but the actual description of the field was fixed in
time.

The Third Edition of the SVID has the same confusion; I hope the SVVS
makes sure that the number of 512-byte blocks is returned (even if the
disk has 1024-byte sectors; just return twice the number of those
sectors).

Still, it's better than the S5R4 Migration Guide claiming that "To allow
binary compatibility with Release 2 programs, the Relase 4.0 'stat'
structure is identical to the Release 3.2 'stat' structure.  BSD
programs requiring the two additional fields need to be relinked with a
compatibility library."

That statement contradicts the SVID (which lists the two fields,
"st_blocks" and "st_blksize"), the S5R4 documentation (which lists those
two fields), and the experience of people who did 4.2BSD (4.2BSD changed
the system call number for "stat", and had an option to let the old
system call number return the old "stat" structure, for binary
compatibility with 4.1BSD, which used the V7 structure that
S5-prior-to-R4 used).