Finally bring in what was produced during Google SoC 2005:

Add functions to rename objects and to move a subdisk from one drive
to another.

Add manual page (finally).

Bring up-to-date the online help.

Obtained from:  Chris Jones <chris.jones@ualberta.ca>
Sponsored by:   Google Summer of Code 2005
MFC in:         1 week

3 files changed, 533 insertions, 51 deletions

diff --git a/sbin/gvinum/Makefile b/sbin/gvinum/Makefile
index 2e9b7c5..6d41497 100644
--- a/sbin/gvinum/Makefile
+++ b/sbin/gvinum/Makefile
@@ -2,7 +2,7 @@
 
 PROG=	gvinum
 SRCS=	gvinum.c gvinum.h geom_vinum_share.c
-NO_MAN=	# not yet
+MAN=	gvinum.8
 
 CFLAGS+=	-I${.CURDIR}/../../sys
 
diff --git a/sbin/gvinum/gvinum.8 b/sbin/gvinum/gvinum.8
new file mode 100644
index 0000000..217751c
--- /dev/null
+++ b/sbin/gvinum/gvinum.8
@@ -0,0 +1,397 @@
+.\"  Copyright (c) 2005 Chris Jones
+.\"  All rights reserved.
+.\" 
+.\" This software was developed for the FreeBSD Project by Chris Jones
+.\" thanks to the support of Google's Summer of Code program and
+.\" mentoring by Lukas Ertl.
+.\" 
+.\" Redistribution and use in source and binary forms, with or without       
+.\" modification, are permitted provided that the following conditions    
+.\" are met:    
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\" 
+.\" $FreeBSD$
+.\"
+.Dd September 1, 2005
+.Dt GVINUM 8
+.Os
+.Sh NAME
+.Nm gvinum
+.Nd Logical Volume Manager control program
+.Sh SYNOPSIS
+.Nm
+.Op Ar command
+.Op Fl options
+.Sh COMMANDS
+.Bl -tag -width indent
+.It Xo
+.Ic checkparity
+.Op Fl f
+.Ar plex
+.Xc 
+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 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
+.It Xo
+.Ic ld
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar drive ...
+.Xc
+.It Xo
+.Ic ls
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar subdisk ...
+.Xc
+.It Xo
+.Ic lp
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar plex ...
+.Xc
+.It Xo
+.Ic lv
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar volume ...
+.Xc
+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 move | mv
+.Fl f
+.Ar drive subdisk 
+.Op Ar ...
+.Xc
+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.  This can currently only be done when the subdisk is
+not being accessed.
+.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
+.Xc
+Write a copy of the current configuration to standard output.
+.It Xo
+.Ic quit
+.Xc
+Exit 
+.Nm
+when running in interactive mode.  Normally this would be done by entering the
+EOF character.
+.It Xo
+.Ic rename
+.Op Fl r
+.Ar drive | subdisk | plex | volume
+.Ar newname
+.Xc
+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.  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 r
+.Ar volume | plex | subdisk
+.Xc
+Remove an object and, if 
+.Fl r
+is specified, its subordinate objects.
+.It Xo
+.Ic saveconfig
+.Xc
+Save 
+.Nm
+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.  The 
+.Fl f
+flag forces state changes regardless of whether they are legal.
+.It Xo
+.Ic start
+.Xc 
+Read configuration from all vinum drives.
+.It Xo
+.Ic start
+.Op Fl S Ar size
+.Ar volume | plex | subdisk
+.Xc
+Allow the system to access the objects.  The
+.Fl S
+flag is currently ignored.
+.El
+.Sh DESCRIPTION
+The
+.Nm
+utility communicates with the kernel component of the GVinum 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, 
+.Nm
+maintains a command line history.
+.Sh OPTIONS
+.Nm
+commands may be followed by an option.
+.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
+directory with device nodes for
+.Nm
+objects
+.It Pa /dev/gvinum/plex
+directory containing device nodes for
+.Nm
+plexes
+.It Pa /dev/gvinum/sd
+directory containing device nodes for
+.Nm
+subdisks
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width EDITOR
+.It Ev EDITOR
+The name of the editor to use for editing configuration files, by 
+default
+.Nm vi .
+.El
+.Sh SEE ALSO
+.Xr geom 4 ,
+.Xr geom 8
+.Pp
+.Sh AUTHORS
+.An Lukas Ertl Aq le@freebsd.org
+.An Chris Jones Aq soc-cjones@freebsd.org
+.Sh HISTORY
+The
+.Nm
+utility first appeared in 
+.Fx 5.3 .  The 
+.Nm vinum 
+utility, on which
+.Nm 
+is based, was written by Greg Lehey.
+.Pp
+.Nm 
+was written by Lukas Ertl.  The move and rename commands and 
+documentation were added by Chris Jones through the 2005 Google Summer 
+of Code program.
+.Sh BUGS
+.Xr gvinum 8 does not rename devices in
+.Pa /dev/gvinum 
+until reloaded.
+.Pp
+The 
+.Fl S
+initsize flag to 
+.Ic start
+is ignored.
+.Pp
+The 
+.Ic stop
+command does not work.
+.Pp
+Moving subdisks that are not part of a mirrored or RAID-5 volume will 
+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 
+.Xr vinum 4 are not supported:
+.Bl -tag -width indent
+.It Ic attach Ar plex volume Op Cm rename
+.It Xo
+.Ic attach Ar subdisk plex
+.Op Ar offset
+.Op Cm rename
+.Xc
+Attach a plex to a volume, or a subdisk to a plex.
+.It Xo
+.Ic concat
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.Xc
+Create a concatenated volume from the specified drives.
+.It Ic debug
+Cause the volume manager to enter the kernel debugger.
+.It Ic debug Ar flags
+Set debugging flags.
+.It Xo
+.Ic detach
+.Op Fl f
+.Op Ar plex | subdisk
+.Xc
+Detach a plex or subdisk from the volume or plex to which it is 
+attached.
+.It Ic dumpconfig Op Ar drive ...
+List the configuration information stored on the specified drives, or all
+drives in the system if no drive names are specified.
+.It Xo
+.Ic info
+.Op Fl v
+.Op Fl V
+.Xc
+List information about volume manager state.
+.It Ic label Ar volume
+Create a volume label.
+.It Xo
+.Ic mirror
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl s
+.Op Fl v
+.Ar drives
+.Xc
+Create a mirrored volume from the specified drives.
+.It Ic resetconfig
+Reset the complete
+.Nm
+configuration.
+.It Xo
+.Ic resetstats
+.Op Fl r
+.Op Ar volume | plex | subdisk
+.Xc
+Reset statistics counters for the specified objects, or for all objects if none
+are specified.
+.It Ic setdaemon Op Ar value
+Set daemon configuration.
+.It Xo
+.Ic stop
+.Op Fl f
+.Op Ar volume | plex | subdisk
+.Xc
+Terminate access to the objects, or stop
+.Nm
+if no parameters are specified.
+.It Xo
+.Ic stripe
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.Xc
+Create a striped volume from the specified drives.
+.El
diff --git a/sbin/gvinum/gvinum.c b/sbin/gvinum/gvinum.c
index 9e2f7b6..87b7003 100644
--- a/sbin/gvinum/gvinum.c
+++ b/sbin/gvinum/gvinum.c
@@ -1,7 +1,11 @@
 /*
- *  Copyright (c) 2004 Lukas Ertl
+ *  Copyright (c) 2004 Lukas Ertl, 2005 Chris Jones
  *  All rights reserved.
  * 
+ * Portions of this software were developed for the FreeBSD Project 
+ * by Chris Jones thanks to the support of Google's Summer of Code 
+ * program and mentoring by Lukas Ertl. 
+ * 
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
@@ -53,8 +57,10 @@
 void	gvinum_create(int, char **);
 void	gvinum_help(void);
 void	gvinum_list(int, char **);
+void	gvinum_move(int, char **);
 void	gvinum_parityop(int, char **, int);
 void	gvinum_printconfig(int, char **);
+void	gvinum_rename(int, char **);
 void	gvinum_rm(int, char **);
 void	gvinum_saveconfig(void);
 void	gvinum_setstate(int, char **);
@@ -320,75 +326,40 @@ void
 gvinum_help(void)
 {
 	printf("COMMANDS\n"
-	    "attach plex volume [rename]\n"
-	    "attach subdisk plex [offset] [rename]\n"
-	    "        Attach a plex to a volume, or a subdisk to a plex.\n"
-	    "checkparity plex [-f] [-v]\n"
-	    "        Check the parity blocks of a RAID-4 or RAID-5 plex.\n"
-	    "concat [-f] [-n name] [-v] drives\n"
-	    "        Create a concatenated volume from the specified drives.\n"
-	    "create [-f] description-file\n"
-	    "        Create a volume as described in description-file.\n"
-	    "detach [-f] [plex | subdisk]\n"
-	    "        Detach a plex or subdisk from the volume or plex to"
-	    "which it is\n"
-	    "        attached.\n"
-	    "dumpconfig [drive ...]\n"
-	    "        List the configuration information stored on the"
-	    " specified\n"
-	    "        drives, or all drives in the system if no drive names"
-	    " are speci-\n"
-	    "        fied.\n"
-	    "info [-v] [-V]\n"
-	    "        List information about volume manager state.\n"
-	    "init [-S size] [-w] plex | subdisk\n"
-	    "        Initialize the contents of a subdisk or all the subdisks"
-	    " of a\n"
-	    "        plex to all zeros.\n"
-	    "label volume\n"
-	    "        Create a volume label.\n"
-	    "l | list [-r] [-s] [-v] [-V] [volume | plex | subdisk]\n"
+	    "checkparity [-f] plex\n"
+	    "        Check the parity blocks of a RAID-5 plex.\n"
+	    "create description-file\n"
+	    "        Create as per description-file or open editor.\n"
+	    "l | list [-r] [-v] [-V] [volume | plex | subdisk]\n"
 	    "        List information about specified objects.\n"
-	    "ld [-r] [-s] [-v] [-V] [volume]\n"
+	    "ld [-r] [-v] [-V] [volume]\n"
 	    "        List information about drives.\n"
-	    "ls [-r] [-s] [-v] [-V] [subdisk]\n"
+	    "ls [-r] [-v] [-V] [subdisk]\n"
 	    "        List information about subdisks.\n"
-	    "lp [-r] [-s] [-v] [-V] [plex]\n"
+	    "lp [-r] [-v] [-V] [plex]\n"
 	    "        List information about plexes.\n"
-	    "lv [-r] [-s] [-v] [-V] [volume]\n"
+	    "lv [-r] [-v] [-V] [volume]\n"
 	    "        List information about volumes.\n"
-	    "mirror [-f] [-n name] [-s] [-v] drives\n"
-	    "        Create a mirrored volume from the specified drives.\n"
 	    "move | mv -f drive object ...\n"
 	    "        Move the object(s) to the specified drive.\n"
-	    "printconfig [file]\n"
-	    "        Write a copy of the current configuration to file.\n"
 	    "quit    Exit the vinum program when running in interactive mode."
 	    "  Nor-\n"
 	    "        mally this would be done by entering the EOF character.\n"
 	    "rename [-r] [drive | subdisk | plex | volume] newname\n"
 	    "        Change the name of the specified object.\n"
-	    "rebuildparity plex [-f] [-v] [-V]\n"
-	    "        Rebuild the parity blocks of a RAID-4 or RAID-5 plex.\n"
-	    "resetconfig\n"
-	    "        Reset the complete vinum configuration.\n"
-	    "rm [-f] [-r] volume | plex | subdisk\n"
+	    "rebuildparity plex [-f]\n"
+	    "        Rebuild the parity blocks of a RAID-5 plex.\n"
+	    "rm [-r] volume | plex | subdisk | drive\n"
 	    "        Remove an object.\n"
 	    "saveconfig\n"
 	    "        Save vinum configuration to disk after configuration"
 	    " failures.\n"
-	    "setstate state [volume | plex | subdisk | drive]\n"
+	    "setstate [-f] state [volume | plex | subdisk | drive]\n"
 	    "        Set state without influencing other objects, for"
 	    " diagnostic pur-\n"
 	    "        poses only.\n"
-	    "start [-i interval] [-S size] [-w] volume | plex | subdisk\n"
+	    "start [-S size] volume | plex | subdisk\n"
 	    "        Allow the system to access the objects.\n"
-	    "stop [-f] [volume | plex | subdisk]\n"
-	    "        Terminate access to the objects, or stop vinum if no"
-	    " parameters\n"
-	    "        are specified.\n"
-	    "stripe [-f] [-n name] [-v] drives\n"
-	    "        Create a striped volume from the specified drives.\n"
 	);
 
 	return;
@@ -514,6 +485,61 @@ gvinum_list(int argc, char **argv)
 	return;
 }
 
+/* Note that move is currently of form '[-r] target object [...]' */
+void
+gvinum_move(int argc, char **argv)
+{
+	struct gctl_req *req;
+	const char *errstr;
+	char buf[20];
+	int flags, i, j;
+
+	flags = 0;
+	if (argc) {
+		optreset = 1;
+		optind = 1;
+		while ((j = getopt(argc, argv, "f")) != -1) {
+			switch (j) {
+			case 'f':
+				flags |= GV_FLAG_F;
+				break;
+			case '?':
+			default:
+				return;
+			}
+		}
+		argc -= optind;
+		argv += optind;
+	}
+
+	switch (argc) {
+		case 0:
+			warnx("no destination or object(s) to move specified");
+			return;
+		case 1:
+			warnx("no object(s) to move specified");
+			return;
+		default:
+			break;
+	}
+
+	req = gctl_get_handle();
+	gctl_ro_param(req, "class", -1, "VINUM");
+	gctl_ro_param(req, "verb", -1, "move");
+	gctl_ro_param(req, "argc", sizeof(int), &argc);
+	gctl_ro_param(req, "flags", sizeof(int), &flags);
+	gctl_ro_param(req, "destination", -1, argv[0]);
+	for (i = 1; i < argc; i++) {
+		snprintf(buf, sizeof(buf), "argv%d", i);
+		gctl_ro_param(req, buf, -1, argv[i]);
+	}
+	errstr = gctl_issue(req); 
+	if (errstr != NULL)
+		warnx("can't move object(s):  %s", errstr);
+	gctl_free(req);
+	return;
+}
+
 void
 gvinum_printconfig(int argc, char **argv)
 {
@@ -604,6 +630,59 @@ gvinum_parityop(int argc, char **argv, int rebuild)
 }
 
 void
