[libvirt] [PATCH 4/4] virsh: Add document for cmdChangeMedia

[Eric Blake]

On 02/03/2012 02:23 AM, Osier Yang wrote:
> ---
>  tools/virsh.pod |   25 +++++++++++++++++++++++++
>  1 files changed, 25 insertions(+), 0 deletions(-)
> 
> diff --git a/tools/virsh.pod b/tools/virsh.pod
> index 28ad422..6ac7d15 100644
> --- a/tools/virsh.pod
> +++ b/tools/virsh.pod
> @@ -1475,6 +1475,31 @@ option can be used to force device update, e.g., to eject a CD-ROM even if it
>  is locked/mounted in the domain. See the documentation to learn about libvirt
>  XML format for a device.
>  
> +=item B<change-media> I<domain-id> I<target> [I<source>] [I<--eject>]
> +[I<--insert>] [I<--update>] [I<--current>] [I<--live>] [I<--config>]
> +[I<--force>]

Given the source code, I think this should be:

=item B<change-media> I<domain-id> I<target>
{I<--insert> | I<--update> | I<--eject>} [I<source>] [I<--force>]
[[I<--live>] [I<--config>] | [I<--current>]]

> +
> +Change media of CDROM or floppy drive. I<target> is the unique target name
> +(<target dev='name'/>) of the device.

It would be nice if we could also recognize existing source file name.
That is, if 'vda' has /path/to/disk1, and I am about to change it to
/path/to/disk2, I think that both of these commands should work:

virsh change-media dom --update /path/to/disk1 /path/to/disk2
virsh change-media dom --update vda /path/to/disk2

> I<source> specifies the path of the media
> +to be inserted or updated.
> +
> +I<--eject> indicates the media will be ejected.
> +I<--insert> indicates the media will be inserted. I<source> must be specified.
> +If the device has source (e.g. <source file='media'>), and I<source> is not
> +specified, I<--update> is equal to I<--eject>. If the device has no source,
> +and I<source> is specified, I<--update> is equal to I<--insert>. If the device
> +has source, and I<source> is specified, I<--update> behaves like combination
> +of I<--eject> and I<--insert>.

Is there any reason why we require exactly one of
--insert/--update/--eject, or could we make the command automatically
assume --update if none of the three flags were given?  Less typing is
nicer.

> +If I<--live> is specified, alter live configuration of running guest.
> +If I<--config> is specified, alter persistent configuration, effect observed
> +on next boot.
> +I<--current> can be either or both of I<live> and I<config>, depends on
> +the hypervisor's implementation.
> +Both I<--live> and I<--config> flags may be given, but I<--current> is
> +exclusive. If no flag is specified, behavior is different depending
> +on hypervisor.
> +The I<--force> option can be used to force media changing.
> +
>  =back
>  
>  =head1 NODEDEV COMMANDS

-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 620 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20120213/69bac4d0/attachment-0001.sig>