PERFORCE change 82746 for review

Mon Aug 29 09:13:19 GMT 2005

http://perforce.freebsd.org/chv.cgi?CH=82746

Change 82746 by soc-cjones at soc-cjones_ishtar on 2005/08/29 09:12:16

	Sync man page's view of arguments with reality, and describe commands.

Affected files ...

.. //depot/projects/soc2005/gvinum/src/sbin/gvinum/gvinum.8#5 edit

Differences ...

==== //depot/projects/soc2005/gvinum/src/sbin/gvinum/gvinum.8#5 (text+ko) ====

@@ -41,55 +41,95 @@
 .It Xo
 .Ic checkparity
 .Op Fl f
-.Op Fl v
 .Ar plex
 .Xc 
-Check the parity blocks of a RAID-5 plex.
+Check the parity blocks of a RAID-5 plex.  The parity check will start at the beginning 
+of the plex if the 
+.Fl f
+flag is specified, or otherwise at the location of the parity check pointer, the 
+first location at which plex's parity is incorrect.  All subdisks in the plex must be
+up for a parity check.
 .It Xo
 .Ic create
-.Op Fl f
-.Ar description-file
+.Op Ar description-file
 .Xc
 Create a volume as described in
 .Ar description-file .
+If no
+.Ar description-file 
+provided, opens an editor and provides the current 
+.Nm
+configuration for editing.
+.It Xo
+.Ic help
+.Xc
+Provides a synopsis of 
+.Nm 
+commands and arguments.
 .It Xo
 .Ic l | list
+.Op Fl r
+.Op Fl v
+.Op Fl V
 .Op Ar volume | plex | subdisk
 .Xc
-List information about specified objects.
 .It Xo
 .Ic ld
-.Op Ar drive
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar drive ...
 .Xc
-List information about drive(s).
 .It Xo
 .Ic ls
-.Op Ar subdisk
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar subdisk ...
 .Xc
-List information about subdisk(s).
 .It Xo
 .Ic lp
-.Op Ar plex
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar plex ...
 .Xc
-List information about plex(es).
 .It Xo
 .Ic lv
-.Op Ar volume
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar volume ...
 .Xc
-List information about volume(s).
+List information about the relevant object(s).  The
+.Fl r
+flag provides recursive display, showing each object's subordinate objects in proper relation.
+The 
+.Fl v
+and 
+.Fl V
+flags provide progressively more detailed output.
 .It Xo
 .Ic mv
 .Fl f
-.Ar drive subdisk ...
+.Ar drive subdisk 
+.Op Ar ...
 .Xc
-Move the subdisk(s) to the specified drive.
+Move the subdisk(s) to the specified drive.  The 
+.Fl f 
+flag is required, as all data on the indicated subdisk(s) will be destroyed as part of the move.
+.Pp
+If the subdisk(s) form part of a RAID-5 plex, the disk(s) will need to be set to the 'up' state 
+and the plex will require a 
+.Ic rebuildparity
+command; if the subdisk(s) form part of a plex that is mirrored with other plexes, the plex will 
+require restarting and will sync once restarted.  Moving more than one subdisk in a RAID-5 plex 
+or subdisks from both sides of a mirrored plex volume will destroy data.  Note that parity 
+rebuilds and syncing must be started manually after a move.
 .It Xo
 .Ic printconfig
-.Op Ar file
 .Xc
-Write a copy of the current configuration to standard output or to 
-.Ar file
-if specified.
+Write a copy of the current configuration to standard output.
 .It Xo
 .Ic quit
 .Xc
@@ -103,19 +143,31 @@
 .Ar drive | subdisk | plex | volume
 .Ar newname
 .Xc
-Change the name of the specified object.
+Change the name of the specified object.  The 
+.Fl r
+flag will recursively rename subordinate objects.
+.Pp
+Note that device nodes will not be renamed until 
+.Nm
+is restarted.
 .It Xo
 .Ic rebuildparity
+.Op Fl f
 .Ar plex
 .Xc
-Rebuild the parity blocks of a RAID-5 plex.
+Rebuild the parity blocks of a RAID-5 plex.  The parity rebuild will start at the beginning of 
+the plex if the 
+.Fl f
+flag is specified, or otherwise at the location of the parity check pointer.  All subdisks in 
+the plex must be up for a parity check.
 .It Xo
 .Ic rm
-.Op Fl f
 .Op Fl r
 .Ar volume | plex | subdisk
 .Xc
-Remove an object.
+Remove an object and, if 
+.Fl r
+is specified, its subordinate objects.
 .It Xo
 .Ic saveconfig
 .Xc
@@ -124,11 +176,14 @@
 configuration to disk after configuration failures.
 .It Xo
 .Ic setstate
+.Op Fl f
 .Ar state
 .Ar volume | plex | subdisk | drive
 .Xc
 Set state without influencing other objects, for diagnostic purposes 
-only.
+only.  The 
+.Fl f
+flag forces state changes regardless of whether they are legal.
 .It Xo
 .Ic start
 .Xc 
@@ -153,7 +208,40 @@
 .Sh OPTIONS
 .Nm
 commands may be followed by an option.
-TODO
+.Bl -tag -width indent
+.It Fl f
+The
+.Fl f
+.Pq Dq force
+option overrides safety checks.  It should be used with extreme caution.  This option is required in order to use the 
+.Ic move
+command.
+.It Fl r
+The 
+.Fl r
+.Pq Dq recursive
+option applies the command recursively to subordinate objects.  For example, in conjunction with the
+.Ic lv
+command, the 
+.Fl r
+option will also show information about the plexes and subdisks belonging to the volume.
+It is also used by the 
+.Ic rename
+command to indicate that subordinate objects such as subdisks should be renamed to match the object(s) specified and by the 
+.Ic rm
+command to delete plexes belonging to a volume and so on.
+.It Fl v
+The
+.Fl v
+.Pq Dq verbose
+option provides more detailed output.
+.It Fl V
+The
+.Fl V
+.Pq Dq very verbose
+option provides even more detailed output than
+.Fl v .
+.El
 .Sh FILES
 .Bl -tag -width /dev/gvinum/plex
 .It Pa /dev/gvinum
@@ -204,7 +292,10 @@
 until reloaded.
 .Pp
 Moving subdisks that are not part of a mirrored or RAID-5 volume will 
-destroy data.
+destroy data.  It is perhaps a bug to permit this.  
+.Pp
+Plexes in which subdisks have been moved do not automatically sync or 
+rebuild parity.  This may leave data unprotected and is perhaps unwise.
 .Pp
 .Xr gvinum 8 does not yet fully implement all functions found in  
 .Xr vinum 4 .  Specifically, the following commands from 
