mirror of
https://git.FreeBSD.org/src.git
synced 2026-06-02 11:24:32 +00:00
geom manuals: Clarify units
The gpart manual says that sizes are specified in blocks, unless an SI unit suffix is provided. This confuses new operators because GEOM uses binary bytes, a large difference at modern storage pool sizes. Rewrite suffixes in all GEOM manuals to consistently clarify this, matching what we and the rest of the industry have been doing in other documentation. While here, use non-breaking spaces between numbers and units, unless they are already written with a hyphen. MFC after: 3 days Reviewed by: fuz Reported by: bbaovanc <bbaovanc@bbaovanc.com> Differential Revision: https://reviews.freebsd.org/D56534
This commit is contained in:
Vendored
+2
-2
@@ -82,9 +82,9 @@ The
|
||||
utility is used to control GEOM cache, which can
|
||||
speed up read performance by sending fixed size
|
||||
read requests to its consumer. It has been developed to address
|
||||
the problem of a horrible read performance of a 64k blocksize FS
|
||||
the problem of a horrible read performance of a 64\~KiB blocksize FS
|
||||
residing on a RAID3 array with 8 data components, where a single
|
||||
disk component would only get 8k read requests, thus effectively
|
||||
disk component would only get 8\~KiB read requests, thus effectively
|
||||
killing disk performance under high load.
|
||||
.Pp
|
||||
Caching can be configured using two different methods:
|
||||
|
||||
+4
-4
@@ -249,7 +249,7 @@ Additional options include:
|
||||
.It Fl a Ar aalgo
|
||||
Enable data integrity verification (authentication) using the given algorithm.
|
||||
This will reduce the size of storage available and also reduce speed.
|
||||
For example, when using 4096 bytes sector and
|
||||
For example, when using 4096\~bytes sector and
|
||||
.Nm HMAC/SHA256
|
||||
algorithm, 89% of the original provider storage will be available for use.
|
||||
Currently supported algorithms are:
|
||||
@@ -883,8 +883,8 @@ The crypto card and the driver have to support this feature.
|
||||
.It Va kern.geom.eli.key_cache_limit : No 8192
|
||||
Specifies how many Data Keys to cache.
|
||||
The default limit
|
||||
(8192 keys) will allow caching of all keys for a 4TB provider with 512 byte
|
||||
sectors and will take around 1MB of memory.
|
||||
(8192 keys) will allow caching of all keys for a 4\~TiB provider with 512\~byte
|
||||
sectors and will take around 1\~MiB of memory.
|
||||
.It Va kern.geom.eli.key_cache_hits
|
||||
Reports how many times we were looking up a Data Key and it was already in
|
||||
cache.
|
||||
@@ -936,7 +936,7 @@ Exit status is 0 on success, and 1 if the command fails.
|
||||
.Sh EXAMPLES
|
||||
Initialize a provider which is going to be encrypted with a
|
||||
passphrase and random data from a file on the user's pen drive.
|
||||
Use 4kB sector size.
|
||||
Use 4\~KiB sector size.
|
||||
Attach the provider, create a filesystem, and mount it.
|
||||
Do the work.
|
||||
Unmount the provider and detach it:
|
||||
|
||||
+29
-23
@@ -22,7 +22,7 @@
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd December 4, 2025
|
||||
.Dd April 20, 2026
|
||||
.Dt GPART 8
|
||||
.Os
|
||||
.Sh NAME
|
||||
@@ -168,7 +168,9 @@ to be multiple of
|
||||
value.
|
||||
.It Fl b Ar start
|
||||
The logical block address where the partition will begin.
|
||||
An SI unit suffix is allowed.
|
||||
A single-character suffix
|
||||
.Pq k, m, g, etc.
|
||||
is allowed to specify binary byte sizes.
|
||||
.It Fl f Ar flags
|
||||
Additional operational flags.
|
||||
See the section entitled
|
||||
@@ -187,7 +189,9 @@ partition labels.
|
||||
.It Fl s Ar size
|
||||
Create a partition of size
|
||||
.Ar size .
|
||||
An SI unit suffix is allowed.
|
||||
A single-character suffix
|
||||
.Pq k, m, g, etc.
|
||||
is allowed to specify binary byte sizes.
|
||||
.It Fl t Ar type
|
||||
Create a partition of type
|
||||
.Ar type .
|
||||
@@ -422,8 +426,10 @@ about its use.
|
||||
.It Fl i Ar index
|
||||
Specifies the index of the partition to be resized.
|
||||
.It Fl s Ar size
|
||||
Specifies the new size of the partition, in logical blocks.
|
||||
An SI unit suffix is allowed.
|
||||
Specifies the new size of the partition, in logical blocks,
|
||||
or binary byte sizes if a single-character suffix
|
||||
.Pq k, m, g, etc.
|
||||
is provided.
|
||||
.El
|
||||
.\" ==== RESTORE ====
|
||||
.It Cm restore
|
||||
@@ -1134,7 +1140,7 @@ with type
|
||||
(see the
|
||||
.Sx "PARTITION TYPES"
|
||||
section).
|
||||
It uses 8 KB size bootstrap code image
|
||||
It uses 8\~KiB size bootstrap code image
|
||||
.Pa /boot/boot ,
|
||||
embedded into the partition table's metadata area.
|
||||
.Pp
|
||||
@@ -1149,7 +1155,7 @@ partition (see the
|
||||
section) and runs the next bootstrap stage from it.
|
||||
The
|
||||
.Cm freebsd-boot
|
||||
partition should be smaller than 545 KB.
|
||||
partition should be smaller than 545\~KiB.
|
||||
It can be located either before or after other
|
||||
.Fx
|
||||
partitions on the disk.
|
||||
@@ -1190,13 +1196,13 @@ After all pools are detected,
|
||||
is started from the first one found set as bootable.
|
||||
.Pp
|
||||
The APM scheme also does not support embedding bootstrap code.
|
||||
Instead, the 800 KBytes bootstrap code image
|
||||
Instead, the 800\~KiB bootstrap code image
|
||||
.Pa /boot/boot1.hfs
|
||||
should be written with the
|
||||
.Cm gpart bootcode
|
||||
command to a partition of type
|
||||
.Cm apple-boot ,
|
||||
which should also be 800 KB in size.
|
||||
which should also be 800\~KiB in size.
|
||||
.Sh OPERATIONAL FLAGS
|
||||
Actions other than the
|
||||
.Cm commit
|
||||
@@ -1351,8 +1357,8 @@ naming scheme.
|
||||
.Sh EXIT STATUS
|
||||
Exit status is 0 on success, and 1 if the command fails.
|
||||
.Sh EXAMPLES
|
||||
The examples below assume that the disk's logical block size is 512
|
||||
bytes, regardless of its physical block size.
|
||||
The examples below assume that the disk's logical block size is 512\~bytes,
|
||||
regardless of its physical block size.
|
||||
.Ss GPT
|
||||
In this example, we will format
|
||||
.Pa ada0
|
||||
@@ -1384,31 +1390,31 @@ for UFS or
|
||||
.Pa /boot/gptzfsboot
|
||||
for ZFS
|
||||
.Pc ,
|
||||
but smaller than 545 kB since the first-stage loader will load the
|
||||
but smaller than 545\~KiB since the first-stage loader will load the
|
||||
entire partition into memory during boot, regardless of how much data
|
||||
it actually contains.
|
||||
We create a 472-block (236 kB) boot partition at offset 40, which is
|
||||
the size of the partition table (34 blocks or 17 kB) rounded up to the
|
||||
nearest 4 kB boundary.
|
||||
We create a 472-block (236\~KiB) boot partition at offset 40, which is
|
||||
the size of the partition table (34\~blocks or 17\~KiB) rounded up to the
|
||||
nearest 4\~KiB boundary.
|
||||
.Bd -literal -offset indent
|
||||
/sbin/gpart add -b 40 -s 472 -t freebsd-boot ada0
|
||||
/sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
|
||||
.Ed
|
||||
.Pp
|
||||
We now create a 4 GB swap partition at the first available offset,
|
||||
which is 40 + 472 = 512 blocks (256 kB).
|
||||
We now create a 4\~GiB swap partition at the first available offset,
|
||||
which is 40 + 472 = 512 blocks (256\~KiB).
|
||||
.Bd -literal -offset indent
|
||||
/sbin/gpart add -s 4G -t freebsd-swap ada0
|
||||
.Ed
|
||||
.Pp
|
||||
Aligning the swap partition and all subsequent partitions on a 256 kB
|
||||
Aligning the swap partition and all subsequent partitions on a 256\~KiB
|
||||
boundary ensures optimal performance on a wide range of media, from
|
||||
plain old disks with 512-byte blocks, through modern
|
||||
.Dq advanced format
|
||||
disks with 4096-byte physical blocks, to RAID volumes with stripe
|
||||
sizes of up to 256 kB.
|
||||
sizes of up to 256\~KiB.
|
||||
.Pp
|
||||
Finally, we create and format an 8 GB
|
||||
Finally, we create and format an 8\~GiB
|
||||
.Cm freebsd-ufs
|
||||
partition for the root filesystem, leaving the rest of the device free
|
||||
for additional filesystems:
|
||||
@@ -1424,8 +1430,8 @@ using a traditional
|
||||
.Bx
|
||||
disklabel.
|
||||
.Pp
|
||||
First, we create the partition table as well as a single partition 64 GB in
|
||||
size and an alignment of 4 kB, then we mark that partition active (bootable)
|
||||
First, we create the partition table as well as a single partition 64\~GiB in
|
||||
size and an alignment of 4\~KiB, then we mark that partition active (bootable)
|
||||
and install the first-stage boot loader:
|
||||
.Bd -literal -offset indent
|
||||
/sbin/gpart create -s MBR ada0
|
||||
@@ -1444,7 +1450,7 @@ with room for up to 20 partitions:
|
||||
/sbin/gpart create -s BSD -n 20 ada0s1
|
||||
.Ed
|
||||
.Pp
|
||||
We then create an 8 GB root partition and a 4 GB swap partition:
|
||||
We then create an 8\~GiB root partition and a 4\~GiB swap partition:
|
||||
.Bd -literal -offset indent
|
||||
/sbin/gpart add -t freebsd-ufs -s 8G ada0s1
|
||||
/sbin/gpart add -t freebsd-swap -s 4G ada0s1
|
||||
|
||||
@@ -101,7 +101,7 @@ providers.
|
||||
.El
|
||||
.Pp
|
||||
Available options:
|
||||
.Bl -tag -width ".Fl s Cm ro | wo | rw"
|
||||
.Bl -tag -width "-q queue_size"
|
||||
.It Fl f
|
||||
Forcibly destroy
|
||||
.Nm ggate
|
||||
@@ -136,15 +136,15 @@ start to be canceled.
|
||||
Default is 1024.
|
||||
.It Fl R Ar rcvbuf
|
||||
Size of receive buffer to use.
|
||||
Default is 131072 (128kB).
|
||||
Default is 131072 (128\~KiB).
|
||||
.It Fl S Ar sndbuf
|
||||
Size of send buffer to use.
|
||||
Default is 131072 (128kB).
|
||||
Default is 131072 (128\~KiB).
|
||||
.It Fl s Ar sectorsize
|
||||
Sector size for
|
||||
.Nm ggate
|
||||
provider.
|
||||
If not specified, it is taken from the device, or set to 512 bytes for files.
|
||||
If not specified, it is taken from the device, or set to 512\~bytes for files.
|
||||
.It Fl t Ar timeout
|
||||
Number of seconds to wait before an I/O request will be canceled.
|
||||
Default is 0, which means no timeout.
|
||||
|
||||
@@ -72,10 +72,10 @@ PID file that
|
||||
uses.
|
||||
.It Fl R Ar rcvbuf
|
||||
Size of receive buffer to use.
|
||||
Default is 131072 (128kB).
|
||||
Default is 131072 (128\~KiB).
|
||||
.It Fl S Ar sndbuf
|
||||
Size of send buffer to use.
|
||||
Default is 131072 (128kB).
|
||||
Default is 131072 (128\~KiB).
|
||||
.It Fl v
|
||||
Do not fork, run in foreground and print debug information on standard
|
||||
output.
|
||||
|
||||
Reference in New Issue
Block a user