[libvirt] [PATCH 1/2] virsh: document attach-disk better

[Eric Blake]

http://bugzilla.redhat.com/601143, part 1 - document existing
behavior.  Ever since Mar 2010 (commit ced154cb), the use of
'attach-disk' or 'attach-device' to change cdrom/floppy media has been
documented but deprecated, but the replacement to use 'update-device'
was not documented.

* tools/virsh.c (cmdAttachInterface, cmdAttachDisk): Fix bad error
message.
* tools/virsh.pod (attach-device, attach-disk): Refer to
update-device for cdrom and floppy behavior.
(update-device): Add documentation.
---
 tools/virsh.c   |    9 ++++++---
 tools/virsh.pod |   13 ++++++++++++-
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/tools/virsh.c b/tools/virsh.c
index d60c27b..fab4b74 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -7262,7 +7262,8 @@ cmdAttachInterface(vshControl *ctl, const vshCmd *cmd)
     } else if (STREQ(type, "bridge")) {
         typ = 2;
     } else {
-        vshError(ctl, _("No support %s in command 'attach-interface'"), type);
+        vshError(ctl, _("No support for %s in command 'attach-interface'"),
+                 type);
         goto cleanup;
     }

@@ -7524,14 +7525,16 @@ cmdAttachDisk(vshControl *ctl, const vshCmd *cmd)
         if (STREQ(driver, "file") || STREQ(driver, "tap")) {
             isFile = 1;
         } else if (STRNEQ(driver, "phy")) {
-            vshError(ctl, _("No support %s in command 'attach-disk'"), driver);
+            vshError(ctl, _("No support for %s in command 'attach-disk'"),
+                     driver);
             goto cleanup;
         }
     }

     if (mode) {
         if (STRNEQ(mode, "readonly") && STRNEQ(mode, "shareable")) {
-            vshError(ctl, _("No support %s in command 'attach-disk'"), mode);
+            vshError(ctl, _("No support for %s in command 'attach-disk'"),
+                     mode);
             goto cleanup;
         }
     }
diff --git a/tools/virsh.pod b/tools/virsh.pod
index b54003c..b195b67 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -525,13 +525,17 @@ format of the device sections to get the most accurate set of accepted values.

 Attach a device to the domain, using a device definition in an XML file.
 See the documentation to learn about libvirt XML format for a device.
+For cdrom and floppy devices, this command only replaces the media within
+the single existing device; consider using B<update-device> for this usage.

 =item B<attach-disk> I<domain-id> I<source> I<target> optional I<--driver driver> I<--subdriver subdriver> I<--type type> I<--mode mode>

 Attach a new disk device to the domain.
 I<source> and I<target> are paths for the files and devices.
 I<driver> can be I<file>, I<tap> or I<phy> depending on the kind of access.
-I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default.
+I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default,
+although this use only replaces the media within the existing virtual cdrom or
+floppy device; consider using B<update-device> for this usage instead.
 I<mode> can specify the two specific mode I<readonly> or I<shareable>.

 =item B<attach-interface> I<domain-id> I<type> I<source> optional I<--target target> I<--mac mac> I<--script script>
@@ -561,6 +565,13 @@ I<type> can be either I<network> to indicate a physical network device or I<brid
 It is recommended to use the I<mac> option to distinguish between the interfaces
 if more than one are present on the domain.

+=item B<update-device> I<domain-id> I<file> optional I<--persistent>
+
+Update the characteristics of a device associated with I<domain-id>,
+based on the device definition in an XML I<file>.  If the I<--persistent>
+option is used, the changes will affect the next boot of the domain.
+See the documentation to learn about libvirt XML format for a device.
+
 =back

 =head1 VIRTUAL NETWORK COMMANDS
-- 
1.7.0.1