+gvinum_rename(int argc, char **argv)
+{
+	struct gctl_req *req;
+	const char *errstr;
+	int flags, j;
+
+	flags = 0;
+
+	if (argc) {
+		optreset = 1;
+		optind = 1;
+		while ((j = getopt(argc, argv, "r")) != -1) {
+			switch (j) {
+			case 'r':
+				flags |= GV_FLAG_R;
+				break;
+			case '?':
+			default:
+				return;
+			}
+		}
+		argc -= optind;
+		argv += optind;
+	}
+
+	switch (argc) {
+		case 0:
+			warnx("no object to rename specified");
+			return;
+		case 1:
+			warnx("no new name specified");
+			return;
+		case 2:
+			break;
+		default:
+			warnx("more than one new name specified");
+			return;
+	}
+
+	req = gctl_get_handle();
+	gctl_ro_param(req, "class", -1, "VINUM");
+	gctl_ro_param(req, "verb", -1, "rename");
+	gctl_ro_param(req, "flags", sizeof(int), &flags);
+	gctl_ro_param(req, "object", -1, argv[0]);
+	gctl_ro_param(req, "newname", -1, argv[1]);
+	errstr = gctl_issue(req); 
+	if (errstr != NULL)
+		warnx("can't rename object:  %s", errstr);
+	gctl_free(req);
+	return;
+}
+
+void
 gvinum_rm(int argc, char **argv)
 {
 	struct gctl_req *req;
@@ -759,8 +838,14 @@ parseline(int argc, char **argv)
 		gvinum_list(argc, argv);
 	else if (!strcmp(argv[0], "lv"))
 		gvinum_list(argc, argv);
+	else if (!strcmp(argv[0], "move"))
+		gvinum_move(argc, argv);
+	else if (!strcmp(argv[0], "mv"))
+		gvinum_move(argc, argv);
 	else if (!strcmp(argv[0], "printconfig"))
 		gvinum_printconfig(argc, argv);
+	else if (!strcmp(argv[0], "rename"))
+		gvinum_rename(argc, argv);
 	else if (!strcmp(argv[0], "rm"))
 		gvinum_rm(argc, argv);
 	else if (!strcmp(argv[0], "saveconfig"))