aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRuslan Ermilov <ru@FreeBSD.org>2004-07-02 21:45:06 +0000
committerRuslan Ermilov <ru@FreeBSD.org>2004-07-02 21:45:06 +0000
commit9806e231322307da0109e101ae2ef997a4a22290 (patch)
tree602e903272257a1c5b455a48800dcaa680741026
parentc481aa05e89e945a535e6e5bec8e05238a6b3628 (diff)
downloadsrc-9806e231322307da0109e101ae2ef997a4a22290.tar.gz
src-9806e231322307da0109e101ae2ef997a4a22290.zip
Mechanically kill hard sentence breaks.
Notes
Notes: svn path=/head/; revision=131488
-rw-r--r--sbin/atacontrol/atacontrol.82
-rw-r--r--sbin/atm/fore_dnld/fore_dnld.83
-rw-r--r--sbin/badsect/badsect.89
-rw-r--r--sbin/camcontrol/camcontrol.8297
-rw-r--r--sbin/ccdconfig/ccdconfig.860
-rw-r--r--sbin/comcontrol/comcontrol.83
-rw-r--r--sbin/dumpfs/dumpfs.83
-rw-r--r--sbin/fdisk/fdisk.82
-rw-r--r--sbin/fdisk_pc98/fdisk.868
-rw-r--r--sbin/fsck/fsck.87
-rw-r--r--sbin/fsck_ffs/fsck_ffs.86
-rw-r--r--sbin/fsdb/fsdb.827
-rw-r--r--sbin/fsirand/fsirand.83
-rw-r--r--sbin/ifconfig/ifconfig.82
-rw-r--r--sbin/init/init.811
-rw-r--r--sbin/ip6fw/ip6fw.829
-rw-r--r--sbin/ipfw/ipfw.894
-rw-r--r--sbin/ldconfig/ldconfig.827
-rw-r--r--sbin/mdconfig/mdconfig.83
-rw-r--r--sbin/mknod/mknod.83
-rw-r--r--sbin/mount_cd9660/mount_cd9660.89
-rw-r--r--sbin/mount_nfs/mount_nfs.82
-rw-r--r--sbin/mount_nullfs/mount_nullfs.840
-rw-r--r--sbin/mount_std/mount_std.86
-rw-r--r--sbin/mount_umapfs/mount_umapfs.825
-rw-r--r--sbin/mount_unionfs/mount_unionfs.87
-rw-r--r--sbin/newfs_msdos/newfs_msdos.827
-rw-r--r--sbin/nos-tun/nos-tun.83
-rw-r--r--sbin/reboot/boot_i386.866
-rw-r--r--sbin/restore/restore.812
-rw-r--r--sbin/route/route.89
-rw-r--r--sbin/routed/routed.816
-rw-r--r--sbin/shutdown/shutdown.812
-rw-r--r--sbin/slattach/slattach.827
-rw-r--r--sbin/spppcontrol/spppcontrol.86
-rw-r--r--sbin/startslip/startslip.115
-rw-r--r--sbin/vinum/vinum.8792
37 files changed, 1148 insertions, 585 deletions
diff --git a/sbin/atacontrol/atacontrol.8 b/sbin/atacontrol/atacontrol.8
index 2f6945721943..4bb18be4f0b1 100644
--- a/sbin/atacontrol/atacontrol.8
+++ b/sbin/atacontrol/atacontrol.8
@@ -104,7 +104,7 @@ is done on boot.
Detach an ATA
.Ar channel .
Devices on the channel are removed from the kernel,
-and all outstanding transfers etc. are returned back to the system marked
+and all outstanding transfers etc.\& are returned back to the system marked
as failed.
.It Ic reinit
Reinitialize an ATA
diff --git a/sbin/atm/fore_dnld/fore_dnld.8 b/sbin/atm/fore_dnld/fore_dnld.8
index a152e216426d..7ffd0d2e51fc 100644
--- a/sbin/atm/fore_dnld/fore_dnld.8
+++ b/sbin/atm/fore_dnld/fore_dnld.8
@@ -64,7 +64,8 @@ for PCA-200E adapters.
.El
.Sh NOTES
For the PCA200E adapter, if no file is specified on the command
-line a built-in copy of version 4.1.12 microcode is used. When the
+line a built-in copy of version 4.1.12 microcode is used.
+When the
option
.Fl 3
is specified version 3.0.1 microcode is used instead.
diff --git a/sbin/badsect/badsect.8 b/sbin/badsect/badsect.8
index 3e387d3b23aa..be24febcd039 100644
--- a/sbin/badsect/badsect.8
+++ b/sbin/badsect/badsect.8
@@ -40,7 +40,8 @@
.Sh DESCRIPTION
The
.Nm
-utility makes a file to contain a bad sector. Normally, bad sectors
+utility makes a file to contain a bad sector.
+Normally, bad sectors
are made inaccessible by the standard formatter, which provides
a forwarding table for bad sectors to the driver.
If a driver supports the bad blocking standard it is much preferable to
@@ -83,8 +84,10 @@ relative sector numbers in its console error messages.)
Then change back to the root directory, unmount the file system
and run
.Xr fsck 8
-on the file system. The bad sectors should show up in two files
-or in the bad sector files and the free list. Have
+on the file system.
+The bad sectors should show up in two files
+or in the bad sector files and the free list.
+Have
.Xr fsck 8
remove files containing the offending bad sectors, but
.Em do not
diff --git a/sbin/camcontrol/camcontrol.8 b/sbin/camcontrol/camcontrol.8
index 84c3bf9a48e3..04eac5483b6d 100644
--- a/sbin/camcontrol/camcontrol.8
+++ b/sbin/camcontrol/camcontrol.8
@@ -152,38 +152,44 @@ CAM subsystem.
The
.Nm
utility
-can cause a loss of data and/or system crashes if used improperly. Even
+can cause a loss of data and/or system crashes if used improperly.
+Even
expert users are encouraged to exercise caution when using this command.
Novice users should stay away from this utility.
.Pp
The
.Nm
utility has a number of primary functions, many of which support an optional
-device identifier. A device identifier can take one of three forms:
+device identifier.
+A device identifier can take one of three forms:
.Bl -tag -width 14n
.It deviceUNIT
Specify a device name and unit number combination, like "da5" or "cd3".
-Note that character device node names (e.g. /dev/da0) are
+Note that character device node names (e.g.\& /dev/da0) are
.Em not
allowed here.
.It bus:target
-Specify a bus number and target id. The bus number can be determined from
+Specify a bus number and target id.
+The bus number can be determined from
the output of
.Dq camcontrol devlist .
The lun defaults to 0.
.It bus:target:lun
-Specify the bus, target and lun for a device. (e.g. 1:2:0)
+Specify the bus, target and lun for a device.
+(e.g.\& 1:2:0)
.El
.Pp
The device identifier, if it is specified,
.Em must
come immediately after the function name, and before any generic or
-function-specific arguments. Note that the
+function-specific arguments.
+Note that the
.Fl n
and
.Fl u
arguments described below will override any device name or unit number
-specified beforehand. The
+specified beforehand.
+The
.Fl n
and
.Fl u
@@ -196,24 +202,28 @@ Most of the
primary functions support these generic arguments:
.Bl -tag -width 14n
.It Fl C Ar count
-SCSI command retry count. In order for this to work, error recovery
+SCSI command retry count.
+In order for this to work, error recovery
.Pq Fl E
must be turned on.
.It Fl E
Instruct the kernel to perform generic SCSI error recovery for the given
-command. This is needed in order for the retry count
+command.
+This is needed in order for the retry count
.Pq Fl C
-to be honored. Other than retrying commands, the generic error recovery in
+to be honored.
+Other than retrying commands, the generic error recovery in
the code will generally attempt to spin up drives that are not spinning.
It may take some other actions, depending upon the sense code returned from
the command.
.It Fl n Ar dev_name
-Specify the device type to operate on, e.g. "da", "cd".
+Specify the device type to operate on, e.g.\& "da", "cd".
.It Fl t Ar timeout
-SCSI command timeout in seconds. This overrides the default timeout for
+SCSI command timeout in seconds.
+This overrides the default timeout for
any given command.
.It Fl u Ar unit_number
-Specify the device unit number, e.g. "1", "5".
+Specify the device unit number, e.g.\& "1", "5".
.It Fl v
Be verbose, print out sense information for failed SCSI commands.
.El
@@ -236,16 +246,19 @@ The
.Nm
utility will report whether the device is ready or not.
.It Ic inquiry
-Send a SCSI inquiry command (0x12) to a device. By default,
+Send a SCSI inquiry command (0x12) to a device.
+By default,
.Nm
will print out the standard inquiry data, device serial number, and
-transfer rate information. The user can specify that only certain types of
+transfer rate information.
+The user can specify that only certain types of
inquiry data be printed:
.Bl -tag -width 4n
.It Fl D
Get the standard inquiry data.
.It Fl S
-Print out the serial number. If this flag is the only one specified,
+Print out the serial number.
+If this flag is the only one specified,
.Nm
will not print out "Serial Number" before the value returned by the drive.
This is to aid in script writing.
@@ -268,8 +281,10 @@ start bit cleared and the load/eject bit set.
Tell the kernel to scan all busses in the system (with the
.Ar all
argument), the given bus (XPT_SCAN_BUS), or bus:target:lun
-(XPT_SCAN_LUN) for new devices or devices that have gone away. The user
-may specify a scan of all busses, a single bus, or a lun. Scanning all luns
+(XPT_SCAN_LUN) for new devices or devices that have gone away.
+The user
+may specify a scan of all busses, a single bus, or a lun.
+Scanning all luns
on a target isn't supported.
.It Ic reset
Tell the kernel to reset all busses in the system (with the
@@ -292,9 +307,13 @@ to print out the list as logical blocks,
.Em bfi ,
to print out the list in bytes from index format, and
.Em phys ,
-to print out the list in physical sector format. The format argument is
-required. Most drives support the physical sector format. Some drives
-support the logical block format. Many drives, if they don't support the
+to print out the list in physical sector format.
+The format argument is
+required.
+Most drives support the physical sector format.
+Some drives
+support the logical block format.
+Many drives, if they don't support the
requested format, return the data in an alternate format, along with sense
information indicating that the requested data format isn't supported.
The
@@ -306,7 +325,8 @@ support the requested format,
.Nm
will probably see the error as a failure to complete the request.
.It Fl G
-Print out the grown defect list. This is a list of bad blocks that have
+Print out the grown defect list.
+This is a list of bad blocks that have
been remapped since the disk left the factory.
.It Fl P
Print out the primary defect list.
@@ -321,7 +341,8 @@ is specified,
will print out the number of defects given in the READ DEFECT DATA header
returned from the drive.
.It Ic modepage
-Allows the user to display and optionally edit a SCSI mode page. The mode
+Allows the user to display and optionally edit a SCSI mode page.
+The mode
page formats are located in
.Pa /usr/share/misc/scsi_modes .
This can be overridden by specifying a different file in the
@@ -336,24 +357,28 @@ Disable block descriptors for mode sense.
.It Fl b
Displays mode page data in binary format.
.It Fl e
-This flag allows the user to edit values in the mode page. The user may
+This flag allows the user to edit values in the mode page.
+The user may
either edit mode page values with the text editor pointed to by his
.Ev EDITOR
environment variable, or supply mode page values via standard input, using
the same format that
.Nm
-uses to display mode page values. The editor will be invoked if
+uses to display mode page values.
+The editor will be invoked if
.Nm
detects that standard input is terminal.
.It Fl l
Lists all available mode pages.
.It Fl m Ar mode_page
This specifies the number of the mode page the user would like to view
-and/or edit. This argument is mandatory unless
+and/or edit.
+This argument is mandatory unless
.Fl l
is specified.
.It Fl P Ar pgctl
-This allows the user to specify the page control field. Possible values are:
+This allows the user to specify the page control field.
+Possible values are:
.Bl -tag -width xxx -compact
.It 0
Current values
@@ -371,8 +396,10 @@ The
.Ic cmd
function requires the
.Fl c
-argument to specify the CDB. Other arguments are optional, depending on
-the command type. The command and data specification syntax is documented
+argument to specify the CDB.
+Other arguments are optional, depending on
+the command type.
+The command and data specification syntax is documented
in
.Xr cam_cdbparse 3 .
NOTE: If the CDB specified causes data to be transfered to or from the
@@ -382,7 +409,8 @@ or
.Fl o .
.Bl -tag -width 17n
.It Fl c Ar cmd Op args
-This specifies the SCSI CDB. CDBs may be 6, 10, 12 or 16 bytes.
+This specifies the SCSI CDB.
+CDBs may be 6, 10, 12 or 16 bytes.
.It Fl i Ar len Ar fmt
This specifies the amount of data to read, and how it should be displayed.
If the format is
@@ -391,15 +419,19 @@ If the format is
bytes of data will be read from the device and written to standard output.
.It Fl o Ar len Ar fmt Op args
This specifies the amount of data to be written to a device, and the data
-that is to be written. If the format is
+that is to be written.
+If the format is
.Sq - ,
.Ar len
bytes of data will be read from standard input and written to the device.
.El
.It Ic debug
-Turn on CAM debugging printfs in the kernel. This requires options CAMDEBUG
-in your kernel config file. WARNING: enabling debugging printfs currently
-causes an EXTREME number of kernel printfs. You may have difficulty
+Turn on CAM debugging printfs in the kernel.
+This requires options CAMDEBUG
+in your kernel config file.
+WARNING: enabling debugging printfs currently
+causes an EXTREME number of kernel printfs.
+You may have difficulty
turning off the debugging printfs once they start, since the kernel will be
busy printing messages and unable to service other requests quickly.
The
@@ -417,46 +449,57 @@ Enable CAM_DEBUG_SUBTRACE printfs.
.It Fl X
Enable CAM_DEBUG_XPT printfs.
.It Fl c
-Enable CAM_DEBUG_CDB printfs. This will cause the kernel to print out the
+Enable CAM_DEBUG_CDB printfs.
+This will cause the kernel to print out the
SCSI CDBs sent to the specified device(s).
.It all
Enable debugging for all devices.
.It off
Turn off debugging for all devices
.It bus Ns Op :target Ns Op :lun
-Turn on debugging for the given bus, target or lun. If the lun or target
-and lun are not specified, they are wildcarded. (i.e., just specifying a
+Turn on debugging for the given bus, target or lun.
+If the lun or target
+and lun are not specified, they are wildcarded.
+(i.e., just specifying a
bus turns on debugging printfs for all devices on that bus.)
.El
.It Ic tags
Show or set the number of "tagged openings" or simultaneous transactions
-we attempt to queue to a particular device. By default, the
+we attempt to queue to a particular device.
+By default, the
.Ic tags
-command, with no command-specific arguments (i.e. only generic arguments)
+command, with no command-specific arguments (i.e., only generic arguments)
prints out the "soft" maximum number of transactions that can be queued to
-the device in question. For more detailed information, use the
+the device in question.
+For more detailed information, use the
.Fl v
argument described below.
.Bl -tag -width 7n
.It Fl N Ar tags
-Set the number of tags for the given device. This must be between the
-minimum and maximum number set in the kernel quirk table. The default for
+Set the number of tags for the given device.
+This must be between the
+minimum and maximum number set in the kernel quirk table.
+The default for
most devices that support tagged queueing is a minimum of 2 and a maximum
-of 255. The minimum and maximum values for a given device may be
+of 255.
+The minimum and maximum values for a given device may be
determined by using the
.Fl v
-switch. The meaning of the
+switch.
+The meaning of the
.Fl v
switch for this
.Nm
subcommand is described below.
.It Fl q
-Be quiet, and don't report the number of tags. This is generally used when
+Be quiet, and don't report the number of tags.
+This is generally used when
setting the number of tags.
.It Fl v
The verbose flag has special functionality for the
.Em tags
-argument. It causes
+argument.
+It causes
.Nm
to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB:
.Bl -tag -width 13n
@@ -465,55 +508,68 @@ This is the amount of capacity for transactions queued to a given device.
.It dev_active
This is the number of transactions currently queued to a device.
.It devq_openings
-This is the kernel queue space for transactions. This count usually mirrors
+This is the kernel queue space for transactions.
+This count usually mirrors
dev_openings except during error recovery operations when
the device queue is frozen (device is not allowed to receive
commands), the number of dev_openings is reduced, or transaction
replay is occurring.
.It devq_queued
This is the number of transactions waiting in the kernel queue for capacity
-on the device. This number is usually zero unless error recovery is in
+on the device.
+This number is usually zero unless error recovery is in
progress.
.It held
The held count is the number of CCBs held by peripheral drivers that have
either just been completed or are about to be released to the transport
-layer for service by a device. Held CCBs reserve capacity on a given
+layer for service by a device.
+Held CCBs reserve capacity on a given
device.
.It mintags
This is the current "hard" minimum number of transactions that can be
-queued to a device at once. The
+queued to a device at once.
+The
.Ar dev_openings
-value above cannot go below this number. The default value for
+value above cannot go below this number.
+The default value for
.Ar mintags
is 2, although it may be set higher or lower for various devices.
.It maxtags
This is the "hard" maximum number of transactions that can be queued to a
-device at one time. The
+device at one time.
+The
.Ar dev_openings
-value cannot go above this number. The default value for
+value cannot go above this number.
+The default value for
.Ar maxtags
is 255, although it may be set higher or lower for various devices.
.El
.El
.It Ic negotiate
-Show or negotiate various communication parameters. Some controllers may
-not support setting or changing some of these values. For instance, the
+Show or negotiate various communication parameters.
+Some controllers may
+not support setting or changing some of these values.
+For instance, the
Adaptec 174x controllers do not support changing a device's sync rate or
offset.
The
.Nm
utility
will not attempt to set the parameter if the controller indicates that it
-does not support setting the parameter. To find out what the controller
+does not support setting the parameter.
+To find out what the controller
supports, use the
.Fl v
-flag. The meaning of the
+flag.
+The meaning of the
.Fl v
flag for the
.Ic negotiate
-command is described below. Also, some controller drivers don't support
+command is described below.
+Also, some controller drivers don't support
setting negotiation parameters, even if the underlying controller supports
-negotiation changes. Some controllers, such as the Advansys wide
+negotiation changes.
+Some controllers, such as the Advansys wide
controllers, support enabling and disabling synchronous negotiation for
a device, but do not support setting the synchronous negotiation rate.
.Bl -tag -width 17n
@@ -521,41 +577,51 @@ a device, but do not support setting the synchronous negotiation rate.
Attempt to make the negotiation settings take effect immediately by sending
a Test Unit Ready command to the device.
.It Fl c
-Show or set current negotiation settings. This is the default.
+Show or set current negotiation settings.
+This is the default.
.It Fl D Ar enable|disable
Enable or disable disconnection.
.It Fl O Ar offset
Set the command delay offset.
.It Fl q
-Be quiet, don't print anything. This is generally useful when you want to
+Be quiet, don't print anything.
+This is generally useful when you want to
set a parameter, but don't want any status information.
.It Fl R Ar syncrate
-Change the synchronization rate for a device. The sync rate is a floating
-point value specified in MHz. So, for instance,
+Change the synchronization rate for a device.
+The sync rate is a floating
+point value specified in MHz.
+So, for instance,
.Sq 20.000
is a legal value, as is
.Sq 20 .
.It Fl T Ar enable|disable
Enable or disable tagged queueing for a device.
.It Fl U
-Show or set user negotiation settings. The default is to show or set
+Show or set user negotiation settings.
+The default is to show or set
current negotiation settings.
.It Fl v
The verbose switch has special meaning for the
.Ic negotiate
-subcommand. It causes
+subcommand.
+It causes
.Nm
to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the
controller driver.
.It Fl W Ar bus_width
-Specify the bus width to negotiate with a device. The bus width is
-specified in bits. The only useful values to specify are 8, 16, and 32
-bits. The controller must support the bus width in question in order for
+Specify the bus width to negotiate with a device.
+The bus width is
+specified in bits.
+The only useful values to specify are 8, 16, and 32
+bits.
+The controller must support the bus width in question in order for
the setting to take effect.
.El
.Pp
In general, sync rate and offset settings will not take effect for a
-device until a command has been sent to the device. The
+device until a command has been sent to the device.
+The
.Fl a
switch above will automatically send a Test Unit Ready to the device so
negotiation parameters will take effect.
@@ -566,27 +632,36 @@ FORMAT UNIT command to the named device.
.Pp
.Em WARNING! WARNING! WARNING!
.Pp
-Low level formatting a disk will destroy ALL data on the disk. Use
-extreme caution when issuing this command. Many users low-level format
-disks that do not really need to be low-level formatted. There are
+Low level formatting a disk will destroy ALL data on the disk.
+Use
+extreme caution when issuing this command.
+Many users low-level format
+disks that do not really need to be low-level formatted.
+There are
relatively few scenarios that call for low-level formatting a disk.
One reason for
low-level formatting a disk is to initialize the disk after changing
-its physical sector size. Another reason for low-level formatting a disk
+its physical sector size.
+Another reason for low-level formatting a disk
is to revive the disk if you are getting "medium format corrupted" errors
from the disk in response to read and write requests.
.Pp
-Some disks take longer than others to format. Users should specify a
-timeout long enough to allow the format to complete. The default format
-timeout is 3 hours, which should be long enough for most disks. Some hard
+Some disks take longer than others to format.
+Users should specify a
+timeout long enough to allow the format to complete.
+The default format
+timeout is 3 hours, which should be long enough for most disks.
+Some hard
disks will complete a format operation in a very short period of time
-(on the order of 5 minutes or less). This is often because the drive
+(on the order of 5 minutes or less).
+This is often because the drive
doesn't really support the FORMAT UNIT command -- it just accepts the
command, waits a few minutes and then returns it.
.Pp
The
.Sq format
-subcommand takes several arguments that modify its default behavior. The
+subcommand takes several arguments that modify its default behavior.
+The
.Fl q
and
.Fl y
@@ -594,21 +669,27 @@ arguments can be useful for scripts.
.Pp
.Bl -tag -width 6n
.It Fl q
-Be quiet, don't print any status messages. This option will not disable
-the questions, however. To disable questions, use the
+Be quiet, don't print any status messages.
+This option will not disable
+the questions, however.
+To disable questions, use the
.Fl y
argument, below.
.It Fl w
-Issue a non-immediate format command. By default,
+Issue a non-immediate format command.
+By default,
.Nm
-issues the FORMAT UNIT command with the immediate bit set. This tells the
+issues the FORMAT UNIT command with the immediate bit set.
+This tells the
device to immediately return the format command, before the format has
-actually completed. Then,
+actually completed.
+Then,
.Nm
gathers
.Tn SCSI
sense information from the device every second to determine how far along
-in the format process it is. If the
+in the format process it is.
+If the
.Fl w
argument is specified,
.Nm
@@ -616,10 +697,12 @@ will issue a non-immediate format command, and will be unable to print any
information to let the user know what percentage of the disk has been
formatted.
.It Fl y
-Don't ask any questions. By default,
+Don't ask any questions.
+By default,
.Nm
will ask the user if he/she really wants to format the disk in question,
-and also if the default format command timeout is acceptable. The user
+and also if the default format command timeout is acceptable.
+The user
will not be asked about the timeout if a timeout is specified on the
command line.
.El
@@ -665,11 +748,14 @@ switch was not specified.
camcontrol tur da1 -E -C 4 -t 50 -v
.Ed
.Pp
-Send a test unit ready command to da1. Enable kernel error recovery.
-Specify a retry count of 4, and a timeout of 50 seconds. Enable sense
+Send a test unit ready command to da1.
+Enable kernel error recovery.
+Specify a retry count of 4, and a timeout of 50 seconds.
+Enable sense
printing (with the
.Fl v
-flag) if the command fails. Since error recovery is turned on, the
+flag) if the command fails.
+Since error recovery is turned on, the
disk will be spun up if it is not currently spinning.
The
.Nm
@@ -679,8 +765,10 @@ camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e
-i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"
.Ed
.Pp
-Issue a READ BUFFER command (0x3C) to cd1. Display the buffer size of cd1,
-and display the first 10 bytes from the cache on cd1. Display SCSI sense
+Issue a READ BUFFER command (0x3C) to cd1.
+Display the buffer size of cd1,
+and display the first 10 bytes from the cache on cd1.
+Display SCSI sense
information if the command fails.
.Pp
.Bd -literal -offset indent
@@ -688,9 +776,12 @@ camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e
-o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8
.Ed
.Pp
-Issue a WRITE BUFFER (0x3B) command to cd1. Write out 10 bytes of data,
-not including the (reserved) 4 byte header. Print out sense information if
-the command fails. Be very careful with this command, improper use may
+Issue a WRITE BUFFER (0x3B) command to cd1.
+Write out 10 bytes of data,
+not including the (reserved) 4 byte header.
+Print out sense information if
+the command fails.
+Be very careful with this command, improper use may
cause data corruption.
.Pp
.Bd -literal -offset indent
@@ -698,7 +789,8 @@ camcontrol modepage da3 -m 1 -e -P 3
.Ed
.Pp
Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the
-settings on the drive. Mode page 1 contains a disk drive's auto read and
+settings on the drive.
+Mode page 1 contains a disk drive's auto read and
write reallocation settings, among other things.
.Pp
.Dl camcontrol rescan all
@@ -729,7 +821,8 @@ Disable tagged queueing for da4.
camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a
.Ed
.Pp
-Negotiate a sync rate of 20MHz and an offset of 15 with da3. Then send a
+Negotiate a sync rate of 20MHz and an offset of 15 with da3.
+Then send a
Test Unit Ready command to make the settings take effect.
.Sh SEE ALSO
.Xr cam 3 ,
@@ -748,7 +841,8 @@ code in the old
.Xr scsi 8
utility and
.Xr scsi 3
-library, written by Julian Elischer and Peter Dufault. The
+library, written by Julian Elischer and Peter Dufault.
+The
.Xr scsi 8
program first appeared in
.Bx 386 0.1.2.4 ,
@@ -760,7 +854,8 @@ in
.An Kenneth Merry Aq ken@FreeBSD.org
.Sh BUGS
The code that parses the generic command line arguments doesn't know that
-some of the subcommands take multiple arguments. So if, for instance, you
+some of the subcommands take multiple arguments.
+So if, for instance, you
tried something like this:
.Bd -literal -offset indent
camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v
@@ -774,9 +869,11 @@ call in
bails out when it sees the second argument to
.Fl c
(0x00),
-above. Fixing this behavior would take some gross code, or changes to the
+above.
+Fixing this behavior would take some gross code, or changes to the
.Xr getopt 3
-interface. The best way to circumvent this problem is to always make sure
+interface.
+The best way to circumvent this problem is to always make sure
to specify generic
.Nm
arguments before any command-specific arguments.
diff --git a/sbin/ccdconfig/ccdconfig.8 b/sbin/ccdconfig/ccdconfig.8
index fdba97bd8e40..ca79dc81006e 100644
--- a/sbin/ccdconfig/ccdconfig.8
+++ b/sbin/ccdconfig/ccdconfig.8
@@ -62,13 +62,15 @@
The
.Nm
utility is used to dynamically configure and unconfigure concatenated disk
-devices, or ccds. For more information about the ccd, see
+devices, or ccds.
+For more information about the ccd, see
.Xr ccd 4 .
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl c
-Configure a ccd. This is the default behavior of
+Configure a ccd.
+This is the default behavior of
.Nm .
.It Fl C
Configure all ccd devices listed in the ccd configuration file.
@@ -79,8 +81,10 @@ instead of the default
.Pa /etc/ccd.conf .
.It Fl g
Dump the current ccd configuration in a format suitable for use as the
-ccd configuration file. If no arguments are specified, every configured
-ccd is dumped. Otherwise, the configuration of each listed ccd is dumped.
+ccd configuration file.
+If no arguments are specified, every configured
+ccd is dumped.
+Otherwise, the configuration of each listed ccd is dumped.
.It Fl u
Unconfigure a ccd.
.It Fl U
@@ -93,7 +97,8 @@ to be verbose.
.Pp
A ccd is described on the command line and in the ccd configuration
file by the name of the ccd, the interleave factor, the ccd configuration
-flags, and a list of one or more devices. The flags may be represented
+flags, and a list of one or more devices.
+The flags may be represented
as a decimal number, a hexadecimal number, a comma-separated list
of strings, or the word
.Dq none .
@@ -127,17 +132,22 @@ as shown by
.Sh EXAMPLES
A number of
.Nm
-examples are shown below. The arguments passed
+examples are shown below.
+The arguments passed
to
.Nm
are exactly the same as you might place in the
.Pa /etc/ccd.conf
-configuration file. The first example creates a 4-disk stripe out of
-four scsi disk partitions. The stripe uses a 64 sector interleave.
+configuration file.
+The first example creates a 4-disk stripe out of
+four scsi disk partitions.
+The stripe uses a 64 sector interleave.
The second example is an example of a complex stripe/mirror combination.
It reads as a two disk stripe of da4 and da5 which is mirrored
-to a two disk stripe of da6 and da7. The last example is a simple
-mirror. The 2nd slice of /dev/da8 is mirrored with the 3rd slice of /dev/da9
+to a two disk stripe of da6 and da7.
+The last example is a simple
+mirror.
+The 2nd slice of /dev/da8 is mirrored with the 3rd slice of /dev/da9
and assigned to ccd0.
.Pp
.Bd -unfilled -offset
@@ -150,14 +160,19 @@ When you create a new ccd disk you generally want to
.Xr fdisk 8
and
.Xr disklabel 8
-it before doing anything else. Once you create the initial label you can
-edit it, adding additional partitions. The label itself takes up the first
-16 sectors of the ccd disk. If all you are doing is creating file systems
+it before doing anything else.
+Once you create the initial label you can
+edit it, adding additional partitions.
+The label itself takes up the first
+16 sectors of the ccd disk.
+If all you are doing is creating file systems
with newfs, you do not have to worry about this as newfs will skip the
-label area. However, if you intend to
+label area.
+However, if you intend to
.Xr dd 1
to or from a ccd partition it is usually a good idea to construct the
-partition such that it does not overlap the label area. For example, if
+partition such that it does not overlap the label area.
+For example, if
you have A ccd disk with 10000 sectors you might create a 'd' partition
with offset 16 and size 9984.
.Pp
@@ -173,16 +188,21 @@ the disklabel you
had created before will still be there and not require reinitialization.
Beware that changing any ccd parameters: interleave, flags, or the
device list making up the ccd disk, will usually destroy any prior
-data on that ccd disk. If this occurs it is usually a good idea to
+data on that ccd disk.
+If this occurs it is usually a good idea to
reinitialize the label before [re]constructing your ccd disk.
.Sh RECOVERY
An error on a ccd disk is usually unrecoverable unless you are using the
-mirroring option. But mirroring has its own perils: It assumes that
-both copies of the data at any given sector are the same. This holds true
+mirroring option.
+But mirroring has its own perils: It assumes that
+both copies of the data at any given sector are the same.
+This holds true
until a write error occurs or until you replace either side of the mirror.
-This is a poor-man's mirroring implementation. It works well enough that if
+This is a poor-man's mirroring implementation.
+It works well enough that if
you begin to get disk errors you should be able to backup the ccd disk,
-replace the broken hardware, and then regenerate the ccd disk. If you need
+replace the broken hardware, and then regenerate the ccd disk.
+If you need
more than this you should look into external hardware RAID SCSI boxes,
RAID controllers (see GENERIC),
or software RAID systems such as
diff --git a/sbin/comcontrol/comcontrol.8 b/sbin/comcontrol/comcontrol.8
index 361ed68c63d1..bf719f9af3be 100644
--- a/sbin/comcontrol/comcontrol.8
+++ b/sbin/comcontrol/comcontrol.8
@@ -60,5 +60,6 @@ dialout devices
.Sh HISTORY
Originally part of cgd's com package patches, version 0.2.1, to
.Bx 386 0.1 .
-Once controlled bidirectional capabilities. Little is left to control now
+Once controlled bidirectional capabilities.
+Little is left to control now
that these capabilities are standard.
diff --git a/sbin/dumpfs/dumpfs.8 b/sbin/dumpfs/dumpfs.8
index 3c3204e36a33..8e701d5ba0f6 100644
--- a/sbin/dumpfs/dumpfs.8
+++ b/sbin/dumpfs/dumpfs.8
@@ -45,7 +45,8 @@ utility prints out the super block and cylinder group information
for the file system or special device specified, unless
.Fl m
is specified.
-The listing is very long and detailed. This
+The listing is very long and detailed.
+This
command is useful mostly for finding out certain file system
information such as the file system block size and minimum
free space percentage.
diff --git a/sbin/fdisk/fdisk.8 b/sbin/fdisk/fdisk.8
index 7eda677f793e..a7730ead3496 100644
--- a/sbin/fdisk/fdisk.8
+++ b/sbin/fdisk/fdisk.8
@@ -267,7 +267,7 @@ it will set up the last BIOS slice to use the whole disk for
.Fx
and make it active.
.Sh NOTES
-The automatic calculation of starting cylinder etc. uses
+The automatic calculation of starting cylinder etc.\& uses
a set of figures that represent what the BIOS thinks the
geometry of the drive is.
These figures are taken from the in-core disklabel by default,
diff --git a/sbin/fdisk_pc98/fdisk.8 b/sbin/fdisk_pc98/fdisk.8
index ba15116fce04..c4b25c75c964 100644
--- a/sbin/fdisk_pc98/fdisk.8
+++ b/sbin/fdisk_pc98/fdisk.8
@@ -24,7 +24,8 @@ Sector 0 of the disk must contain boot code,
a partition table,
and a magic number.
BIOS partitions can be used to break the disk up into several pieces.
-The BIOS brings in sector 0 and verifies the magic number. The sector
+The BIOS brings in sector 0 and verifies the magic number.
+The sector
0 boot code then searches the partition table to determine which
partition is marked
.Em active .
@@ -42,23 +43,27 @@ utility can be used to divide space on the disk into partitions and set one
The
.Fx
.Nm
-utility serves a similar purpose to the DOS program. The first form is used to
+utility serves a similar purpose to the DOS program.
+The first form is used to
display partition information or to interactively edit the partition
-table. The second is used to write a partition table using a
+table.
+The second is used to write a partition table using a
.Ar configfile
and is designed to be used by other scripts/programs.
.Pp
Options are:
.Bl -tag -width time
.It Fl a
-Change the active partition only. Ignored if
+Change the active partition only.
+Ignored if
.Fl f
is given.
.It Fl b Ar bootcode
Get the boot code from the file
.Ar bootcode .
.It Fl B
-Reinitialize the boot code contained in sector 0 of the disk. Ignored
+Reinitialize the boot code contained in sector 0 of the disk.
+Ignored
if
.Fl f
is given.
@@ -72,11 +77,13 @@ always modifies existing partitions, unless
is also given, in which case all existing partitions are deleted (marked
as "unused") before the
.Ar configfile
-is read. The
+is read.
+The
.Ar configfile
can be "-", in which case
.Ar stdin
-is read. See
+is read.
+See
.Sx CONFIGURATION FILE ,
below, for file syntax.
.Pp
@@ -84,7 +91,8 @@ below, for file syntax.
when
.Fl f
is used, you are not asked if you really want to write the partition
-table (as you are in the interactive mode). Use with caution!
+table (as you are in the interactive mode).
+Use with caution!
.\" !PC98
.\" .It Fl i
.\" Initialize sector 0 of the disk. This implies
@@ -100,22 +108,27 @@ table (as you are in the interactive mode). Use with caution!
.It Fl s
Print summary information and exit.
.It Fl t
-Test mode; do not write partition values. Generally used with the
+Test mode; do not write partition values.
+Generally used with the
.Fl f
-option to see what would be written to the partition table. Implies
+option to see what would be written to the partition table.
+Implies
.Fl v .
.It Fl u
-Is used for updating (editing) sector 0 of the disk. Ignored if
+Is used for updating (editing) sector 0 of the disk.
+Ignored if
.Fl f
is given.
.It Fl v
-Be verbose. When
+Be verbose.
+When
.Fl f
is used,
.Nm
prints out the partition table that is written to the disk.
.It Fl 12345678
-Operate on a single fdisk entry only. Ignored if
+Operate on a single fdisk entry only.
+Ignored if
.Fl f
is given.
.El
@@ -219,7 +232,8 @@ The flags
.Fl u
are used to indicate that the partition data is to be updated, unless the
.Fl f
-option is used. If the
+option is used.
+If the
.Fl f
option is not used, the
.Nm
@@ -275,7 +289,7 @@ it will setup the last BIOS partition to use the whole disk for
.Fx ;
and make it active.
.Sh NOTES
-The automatic calculation of starting cylinder etc. uses
+The automatic calculation of starting cylinder etc.\& uses
a set of figures that represent what the BIOS thinks is the
geometry of the drive.
These figures are by default taken from the incore disklabel,
@@ -294,8 +308,10 @@ Editing an existing partition will most likely cause you to
lose all the data in that partition.
.Pp
You should run this program interactively once or twice to see how it
-works. This is completely safe as long as you answer the last question
-in the negative. There are subtleties that the program detects that are
+works.
+This is completely safe as long as you answer the last question
+in the negative.
+There are subtleties that the program detects that are
not fully explained in this manual page.
.Sh CONFIGURATION FILE
When the
@@ -303,7 +319,8 @@ When the
option is given, a disk's partition table can be written using values
from a
.Ar configfile .
-The syntax of this file is very simple. Each line is either a comment or
+The syntax of this file is very simple.
+Each line is either a comment or
a specification, and whitespace (except for newlines) are ignored:
.Bl -tag -width Ds
.It Xo
@@ -317,7 +334,8 @@ Lines beginning with a "#" are comments and are ignored.
.Ar spec2
.Ar spec3
.Xc
-Set the BIOS geometry used in partition calculations. There must be
+Set the BIOS geometry used in partition calculations.
+There must be
three values specified, with a letter preceding each number:
.Bl -tag -width Ds
.Sm off
@@ -351,7 +369,8 @@ It is an error if the following is not true:
.Ed
.Pp
The number of cylinders should be less than or equal to 1024, but this
-is not enforced, although a warning will be output. Note that bootable
+is not enforced, although a warning will be output.
+Note that bootable
.Fx
partitions (the "/" file system) must lie completely within the
first 1024 cylinders; if this is not true, booting may fail.
@@ -387,7 +406,8 @@ However, if an invalid partition table is present, or the
.Fl i
option is specified, all existing partition entries will be cleared
(marked as unused), and these "p" lines will have to be used to
-explicitly set partition information. If multiple partitions need to be
+explicitly set partition information.
+If multiple partitions need to be
set, multiple "p" lines must be specified; one for each partition.
.Pp
These partition lines must occur after any geometry specification lines,
@@ -397,7 +417,8 @@ The
.Ar type
is 165 for
.Fx
-partitions. Specifying a partition type of zero is
+partitions.
+Specifying a partition type of zero is
the same as clearing the partition and marking it as unused; however,
dummy values (such as "0") must still be specified for
.Ar start
@@ -427,7 +448,8 @@ p 1 165 1 2503871
.Xc
Make
.Ar partition
-the active partition. Can occur anywhere in the config file, but only
+the active partition.
+Can occur anywhere in the config file, but only
one must be present.
.Pp
Example: to make partition 1 the active partition:
diff --git a/sbin/fsck/fsck.8 b/sbin/fsck/fsck.8
index 6caa47dd92ce..734c83c8134d 100644
--- a/sbin/fsck/fsck.8
+++ b/sbin/fsck/fsck.8
@@ -112,7 +112,9 @@ to be the partition and slice designators.
The options are as follows:
.Bl -tag -width indent
.It Fl d
-Debugging mode. Just print the commands without executing them. Available
+Debugging mode.
+Just print the commands without executing them.
+Available
only if
.Nm
is compiled to support it.
@@ -164,7 +166,8 @@ only one file system at a time will be checked.
.It Fl t Ar fstype
Invoke
.Nm
-only for the comma separated list of file system types. If the
+only for the comma separated list of file system types.
+If the
list starts with
.Dq no
then invoke
diff --git a/sbin/fsck_ffs/fsck_ffs.8 b/sbin/fsck_ffs/fsck_ffs.8
index 64b743097c16..4bfa11cb45e6 100644
--- a/sbin/fsck_ffs/fsck_ffs.8
+++ b/sbin/fsck_ffs/fsck_ffs.8
@@ -83,7 +83,8 @@ option will correct; if it encounters other inconsistencies, it exits
with an abnormal return status and an automatic reboot will then fail.
For each corrected inconsistency one or more lines will be printed
identifying the file system on which the correction will take place,
-and the nature of the correction. After successfully correcting a file system,
+and the nature of the correction.
+After successfully correcting a file system,
.Nm
will print the number of files on that file system,
the number of used and free blocks,
@@ -171,7 +172,8 @@ the file system is marked as needing a foreground check and
exits without attempting any further cleaning.
.It Fl b
Use the block specified immediately after the flag as
-the super block for the file system. Block 32 is usually
+the super block for the file system.
+Block 32 is usually
an alternate super block.
.It Fl c
Convert the file system to the specified level.
diff --git a/sbin/fsdb/fsdb.8 b/sbin/fsdb/fsdb.8
index 21b4b70d189b..194ba830c868 100644
--- a/sbin/fsdb/fsdb.8
+++ b/sbin/fsdb/fsdb.8
@@ -46,12 +46,14 @@ The
utility opens
.Ar fsname
(usually a raw disk partition) and runs a command loop
-allowing manipulation of the file system's inode data. You are prompted
+allowing manipulation of the file system's inode data.
+You are prompted
to enter a command with
.Ic "fsdb (inum X)>"
where
.Va X
-is the currently selected i-number. The initial selected inode is the
+is the currently selected i-number.
+The initial selected inode is the
root of the file system (i-number 2).
The command processor uses the
.Xr editline 3
@@ -101,7 +103,8 @@ Find
in the current directory and make its inode the current inode.
.Ar Name
may be a multi-component name or may begin with slash to indicate that
-the root inode should be used to start the lookup. If some component
+the root inode should be used to start the lookup.
+If some component
along the pathname is not found, the last valid directory encountered is
left as the active inode.
This command is valid only if the starting inode is a directory.
@@ -125,14 +128,16 @@ Set the active inode's link count to
.Ar number .
.Pp
.It Cm ls
-List the current inode's directory entries. This command is valid only
+List the current inode's directory entries.
+This command is valid only
if the current inode is a directory.
.Pp
.It Cm rm Ar name
.It Cm del Ar name
Remove the entry
.Ar name
-from the current directory inode. This command is valid only
+from the current directory inode.
+This command is valid only
if the current inode is a directory.
.Pp
.It Cm ln Ar ino Ar name
@@ -140,7 +145,8 @@ Create a link to inode
.Ar ino
under the name
.Ar name
-in the current directory inode. This command is valid only
+in the current directory inode.
+This command is valid only
if the current inode is a directory.
.Pp
.It Cm chinum Ar dirslot Ar inum
@@ -154,7 +160,8 @@ Change the name in directory entry
.Ar dirslot
to
.Ar name .
-This command cannot expand a directory entry. You can only rename an
+This command cannot expand a directory entry.
+You can only rename an
entry if the name will fit into the existing directory slot.
.Pp
.It Cm chtype Ar type
@@ -202,7 +209,8 @@ should be in the format
.Em YYYYMMDDHHMMSS[.nsec]
where
.Em nsec
-is an optional nanosecond specification. If no nanoseconds are specified, the
+is an optional nanosecond specification.
+If no nanoseconds are specified, the
.Va mtimensec ,
.Va ctimensec ,
or
@@ -231,7 +239,8 @@ The
.Nm
utility uses the source code for
.Xr fsck 8
-to implement most of the file system manipulation code. The remainder of
+to implement most of the file system manipulation code.
+The remainder of
.Nm
first appeared in
.Nx ,
diff --git a/sbin/fsirand/fsirand.8 b/sbin/fsirand/fsirand.8
index 1d7e56e0d13b..00f0eeee4c99 100644
--- a/sbin/fsirand/fsirand.8
+++ b/sbin/fsirand/fsirand.8
@@ -58,7 +58,8 @@ now does the equivalent of
itself so it is no longer necessary to
run
.Nm
-by hand on a new file system. It is only used to
+by hand on a new file system.
+It is only used to
re-randomize or report on an existing file system.
.Pp
The
diff --git a/sbin/ifconfig/ifconfig.8 b/sbin/ifconfig/ifconfig.8
index 24a954ee1248..a9c6a21db08e 100644
--- a/sbin/ifconfig/ifconfig.8
+++ b/sbin/ifconfig/ifconfig.8
@@ -135,7 +135,7 @@ The link-level
address
is specified as a series of colon-separated hex digits.
This can be used to
-e.g. set a new MAC address on an ethernet interface, though the
+e.g.\& set a new MAC address on an ethernet interface, though the
mechanism used is not ethernet-specific.
If the interface is already
up when this option is used, it will be briefly brought down and
diff --git a/sbin/init/init.8 b/sbin/init/init.8
index 240bfed88d3d..3a6419191269 100644
--- a/sbin/init/init.8
+++ b/sbin/init/init.8
@@ -121,7 +121,8 @@ but also inhibits running
while the system is multi-user.
.Pp
In addition, kernel time changes are restricted to less than or equal to one
-second. Attempts to change the time by more than this will log the message
+second.
+Attempts to change the time by more than this will log the message
.Dq Time adjustment clamped to +1 second .
.It Ic 3
Network secure mode \- same as highly secure mode, plus
@@ -189,7 +190,8 @@ program.
The
.Nm login
program, when a valid user logs in,
-executes a shell for that user. When this shell
+executes a shell for that user.
+When this shell
dies, either because the user logged out
or an abnormal termination occurred (a signal),
the
@@ -330,7 +332,7 @@ If run as a user process as shown in the second synopsis line,
.Nm
will emulate
.At V
-behavior, i.e. super-user can specify the desired
+behavior, i.e., super-user can specify the desired
.Em run-level
on a command line, and
.Nm
@@ -413,7 +415,8 @@ behave as though they have security level \-1.
Setting the security level above 1 too early in the boot sequence can
prevent
.Xr fsck 8
-from repairing inconsistent file systems. The
+from repairing inconsistent file systems.
+The
preferred location to set the security level is at the end of
.Pa /etc/rc
after all multi-user startup actions are complete.
diff --git a/sbin/ip6fw/ip6fw.8 b/sbin/ip6fw/ip6fw.8
index c036c23a2270..c6dd84e0d1c5 100644
--- a/sbin/ip6fw/ip6fw.8
+++ b/sbin/ip6fw/ip6fw.8
@@ -112,7 +112,7 @@ name search is performed.
Care should be taken with this in environments where not all
file systems are mounted (yet) by the time
.Nm
-is being run (e.g. when they are mounted over NFS).
+is being run (e.g.\& when they are mounted over NFS).
Once
.Fl p
has been specified, optional
@@ -175,7 +175,8 @@ needs.
The following options are available:
.Bl -tag -width flag
.It Fl a
-While listing, show counter values. See also
+While listing, show counter values.
+See also
.Dq show
command.
.It Fl f
@@ -189,11 +190,14 @@ without actually passing them into the kernel.
.It Fl q
While adding, zeroing or flushing, be quiet about actions (implies '-f').
This is useful for adjusting rules by executing multiple ip6fw commands in a
-script (e.g. sh /etc/rc.firewall), or by processing a file of many ip6fw rules,
-across a remote login session. If a flush is performed in normal
-(verbose) mode, it prints a message. Because all rules are flushed, the
+script (e.g.\& sh /etc/rc.firewall), or by processing a file of many ip6fw rules,
+across a remote login session.
+If a flush is performed in normal
+(verbose) mode, it prints a message.
+Because all rules are flushed, the
message cannot be delivered to the login session, the login session is
-closed and the remainder of the ruleset is not processed. Access to the
+closed and the remainder of the ruleset is not processed.
+Access to the
console is required to recover.
.It Fl t
While listing, show last match timestamp.
@@ -257,7 +261,8 @@ then when a packet matches a rule with the
.Dq log
keyword or a clear/resetlog is performed, a message will be logged to
.Xr syslogd 8 ,
-or, if that fails, to the console. If the kernel was compiled with the
+or, if that fails, to the console.
+If the kernel was compiled with the
.Dv IPV6FIREWALL_VERBOSE_LIMIT
option, then logging will cease after the number of packets
specified by the option are received for that particular
@@ -335,9 +340,10 @@ and the length of the port list is limited to
.In netinet6/ip6_fw.h )
ports.
.Pp
-Fragmented packets which have a non-zero offset (i.e. not the first
+Fragmented packets which have a non-zero offset (i.e., not the first
fragment) will never match a rule which has one or more port
-specifications. See the
+specifications.
+See the
.Ar frag
option for details on matching fragmented packets.
.Pp
@@ -405,7 +411,7 @@ or
is invalid.
.Pp
A packet may not have a receive or transmit interface: packets originating
-from the local host have no receive interface. while packets destined for
+from the local host have no receive interface, while packets destined for
the local host have no transmit interface.
.Pp
Additional
@@ -469,7 +475,8 @@ with a
A rule which contains a
.Ar tcpflags
specification can never match a fragmented packet which has
-a non-zero offset. See the
+a non-zero offset.
+See the
.Ar frag
option for details on matching fragmented packets.
.It icmptypes Ar types
diff --git a/sbin/ipfw/ipfw.8 b/sbin/ipfw/ipfw.8
index 1845c68a9e6f..9197b6b12285 100644
--- a/sbin/ipfw/ipfw.8
+++ b/sbin/ipfw/ipfw.8
@@ -151,7 +151,7 @@ option, then
.Nm
assumes a
.Em stateful
-behaviour, i.e. upon a match it will create dynamic rules matching
+behaviour, i.e., upon a match it will create dynamic rules matching
the exact parameters (addresses and ports) of the matching packet.
.Pp
These dynamic rules, which have a limited lifetime, are checked
@@ -200,7 +200,8 @@ Also, each rule belongs to one of 32 different
.Nm
commands to atomically manipulate sets, such as enable,
disable, swap sets, move all rules in a set to another
-one, delete all rules in a set. These can be useful to
+one, delete all rules in a set.
+These can be useful to
install temporary configurations, or to test them.
See Section
.Sx SETS OF RULES
@@ -220,7 +221,7 @@ Implies
.Fl c .
.It Fl c
When entering or showing rules, print them in compact form,
-i.e. without the optional "ip from any to any" string
+i.e., without the optional "ip from any to any" string
when this does not carry any additional information.
.It Fl d
While listing, show dynamic rules in addition to static ones.
@@ -310,7 +311,7 @@ name search is performed.
Care should be taken with this in environments where not all
file systems are mounted (yet) by the time
.Nm
-is being run (e.g. when they are mounted over NFS).
+is being run (e.g.\& when they are mounted over NFS).
Once
.Fl p
has been specified, any additional arguments as passed on to the preprocessor
@@ -330,8 +331,10 @@ Section below.
.Pp
If the world and the kernel get out of sync the
.Nm
-ABI may break, preventing you from being able to add any rules. This can
-adversely effect the booting process. You can use
+ABI may break, preventing you from being able to add any rules.
+This can
+adversely effect the booting process.
+You can use
.Nm
.Cm disable
.Cm firewall
@@ -377,7 +380,7 @@ is invoked from
Also note that each packet is always checked against the complete ruleset,
irrespective of the place where the check occurs, or the source of the packet.
If a rule contains some match patterns or actions which are not valid
-for the place of invocation (e.g. trying to match a MAC header within
+for the place of invocation (e.g.\& trying to match a MAC header within
.Cm ip_input()
), the match pattern will not match, but a
.Cm not
@@ -407,16 +410,18 @@ ether_demux and bdg_forward).
.Sh SYNTAX
In general, each keyword or argument must be provided as
a separate command line argument, with no leading or trailing
-spaces. Keywords are case-sensitive, whereas arguments may
+spaces.
+Keywords are case-sensitive, whereas arguments may
or may not be case-sensitive depending on their nature
-(e.g. uid's are, hostnames are not).
+(e.g.\& uid's are, hostnames are not).
.Pp
In
.Nm ipfw2
you can introduce spaces after commas ',' to make
-the line more readable. You can also put the entire
+the line more readable.
+You can also put the entire
command (including flags) into a single argument.
-E.g. the following forms are equivalent:
+E.g., the following forms are equivalent:
.Bd -literal -offset indent
ipfw -q add deny src-ip 10.0.0.0/24,127.0.0.1/8
ipfw -q add deny src-ip 10.0.0.0/24, 127.0.0.1/8
@@ -466,7 +471,7 @@ for ICMP packets
When the packet can be associated with a local socket.
.El
.Pp
-Note that some of the above information, e.g. source MAC or IP addresses and
+Note that some of the above information, e.g.\& source MAC or IP addresses and
TCP/UDP ports, could easily be spoofed, so filtering on those fields
alone might not guarantee the desired results.
.Bl -tag -width indent
@@ -489,7 +494,7 @@ Automatic rule numbers are assigned by incrementing the last
non-default rule number by the value of the sysctl variable
.Ar net.inet.ip.fw.autoinc_step
which defaults to 100.
-If this is not possible (e.g. because we would go beyond the
+If this is not possible (e.g.\& because we would go beyond the
maximum allowed rule number), the number of the last
non-default value is used instead.
.It Cm set Ar set_number
@@ -693,7 +698,7 @@ protocol options, incoming or outgoing interfaces, etc.)
that the packet must match in order to be recognised.
In general, the patterns are connected by (implicit)
.Cm and
-operators -- i.e. all must match in order for the
+operators -- i.e., all must match in order for the
rule to match.
Individual patterns can be prefixed by the
.Cm not
@@ -813,7 +818,8 @@ specified as a dotted quad.
As an example, 1.2.3.4:255.0.255.0 will match
1.*.3.*.
This form is advised only for non-contiguous
-masks. It is better to resort to the
+masks.
+It is better to resort to the
.Ar addr Ns / Ns Ar masklen
format for contiguous masks, which is more compact and less
error-prone.
@@ -831,11 +837,13 @@ or ranges.
The
.Ar masklen
field is used to limit the size of the set of addresses,
-and can have any value between 24 and 32. If not specified,
+and can have any value between 24 and 32.
+If not specified,
it will be assumed as 24.
.br
This format is particularly useful to handle sparse address sets
-within a single rule. Because the matching occurs using a
+within a single rule.
+Because the matching occurs using a
bitmask, it takes constant time and dramatically reduces
the complexity of rulesets.
.br
@@ -874,7 +882,7 @@ character).
.Pp
.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any"
.Pp
-Fragmented packets which have a non-zero offset (i.e. not the first
+Fragmented packets which have a non-zero offset (i.e., not the first
fragment) will never match a rule which has one or more port
specifications.
See the
@@ -883,7 +891,8 @@ option for details on matching fragmented packets.
.El
.Ss RULE OPTIONS (MATCH PATTERNS)
Additional match patterns can be used within
-rules. Zero or more of these so-called
+rules.
+Zero or more of these so-called
.Em options
can be present in a rule, optionally prefixed by the
.Cm not
@@ -910,8 +919,9 @@ specified as argument.
Matches TCP packets that have the RST or ACK bits set.
.It Cm frag
Matches packets that are fragments and not the first
-fragment of an IP datagram. Note that these packets will not have
-the next protocol header (e.g. TCP, UDP) so options that look into
+fragment of an IP datagram.
+Note that these packets will not have
+the next protocol header (e.g.\& TCP, UDP) so options that look into
these headers cannot match.
.It Cm gid Ar group
Matches all TCP or UDP packets sent by or received for a
@@ -978,7 +988,7 @@ specified in the same way as
Matches IP packets whose total length, including header and data, is
in the set
.Ar len-list ,
-which is either a single value or a list of values or ranges
+which is either a single value or a list of values or ranges
specified in the same way as
.Ar ports .
.It Cm ipoptions Ar spec
@@ -1003,7 +1013,7 @@ Matches IP packets whose precedence field is equal to
.Ar precedence .
.It Cm ipsec
Matches packets that have IPSEC history associated with them
-(i.e. the packet comes encapsulated in IPSEC, the kernel
+(i.e., the packet comes encapsulated in IPSEC, the kernel
has IPSEC support and IPSEC_FILTERGIF option, and can correctly
decapsulate it).
.Pp
@@ -1059,7 +1069,7 @@ The rule has a limited lifetime (controlled by a set of
variables), and the lifetime is refreshed every time a matching
packet is found.
.It Cm layer2
-Matches only layer2 packets, i.e. those passed to
+Matches only layer2 packets, i.e., those passed to
.Nm
from ether_demux() and ether_output_frame().
.It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N
@@ -1114,7 +1124,7 @@ corresponds to one of those specified as argument.
.Ar mac-type
is specified in the same way as
.Cm port numbers
-(i.e. one or more comma-separated single values or ranges).
+(i.e., one or more comma-separated single values or ranges).
You can use symbolic names for known values such as
.Em vlan , ipv4, ipv6 .
Values can be entered as decimal or hexadecimal (if prefixed by 0x),
@@ -1337,7 +1347,8 @@ When you disable a set, its rules behave as if they do not exist
in the firewall configuration, with only one exception:
.Bd -ragged -offset indent
dynamic rules created from a rule before it had been disabled
-will still be active until they expire. In order to delete
+will still be active until they expire.
+In order to delete
dynamic rules you have to explicitly delete the parent rule
which generated them.
.Ed
@@ -1362,7 +1373,8 @@ Section on some possible uses of sets of rules.
.Sh STATEFUL FIREWALL
Stateful operation is a way for the firewall to dynamically
create rules for specific flows when packets that
-match a given pattern are detected. Support for stateful
+match a given pattern are detected.
+Support for stateful
operation comes through the
.Cm check-state , keep-state
and
@@ -1589,7 +1601,8 @@ where the latter means all bits in all fields are significant.
.It Cm noerror
When a packet is dropped by a dummynet queue or pipe, the error
is normally reported to the caller routine in the kernel, in the
-same way as it happens when a device queue fills up. Setting this
+same way as it happens when a device queue fills up.
+Setting this
option reports the packet as successfully delivered, which can be
needed for some experimental setups where you want to simulate
loss or congestion at a remote router.
@@ -1615,7 +1628,7 @@ queueing delay.
E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
or 20s of queue on a 30Kbit/s pipe.
Even worse effects can result if you get packets from an
-interface with a much larger MTU, e.g. the loopback interface
+interface with a much larger MTU, e.g.\& the loopback interface
with its 16KB packets.
.Pp
.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p
@@ -1783,7 +1796,8 @@ Current number of dynamic rules
.It Em net.inet.ip.fw.dyn_keepalive : No 1
Enables generation of keepalive packets for
.Cm keep-state
-rules on TCP sessions. A keepalive is generated to both
+rules on TCP sessions.
+A keepalive is generated to both
sides of the connection every 5 seconds for the last 20
seconds of the lifetime of the rule.
.It Em net.inet.ip.fw.dyn_max : No 8192
@@ -1806,7 +1820,8 @@ Both
and
.Em dyn_rst_lifetime
must be strictly lower than 5 seconds, the period of
-repetition of keepalives. The firewall enforces that.
+repetition of keepalives.
+The firewall enforces that.
.It Em net.inet.ip.fw.enable : No 1
Enables the firewall.
Setting this variable to 0 lets you run your machine without
@@ -1911,7 +1926,8 @@ you can only specify ports when the rule is requesting
.Cm tcp
or
.Cm udp
-packets. With
+packets.
+With
.Nm ipfw2
you can put port specifications in rules matching all packets,
and the match will be attempted only on those packets carrying
@@ -2035,7 +2051,8 @@ following to the top of a ruleset:
.Dl "ipfw add deny ip from any to any not verrevpath in"
.Pp
This rule drops all incoming packets that appear to be coming to the
-system on the wrong interface. For example, a packet with a source
+system on the wrong interface.
+For example, a packet with a source
address belonging to a host on a protected internal network would be
dropped if it tried to enter the system from an external interface.
.Ss DYNAMIC RULES
@@ -2115,7 +2132,7 @@ A similar effect can be achieved making use of dummynet pipes:
.Dl "ipfw add pipe 10 ip from any to any"
.Dl "ipfw pipe 10 config plr 0.05"
.Pp
-We can use pipes to artificially limit bandwidth, e.g. on a
+We can use pipes to artificially limit bandwidth, e.g.\& on a
machine acting as a router, if we want to limit traffic from
local clients on 192.168.2.0/24 we do:
.Pp
@@ -2137,11 +2154,11 @@ limitations, the correct way is the following:
.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes"
.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes"
.Pp
-The above can be very useful, e.g. if you want to see how
+The above can be very useful, e.g.\& if you want to see how
your fancy Web page will look for a residential user who
is connected only through a slow link.
You should not use only one pipe for both directions, unless
-you want to simulate a half-duplex medium (e.g. AppleTalk,
+you want to simulate a half-duplex medium (e.g.\& AppleTalk,
Ethernet, IRDA).
It is not necessary that both pipes have the same configuration,
so we can also simulate asymmetric links.
@@ -2191,7 +2208,7 @@ on a net with per-host limits, rather than per-network limits:
.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
.Ss SETS OF RULES
-To add a set of rules atomically, e.g. set 18:
+To add a set of rules atomically, e.g.\& set 18:
.Pp
.Dl "ipfw set disable 18"
.Dl "ipfw add NN set 18 ... # repeat as needed"
@@ -2208,7 +2225,8 @@ To test a ruleset and disable it and regain control if something goes wrong:
.Dl "ipfw set enable 18; echo done; sleep 30 && ipfw set disable 18"
.Pp
Here if everything goes well, you press control-C before the "sleep"
-terminates, and your ruleset will be left active. Otherwise, e.g. if
+terminates, and your ruleset will be left active.
+Otherwise, e.g.\& if
you cannot access your box, the ruleset will be disabled after
the sleep terminates thus restoring the previous situation.
.Sh SEE ALSO
diff --git a/sbin/ldconfig/ldconfig.8 b/sbin/ldconfig/ldconfig.8
index 2c84f0ee4daf..007d30d44a2c 100644
--- a/sbin/ldconfig/ldconfig.8
+++ b/sbin/ldconfig/ldconfig.8
@@ -48,7 +48,8 @@ utility is used to prepare a set of
.Dq hints
for use by the dynamic linker
to facilitate quick lookup of shared libraries available in multiple
-directories. It scans a set of built-in system directories and any
+directories.
+It scans a set of built-in system directories and any
.Ar directories
specified on the command line (in the given order) looking for
shared libraries and stores the results in a system file to forestall
@@ -57,8 +58,10 @@ operations the dynamic linker would have to perform to load the
required shared libraries.
.Pp
Files named on the command line are expected to contain directories
-to scan for shared libraries. Each directory's pathname must start on a new
-line. Blank lines and lines starting with the comment character
+to scan for shared libraries.
+Each directory's pathname must start on a new
+line.
+Blank lines and lines starting with the comment character
.Ql \&#
are ignored.
Filenames must conform to the
@@ -105,15 +108,18 @@ Generate the hints for a.out format shared libraries.
.It Fl elf
Generate the hints for ELF format shared libraries.
.It Fl R
-Rescan the previously configured directories. This opens the previous hints
-file and fetches the directory list from the header. Any additional pathnames
+Rescan the previously configured directories.
+This opens the previous hints
+file and fetches the directory list from the header.
+Any additional pathnames
on the command line are also processed.
This is the default action when no parameters are given.
.It Fl f Ar hints_file
Read and/or update the specified hints file, instead of the standard file.
This option is provided primarily for testing.
.It Fl i
-Run in insecure mode. The security checks will not be performed.
+Run in insecure mode.
+The security checks will not be performed.
.It Fl m
Instead of replacing the contents of the hints file
with those found in the directories specified,
@@ -125,7 +131,8 @@ are also rescanned for new shared libraries.
.It Fl r
List the current contents of the hints file
on the standard output.
-The hints file is not modified. The list of
+The hints file is not modified.
+The list of
directories stored in the hints file is included.
.It Fl s
Do not scan the built-in system directory
@@ -160,7 +167,8 @@ Overrides
.Fl aout
or
.Fl elf
-is the default. If set, its value should be either
+is the default.
+If set, its value should be either
.Ql aout
or
.Ql elf .
@@ -184,7 +192,8 @@ Determines whether
.Fl aout
or
.Fl elf
-is the default. If present, it must consist of a single line
+is the default.
+If present, it must consist of a single line
containing either
.Ql OBJFORMAT=aout
or
diff --git a/sbin/mdconfig/mdconfig.8 b/sbin/mdconfig/mdconfig.8
index 1e22dc468b34..fb2b4067450d 100644
--- a/sbin/mdconfig/mdconfig.8
+++ b/sbin/mdconfig/mdconfig.8
@@ -105,7 +105,8 @@ Filename to use for the vnode type memory disk.
.It Fl l
List information about configured
.Xr md 4
-devices. If the
+devices.
+If the
.Fl u
option is used in conjuction with this, the output is limited to
information on the specified device.
diff --git a/sbin/mknod/mknod.8 b/sbin/mknod/mknod.8
index 2bc91cd5449c..7de2a1b7de58 100644
--- a/sbin/mknod/mknod.8
+++ b/sbin/mknod/mknod.8
@@ -65,7 +65,8 @@ and pseudo devices, and are type
.Cm c .
.It Ar major
The major device number is an integer number which tells the kernel
-which device driver entry point to use. To learn what
+which device driver entry point to use.
+To learn what
major device number to use for a particular device, check
.Pa /usr/src/sys/conf/majors .
.It Ar minor
diff --git a/sbin/mount_cd9660/mount_cd9660.8 b/sbin/mount_cd9660/mount_cd9660.8
index 6f281fb63f24..b72bd6e63375 100644
--- a/sbin/mount_cd9660/mount_cd9660.8
+++ b/sbin/mount_cd9660/mount_cd9660.8
@@ -105,12 +105,15 @@ Start the file system at
Normally, if the underlying device is a CD-ROM drive,
.Nm
will try to figure out the last track from the CD-ROM containing
-data, and start the file system there. If the device is not a CD-ROM,
+data, and start the file system there.
+If the device is not a CD-ROM,
or the table of contents cannot be examined, the file system will be
-started at sector 0. This option can be used to override the behaviour.
+started at sector 0.
+This option can be used to override the behaviour.
Note that
.Ar startsector
-is measured in CD-ROM blocks, with 2048 bytes each. This is the same
+is measured in CD-ROM blocks, with 2048 bytes each.
+This is the same
as for example the
.Cm info
command of
diff --git a/sbin/mount_nfs/mount_nfs.8 b/sbin/mount_nfs/mount_nfs.8
index b12ddab5be30..48c55efc4c72 100644
--- a/sbin/mount_nfs/mount_nfs.8
+++ b/sbin/mount_nfs/mount_nfs.8
@@ -315,7 +315,7 @@ tune the timeout
interval.)
.It Fl w
Set the write data size to the specified value.
-Ditto the comments w.r.t. the
+Ditto the comments w.r.t.\& the
.Fl r
option, but using the
.Dq "fragments dropped due to timeout"
diff --git a/sbin/mount_nullfs/mount_nullfs.8 b/sbin/mount_nullfs/mount_nullfs.8
index 43534f000f49..03060debda6b 100644
--- a/sbin/mount_nullfs/mount_nullfs.8
+++ b/sbin/mount_nullfs/mount_nullfs.8
@@ -103,7 +103,8 @@ The
.Nm
utility takes two arguments, the pathname
of the lower vfs (target-pn) and the pathname where the null
-layer will appear in the namespace (mount-point-pn). After
+layer will appear in the namespace (mount-point-pn).
+After
the null layer is put into place, the contents
of target-pn subtree will be aliased under mount-point-pn.
.\"
@@ -111,15 +112,19 @@ of target-pn subtree will be aliased under mount-point-pn.
.Sh OPERATION OF A NULL LAYER
The null layer is the minimum file system layer,
simply bypassing all possible operations to the lower layer
-for processing there. The majority of its activity centers
+for processing there.
+The majority of its activity centers
on the bypass routine, through which nearly all vnode operations
pass.
.Pp
The bypass routine accepts arbitrary vnode operations for
-handling by the lower layer. It begins by examining vnode
+handling by the lower layer.
+It begins by examining vnode
operation arguments and replacing any null-nodes by their
-lower-layer equivalents. It then invokes the operation
-on the lower layer. Finally, it replaces the null-nodes
+lower-layer equivalents.
+It then invokes the operation
+on the lower layer.
+Finally, it replaces the null-nodes
in the arguments and, if a vnode is returned by the operation,
stacks a null-node on top of the returned vnode.
.Pp
@@ -144,11 +149,13 @@ information.
.\"
.Sh INSTANTIATING VNODE STACKS
Mounting associates the null layer with a lower layer,
-in effect stacking two VFSes. Vnode stacks are instead
+in effect stacking two VFSes.
+Vnode stacks are instead
created on demand as files are accessed.
.Pp
The initial mount creates a single vnode stack for the
-root of the new null layer. All other vnode stacks
+root of the new null layer.
+All other vnode stacks
are created as a result of vnode operations on
this or other null vnode stacks.
.Pp
@@ -168,7 +175,8 @@ the root null-node (which was created when the null layer was mounted).
Now consider opening
.Pa sys .
A vop_lookup would be
-done on the root null-node. This operation would bypass through
+done on the root null-node.
+This operation would bypass through
to the lower layer which would return a vnode representing
the UFS
.Pa sys .
@@ -197,8 +205,10 @@ null layer.
.\"
.Sh INVOKING OPERATIONS ON LOWER LAYERS
There are two techniques to invoke operations on a lower layer
-when the operation cannot be completely bypassed. Each method
-is appropriate in different situations. In both cases,
+when the operation cannot be completely bypassed.
+Each method
+is appropriate in different situations.
+In both cases,
it is the responsibility of the aliasing layer to make
the operation arguments "correct" for the lower layer
by mapping a vnode argument to the lower layer.
@@ -217,7 +227,8 @@ the lower layer with the
.Em VOP_OPERATIONNAME
interface.
The advantage of this method is that it is easy to invoke
-arbitrary operations on the lower layer. The disadvantage
+arbitrary operations on the lower layer.
+The disadvantage
is that vnode arguments must be manually mapped.
.\"
.\"
@@ -228,8 +239,11 @@ UCLA Technical Report CSD-910056,
.Em "Stackable Layers: an Architecture for File System Development" .
.Sh BUGS
THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK)
-AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR
-OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET.
+AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM.
+USE AT YOUR
+OWN RISK.
+BEWARE OF DOG.
+SLIPPERY WHEN WET.
.Pp
This code also needs an owner in order to be less dangerous - serious
hackers can apply by sending mail to
diff --git a/sbin/mount_std/mount_std.8 b/sbin/mount_std/mount_std.8
index 56ff0ff8e19d..86284d6dab5e 100644
--- a/sbin/mount_std/mount_std.8
+++ b/sbin/mount_std/mount_std.8
@@ -53,7 +53,8 @@ file systems
The
.Nm
utility is a generic mechanism for attaching ``standard'' file systems to
-the file system. The
+the file system.
+The
.Nm
utility currently supports the following file systems:
.Nm devfs ,
@@ -96,7 +97,8 @@ man page for possible options and their meanings.
The
.Nm
utility examines its zeroth command-line argument (the name by which
-it was called) to determine the type of file system to be mounted. If
+it was called) to determine the type of file system to be mounted.
+If
it is called by a name which does not end in
.Dq Li _ Ns Ar fsname ,
.Nm
diff --git a/sbin/mount_umapfs/mount_umapfs.8 b/sbin/mount_umapfs/mount_umapfs.8
index 403b219b9ede..1fe47657ce56 100644
--- a/sbin/mount_umapfs/mount_umapfs.8
+++ b/sbin/mount_umapfs/mount_umapfs.8
@@ -58,9 +58,11 @@ The
.Nm
utility uses a set of files provided by the user to make correspondences
between uids and gids in the sub-tree's original environment and
-some other set of ids in the local environment. For instance, user
+some other set of ids in the local environment.
+For instance, user
smith might have uid 1000 in the original environment, while having
-uid 2000 in the local environment. The
+uid 2000 in the local environment.
+The
.Nm
utility allows the subtree from smith's original environment to be
mapped in such a way that all files with owning uid 1000 look like
@@ -86,7 +88,8 @@ where the mapped subtree is to be placed.
Describe the mappings to be made between identifiers.
Briefly, the format of these files is a count of the number of
mappings on the first line, with each subsequent line containing
-a single mapping. Each of these mappings consists of an id in
+a single mapping.
+Each of these mappings consists of an id in
the local environment and the corresponding id from the original environment,
separated by white space.
.Ar Uid-mapfile
@@ -100,7 +103,8 @@ will be treated as user NOBODY,
and any gids not mapped in
.Ar gid-mapfile
will be treated as group
-NULLGROUP. At most 64 uids can be mapped for a given subtree, and
+NULLGROUP.
+At most 64 uids can be mapped for a given subtree, and
at most 16 groups can be mapped by a given subtree.
.El
.Pp
@@ -109,21 +113,26 @@ must be owned by root, and they must be writable only by root.
The
.Nm
utility will refuse to map the sub-tree if the ownership or permissions on
-these files are improper. It will also balk if the count of mappings
+these files are improper.
+It will also balk if the count of mappings
in the first line of the map files is not correct.
.Pp
The layer created by the
.Nm
utility is meant to serve as a simple example of file system layering.
-It is not meant for production use. The implementation is not very
+It is not meant for production use.
+The implementation is not very
sophisticated.
.Sh SEE ALSO
.Xr mount 8 ,
.Xr mount_nullfs 8
.Sh BUGS
THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK)
-AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR
-OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET.
+AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM.
+USE AT YOUR
+OWN RISK.
+BEWARE OF DOG.
+SLIPPERY WHEN WET.
.Pp
This code also needs an owner in order to be less dangerous - serious
hackers can apply by sending mail to
diff --git a/sbin/mount_unionfs/mount_unionfs.8 b/sbin/mount_unionfs/mount_unionfs.8
index 2a939f9b5f62..2a41aa6d3a09 100644
--- a/sbin/mount_unionfs/mount_unionfs.8
+++ b/sbin/mount_unionfs/mount_unionfs.8
@@ -179,8 +179,11 @@ accessible via
.Xr mount_nullfs 8
.Sh BUGS
THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK)
-AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR
-OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET.
+AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM.
+USE AT YOUR
+OWN RISK.
+BEWARE OF DOG.
+SLIPPERY WHEN WET.
.Pp
This code also needs an owner in order to be less dangerous - serious
hackers can apply by sending mail to
diff --git a/sbin/newfs_msdos/newfs_msdos.8 b/sbin/newfs_msdos/newfs_msdos.8
index 7d5718d530e6..b4189a5a9e94 100644
--- a/sbin/newfs_msdos/newfs_msdos.8
+++ b/sbin/newfs_msdos/newfs_msdos.8
@@ -78,26 +78,32 @@ FAT type (one of 12, 16, or 32).
.It Fl I Ar volid
Volume ID.
.It Fl L Ar label
-Volume label (up to 11 characters). The label should consist of
+Volume label (up to 11 characters).
+The label should consist of
only those characters permitted in regular DOS (8+3) filenames.
.It Fl O Ar OEM
-OEM string (up to 8 characters). The default is
+OEM string (up to 8 characters).
+The default is
.Qq Li "BSD 4.4" .
.It Fl S Ar sector-size
-Number of bytes per sector. Acceptable values are powers of 2
+Number of bytes per sector.
+Acceptable values are powers of 2
in the range 128 through 32768.
.It Fl a Ar FAT-size
Number of sectors per FAT.
.It Fl b Ar block-size
-File system block size (bytes per cluster). This should resolve to an
+File system block size (bytes per cluster).
+This should resolve to an
acceptable number of sectors per cluster (see below).
.It Fl c Ar cluster-size
-Sectors per cluster. Acceptable values are powers of 2 in the range
+Sectors per cluster.
+Acceptable values are powers of 2 in the range
1 through 128.
.It Fl e Ar dirents
Number of root directory entries (FAT12 and FAT16 only).
.It Fl f Ar format
-Specify a standard (floppy disk) format. The standard formats
+Specify a standard (floppy disk) format.
+The standard formats
are (capacities in kilobytes): 160, 180, 320, 360, 640, 720, 1200,
1232, 1440, 2880.
.It Fl h Ar heads
@@ -106,12 +112,14 @@ Number of drive heads.
Location of the file system info sector (FAT32 only).
A value of 0xffff signifies no info sector.
.It Fl k Ar backup
-Location of the backup boot sector (FAT32 only). A value
+Location of the backup boot sector (FAT32 only).
+A value
of 0xffff signifies no backup sector.
.It Fl m Ar media
Media descriptor (acceptable range 0xf0 to 0xff).
.It Fl n Ar FATs
-Number of FATs. Acceptable values are 1 to 16 inclusive.
+Number of FATs.
+Acceptable values are 1 to 16 inclusive.
The default
is 2.
.It Fl o Ar hidden
@@ -126,7 +134,8 @@ Number of sectors per track.
.Sh NOTES
FAT file system parameters occupy a "Boot Sector BPB (BIOS Parameter
Block)" in the first of the "reserved" sectors which precede the actual
-file system. For reference purposes, this structure is presented
+file system.
+For reference purposes, this structure is presented
below.
.Bd -literal
struct bsbpb {
diff --git a/sbin/nos-tun/nos-tun.8 b/sbin/nos-tun/nos-tun.8
index 0cfdeb132df1..9e7b9ae02692 100644
--- a/sbin/nos-tun/nos-tun.8
+++ b/sbin/nos-tun/nos-tun.8
@@ -49,7 +49,8 @@ and
are the addresses used on the tunnel device.
If you configure the tunnel against a cisco router, use a netmask of
.Dq 255.255.255.252
-on the cisco. This is because the tunnel is a point-to-point interface
+on the cisco.
+This is because the tunnel is a point-to-point interface
in the
.Fx
end, a concept cisco doesn't really implement.
diff --git a/sbin/reboot/boot_i386.8 b/sbin/reboot/boot_i386.8
index b5f86f5b0c9c..7b98df014737 100644
--- a/sbin/reboot/boot_i386.8
+++ b/sbin/reboot/boot_i386.8
@@ -51,7 +51,8 @@ and unless this fails, the system will resume multi-user operations.
.Sy Cold starts .
Most i386 PCs attempt to boot first from floppy disk drive 0 (sometimes
known as drive A:) and, failing that, from hard disk drive 0 (sometimes
-known as drive C:, or as drive 0x80 to the BIOS). Some BIOSes allow
+known as drive C:, or as drive 0x80 to the BIOS).
+Some BIOSes allow
you to change this default sequence, and may also include a CD-ROM
drive as a boot device.
.Pp
@@ -77,10 +78,12 @@ or
.Sy /
is displayed) before
.Xr loader 8
-is invoked. Booting will also be attempted at stage two, if the
+is invoked.
+Booting will also be attempted at stage two, if the
third stage cannot be loaded.
.Pp
-The remainder of this subsection deals only with the boot blocks. The
+The remainder of this subsection deals only with the boot blocks.
+The
.Xr loader 8
program is documented separately.
.Pp
@@ -100,11 +103,13 @@ of either the floppy or the hard disk.
This boot may be aborted by typing any character on the keyboard
at the
.Ql boot:
-prompt. At this time, the following input will be accepted:
+prompt.
+At this time, the following input will be accepted:
.Bl -tag -width indent
.It Ic \&?
Give a short listing of the files in the root directory of the default
-boot device, as a hint about available boot files. (A
+boot device, as a hint about available boot files.
+(A
.Ic ?\&
may also be specified as the last segment of a path, in which case
the listing will be of the relevant subdirectory.)
@@ -122,7 +127,8 @@ Specify boot file and flags.
The drive number as recognized by the BIOS.
0 for the first drive, 1 for the second drive, etc.
.It Ar interface
-The type of controller to boot from. Note that the controller is required
+The type of controller to boot from.
+Note that the controller is required
to have BIOS support since the BIOS services are used to load the
boot file image.
.Pp
@@ -145,11 +151,13 @@ The unit number of the drive on the interface being used.
.It Oo Ar slice , Oc Ns Ar part
The partition letter inside the
.Bx
-portion of the disk. See
+portion of the disk.
+See
.Xr disklabel 8 .
By convention, only partition
.Ql a
-contains a bootable image. If sliced disks are used
+contains a bootable image.
+If sliced disks are used
.Pq Dq fdisk partitions ,
any
.Ar slice
@@ -167,7 +175,8 @@ slice (also known as
slice) is booted from.
.It Ar filename
The pathname of the file to boot (relative to the root directory
-on the specified partition). Defaults to
+on the specified partition).
+Defaults to
.Pa /kernel .
Symbolic links are not supported (hard links are).
.It Fl aCcDdghmnPprsv
@@ -181,23 +190,28 @@ ask for the device to mount as the root file system.
boot from CDROM.
.It Fl c
run UserConfig to modify hardware parameters for the loaded
-kernel. If the kernel was built with one of
+kernel.
+If the kernel was built with one of
.Dv USERCONFIG , INTRO_USERCONFIG , VISUAL_USERCONFIG
options,
remain in UserConfig regardless of any
.Ic quit
commands present in the script.
.It Fl D
-toggle single and dual console configurations. In the single
+toggle single and dual console configurations.
+In the single
configuration the console will be either the internal display
or the serial port, depending on the state of the
.Fl h
-option below. In the dual console configuration,
+option below.
+In the dual console configuration,
both the internal display and the serial port will become the console
at the same time, regardless of the state of the
.Fl h
-option. However, the dual console configuration takes effect only during
-the boot prompt. Once the kernel is loaded, the console specified
+option.
+However, the dual console configuration takes effect only during
+the boot prompt.
+Once the kernel is loaded, the console specified
by the
.Fl h
option becomes the only console.
@@ -209,12 +223,15 @@ as early as possible in kernel initialization.
.It Fl g
use the GDB remote debugging protocol.
.It Fl h
-toggle internal and serial consoles. You can use this to switch
-console devices. For instance, if you boot from the internal console,
+toggle internal and serial consoles.
+You can use this to switch
+console devices.
+For instance, if you boot from the internal console,
you can use the
.Fl h
option to force the kernel to use the serial port as its
-console device. Alternatively, if you boot from the serial port,
+console device.
+Alternatively, if you boot from the serial port,
you can use this option to force the kernel to use the internal display
as the console instead.
The serial port driver
@@ -223,7 +240,8 @@ has a flag to override this option.
If that flag is set, the serial port will always be used as the console,
regardless of the
.Fl h
-option described here. See the man page for
+option described here.
+See the man page for
.Xr sio 4
for more details.
.It Fl m
@@ -233,7 +251,8 @@ ignore key press to interrupt boot before
.Xr loader 8
is invoked.
.It Fl P
-probe the keyboard. If no keyboard is found, the
+probe the keyboard.
+If no keyboard is found, the
.Fl D
and
.Fl h
@@ -262,7 +281,8 @@ be verbose during device probing (and later).
You may put a BIOS drive number, a controller type, a unit number,
a partition, a kernel file name, and any valid option in
.Pa /boot.config
-to set defaults. Enter them in one line just as you type at the
+to set defaults.
+Enter them in one line just as you type at the
.Ql boot:
prompt.
.Sh FILES
@@ -325,7 +345,8 @@ On older machines, or otherwise where EDD support (disk packet
interface support) is not available, all boot-related files and
structures (including the kernel) that need to be accessed during the
boot phase must reside on the disk at or below cylinder 1023 (as the
-BIOS understands the geometry). When a
+BIOS understands the geometry).
+When a
.Dq Disk error 0x1
is reported by the second-stage bootstrap, it generally means that this
requirement has not been adhered to.
@@ -341,7 +362,8 @@ Due to space constraints, the keyboard probe initiated by the
.Fl P
option is simply a test that the BIOS has detected an
.Dq extended
-keyboard. If an
+keyboard.
+If an
.Dq XT/AT
keyboard (with no F11 and F12 keys, etc.) is attached, the probe will
fail.
diff --git a/sbin/restore/restore.8 b/sbin/restore/restore.8
index 445a157d18ce..1d5776021272 100644
--- a/sbin/restore/restore.8
+++ b/sbin/restore/restore.8
@@ -205,7 +205,8 @@ The
.Fl r
flag precludes an interactive file extraction and can be
detrimental to one's health if not used carefully (not to mention
-the disk). An example:
+the disk).
+An example:
.Bd -literal -offset indent
newfs /dev/da0s1a
mount /dev/da0s1a /mnt
@@ -279,7 +280,8 @@ tries to determine the media block size dynamically.
Normally,
.Nm
will try to determine dynamically whether the dump was made from an
-old (pre-4.4) or new format file system. The
+old (pre-4.4) or new format file system.
+The
.Fl c
flag disables this check, and only allows reading a dump in the old
format.
@@ -472,8 +474,10 @@ thus a full dump must be done to get a new set of directories
reflecting the new inode numbering,
even though the contents of the files is unchanged.
.Pp
-To do a network restore, you have to run restore as root. This is due
-to the previous security history of dump and restore. (restore is
+To do a network restore, you have to run restore as root.
+This is due
+to the previous security history of dump and restore.
+(restore is
written to be setuid root, but we are not certain all bugs are gone
from the restore code - run setuid at your own risk.)
.Pp
diff --git a/sbin/route/route.8 b/sbin/route/route.8
index 335d07286f0d..30b807cd87c3 100644
--- a/sbin/route/route.8
+++ b/sbin/route/route.8
@@ -46,7 +46,8 @@
The
.Nm
utility is used to manually manipulate the network
-routing tables. It normally is not needed, as a
+routing tables.
+It normally is not needed, as a
system routing table management daemon, such as
.Xr routed 8 ,
should tend to this task.
@@ -65,7 +66,8 @@ The following options are available:
Run in debug-only mode, i.e., do not actually modify the routing table.
.It Fl n
Bypass attempts to print host and network names symbolically
-when reporting actions. (The process of translating between symbolic
+when reporting actions.
+(The process of translating between symbolic
names and numerical equivalents can be quite time consuming, and
may require correct operation of the network; thus it may be expedient
to forget this, especially when attempting to repair networking operations).
@@ -356,7 +358,8 @@ the routing tables.
.Sh DIAGNOSTICS
.Bl -diag
.It "add [host \&| network ] %s: gateway %s flags %x"
-The specified route is being added to the tables. The
+The specified route is being added to the tables.
+The
values printed are from the routing table entry supplied
in the
.Xr ioctl 2
diff --git a/sbin/routed/routed.8 b/sbin/routed/routed.8
index f483ed947799..afee816fdee9 100644
--- a/sbin/routed/routed.8
+++ b/sbin/routed/routed.8
@@ -211,9 +211,11 @@ It continues listening to RIP while using Router Discovery
if multi-homed to ensure all interfaces are used.
.Pp
The Router Discovery standard requires that advertisements
-have a default "lifetime" of 30 minutes. That means should
+have a default "lifetime" of 30 minutes.
+That means should
something happen, a client can be without a good route for
-30 minutes. It is a good idea to reduce the default to 45
+30 minutes.
+It is a good idea to reduce the default to 45
seconds using
.Fl P Cm rdisc_interval=45
on the command line or
@@ -240,7 +242,7 @@ facility described below to support "legacy" systems
that can handle neither RIPv2 nor Router Discovery.
.Pp
By default, neither Router Discovery advertisements nor solicitations
-are sent over point to point links (e.g. PPP).
+are sent over point to point links (e.g.\& PPP).
The netmask associated with point-to-point links (such as SLIP
or PPP, with the IFF_POINTOPOINT flag) is used by
.Nm
@@ -286,7 +288,8 @@ This is typically used on a gateway to the Internet,
or on a gateway that uses another routing protocol whose routes
are not reported to other local routers.
Notice that because a metric of 1 is used, this feature is
-dangerous. It is more commonly accidentally used to create chaos with a
+dangerous.
+It is more commonly accidentally used to create chaos with a
routing loop than to solve problems.
.It Fl h
cause host or point-to-point routes to not be advertised,
@@ -514,7 +517,7 @@ To set parameters for remote or external interfaces,
a line starting with
.Cm if=alias(Hname) ,
.Cm if=remote(Hname) ,
-etc. should be used.
+etc.\& should be used.
.Ss Parameters
Lines that start with neither "net" nor "host" must consist of one
or more of the following parameter settings, separated by commas or
@@ -535,7 +538,8 @@ This parameter must appear by itself on a line.
The network number must specify a full, 32-bit value, as in 192.0.2.0
instead of 192.0.2.
.Pp
-Do not use this feature unless necessary. It is dangerous.
+Do not use this feature unless necessary.
+It is dangerous.
.It Cm ripv1_mask Ns = Ns Ar nname Ns / Ns Ar mask1 , Ns Ar mask2
specifies that netmask of the network of which
.Ar nname Ns / Ns Ar mask1
diff --git a/sbin/shutdown/shutdown.8 b/sbin/shutdown/shutdown.8
index e0fa853726e7..d7073b2bc2f1 100644
--- a/sbin/shutdown/shutdown.8
+++ b/sbin/shutdown/shutdown.8
@@ -112,7 +112,8 @@ specify a future time in one of two formats:
or
.Ar yymmddhhmm ,
where the year, month, and day may be defaulted
-to the current system values. The first form brings the system down in
+to the current system values.
+The first form brings the system down in
.Ar number
minutes and the second at the absolute time specified.
.It Ar warning-message
@@ -127,15 +128,18 @@ input.
.Pp
At intervals, becoming more frequent as apocalypse approaches
and starting at ten hours before shutdown, warning messages are displayed
-on the terminals of all users logged in. Five minutes before
+on the terminals of all users logged in.
+Five minutes before
shutdown, or immediately if shutdown is in less than 5 minutes,
logins are disabled by creating
.Pa /var/run/nologin
and copying the
-warning message there. If this file exists when a user attempts to
+warning message there.
+If this file exists when a user attempts to
log in,
.Xr login 1
-prints its contents and exits. The file is
+prints its contents and exits.
+The file is
removed just before
.Nm
exits.
diff --git a/sbin/slattach/slattach.8 b/sbin/slattach/slattach.8
index 594c4b4cfeea..a6355d884d4a 100644
--- a/sbin/slattach/slattach.8
+++ b/sbin/slattach/slattach.8
@@ -66,7 +66,8 @@ Autoenable the VJ header compression option, if the other end of the link
is capable of VJ header compression then it will be used otherwise normal
headers will be used.
.It Fl c
-Enable the VJ header compression option. Note that both ends of the link
+Enable the VJ header compression option.
+Note that both ends of the link
must be able to use VJ header compression for this to work.
.It Fl e Ar exit-command
Specify a command to be invoked within a shell
@@ -83,7 +84,8 @@ Turn on cts/rts style flow control on the slip port, by default no flow
control is done.
.It Fl l
Disable modem control (CLOCAL) and ignore carrier detect on the slip
-port. By default the
+port.
+By default the
.Ar redial-command
is invoked upon carrier drop and
.Nm
@@ -91,7 +93,8 @@ aborts if no
.Ar redial-command
is specified.
.It Fl n
-Throw away ICMP packets. The slip interface will ignore ICMP packets
+Throw away ICMP packets.
+The slip interface will ignore ICMP packets
to prevent slow lines being saturated by ICMP responses.
.It Fl r Ar redial-command
Specify a command to be invoked within a shell
@@ -116,7 +119,8 @@ and
.Ar new
are the slip unit numbers when the line was
last opened and the unit number of the current slip connection
-respectively. The unit number can change after redialing if you are
+respectively.
+The unit number can change after redialing if you are
using more than one slip line.
When
.Nm
@@ -150,7 +154,8 @@ If FRAME_END is not received in
this amount of time, re-connect occurs.
The default value is no timeout.
.It Fl O Ar outfill
-Set SLIP "out fill" timeout in seconds. It forces at least one FRAME_END
+Set SLIP "out fill" timeout in seconds.
+It forces at least one FRAME_END
to be sent during this time period, which is necessary for the "keep alive"
timeout on the remote side.
The default value is no timeout.
@@ -185,7 +190,8 @@ To setup
to redial the phone when carrier is lost, use the
.Fl r Ar redial-command
option to specify a script or executable that will reconnect the
-serial line to the slip server. For example, the script could redial
+serial line to the slip server.
+For example, the script could redial
the server and log in, etc.
.Pp
To reconfigure the network interface in case the slip unit number
@@ -198,8 +204,10 @@ where
and
.Ar new
are the slip unit numbers before and after
-reconnecting the line. The unit number can change if you have more
-than one line disconnect at the same time. The first to succeed in
+reconnecting the line.
+The unit number can change if you have more
+than one line disconnect at the same time.
+The first to succeed in
reconnecting will get the lowest unit number.
.Pp
To kill
@@ -240,7 +248,8 @@ The
.Nm
utility
also logs failure to set the controlling terminal or failure to install
-signal handlers. Upon connection and redial the ttyname and baud rate
+signal handlers.
+Upon connection and redial the ttyname and baud rate
are logged and on shutdown the ttyname is logged.
.Sh FILES
.Bl -tag -width /usr/share/examples/slattach/* -compact
diff --git a/sbin/spppcontrol/spppcontrol.8 b/sbin/spppcontrol/spppcontrol.8
index 66896c30b98b..0b038c2e49fa 100644
--- a/sbin/spppcontrol/spppcontrol.8
+++ b/sbin/spppcontrol/spppcontrol.8
@@ -117,11 +117,11 @@ In the latter case, the use of an authentication protocol will be
turned off for the named interface.
This has the side-effect of
clearing the other authentication-related parameters for this
-interface as well (i.e. system name and authentication secret will
+interface as well (i.e., system name and authentication secret will
be forgotten).
.It Va myauthproto Ns Li = Ns Ar protoname
Same as above, but only for my end of the link.
-I.e. this is the
+I.e., this is the
protocol when remote is authenticator, and I am the peer required to
authenticate.
.It Va hisauthproto Ns Li = Ns Ar protoname
@@ -221,7 +221,7 @@ Display the settings for
.Li bppp0 .
The interface is currently in
.Em dead
-phase, i.e. the LCP layer is down, and no traffic is possible.
+phase, i.e., the LCP layer is down, and no traffic is possible.
Both
ends of the connection use the CHAP protocol, my end tells remote the
system name
diff --git a/sbin/startslip/startslip.1 b/sbin/startslip/startslip.1
index 47738736fc41..e18506547d5e 100644
--- a/sbin/startslip/startslip.1
+++ b/sbin/startslip/startslip.1
@@ -121,7 +121,8 @@ the string is used to specify a dial sequence.
No string written by default.
You can specify several
.Fl s Ar stringN
-arguments to use with each try, f.e. several host phone numbers.
+arguments to use with each try, f.e.
+several host phone numbers.
.It Fl A Ar annexname
The
.Nm
@@ -144,11 +145,13 @@ Disable modem control (waiting for carrier and carrier drop sense) for
.Ar device .
Modem control is enabled by default.
.It Fl U Ar upscript
-Specify a script to run when a SLIP interface becomes connected. This may
+Specify a script to run when a SLIP interface becomes connected.
+This may
contain
.Xr ifconfig 8 ,
.Xr route 8 ,
-and other appropriate commands. The arguments that
+and other appropriate commands.
+The arguments that
are passed to the script are "slX up".
Default value is
.Pa /sbin/ifconfig .
@@ -158,8 +161,10 @@ passed via
.Ev LINE
environment variable.
.It Fl D Ar downscript
-Specify a script to run when a SLIP connection goes away. The arguments that
-are passed to the script are "slX down". Default value is
+Specify a script to run when a SLIP connection goes away.
+The arguments that
+are passed to the script are "slX down".
+Default value is
.Pa /sbin/ifconfig .
Dial sequence number (see
.Fl s )
diff --git a/sbin/vinum/vinum.8 b/sbin/vinum/vinum.8
index fd8db0903aac..157b020a7aa5 100644
--- a/sbin/vinum/vinum.8
+++ b/sbin/vinum/vinum.8
@@ -173,7 +173,8 @@ Write a copy of the current configuration to
.It Ic quit
Exit the
.Nm
-utility when running in interactive mode. Normally this would be done by
+utility when running in interactive mode.
+Normally this would be done by
entering the
.Dv EOF
character.
@@ -271,12 +272,14 @@ utility communicates with the kernel component of the Vinum
logical volume manager.
It is designed either for interactive use, when started without command line
arguments, or to execute a single command if the command is supplied on the
-command line. In interactive mode,
+command line.
+In interactive mode,
.Nm
maintains a command line history.
.Sh OPTIONS
.Nm
-commands may optionally be followed by an option. Any of the following options
+commands may optionally be followed by an option.
+Any of the following options
may be specified with any command, but in some cases the options are ignored.
For example, the
.Ic stop
@@ -290,14 +293,18 @@ options.
The
.Fl f
.Pq Dq force
-option overrides safety checks. Use with extreme care. This option is for
-emergency use only. For example, the command
+option overrides safety checks.
+Use with extreme care.
+This option is for
+emergency use only.
+For example, the command
.Pp
.Dl rm -f myvolume
.Pp
removes
.Ar myvolume
-even if it is open. Any subsequent access to the volume will almost certainly
+even if it is open.
+Any subsequent access to the volume will almost certainly
cause a panic.
.It Fl i Ar millisecs
When performing the
@@ -306,7 +313,8 @@ and
.Ic start
commands, wait
.Ar millisecs
-milliseconds between copying each block. This lowers the load on the system.
+milliseconds between copying each block.
+This lowers the load on the system.
.It Fl n Ar name
Use the
.Fl n
@@ -319,7 +327,8 @@ The
.Fl r
.Pq Dq recursive
option is used by the list commands to display information not
-only about the specified objects, but also about subordinate objects. For
+only about the specified objects, but also about subordinate objects.
+For
example, in conjunction with the
.Ic lv
command, the
@@ -330,7 +339,8 @@ volume.
The
.Fl s
.Pq Dq statistics
-option is used by the list commands to display statistical information. The
+option is used by the list commands to display statistical information.
+The
.Ic mirror
command also uses this option to specify that it should create striped plexes.
.It Fl S Ar size
@@ -374,9 +384,12 @@ commands perform the following functions:
.Op Cm rename
.Xc
.Nm Ic attach
-inserts the specified plex or subdisk in a volume or plex. In the case of a
-subdisk, an offset in the plex may be specified. If it is not, the subdisk will
-be attached at the first possible location. After attaching a plex to a
+inserts the specified plex or subdisk in a volume or plex.
+In the case of a
+subdisk, an offset in the plex may be specified.
+If it is not, the subdisk will
+be attached at the first possible location.
+After attaching a plex to a
non-empty volume,
.Nm
reintegrates the plex.
@@ -388,7 +401,8 @@ is specified,
renames the object (and in the case of a plex, any subordinate subdisks) to fit
in with the default
.Nm
-naming convention. To rename the object to any other name, use the
+naming convention.
+To rename the object to any other name, use the
.Ic rename
command.
.Pp
@@ -402,18 +416,21 @@ failure), it should be replaced by a subdisk of the same size only.
.It
In order to add further subdisks to a striped or RAID-5 plex, use the
.Fl f
-(force) option. This will corrupt the data in the plex.
+(force) option.
+This will corrupt the data in the plex.
.\"No other attachment of
.\"subdisks is currently allowed for striped and RAID-5 plexes.
.It
For concatenated plexes, the
.Ar offset
-parameter specifies the offset in blocks from the beginning of the plex. For
+parameter specifies the offset in blocks from the beginning of the plex.
+For
striped and RAID-5 plexes, it specifies the offset of the first block of the
subdisk: in other words, the offset is the numerical position of the subdisk
-multiplied by the stripe size. For example, in a plex with stripe size 271k,
+multiplied by the stripe size.
+For example, in a plex with stripe size 271k,
the first subdisk will have offset 0, the second offset 271k, the third 542k,
-etc. This calculation ignores parity blocks in RAID-5 plexes.
+etc.\& This calculation ignores parity blocks in RAID-5 plexes.
.El
.Pp
.It Xo
@@ -422,9 +439,11 @@ etc. This calculation ignores parity blocks in RAID-5 plexes.
.Op Fl v
.Ar plex
.Xc
-Check the parity blocks on the specified RAID-4 or RAID-5 plex. This operation
+Check the parity blocks on the specified RAID-4 or RAID-5 plex.
+This operation
maintains a pointer in the plex, so it can be stopped and later restarted from
-the same position if desired. In addition, this pointer is used by the
+the same position if desired.
+In addition, this pointer is used by the
.Ic rebuildparity
command, so rebuilding the parity blocks need only start at the location where
the first parity problem has been detected.
@@ -433,7 +452,8 @@ If the
.Fl f
flag is specified,
.Ic checkparity
-starts checking at the beginning of the plex. If the
+starts checking at the beginning of the plex.
+If the
.Fl v
flag is specified,
.Ic checkparity
@@ -450,26 +470,31 @@ The
.Ic concat
command provides a simplified alternative to the
.Ic create
-command for creating volumes with a single concatenated plex. The largest
+command for creating volumes with a single concatenated plex.
+The largest
contiguous space available on each drive is used to create the subdisks for the
plexes.
.Pp
Normally, the
.Ic concat
-command creates an arbitrary name for the volume and its components. The name
+command creates an arbitrary name for the volume and its components.
+The name
is composed of the text
.Dq Li vinum
and a small integer, for example
.Dq Li vinum3 .
You can override this with the
.Fl n Ar name
-option, which assigns the name specified to the volume. The plexes and subdisks
+option, which assigns the name specified to the volume.
+The plexes and subdisks
are named after the volume in the default manner.
.Pp
-There is no choice of name for the drives. If the drives have already been
+There is no choice of name for the drives.
+If the drives have already been
initialized as
.Nm
-drives, the name remains. Otherwise the drives are given names starting with
+drives, the name remains.
+Otherwise the drives are given names starting with
the text
.Dq Li vinumdrive
and a small integer, for example
@@ -478,7 +503,8 @@ As with the
.Ic create
command, the
.Fl f
-option can be used to specify that a previous name should be overwritten. The
+option can be used to specify that a previous name should be overwritten.
+The
.Fl v
is used to specify verbose output.
.Pp
@@ -493,17 +519,21 @@ command.
.Ar description-file
.Xc
.Nm Ic create
-is used to create any object. In view of the relatively complicated
+is used to create any object.
+In view of the relatively complicated
relationship and the potential dangers involved in creating a
.Nm
-object, there is no interactive interface to this function. If you do not
+object, there is no interactive interface to this function.
+If you do not
specify a file name,
.Nm
-starts an editor on a temporary file. If the environment variable
+starts an editor on a temporary file.
+If the environment variable
.Ev EDITOR
is set,
.Nm
-starts this editor. If not, it defaults to
+starts this editor.
+If not, it defaults to
.Nm vi .
See the section
.Sx CONFIGURATION FILE
@@ -519,31 +549,38 @@ Normally the
.Ic create
command will not change the names of existing
.Nm
-drives, in order to avoid accidentally erasing them. The correct way to dispose
+drives, in order to avoid accidentally erasing them.
+The correct way to dispose
of no longer wanted
.Nm
drives is to reset the configuration with the
.Ic resetconfig
-command. In some cases, however, it may be necessary to create new data on
+command.
+In some cases, however, it may be necessary to create new data on
.Nm
-drives which can no longer be started. In this case, use the
+drives which can no longer be started.
+In this case, use the
.Ic create Fl f
command.
.Pp
.It Ic debug
.Nm Ic debug ,
-without any arguments, is used to enter the remote kernel debugger. It is only
+without any arguments, is used to enter the remote kernel debugger.
+It is only
activated if
.Nm
is built with the
.Dv VINUMDEBUG
-option. This option will stop the execution of the operating system until the
-kernel debugger is exited. If remote debugging is set and there is no remote
+option.
+This option will stop the execution of the operating system until the
+kernel debugger is exited.
+If remote debugging is set and there is no remote
connection for a kernel debugger, it will be necessary to reset the system and
reboot in order to leave the debugger.
.Pp
.It Ic debug Ar flags
-Set a bit mask of internal debugging flags. These will change without warning
+Set a bit mask of internal debugging flags.
+These will change without warning
as the product matures; to be certain, read the header file
.In sys/dev/vinumvar.h .
The bit mask is composed of the following values:
@@ -580,10 +617,12 @@ Print some warnings about minor problems in the implementation.
.It Ic detach Oo Fl f Oc Ar subdisk
.Nm Ic detach
removes the specified plex or subdisk from the volume or plex to which it is
-attached. If removing the object would impair the data integrity of the volume,
+attached.
+If removing the object would impair the data integrity of the volume,
the operation will fail unless the
.Fl f
-option is specified. If the object is named after the object above it (for
+option is specified.
+If the object is named after the object above it (for
example, subdisk
.Li vol1.p7.s0
attached to plex
@@ -597,7 +636,8 @@ If necessary, the name will be truncated in the
process.
.Pp
.Ic detach
-does not reduce the number of subdisks in a striped or RAID-5 plex. Instead,
+does not reduce the number of subdisks in a striped or RAID-5 plex.
+Instead,
the subdisk is marked absent, and can later be replaced with the
.Ic attach
command.
@@ -605,20 +645,25 @@ command.
.It Ic dumpconfig Op Ar drive ...
.Pp
.Nm Ic dumpconfig
-shows the configuration information stored on the specified drives. If no drive
+shows the configuration information stored on the specified drives.
+If no drive
names are specified,
.Ic dumpconfig
searches all drives on the system for Vinum partitions and dumps the
-information. If configuration updates are disabled, it is possible that this
+information.
+If configuration updates are disabled, it is possible that this
information is not the same as the information returned by the
.Ic list
-command. This command is used primarily for maintenance and debugging.
+command.
+This command is used primarily for maintenance and debugging.
.Pp
.It Ic info
.Nm Ic info
displays information about
.Nm
-memory usage. This is intended primarily for debugging. With the
+memory usage.
+This is intended primarily for debugging.
+With the
.Fl v
option, it will give detailed information about the memory areas in use.
.Pp
@@ -628,7 +673,9 @@ option,
.Ic info
displays information about the last up to 64 I/O requests handled by the
.Nm
-driver. This information is only collected if debug flag 8 is set. The format
+driver.
+This information is only collected if debug flag 8 is set.
+The format
looks like:
.Bd -literal
vinum -> info -V
@@ -656,21 +703,25 @@ Time Event Buf Dev Offset Bytes SD
.Pp
The
.Ar Buf
-field always contains the address of the user buffer header. This can be used
+field always contains the address of the user buffer header.
+This can be used
to identify the requests associated with a user request, though this is not 100%
reliable: theoretically two requests in sequence could use the same buffer
-header, though this is not common. The beginning of a request can be identified
+header, though this is not common.
+The beginning of a request can be identified
by the event
.Ar 1VS
or
.Ar 7VS .
-The first example above shows the requests involved in a user request. The
+The first example above shows the requests involved in a user request.
+The
second is a subdisk I/O request with locking.
.Pp
The
.Ar Event
field contains information related to the sequence of events in the request
-chain. The digit
+chain.
+The digit
.Ar 1
to
.Ar 6
@@ -682,7 +733,8 @@ a mnemonic for the location:
.Fn vinumstrategy .
The device number is the
.Nm
-device, and offset and length are the user parameters. This is always the
+device, and offset and length are the user parameters.
+This is always the
beginning of a request sequence.
.It 2LR
(launch_requests) shows the user request just prior to launching the low-level
@@ -712,13 +764,15 @@ is the offset of the associated group request, where applicable.
.It 3RQ
(request) shows one of possibly several low-level
.Nm
-requests which are launched to satisfy the high-level request. This information
+requests which are launched to satisfy the high-level request.
+This information
is also logged in
.Fn launch_requests .
.It 4DN
(done) is called from
.Fn complete_rqe ,
-showing the completion of a request. This completion should match a request
+showing the completion of a request.
+This completion should match a request
launched either at stage
.Ar 4DN
from
@@ -740,21 +794,25 @@ parity.
and represents the data written to a RAID-5 parity stripe after calculating
parity.
.It 7VS
-shows a subdisk I/O request. These requests are usually internal to
+shows a subdisk I/O request.
+These requests are usually internal to
.Nm
for operations like initialization or rebuilding plexes.
.It 8LR
shows the low-level operation generated for a subdisk I/O request.
.It Lockwait
-specifies that the process is waiting for a range lock. The parameters are the
+specifies that the process is waiting for a range lock.
+The parameters are the
buffer header associated with the request, the plex number and the block number.
For internal reasons the block number is one higher than the address of the
beginning of the stripe.
.It Lock
-specifies that a range lock has been obtained. The parameters are the same as
+specifies that a range lock has been obtained.
+The parameters are the same as
for the range lock.
.It Unlock
-specifies that a range lock has been released. The parameters are the same as
+specifies that a range lock has been released.
+The parameters are the same as
for the range lock.
.El
.\" XXX
@@ -766,13 +824,19 @@ for the range lock.
.Ar plex | subdisk
.Xc
.Nm Ic init
-initializes a subdisk by writing zeroes to it. You can initialize all subdisks
-in a plex by specifying the plex name. This is the only way to ensure
-consistent data in a plex. You must perform this initialization before using a
-RAID-5 plex. It is also recommended for other new plexes.
-.Nm
-initializes all subdisks of a plex in parallel. Since this operation can take a
-long time, it is normally performed in the background. If you want to wait for
+initializes a subdisk by writing zeroes to it.
+You can initialize all subdisks
+in a plex by specifying the plex name.
+This is the only way to ensure
+consistent data in a plex.
+You must perform this initialization before using a
+RAID-5 plex.
+It is also recommended for other new plexes.
+.Nm
+initializes all subdisks of a plex in parallel.
+Since this operation can take a
+long time, it is normally performed in the background.
+If you want to wait for
completion of the command, use the
.Fl w
(wait) option.
@@ -789,7 +853,8 @@ The
.Ic label
command writes a
.Em ufs
-style volume label on a volume. It is a simple alternative to an appropriate
+style volume label on a volume.
+It is a simple alternative to an appropriate
call to
.Ic disklabel .
This is needed because some
@@ -848,7 +913,8 @@ This command is deprecated.
.Op Ar volume
.Xc
.Ic list
-is used to show information about the specified object. If the argument is
+is used to show information about the specified object.
+If the argument is
omitted, information is shown about all objects known to
.Nm .
The
@@ -860,11 +926,13 @@ The
.Fl r
option relates to volumes and plexes: if specified, it recursively lists
information for the subdisks and (for a volume) plexes subordinate to the
-objects. The commands
+objects.
+The commands
.Ic lv , lp , ls
and
.Ic ld
-list only volumes, plexes, subdisks and drives respectively. This is
+list only volumes, plexes, subdisks and drives respectively.
+This is
particularly useful when used without parameters.
.Pp
The
@@ -889,37 +957,47 @@ The
.Ic mirror
command provides a simplified alternative to the
.Ic create
-command for creating mirrored volumes. Without any options, it creates a RAID-1
-(mirrored) volume with two concatenated plexes. The largest contiguous space
-available on each drive is used to create the subdisks for the plexes. The
+command for creating mirrored volumes.
+Without any options, it creates a RAID-1
+(mirrored) volume with two concatenated plexes.
+The largest contiguous space
+available on each drive is used to create the subdisks for the plexes.
+The
first plex is built from the odd-numbered drives in the list, and the second
-plex is built from the even-numbered drives. If the drives are of different
+plex is built from the even-numbered drives.
+If the drives are of different
sizes, the plexes will be of different sizes.
.Pp
If the
.Fl s
option is provided,
.Ic mirror
-builds striped plexes with a stripe size of 279 kB. The size of the subdisks in
+builds striped plexes with a stripe size of 279 kB.
+The size of the subdisks in
each plex is the size of the smallest contiguous storage available on any of the
-drives which form the plex. Again, the plexes may differ in size.
+drives which form the plex.
+Again, the plexes may differ in size.
.Pp
Normally, the
.Ic mirror
-command creates an arbitrary name for the volume and its components. The name
+command creates an arbitrary name for the volume and its components.
+The name
is composed of the text
.Dq Li vinum
and a small integer, for example
.Dq Li vinum3 .
You can override this with the
.Fl n Ar name
-option, which assigns the name specified to the volume. The plexes and subdisks
+option, which assigns the name specified to the volume.
+The plexes and subdisks
are named after the volume in the default manner.
.Pp
-There is no choice of name for the drives. If the drives have already been
+There is no choice of name for the drives.
+If the drives have already been
initialized as
.Nm
-drives, the name remains. Otherwise the drives are given names starting with
+drives, the name remains.
+Otherwise the drives are given names starting with
the text
.Dq Li vinumdrive
and a small integer, for example
@@ -928,7 +1006,8 @@ As with the
.Ic create
command, the
.Fl f
-option can be used to specify that a previous name should be overwritten. The
+option can be used to specify that a previous name should be overwritten.
+The
.Fl v
is used to specify verbose output.
.Pp
@@ -939,14 +1018,18 @@ command.
.Pp
.It Ic mv Fl f Ar drive object ...
.It Ic move Fl f Ar drive object ...
-Move all the subdisks from the specified objects onto the new drive. The
-objects may be subdisks, drives or plexes. When drives or plexes are specified,
+Move all the subdisks from the specified objects onto the new drive.
+The
+objects may be subdisks, drives or plexes.
+When drives or plexes are specified,
all subdisks associated with the object are moved.
.Pp
The
.Fl f
option is required for this function, since it currently does not preserve the
-data in the subdisk. This functionality will be added at a later date. In this
+data in the subdisk.
+This functionality will be added at a later date.
+In this
form, however, it is suited to recovering a failed disk drive.
.Pp
.It Ic printconfig Op Ar file
@@ -954,8 +1037,10 @@ Write a copy of the current configuration to
.Ar file
in a format that can be used to recreate the
.Nm
-configuration. Unlike the configuration saved on disk, it includes definitions
-of the drives. If you omit
+configuration.
+Unlike the configuration saved on disk, it includes definitions
+of the drives.
+If you omit
.Ar file ,
.Nm
writes the list to
@@ -964,7 +1049,8 @@ writes the list to
.It Ic quit
Exit the
.Nm
-utility when running in interactive mode. Normally this would be done by
+utility when running in interactive mode.
+Normally this would be done by
entering the
.Dv EOF
character.
@@ -974,14 +1060,16 @@ The
.Ic read
command scans the specified disks for
.Nm
-partitions containing previously created configuration information. It reads
+partitions containing previously created configuration information.
+It reads
the configuration in order from the most recently updated to least recently
updated configuration.
The
.Nm
utility
maintains an up-to-date copy of all configuration information on each disk
-partition. You must specify all of the slices in a configuration as the
+partition.
+You must specify all of the slices in a configuration as the
parameter to this command.
.Pp
The
@@ -990,7 +1078,8 @@ command is intended to selectively load a
.Nm
configuration on a system which has other
.Nm
-partitions. If you want to start all partitions on the system, it is easier to
+partitions.
+If you want to start all partitions on the system, it is easier to
use the
.Ic start
command.
@@ -998,14 +1087,17 @@ command.
If
.Nm
encounters any errors during this command, it will turn off automatic
-configuration update to avoid corrupting the copies on disk. This will also
+configuration update to avoid corrupting the copies on disk.
+This will also
happen if the configuration on disk indicates a configuration error (for
-example, subdisks which do not have a valid space specification). You can turn
+example, subdisks which do not have a valid space specification).
+You can turn
the updates on again with the
.Ic setdaemon
and
.Ic saveconfig
-commands. Reset bit 2 (numerical value 4) of the daemon options mask to
+commands.
+Reset bit 2 (numerical value 4) of the daemon options mask to
re-enable configuration saves.
.Pp
.It Xo
@@ -1015,9 +1107,11 @@ re-enable configuration saves.
.Op Fl V
.Ar plex
.Xc
-Rebuild the parity blocks on the specified RAID-4 or RAID-5 plex. This
+Rebuild the parity blocks on the specified RAID-4 or RAID-5 plex.
+This
operation maintains a pointer in the plex, so it can be stopped and later
-restarted from the same position if desired. In addition, this pointer is used
+restarted from the same position if desired.
+In addition, this pointer is used
by the
.Ic checkparity
command, so rebuilding the parity blocks need only start at the location where
@@ -1027,12 +1121,14 @@ If the
.Fl f
flag is specified,
.Ic rebuildparity
-starts rebuilding at the beginning of the plex. If the
+starts rebuilding at the beginning of the plex.
+If the
.Fl v
flag is specified,
.Ic rebuildparity
first checks the existing parity blocks prints information about those found to
-be incorrect before rebuilding. If the
+be incorrect before rebuilding.
+If the
.Fl V
flag is specified,
.Ic rebuildparity
@@ -1044,7 +1140,8 @@ prints a running progress report.
.Op Ar drive | subdisk | plex | volume
.Ar newname
.Xc
-Change the name of the specified object. If the
+Change the name of the specified object.
+If the
.Fl r
option is specified, subordinate objects will be named by the default rules:
plex names will be formed by appending
@@ -1068,7 +1165,8 @@ The
.Ic resetconfig
command completely obliterates the
.Nm
-configuration on a system. Use this command only when you want to completely
+configuration on a system.
+Use this command only when you want to completely
delete the configuration.
.Nm
will ask for confirmation; you must type in the words
@@ -1086,7 +1184,8 @@ NO FUTURE
Vinum configuration obliterated
.Ed
.Pp
-As the message suggests, this is a last-ditch command. Don't use it unless you
+As the message suggests, this is a last-ditch command.
+Don't use it unless you
have an existing configuration which you never want to see again.
.Pp
.It Xo
@@ -1095,13 +1194,15 @@ have an existing configuration which you never want to see again.
.Op Ar volume | plex | subdisk
.Xc
.Nm
-maintains a number of statistical counters for each object. See the header file
+maintains a number of statistical counters for each object.
+See the header file
.In sys/dev/vinumvar.h
for more information.
.\" XXX put it in here when it's finalized
Use the
.Ic resetstats
-command to reset these counters. In conjunction with the
+command to reset these counters.
+In conjunction with the
.Fl r
option,
.Nm
@@ -1116,20 +1217,24 @@ also resets the counters of subordinate objects.
.Ic rm
removes an object from the
.Nm
-configuration. Once an object has been removed, there is no way to recover it.
+configuration.
+Once an object has been removed, there is no way to recover it.
Normally
.Nm
-performs a large amount of consistency checking before removing an object. The
+performs a large amount of consistency checking before removing an object.
+The
.Fl f
option tells
.Nm
-to omit this checking and remove the object anyway. Use this option with great
+to omit this checking and remove the object anyway.
+Use this option with great
care: it can result in total loss of data on a volume.
.Pp
Normally,
.Nm
refuses to remove a volume or plex if it has subordinate plexes or subdisks
-respectively. You can tell
+respectively.
+You can tell
.Nm
to remove the object anyway by using the
.Fl f
@@ -1137,20 +1242,25 @@ option, or you can cause
.Nm
to remove the subordinate objects as well by using the
.Fl r
-(recursive) option. If you remove a volume with the
+(recursive) option.
+If you remove a volume with the
.Fl r
option, it will remove both the plexes and the subdisks which belong to the
plexes.
.Pp
.It Ic saveconfig
-Save the current configuration to disk. Normally this is not necessary, since
+Save the current configuration to disk.
+Normally this is not necessary, since
.Nm
-automatically saves any change in configuration. If an error occurs on startup,
-updates will be disabled. When you reenable them with the
+automatically saves any change in configuration.
+If an error occurs on startup,
+updates will be disabled.
+When you reenable them with the
.Ic setdaemon
command,
.Nm
-does not automatically save the configuration to disk. Use this command to save
+does not automatically save the configuration to disk.
+Use this command to save
the configuration.
.\".Pp
.\".It Xo
@@ -1175,19 +1285,24 @@ the configuration.
.Ic setdaemon
sets a variable bitmask for the
.Nm
-daemon. This command is temporary and will be replaced. Currently, the bit mask
+daemon.
+This command is temporary and will be replaced.
+Currently, the bit mask
may contain the bits 1 (log every action to syslog) and 4 (don't update
-configuration). Option bit 4 can be useful for error recovery.
+configuration).
+Option bit 4 can be useful for error recovery.
.Pp
.It Xo
.Ic setstate Ar state
.Op Ar volume | plex | subdisk | drive
.Xc
.Ic setstate
-sets the state of the specified objects to the specified state. This bypasses
+sets the state of the specified objects to the specified state.
+This bypasses
the usual consistency mechanism of
.Nm
-and should be used only for recovery purposes. It is possible to crash the
+and should be used only for recovery purposes.
+It is possible to crash the
system by incorrect use of this command.
.Pp
.It Xo
@@ -1210,7 +1325,8 @@ scans the disks known to the system for
.Nm
drives and then reads in the configuration as described under the
.Ic read
-commands. The
+commands.
+The
.Nm
drive contains a header with all information about the data stored on the drive,
including the names of the other drives which are required in order to represent
@@ -1219,19 +1335,24 @@ plexes and volumes.
If
.Nm
encounters any errors during this command, it will turn off automatic
-configuration update to avoid corrupting the copies on disk. This will also
+configuration update to avoid corrupting the copies on disk.
+This will also
happen if the configuration on disk indicates a configuration error (for
-example, subdisks which do not have a valid space specification). You can turn
+example, subdisks which do not have a valid space specification).
+You can turn
the updates on again with the
.Ic setdaemon
and
.Ic saveconfig
-command. Reset bit 4 of the daemon options mask to re-enable configuration
+command.
+Reset bit 4 of the daemon options mask to re-enable configuration
saves.
.Pp
If object names are specified,
.Nm
-starts them. Normally this operation is only of use with subdisks. The action
+starts them.
+Normally this operation is only of use with subdisks.
+The action
depends on the current state of the object:
.Bl -bullet
.It
@@ -1253,15 +1374,18 @@ state.
.It
If the object is a subdisk in the
.Em empty
-state, the change depends on the subdisk. If it is part of a plex which is part
+state, the change depends on the subdisk.
+If it is part of a plex which is part
of a volume which contains other plexes,
.Nm
places the subdisk in the
.Em reviving
-state and attempts to copy the data from the volume. When the operation
+state and attempts to copy the data from the volume.
+When the operation
completes, the subdisk is set into the
.Em up
-state. If it is part of a plex which is part of a volume which contains no
+state.
+If it is part of a plex which is part of a volume which contains no
other plexes, or if it is not part of a plex,
.Nm
brings it into the
@@ -1273,7 +1397,8 @@ If the object is a subdisk in the
state,
.Nm
continues the revive
-operation offline. When the operation completes, the subdisk is set into the
+operation offline.
+When the operation completes, the subdisk is set into the
.Em up
state.
.El
@@ -1291,19 +1416,23 @@ checks the state of the subordinate subdisks (and plexes in the case of a
volume) and starts any subdisks which can be started.
.Pp
To start a plex in a multi-plex volume, the data must be copied from another
-plex in the volume. Since this frequently takes a long time, it is normally
-done in the background. If you want to wait for this operation to complete (for
+plex in the volume.
+Since this frequently takes a long time, it is normally
+done in the background.
+If you want to wait for this operation to complete (for
example, if you are performing this operation in a script), use the
.Fl w
option.
.Pp
Copying data doesn't just take a long time, it can also place a significant load
-on the system. You can specify the transfer size in bytes or sectors with the
+on the system.
+You can specify the transfer size in bytes or sectors with the
.Fl S
option, and an interval (in milliseconds) to wait between copying each block with
the
.Fl i
-option. Both of these options lessen the load on the system.
+option.
+Both of these options lessen the load on the system.
.Pp
.It Xo
.Ic stop
@@ -1316,14 +1445,17 @@ removes the
.Nm
kld and stops
.Xr vinum 4 .
-This can only be done if no objects are active. In particular, the
+This can only be done if no objects are active.
+In particular, the
.Fl f
-option does not override this requirement. Normally, the
+option does not override this requirement.
+Normally, the
.Ic stop
command writes the current configuration back to the drives before terminating.
This will not be possible if configuration updates are disabled, so
.Nm
-will not stop if configuration updates are disabled. You can override this by
+will not stop if configuration updates are disabled.
+You can override this by
specifying the
.Fl f
option.
@@ -1341,25 +1473,31 @@ is statically configured.
.Pp
If object names are specified,
.Ic stop
-disables access to the objects. If the objects have subordinate objects, the
+disables access to the objects.
+If the objects have subordinate objects, the
subordinate objects must either already be inactive (stopped or in error), or
the
.Fl r
and
.Fl f
-options must be specified. This command does not remove the objects from the
-configuration. They can be accessed again after a
+options must be specified.
+This command does not remove the objects from the
+configuration.
+They can be accessed again after a
.Ic start
command.
.Pp
By default,
.Nm
-does not stop active objects. For example, you cannot stop a plex which is
-attached to an active volume, and you cannot stop a volume which is open. The
+does not stop active objects.
+For example, you cannot stop a plex which is
+attached to an active volume, and you cannot stop a volume which is open.
+The
.Fl f
option tells
.Nm
-to omit this checking and remove the object anyway. Use this option with great
+to omit this checking and remove the object anyway.
+Use this option with great
care and understanding: used incorrectly, it can result in serious data
corruption.
.Pp
@@ -1374,26 +1512,32 @@ The
.Ic stripe
command provides a simplified alternative to the
.Ic create
-command for creating volumes with a single striped plex. The size of the
+command for creating volumes with a single striped plex.
+The size of the
subdisks is the size of the largest contiguous space available on all the
-specified drives. The stripe size is fixed at 279 kB.
+specified drives.
+The stripe size is fixed at 279 kB.
.Pp
Normally, the
.Ic stripe
-command creates an arbitrary name for the volume and its components. The name
+command creates an arbitrary name for the volume and its components.
+The name
is composed of the text
.Dq Li vinum
and a small integer, for example
.Dq Li vinum3 .
You can override this with the
.Fl n Ar name
-option, which assigns the name specified to the volume. The plexes and subdisks
+option, which assigns the name specified to the volume.
+The plexes and subdisks
are named after the volume in the default manner.
.Pp
-There is no choice of name for the drives. If the drives have already been
+There is no choice of name for the drives.
+If the drives have already been
initialized as
.Nm
-drives, the name remains. Otherwise the drives are given names starting with
+drives, the name remains.
+Otherwise the drives are given names starting with
the text
.Dq Li vinumdrive
and a small integer, for example
@@ -1402,7 +1546,8 @@ As with the
.Ic create
command, the
.Fl f
-option can be used to specify that a previous name should be overwritten. The
+option can be used to specify that a previous name should be overwritten.
+The
.Fl v
is used to specify verbose output.
.Pp
@@ -1419,21 +1564,26 @@ configuration using the
.Ic mirror
and
.Ic stripe
-commands. These commands create convenient configurations for some more normal
+commands.
+These commands create convenient configurations for some more normal
situations, but they are not as flexible as the
.Ic create
command.
.Pp
-See above for the description of the commands. Here are some examples, all
-performed with the same collection of disks. Note that the first drive,
+See above for the description of the commands.
+Here are some examples, all
+performed with the same collection of disks.
+Note that the first drive,
.Pa /dev/da1h ,
-is smaller than the others. This has an effect on the sizes chosen for each
+is smaller than the others.
+This has an effect on the sizes chosen for each
kind of subdisk.
.Pp
The following examples all use the
.Fl v
option to show the commands passed to the system, and also to list the structure
-of the volume. Without the
+of the volume.
+Without the
.Fl v
option, these commands produce no output.
.Ss Volume with a single concatenated plex
@@ -1464,7 +1614,8 @@ In this case, the complete space on all four disks was used, giving a volume
.Ss Volume with a single striped plex
A volume with a single striped plex may give better performance than a
concatenated plex, but restrictions on striped plexes can mean that the volume
-is smaller. It will also not be resilient to a drive failure:
+is smaller.
+It will also not be resilient to a drive failure:
.Bd -literal
vinum -> stripe -v /dev/da1h /dev/da2h /dev/da3h /dev/da4h
drive vinumdrive0 device /dev/da1h
@@ -1514,7 +1665,8 @@ S vinum0.p0.s3 State: up D: vinumdrive3 Size: 414 MB
This example specifies the name of the volume,
.Ar mirror .
Since one drive is smaller than the others, the two plexes are of different
-size, and the last 158 MB of the volume is non-resilient. To ensure complete
+size, and the last 158 MB of the volume is non-resilient.
+To ensure complete
reliability in such a situation, use the
.Ic create
command to create a volume with 988 MB.
@@ -1551,7 +1703,8 @@ The
.Nm
utility requires that all parameters to the
.Ic create
-commands must be in a configuration file. Entries in the configuration file
+commands must be in a configuration file.
+Entries in the configuration file
define volumes, plexes and subdisks, and may be in free format, except that each
entry must be on a single line.
.Ss Scale factors
@@ -1573,7 +1726,8 @@ is used for compatibility with
It stands for blocks of 512 bytes.
This abbreviation is confusing, since the word
.Dq block
-is used in different meanings, and its use is deprecated. Use the keyword 's'
+is used in different meanings, and its use is deprecated.
+Use the keyword 's'
instead.
.El
.Pp
@@ -1586,7 +1740,8 @@ or
The configuration file can contain the following entries:
.Bl -tag -width 4n
.It Ic drive Ar name devicename Op Ar options
-Define a drive. The options are:
+Define a drive.
+The options are:
.Bl -tag -width 18n
.It Cm device Ar devicename
Specify the device on which the drive resides.
@@ -1607,8 +1762,10 @@ drive, which is maintained to automatically replace a failed drive.
The
.Nm
utility
-does not allow this drive to be used for any other purpose. In particular, it
-is not possible to create subdisks on it. This functionality has not been
+does not allow this drive to be used for any other purpose.
+In particular, it
+is not possible to create subdisks on it.
+This functionality has not been
completely implemented.
.El
.It Ic volume Ar name Op Ar options
@@ -1617,7 +1774,8 @@ Define a volume with name
Options are:
.Bl -tag -width 18n
.It Cm plex Ar plexname
-Add the specified plex to the volume. If
+Add the specified plex to the volume.
+If
.Ar plexname
is specified as
.Cm * ,
@@ -1635,30 +1793,37 @@ or
.Cm prefer Ar plexname .
The
.Nm
-utility satisfies a read request from only one of the plexes. A
+utility satisfies a read request from only one of the plexes.
+A
.Cm round
read policy specifies that each read should be performed from a different plex
in
.Em round-robin
-fashion. A
+fashion.
+A
.Cm prefer
read policy reads from the specified plex every time.
.It Cm setupstate
When creating a multi-plex volume, assume that the contents of all the plexes
-are consistent. This is normally not the case, so by default
+are consistent.
+This is normally not the case, so by default
.Nm
sets all plexes except the first one to the
.Em faulty
-state. Use the
+state.
+Use the
.Ic start
-command to first bring them to a consistent state. In the case of striped and
+command to first bring them to a consistent state.
+In the case of striped and
concatenated plexes, however, it does not normally cause problems to leave them
inconsistent: when using a volume for a file system or a swap partition, the
previous contents of the disks are not of interest, so they may be ignored.
If you want to take this risk, use the
.Cm setupstate
-keyword. It will only apply to the plexes defined immediately after the volume
-in the configuration file. If you add plexes to a volume at a later time, you
+keyword.
+It will only apply to the plexes defined immediately after the volume
+in the configuration file.
+If you add plexes to a volume at a later time, you
must integrate them manually with the
.Ic start
command.
@@ -1671,11 +1836,13 @@ command with RAID-5 plexes: otherwise extreme data corruption will result if one
subdisk fails.
.El
.It Ic plex Op Ar options
-Define a plex. Unlike a volume, you do not need to specify a name for a plex.
+Define a plex.
+Unlike a volume, you do not need to specify a name for a plex.
The options may be:
.Bl -tag -width 18n
.It Cm name Ar plexname
-Specify the name of the plex. Note that you must use the keyword
+Specify the name of the plex.
+Note that you must use the keyword
.Cm name
when naming a plex or subdisk.
.It Cm org Ar organization Op Ar stripesize
@@ -1693,31 +1860,42 @@ plexes, the parameter
.Ar stripesize
must be specified, while for
.Cm concat
-it must be omitted. For type
+it must be omitted.
+For type
.Cm striped ,
-it specifies the width of each stripe. For type
+it specifies the width of each stripe.
+For type
.Cm raid5 ,
-it specifies the size of a group. A group is a portion of a plex which
-stores the parity bits all in the same subdisk. It must be a factor of the plex size (in
+it specifies the size of a group.
+A group is a portion of a plex which
+stores the parity bits all in the same subdisk.
+It must be a factor of the plex size (in
other words, the result of dividing the plex size by the stripe size must be an
integer), and it must be a multiple of a disk sector (512 bytes).
.Pp
For optimum performance, stripes should be at least 128 kB in size: anything
smaller will result in a significant increase in I/O activity due to mapping of
-individual requests over multiple disks. The performance improvement due to the
+individual requests over multiple disks.
+The performance improvement due to the
increased number of concurrent transfers caused by this mapping will not make up
-for the performance drop due to the increase in latency. A good guideline for
-stripe size is between 256 kB and 512 kB. Avoid powers of 2, however: they tend
-to cause all superblocks to be placed on the first subdisk. The simplified
+for the performance drop due to the increase in latency.
+A good guideline for
+stripe size is between 256 kB and 512 kB.
+Avoid powers of 2, however: they tend
+to cause all superblocks to be placed on the first subdisk.
+The simplified
commands use a stripe size of 279 kB, which shows a reasonable distribution of
superblocks.
.Pp
A striped plex must have at least two subdisks (otherwise it is a concatenated
-plex), and each must be the same size. A RAID-5 plex must have at least three
-subdisks, and each must be the same size. In practice, a RAID-5 plex should
+plex), and each must be the same size.
+A RAID-5 plex must have at least three
+subdisks, and each must be the same size.
+In practice, a RAID-5 plex should
have at least 5 subdisks.
.It Cm volume Ar volname
-Add the plex to the specified volume. If no
+Add the plex to the specified volume.
+If no
.Cm volume
keyword is specified, the plex will be added to the last volume mentioned in the
configuration file.
@@ -1726,28 +1904,35 @@ Add the specified subdisk to the plex at offset
.Ar offset .
.El
.It Ic subdisk Op Ar options
-Define a subdisk. Options may be:
+Define a subdisk.
+Options may be:
.Bl -hang -width 18n
.It Cm name Ar name
-Specify the name of a subdisk. It is not necessary to specify a name for a
+Specify the name of a subdisk.
+It is not necessary to specify a name for a
subdisk\(emsee
.Sx OBJECT NAMING
-above. Note that you must specify the keyword
+above.
+Note that you must specify the keyword
.Cm name
if you wish to name a subdisk.
.It Cm plexoffset Ar offset
-Specify the starting offset of the subdisk in the plex. If not specified,
+Specify the starting offset of the subdisk in the plex.
+If not specified,
.Nm
allocates the space immediately after the previous subdisk, if any, or otherwise
at the beginning of the plex.
.It Cm driveoffset Ar offset
-Specify the starting offset of the subdisk in the drive. If not specified,
+Specify the starting offset of the subdisk in the drive.
+If not specified,
.Nm
allocates the first contiguous
.Ar length
bytes of free space on the drive.
.It Cm length Ar length
-Specify the length of the subdisk. This keyword must be specified. There is no
+Specify the length of the subdisk.
+This keyword must be specified.
+There is no
default, but the value 0 may be specified to mean
.Dq "use the largest available contiguous free area on the drive" .
If the drive is empty, this means that the entire drive will be used for the
@@ -1756,14 +1941,17 @@ subdisk.
may be shortened to
.Cm len .
.It Cm plex Ar plex
-Specify the plex to which the subdisk belongs. By default, the subdisk belongs
+Specify the plex to which the subdisk belongs.
+By default, the subdisk belongs
to the last plex specified.
.It Cm drive Ar drive
-Specify the drive on which the subdisk resides. By default, the subdisk resides
+Specify the drive on which the subdisk resides.
+By default, the subdisk resides
on the last drive specified.
.It Cm retryerrors
Specify that the subdisk should not be taken down if an unrecoverable error
-occurs. Normally
+occurs.
+Normally
.Nm
responds to an unrecoverable error by making the entire subdisk inaccessible.
.El
@@ -1821,11 +2009,14 @@ volume vol5
.Nm
drives are currently
.Bx
-disk partitions. They must be of type
+disk partitions.
+They must be of type
.Em vinum
-in order to avoid overwriting data used for other purposes. Use
+in order to avoid overwriting data used for other purposes.
+Use
.Nm disklabel Fl e
-to edit a partition type definition. The following display shows a typical
+to edit a partition type definition.
+The following display shows a typical
partition layout as shown by
.Xr disklabel 8 :
.Bd -literal
@@ -1843,7 +2034,8 @@ In this example, partition
.Dq Li g
may be used as a
.Nm
-partition. Partitions
+partition.
+Partitions
.Dq Li a ,
.Dq Li e
and
@@ -1852,7 +2044,8 @@ may be used as
.Em UFS
file systems or
.Em ccd
-partitions. Partition
+partitions.
+Partition
.Dq Li b
is a swap partition, and partition
.Dq Li c
@@ -1874,11 +2067,13 @@ You can override the name of this file by setting the environment variable
.Ev VINUM_HISTORY
to the name of the file.
.Pp
-Each message in the log file is preceded by a date. The default format is
+Each message in the log file is preceded by a date.
+The default format is
.Qq Li %e %b %Y %H:%M:%S .
See
.Xr strftime 3
-for further details of the format string. It can be overridden by the
+for further details of the format string.
+It can be overridden by the
environment variable
.Ev VINUM_DATEFORMAT .
.Sh HOW TO SET UP VINUM
@@ -1886,7 +2081,8 @@ This section gives practical advice about how to implement a
.Nm
system.
.Ss Where to put the data
-The first choice you need to make is where to put the data. You need dedicated
+The first choice you need to make is where to put the data.
+You need dedicated
disk partitions for
.Nm .
They should be partitions, not devices, and they should not be partition
@@ -1909,11 +2105,13 @@ above.
.Ss Designing volumes
The way you set up
.Nm
-volumes depends on your intentions. There are a number of possibilities:
+volumes depends on your intentions.
+There are a number of possibilities:
.Bl -enum
.It
You may want to join up a number of small disks to make a reasonable sized file
-system. For example, if you had five small drives and wanted to use all the
+system.
+For example, if you had five small drives and wanted to use all the
space for a single volume, you might write a configuration file like:
.Bd -literal -offset indent
drive d1 device /dev/da2e
@@ -1937,13 +2135,15 @@ space.
.It
You want to set up
.Nm
-to obtain additional resilience against disk failures. You have the choice of
+to obtain additional resilience against disk failures.
+You have the choice of
RAID-1, also called
.Dq mirroring ,
or RAID-5, also called
.Dq parity .
.Pp
-To set up mirroring, create multiple plexes in a volume. For example, to create
+To set up mirroring, create multiple plexes in a volume.
+For example, to create
a mirrored volume of 2 GB, you might create the following configuration file:
.Bd -literal -offset indent
drive d1 device /dev/da2e
@@ -1983,10 +2183,13 @@ volume raid
.Ed
.Pp
RAID-5 plexes require at least three subdisks, one of which is used for storing
-parity information and is lost for data storage. The more disks you use, the
-greater the proportion of the disk storage can be used for data storage. In
+parity information and is lost for data storage.
+The more disks you use, the
+greater the proportion of the disk storage can be used for data storage.
+In
this example, the total storage usage is 2.5 GB, compared to 4 GB for a mirrored
-configuration. If you were to use the minimum of only three disks, you would
+configuration.
+If you were to use the minimum of only three disks, you would
require 3 GB to store the information, for example:
.Bd -literal -offset indent
drive d1 device /dev/da2e
@@ -2006,8 +2209,10 @@ can access the complete address space of the volume even if a drive fails.
.It
You want to set up
.Nm
-to allow more concurrent access to a file system. In many cases, access to a
-file system is limited by the speed of the disk. By spreading the volume across
+to allow more concurrent access to a file system.
+In many cases, access to a
+file system is limited by the speed of the disk.
+By spreading the volume across
multiple disks, you can increase the throughput in multi-access environments.
This technique shows little or no performance improvement in single-access
environments.
@@ -2015,7 +2220,8 @@ The
.Nm
utility uses a technique called
.Dq striping ,
-or sometimes RAID-0, to increase this concurrency of access. The name RAID-0 is
+or sometimes RAID-0, to increase this concurrency of access.
+The name RAID-0 is
misleading: striping does not provide any redundancy or additional reliability.
In fact, it decreases the reliability, since the failure of a single disk will
render the volume useless, and the more disks you have, the more likely it is
@@ -2041,8 +2247,10 @@ A striped plex must have at least two subdisks, but the increase in performance
is greater if you have a larger number of disks.
.It
You may want to have the best of both worlds and have both resilience and
-performance. This is sometimes called RAID-10 (a combination of RAID-1 and
-RAID-0), though again this name is misleading. With
+performance.
+This is sometimes called RAID-10 (a combination of RAID-1 and
+RAID-0), though again this name is misleading.
+With
.Nm
you can do this with the following configuration file:
.Bd -literal -offset indent
@@ -2064,9 +2272,12 @@ volume raid setupstate
.Ed
.Pp
Here the plexes are striped, increasing performance, and there are two of them,
-increasing reliability. Note that this example shows the subdisks of the second
-plex in reverse order from the first plex. This is for performance reasons and
-will be discussed below. In addition, the volume specification includes the
+increasing reliability.
+Note that this example shows the subdisks of the second
+plex in reverse order from the first plex.
+This is for performance reasons and
+will be discussed below.
+In addition, the volume specification includes the
keyword
.Cm setupstate ,
which ensures that all plexes are
@@ -2076,7 +2287,8 @@ after creation.
.Ss Creating the volumes
Once you have created your configuration files, start
.Nm
-and create the volumes. In this example, the configuration is in the file
+and create the volumes.
+In this example, the configuration is in the file
.Pa configfile :
.Bd -literal -offset 2n
# vinum create -v configfile
@@ -2143,7 +2355,8 @@ The
.Fl v
option tells
.Nm
-to list the file as it configures. Subsequently it lists the current
+to list the file as it configures.
+Subsequently it lists the current
configuration in the same format as the
.Ic list Fl v
command.
@@ -2152,8 +2365,10 @@ Once you have created the
.Nm
volumes,
.Nm
-keeps track of them in its internal configuration files. You do not need to
-create them again. In particular, if you run the
+keeps track of them in its internal configuration files.
+You do not need to
+create them again.
+In particular, if you run the
.Ic create
command again, you will create additional objects:
.Bd -literal
@@ -2185,11 +2400,14 @@ As this example (this time with the
.Fl f
option) shows, re-running the
.Ic create
-has created four new plexes, each with a new subdisk. If you want to add other
-volumes, create new configuration files for them. They do not need to reference
+has created four new plexes, each with a new subdisk.
+If you want to add other
+volumes, create new configuration files for them.
+They do not need to reference
the drives that
.Nm
-already knows about. For example, to create a volume
+already knows about.
+For example, to create a volume
.Pa raid
on the four drives
.Pa /dev/da1e , /dev/da2e , /dev/da3e
@@ -2242,7 +2460,8 @@ S raid.p0.s3 State: empty PO: 1299 kB Size: 2048 MB
.Ed
.Pp
Note the size of the RAID-5 plex: it is only 6 GB, although together its
-components use 8 GB of disk space. This is because the equivalent of one
+components use 8 GB of disk space.
+This is because the equivalent of one
subdisk is used for storing parity data.
.Ss Restarting Vinum
On rebooting the system, start
@@ -2255,22 +2474,27 @@ command:
.Pp
This will start all the
.Nm
-drives in the system. If for some reason you wish to start only some of them,
+drives in the system.
+If for some reason you wish to start only some of them,
use the
.Ic read
command.
.Ss Performance considerations
A number of misconceptions exist about how to set up a RAID array for best
-performance. In particular, most systems use far too small a stripe size. The
+performance.
+In particular, most systems use far too small a stripe size.
+The
following discussion applies to all RAID systems, not just to
.Nm .
.Pp
The
.Fx
block I/O system issues requests of between .5kB and 128 kB; a
-typical mix is somewhere round 8 kB. You can't stop any striping system from
+typical mix is somewhere round 8 kB.
+You can't stop any striping system from
breaking a request into two physical requests, and if you make the stripe small
-enough, it can be broken into several. This will result in a significant drop
+enough, it can be broken into several.
+This will result in a significant drop
in performance: the decrease in transfer time per disk is offset by the order of
magnitude greater increase in latency.
.Pp
@@ -2282,7 +2506,8 @@ and 512 kB; with correct RAID implementations there is no obvious reason not to
increase the size to 2 or 4 MB on a large disk.
.Pp
When choosing a stripe size, consider that most current UFS file systems have
-cylinder groups 32 MB in size. If you have a stripe size and number of disks
+cylinder groups 32 MB in size.
+If you have a stripe size and number of disks
both of which are a power of two, it is probable that all superblocks and inodes
will be placed on the same subdisk, which will impact performance significantly.
Choose an odd number instead, for example 479 kB.
@@ -2294,35 +2519,51 @@ Since just about
everything is cached, the time relationship between the request and its
completion is not so important: the important parameter is the total time that
the request keeps the disks active, the time when the disks are not available to
-perform other transfers. As a result, it doesn't really matter if the transfers
-are happening at the same time or different times. In practical terms, the time
+perform other transfers.
+As a result, it doesn't really matter if the transfers
+are happening at the same time or different times.
+In practical terms, the time
we're looking at is the sum of the total latency (positioning time and
rotational latency, or the time it takes for the data to arrive under the disk
-heads) and the total transfer time. For a given transfer to disks of the same
+heads) and the total transfer time.
+For a given transfer to disks of the same
speed, the transfer time depends only on the total size of the transfer.
.Pp
Consider a typical news article or web page of 24 kB, which will probably be
-read in a single I/O. Take disks with a transfer rate of 6 MB/s and an average
-positioning time of 8 ms, and a file system with 4 kB blocks. Since it's 24 kB,
+read in a single I/O.
+Take disks with a transfer rate of 6 MB/s and an average
+positioning time of 8 ms, and a file system with 4 kB blocks.
+Since it's 24 kB,
we don't have to worry about fragments, so the file will start on a 4 kB
-boundary. The number of transfers required depends on where the block starts:
+boundary.
+The number of transfers required depends on where the block starts:
it's (S + F - 1) / S, where S is the stripe size in file system blocks, and F is
the file size in file system blocks.
.Bl -enum
.It
-Stripe size of 4 kB. You'll have 6 transfers. Total subsystem load: 48 ms
+Stripe size of 4 kB.
+You'll have 6 transfers.
+Total subsystem load: 48 ms
latency, 2 ms transfer, 50 ms total.
.It
-Stripe size of 8 kB. On average, you'll have 3.5 transfers. Total subsystem
+Stripe size of 8 kB.
+On average, you'll have 3.5 transfers.
+Total subsystem
load: 28 ms latency, 2 ms transfer, 30 ms total.
.It
-Stripe size of 16 kB. On average, you'll have 2.25 transfers. Total subsystem
+Stripe size of 16 kB.
+On average, you'll have 2.25 transfers.
+Total subsystem
load: 18 ms latency, 2 ms transfer, 20 ms total.
.It
-Stripe size of 256 kB. On average, you'll have 1.08 transfers. Total subsystem
+Stripe size of 256 kB.
+On average, you'll have 1.08 transfers.
+Total subsystem
load: 8.6 ms latency, 2 ms transfer, 10.6 ms total.
.It
-Stripe size of 4 MB. On average, you'll have 1.0009 transfers. Total subsystem
+Stripe size of 4 MB.
+On average, you'll have 1.0009 transfers.
+Total subsystem
load: 8.01 ms latency, 2 ms transfer, 10.01 ms total.
.El
.Pp
@@ -2349,7 +2590,8 @@ chance of individual requests being on different drives.
.It
Concatenating UFS file systems across multiple drives can also improve
performance for multiple file access, since UFS divides a file system into
-cylinder groups and attempts to keep files in a single cylinder group. In
+cylinder groups and attempts to keep files in a single cylinder group.
+In
general, it is not as effective as striping.
.It
Mirroring can improve multi-access performance for reads, since by default
@@ -2357,7 +2599,8 @@ Mirroring can improve multi-access performance for reads, since by default
issues consecutive reads to consecutive plexes.
.It
Mirroring decreases performance for all writes, whether multi-access or single
-access, since the data must be written to both plexes. This explains the
+access, since the data must be written to both plexes.
+This explains the
subdisk layout in the example of a mirroring configuration above: if the
corresponding subdisk in each plex is on a different physical disk, the write
commands can be issued in parallel, whereas if they are on the same physical
@@ -2372,7 +2615,8 @@ the write,
.Nm
must first read the data block and the corresponding parity block, perform some
calculations and write back the parity block and the data block, four times as
-many transfers as for writing a striped plex. On the other hand, this is offset
+many transfers as for writing a striped plex.
+On the other hand, this is offset
by the cost of mirroring, so writes to a volume with a single RAID-5 plex are
approximately half the speed of writes to a correctly configured volume with two
striped plexes.
@@ -2382,7 +2626,8 @@ When the
configuration changes (for example, adding or removing objects, or the change of
state of one of the objects),
.Nm
-writes up to 128 kB of updated configuration to each drive. The larger the
+writes up to 128 kB of updated configuration to each drive.
+The larger the
number of drives, the longer this takes.
.El
.Ss Creating file systems on Vinum volumes
@@ -2390,11 +2635,13 @@ You do not need to run
.Xr disklabel 8
before creating a file system on a
.Nm
-volume. Just run
+volume.
+Just run
.Xr newfs 8 .
Use the
.Fl v
-option to state that the device is not divided into partitions. For example, to
+option to state that the device is not divided into partitions.
+For example, to
create a file system on volume
.Pa mirror ,
enter the following command:
@@ -2406,9 +2653,11 @@ A number of other considerations apply to
configuration:
.Bl -bullet
.It
-There is no advantage in creating multiple drives on a single disk. Each drive
+There is no advantage in creating multiple drives on a single disk.
+Each drive
uses 131.5 kB of data for label and configuration information, and performance
-will suffer when the configuration changes. Use appropriately sized subdisks instead.
+will suffer when the configuration changes.
+Use appropriately sized subdisks instead.
.It
It is possible to increase the size of a concatenated
.Nm
@@ -2421,34 +2670,43 @@ Vinum objects have the concept of
.Em state .
See
.Xr vinum 4
-for more details. They are only completely accessible if their state is
+for more details.
+They are only completely accessible if their state is
.Em up .
To change an object state to
.Em up ,
use the
.Ic start
-command. To change an object state to
+command.
+To change an object state to
.Em down ,
use the
.Ic stop
-command. Normally other states are created automatically by the relationship
-between objects. For example, if you add a plex to a volume, the subdisks of
+command.
+Normally other states are created automatically by the relationship
+between objects.
+For example, if you add a plex to a volume, the subdisks of
the plex will be set in the
.Em empty
state, indicating that, though the hardware is accessible, the data on the
-subdisk is invalid. As a result of this state, the plex will be set in the
+subdisk is invalid.
+As a result of this state, the plex will be set in the
.Em faulty
state.
.Ss The `reviving' state
In many cases, when you start a subdisk the system must copy data to the
-subdisk. Depending on the size of the subdisk, this can take a long time.
+subdisk.
+Depending on the size of the subdisk, this can take a long time.
During this time, the subdisk is set in the
.Em reviving
-state. On successful completion of the copy operation, it is automatically set
+state.
+On successful completion of the copy operation, it is automatically set
to the
.Em up
-state. It is possible for the process performing the revive to be stopped and
-restarted. The system keeps track of how far the subdisk has been revived, and
+state.
+It is possible for the process performing the revive to be stopped and
+restarted.
+The system keeps track of how far the subdisk has been revived, and
when the
.Ic start
command is reissued, the copying continues from this point.
@@ -2456,11 +2714,13 @@ command is reissued, the copying continues from this point.
In order to maintain the consistency of a volume while one or more of its plexes
is being revived,
.Nm
-writes to subdisks which have been revived up to the point of the write. It may
+writes to subdisks which have been revived up to the point of the write.
+It may
also read from the plex if the area being read has already been revived.
.Sh GOTCHAS
The following points are not bugs, and they have good reasons for existing, but
-they have shown to cause confusion. Each is discussed in the appropriate
+they have shown to cause confusion.
+Each is discussed in the appropriate
section above.
.Bl -enum
.It
@@ -2496,8 +2756,10 @@ partition.
.It
When you create a volume with multiple plexes,
.Nm
-does not automatically initialize the plexes. This means that the contents are
-not known, but they are certainly not consistent. As a result, by default
+does not automatically initialize the plexes.
+This means that the contents are
+not known, but they are certainly not consistent.
+As a result, by default
.Nm
sets the state of all newly-created plexes except the first to
.Em faulty .
@@ -2507,7 +2769,8 @@ them, which causes
.Nm
to copy the data from a plex which is in the
.Em up
-state. Depending on the size of the subdisks involved, this can take a long
+state.
+Depending on the size of the subdisks involved, this can take a long
time.
.Pp
In practice, people aren't too interested in what was in the plex when it was
@@ -2533,18 +2796,22 @@ to ignore any possible inconsistency and set the plexes to be
.It
Some of the commands currently supported by
.Nm
-are not really needed. For reasons which I don't understand, however, I find
+are not really needed.
+For reasons which I don't understand, however, I find
that users frequently try the
.Ic label
and
.Ic resetconfig
commands, though especially
.Ic resetconfig
-outputs all sort of dire warnings. Don't use these commands unless you have a
+outputs all sort of dire warnings.
+Don't use these commands unless you have a
good reason to do so.
.It
-Some state transitions are not very intuitive. In fact, it's not clear whether
-this is a bug or a feature. If you find that you can't start an object in some
+Some state transitions are not very intuitive.
+In fact, it's not clear whether
+this is a bug or a feature.
+If you find that you can't start an object in some
strange state, such as a
.Em reborn
subdisk, try first to get it into
@@ -2553,7 +2820,9 @@ state, with the
.Ic stop
or
.Ic stop Fl f
-commands. If that works, you should then be able to start it. If you find
+commands.
+If that works, you should then be able to start it.
+If you find
that this is the only way to get out of a position where easier methods fail,
please report the situation.
.It
@@ -2564,17 +2833,20 @@ option, you must also build
with the
.Fl D Ns Dv VINUMDEBUG
option, since the size of some data objects used by both components depends on
-this option. If you don't do so, commands will fail with a corresponding error
+this option.
+If you don't do so, commands will fail with a corresponding error
message.
.It
The
.Nm Ic read
-command has a particularly emetic syntax. Once it was the only way to start
+command has a particularly emetic syntax.
+Once it was the only way to start
.Nm ,
but now the preferred method is with
.Nm Ic start .
.Nm Ic read
-should be used for maintenance purposes only. Note that its syntax has changed,
+should be used for maintenance purposes only.
+Note that its syntax has changed,
and the arguments must be disk slices, such as
.Pa /dev/da0 ,
not partitions such as