ccdconfig: Improve markup & sync usage()
authorThomas Nikolajsen <thomas@dragonflybsd.org>
Sun, 8 Feb 2009 14:04:37 +0000 (15:04 +0100)
committerThomas Nikolajsen <thomas@dragonflybsd.org>
Sun, 8 Feb 2009 15:02:30 +0000 (16:02 +0100)
 * Fix SYNOPSIS: problems in `...' use
 * Sync usage() to SYNOPSIS
 * Add reference to disklabel64(8)
 * Add markup
 * Break long command lines in examples
 * Start sentence on new line

sbin/ccdconfig/ccdconfig.8
sbin/ccdconfig/ccdconfig.c

index 5b5c696..2a23ece 100644 (file)
@@ -33,7 +33,7 @@
 .\" $FreeBSD: src/sbin/ccdconfig/ccdconfig.8,v 1.9.2.10 2003/01/26 03:38:39 keramida Exp $
 .\" $DragonFly: src/sbin/ccdconfig/ccdconfig.8,v 1.7 2008/05/02 02:05:05 swildner Exp $
 .\"
-.Dd July 17, 1995
+.Dd February 8, 2009
 .Dt CCDCONFIG 8
 .Os
 .Sh NAME
@@ -45,8 +45,7 @@
 .Ar ccd
 .Ar ileave
 .Op Ar flags
-.Ar dev
-.Op Ar
+.Ar dev ...
 .Nm
 .Fl C
 .Op Fl v
@@ -54,8 +53,7 @@
 .Nm
 .Fl u
 .Op Fl v
-.Ar ccd
-.Op Ar
+.Ar ccd ...
 .Nm
 .Fl U
 .Op Fl v
 .Fl g
 .Op Fl M Ar core
 .Op Fl N Ar system
-.Op Ar ccd Op Ar ...
+.Op Ar ccd ...
 .Sh DESCRIPTION
 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.
@@ -86,8 +86,9 @@ 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 M Ar core
 Extract values associated with the name list from
 .Pa core
@@ -110,9 +111,9 @@ 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
-as a decimal number, a hexadecimal number, a comma-separated list
-of strings, or the word
+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 .
 The flags are as follows:
 .Bd -literal -offset indent
@@ -145,14 +146,17 @@ as shown by
 .Xr disklabel 8 ) .
 .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
-more than this you should look into external hardware RAID SCSI boxes,
-RAID controllers such as the
+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 such as the
 .Xr dpt 4
 controller, or software RAID systems such as
 .Xr vinum 8 .
@@ -164,36 +168,57 @@ default ccd configuration file
 .Sh EXAMPLES
 A number of
 .Nm
-examples are shown below.  The arguments passed
-to
+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 da2s0e and da3s0e which is mirrored
-to a two disk stripe of da4s0e and da5s0e.  The last example is a simple
-mirror.  /dev/da2s0e is mirrored with /dev/da4s0e and assigned to ccd0.
-.Bd -literal
-# ccdconfig ccd0 64 none /dev/da2s0e /dev/da3s0e /dev/da4s0e /dev/da5s0e
-# ccdconfig ccd0 128 CCDF_MIRROR /dev/da2s0e /dev/da3s0e /dev/da4s0e /dev/da5s0e
+It reads as a two disk stripe of
+.Pa da2s0e
+and
+.Pa da3s0e
+which is mirrored to a two disk stripe of
+.Pa da4s0e
+and
+.Pa da5s0e .
+The last example is a simple mirror.
+.Pa /dev/da2s0e
+is mirrored with
+.Pa /dev/da4s0e
+and assigned to
+.Pa ccd0 .
+.Bd -literal -offset indent
+# ccdconfig ccd0 64 none /dev/da2s0e /dev/da3s0e /dev/da4s0e \e
+       /dev/da5s0e
+# ccdconfig ccd0 128 CCDF_MIRROR /dev/da2s0e /dev/da3s0e \e
+       /dev/da4s0e /dev/da5s0e
 # ccdconfig ccd0 128 CCDF_MIRROR /dev/da2s0e /dev/da4s0e
 .Ed
 .Pp
-When you create a new ccd disk you generally want to
+When you create a new ccd disk you generally want to label it, using
 .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
-with newfs, you do not have to worry about this as newfs will skip the
-label area.  However, if you intend to
+or
+.Xr disklabel64 8 ,
+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
+.Xr newfs 8 ,
+you do not have to worry about this as
+.Xr newfs 8
+will skip the 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
-you have A ccd disk with 10000 sectors you might create a 'd' partition
-with offset 16 and size 9984.
-.Bd -literal
+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
+.Ql d
+partition with offset 16 and size 9984.
+.Bd -literal -offset indent
 # disklabel -r -w ccd0s0 auto
 # disklabel -e ccd0s0
 .Ed
@@ -203,13 +228,15 @@ If you reboot the machine and reconfigure the ccd disk, 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 SEE ALSO
 .Xr dd 1 ,
 .Xr ccd 4 ,
 .Xr dpt 4 ,
 .Xr disklabel 8 ,
+.Xr disklabel64 8 ,
 .Xr rc 8 ,
 .Xr vinum 8
 .Sh HISTORY
index 13a113f..403eaa4 100644 (file)
@@ -682,11 +682,11 @@ static void
 usage(void)
 {
        fprintf(stderr, "%s\n%s\n%s\n%s\n%s\n",
-               "usage: ccdconfig [-cv] ccd ileave [flags] dev [...]",
+               "usage: ccdconfig [-cv] ccd ileave [flags] dev ...",
                "       ccdconfig -C [-v] [-f config_file]",
-               "       ccdconfig -u [-v] ccd [...]",
+               "       ccdconfig -u [-v] ccd ...",
                "       ccdconfig -U [-v] [-f config_file]",
-               "       ccdconfig -g [-M core] [-N system] [ccd [...]]");
+               "       ccdconfig -g [-M core] [-N system] [ccd ...]");
        exit(1);
 }