bin/60533: clarify the role of -g, -h in newfs(8)

>Number:         60533
>Category:       bin
>Synopsis:       clarify the role of -g, -h in newfs(8)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Aug 03 12:45:00 +0000 2026
>Originator:     Ivan Shmakov
>Release:        NetBSD 10.1
>Organization:
Dbus-free station.
>Environment:
Architecture: x86_64
Machine: amd64
>Description:

	newfs(8) reads:

 > -g avgfilesize
 >     The expected average file size for the file system.

 > -h avgfpdir
 >     The expected average number of files per directory on the file system.

	The role of these parameters and when the user might want to change
	them is not explained.  Moreover, they can be mistaken for affecting
	the number of inodes on the newly created filesystem (as in: FS size
	divided by the average file size), yet this is not the case - the
	-i (bytes-per-inode) parameter determines that.

	In fact, reading /usr/src/sys/ufs/ffs/ffs_alloc.c (as of 11.0 RC7),
	and the adjacent files, reveals that the only thing -g, -h influence
	is the selection of a group to allocate a new directory inode in.

>How-To-Repeat:

	(Regarding possible confusion of -g, -h vs. -i.)

	Create two filesystems with the same size and different -g values:

$ /sbin/newfs -Fs64M -g127 -- /tmp/fs1 
/tmp/fs1: 64.0MB (131072 sectors) block size 8192, fragment size 1024
	using 4 cylinder groups of 16.00MB, 2048 blks, 3968 inodes.
super-block backups (for fsck_ffs -b #) at:
32, 32800, 65568, 98336,
$ /sbin/newfs -Fs64M -g17137 -- /tmp/fs2 
/tmp/fs2: 64.0MB (131072 sectors) block size 8192, fragment size 1024
	using 4 cylinder groups of 16.00MB, 2048 blks, 3968 inodes.
super-block backups (for fsck_ffs -b #) at:
32, 32800, 65568, 98336,
$ 

	As can be seen, both have the same number of groups and the same
	number of inodes per group, hence the same number of inodes overall.

>Fix:

	I suggest expanding the description as follows.

--- newfs.8~	2022-11-17 06:40:39 +0000
+++ newfs.8	2026-08-02 14:50:10 +0000
@@ -166,6 +166,14 @@ .Sh DESCRIPTION
 panic and should only be used for testing.
 .It Fl g Ar avgfilesize
 The expected average file size for the file system.
+.Pp
+The values of this and the following option
+.Em only
+determine what cylinder group the kernel code will choose
+to allocate a new directory inode in.
+See
+.Fl i
+for how the number of inodes available is determined.
 .It Fl h Ar avgfpdir
 The expected average number of files per directory on the file system.
 .It Fl I