[Question] st_blocks of shm is number of pages, not 512B blocks

Hi!

Just out of curiosity, when you do ...

	struct stat st;
	int fd;

	fd = shm_open(...);
	ftruncate(fd, ...);
	fstat(fd, &st);

	printf("%lld\n", st.st_blocks);

you get st.st_blocks as the number of system memory pages allocated, not
the usual 512-byte unit. Because, in sys/kern/uipc_shm.c:

static int
shm_stat(struct file *fp, struct stat *sb, struct ucred *active_cred)
{
	...
	if (shm_largepage(shmfd)) {
		sb->st_blocks = shmfd->shm_object->size /
		    (pagesizes[shmfd->shm_lp_psind] >> PAGE_SHIFT);
	} else {
		sb->st_blocks = shmfd->shm_pages;
	}

I was a bit confused when I discovered this. FreeBSD is the only BSD
that exhibit this behaviour.

I'm just wondering if there was any case where getting the number of
pages is better? Was there a historic precedence? If so, I think this
behaviour has to be documented somewhere.

The showcases:

  * https://github.com/dxdxdt/gists/blob/09b721a50fa2811846e31a986e9b1bdc0f0d35a1/writeups/mmap-magic/mmap-arena-test.c#L108
  * https://github.com/dxdxdt/gists/actions/runs/30700765339/job/91371261488


Davo