From c419baec280de1bc5cbe24bffab8464e02f0397d Mon Sep 17 00:00:00 2001 From: Daniel Gerzo Date: Sun, 4 Jan 2009 15:41:01 +0000 Subject: [PATCH] - grammar and language fixes - hard sentence breaks - trim EXIT STATUS section and move it to DIAGNOSTICS as well as use .Er macro - sort SEE ALSO MFC after: 7 days --- sbin/geom/class/virstor/gvirstor.8 | 94 ++++++++++++++++-------------- 1 file changed, 49 insertions(+), 45 deletions(-) diff --git a/sbin/geom/class/virstor/gvirstor.8 b/sbin/geom/class/virstor/gvirstor.8 index 4b112094ec99..ebb743163487 100644 --- a/sbin/geom/class/virstor/gvirstor.8 +++ b/sbin/geom/class/virstor/gvirstor.8 @@ -29,7 +29,7 @@ .Os .Sh NAME .Nm gvirstor -.Nd "provides virtual data storage geom" +.Nd "control utility for virtual data storage devices" .Sh SYNOPSIS .Nm .Cm label @@ -72,9 +72,10 @@ utility is used for setting up a virtual storage device of arbitrary large size .Pq for example, several TB , consisting of an arbitrary number of physical storage devices with the -total size which is equal to or smaller than the virtual size. Data -for the virtual devices will be allocated from physical devices on -demand. The idea behind +total size which is equal to or smaller than the virtual size. +Data for the virtual devices will be allocated from physical devices on +demand. +The idea behind .Nm is similar to the concept of Virtual Memory in operating systems, effectively allowing users to overcommit on storage @@ -82,35 +83,35 @@ effectively allowing users to overcommit on storage The first argument to .Nm indicates an action to be performed: -.Bl -tag -width ".Cm destroy" +.Bl -tag -width ".Cm remove" .It Cm label Set up a virtual device from the given components with the specified .Ar name . -Metadata are stored in the last sector of every component. +Metadata is stored in the last sector of every component. Argument .Fl s Ar virsize -is the size of new virtual device, with default being 2 TiB +is the size of new virtual device, with default being set to 2 TiB .Pq 2097152 MiB . Argument .Fl m Ar chunksize -is the chunk size, with default being 4 MiB +is the chunk size, with default being set to 4 MiB .Pq 4096 KiB . -The default is thus +The default arguments are thus .Qq Fl s Ar 2097152 Fl m Ar 4096 . .It Cm stop -Turn off an existing virtual device by its +Turn off an existing virtual device with the given .Ar name . This command does not touch on-disk metadata. As with other GEOM classes, stopped geoms cannot be started manually. .It Cm add -Adds new components to existing virtual device by its +Adds new components to existing virtual device with the given .Ar name . The specified virstor device must exist and be active .Pq i.e. module loaded, device present in Pa /dev . This action can be safely performed while the virstor device is in use .Pq Qo hot Qc operation .It Cm remove -Removes components from existing virtual device by its +Removes components from existing virtual device with the given .Ar name . Only unallocated providers can be removed. .It Cm clear @@ -140,10 +141,6 @@ Hardcode providers' names in metadata. .It Fl v Be more verbose. .El -.Sh EXIT STATUS -The -.Nm -utility exits 0 on success, and 1 if an error occurs. .Sh EXAMPLES The following example shows how to create a virtual device of default size .Pq 2 TiB , @@ -165,12 +162,13 @@ To add a new physical device / component to an active virstor device: .No gvirstor add Ar mydata Ar ad8 .Ed .Pp -This will add physical storage +This will add physical storage of .Ar ad8 to .Pa /dev/virstor/mydata device. -To see device status information +.Pp +To see the device status information .Pq including how much physical storage is still available for the virtual device , use: .Bd -literal -offset indent @@ -192,17 +190,20 @@ tunable variables. .Ed .Pp This sysctl controls verbosity of the kernel module, in the range -1 to 15. Messages that are marked with higher verbosity levels than -this are suppressed. Default value is 5 and it's not -recommended to set this tunable to less than 2, because level 1 messages -are error events, and level 2 messages are system warnings. +1 to 15. +Messages that are marked with higher verbosity levels than this are +suppressed. +Default value is 5 and it is not recommended to set this tunable to less +than 2, because level 1 messages are error events, and level 2 messages +are system warnings. .Bd -literal -offset indent .Va int kern.geom.virstor.chunk_watermark .Ed .Pp -Value in this sysctl sets warning watermark level for physical chunk usage -on a single component. The warning is issued when a virstor component -has less than this many free chunks +Value in this sysctl sets warning watermark level for physical chunk +usage on a single component. +The warning is issued when a virstor component has less than this many +free chunks .Pq default 100 . .Bd -literal -offset indent .Va int kern.geom.virstor.component_watermark @@ -217,31 +218,33 @@ All these sysctls are also available as .Xr loader 8 tunables. .Sh DIAGNOSTICS +.Ex -std +.Pp .Nm kernel module issues log messages with prefixes in standardized format, -which is useful for log message filtering and dispatching. Each message -line begins with +which is useful for log message filtering and dispatching. +Each message line begins with .Bd -literal -offset indent .Li GEOM_VIRSTOR[%d]: .Ed .Pp The number .Pq %d -is message verbosity / importance level, in the range 1 to 15. If a -message filtering, dispatching or operator alert system is used, it is -recommended that messages with levels 1 and 2 be taken seriously +is message verbosity / importance level, in the range 1 to 15. +If a message filtering, dispatching or operator alert system is used, it +is recommended that messages with levels 1 and 2 be taken seriously .Pq for example, to catch out-of-space conditions as set by watermark -sysctls . +sysctls. .Sh SEE ALSO .Xr geom 4 , -.Xr geom 8 , -.Xr newfs 8 , .Xr fstab 5 , -.Xr glabel 8 +.Xr geom 8 , +.Xr glabel 8 , +.Xr newfs 8 .Sh HISTORY The .Nm -utility appeared in +utility first appeared in .Fx 7.0 . .Sh BUGS Commands @@ -251,15 +254,15 @@ and contain unavoidable critical sections which may make the virstor device unusable if a power failure .Pq or other disruptive event -happens during their execution. It's recommended to run them when the -system is quiescent. +happens during their execution. +It is recommended to run them when the system is quiescent. .Sh ASSUMPTIONS AND INTERACTION WITH FILE SYSTEMS There are several assumptions that .Nm has in its operation: that the size of the virtual storage device will not -change once it's set, and that the sizes of individual physical storage -components will always remain constant during their existence. For -alternative ways to implement virtual or resizable file systems see +change once it is set, and that the sizes of individual physical storage +components will always remain constant during their existence. +For alternative ways to implement virtual or resizable file systems see .Xr zfs 1M , .Xr gconcat 8 and .Xr growfs 8 . @@ -267,17 +270,18 @@ alternative ways to implement virtual or resizable file systems see Note that .Nm has nontrivial interaction with file systems which initialize a large -number of on-disk structures during newfs. If such file systems -attempt to spread their structures across the drive media +number of on-disk structures during newfs. +If such file systems attempt to spread their structures across the drive +media .Pq like UFS/UFS2 does , their efforts will be effectively foiled by sequential allocation of chunks in .Nm and all their structures will be physically allocated at the start -of the first virstor component. This could have a significant impac -t on file system performance +of the first virstor component. +This could have a significant impact on file system performance .Pq which can in some rare cases be even positive . .Sh AUTHOR .An Ivan Voras Aq ivoras@FreeBSD.org .Pp -Sponsored by Google Summer of Code 2006 +Sponsored by Google Summer of Code 2006.