man pages: Add a standard EXIT STATUS section to most pages.

[libguestfs.git] / resize / virt-resize.pod

diff --git a/resize/virt-resize.pod b/resize/virt-resize.pod
index 473c582..17a5953 100644 (file)
--- a/resize/virt-resize.pod
+++ b/resize/virt-resize.pod
@@ -26,24 +26,48 @@ those manual pages first.
 
 =head1 EXAMPLES
 
 
 =head1 EXAMPLES
 

+=over 4
+
+=item 1.
+

 Copy C<olddisk> to C<newdisk>, extending one of the guest's partitions
 to fill the extra 5GB of space.
 
 Copy C<olddisk> to C<newdisk>, extending one of the guest's partitions
 to fill the extra 5GB of space.
 

- truncate -r olddisk newdisk; truncate -s +5G newdisk

  virt-filesystems --long -h --all -a olddisk
  virt-filesystems --long -h --all -a olddisk

+ 
+ truncate -r olddisk newdisk
+ truncate -s +5G newdisk
+ 

  # Note "/dev/sda2" is a partition inside the "olddisk" file.
  virt-resize --expand /dev/sda2 olddisk newdisk
 
  # Note "/dev/sda2" is a partition inside the "olddisk" file.
  virt-resize --expand /dev/sda2 olddisk newdisk
 

+=item 2.
+

 As above, but make the /boot partition 200MB bigger, while giving the
 remaining space to /dev/sda2:
 
 As above, but make the /boot partition 200MB bigger, while giving the
 remaining space to /dev/sda2:
 

- virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 olddisk newdisk
+ virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 \
+   olddisk newdisk
+
+=item 3.

 
 

-As above, but the output format will be uncompressed qcow2:
+As in the first example, but expand a logical volume as the final
+step.  This is what you would typically use for Linux guests that use
+LVM:
+
+ virt-resize --expand /dev/sda2 --LV-expand /dev/vg_guest/lv_root \
+   olddisk newdisk
+
+=item 4.
+
+As in the first example, but the output format will be qcow2 instead
+of a raw disk:

 
  qemu-img create -f qcow2 newdisk.qcow2 15G
  virt-resize --expand /dev/sda2 olddisk newdisk.qcow2
 
 
  qemu-img create -f qcow2 newdisk.qcow2 15G
  virt-resize --expand /dev/sda2 olddisk newdisk.qcow2
 

+=back
+

 =head1 DETAILED USAGE
 
 =head2 EXPANDING A VIRTUAL MACHINE DISK
 =head1 DETAILED USAGE
 
 =head2 EXPANDING A VIRTUAL MACHINE DISK


@@ -133,9 +157,9 @@ to fill the rest of the available space:
 If the expanded partition in the image contains a filesystem or LVM
 PV, then if virt-resize knows how, it will resize the contents, the
 equivalent of calling a command such as L<pvresize(8)>,
 If the expanded partition in the image contains a filesystem or LVM
 PV, then if virt-resize knows how, it will resize the contents, the
 equivalent of calling a command such as L<pvresize(8)>,

-L<resize2fs(8)> or L<ntfsresize(8)>.  However virt-resize does not
-know how to resize some filesystems, so you would have to online
-resize them after booting the guest.
+L<resize2fs(8)>, L<ntfsresize(8)> or L<btrfs(8)>.  However virt-resize
+does not know how to resize some filesystems, so you would have to
+online resize them after booting the guest.

 
 Other options are covered below.
 
 
 Other options are covered below.
 


@@ -257,13 +281,11 @@ Currently virt-resize can resize:
 
 =item *
 
 
 =item *
 

-ext2, ext3 and ext4 filesystems when they are contained
-directly inside a partition.
+ext2, ext3 and ext4 filesystems.

 
 =item *
 
 
 =item *
 

-NTFS filesystems contained directly in a partition, if libguestfs was
-compiled with support for NTFS.
+NTFS filesystems, if libguestfs was compiled with support for NTFS.

 
 The filesystem must have been shut down consistently last time it was
 used.  Additionally, L<ntfsresize(8)> marks the resized filesystem as
 
 The filesystem must have been shut down consistently last time it was
 used.  Additionally, L<ntfsresize(8)> marks the resized filesystem as


@@ -276,6 +298,10 @@ LVM PVs (physical volumes).  virt-resize does not usually resize
 anything inside the PV, but see the I<--LV-expand> option.  The user
 could also resize LVs as desired after boot.
 
 anything inside the PV, but see the I<--LV-expand> option.  The user
 could also resize LVs as desired after boot.
 

+=item *
+
+Btrfs filesystems, if libguestfs was compiled with support for btrfs.
+

 =back
 
 Note that you cannot use I<--expand> and I<--shrink> together.
 =back
 
 Note that you cannot use I<--expand> and I<--shrink> together.


@@ -323,6 +349,12 @@ You can give this option multiple times, I<but> it doesn't
 make sense to do this unless the logical volumes you specify
 are all in different volume groups.
 
 make sense to do this unless the logical volumes you specify
 are all in different volume groups.
 

+=item B<--machine-readable>
+
+This option is used to make the output more machine friendly
+when being parsed by other programs.  See
+L</MACHINE READABLE OUTPUT> below.
+

 =item B<-n>
 
 =item B<--dryrun>
 =item B<-n>
 
 =item B<--dryrun>


@@ -457,6 +489,58 @@ Display version number and exit.
 
 =back
 
 
 =back
 

+=head1 MACHINE READABLE OUTPUT
+
+The I<--machine-readable> option can be used to make the output more
+machine friendly, which is useful when calling virt-resize from other
+programs, GUIs etc.
+
+There are two ways to use this option.
+
+Firstly use the option on its own to query the capabilities of the
+virt-resize binary.  Typical output looks like this:
+
+ $ virt-resize --machine-readable
+ virt-resize
+ ntfsresize-force
+ 32bitok
+ ntfs
+ btrfs
+
+A list of features is printed, one per line, and the program exits
+with status 0.
+
+Secondly use the option in conjunction with other options to make the
+regular program output more machine friendly.
+
+At the moment this means:
+
+=over 4
+
+=item 1.
+
+Progress bar messages can be parsed from stdout by looking for this
+regular expression:
+
+ ^[0-9]+/[0-9]+$
+
+=item 2.
+
+The calling program should treat messages sent to stdout (except for
+progress bar messages) as status messages.  They can be logged and/or
+displayed to the user.
+
+=item 3.
+
+The calling program should treat messages sent to stderr as error
+messages.  In addition, virt-resize exits with a non-zero status code
+if there was a fatal error.
+
+=back
+
+Versions of the program prior to 1.13.9 did not support the
+I<--machine-readable> option and will return an error.
+

 =head1 NOTES
 
 =head2 "Partition 1 does not end on cylinder boundary."
 =head1 NOTES
 
 =head2 "Partition 1 does not end on cylinder boundary."


@@ -521,6 +605,11 @@ have meaning to the shell such as C<#> and space.  You may need to
 quote or escape these characters on the command line.  See the shell
 manual page L<sh(1)> for details.
 
 quote or escape these characters on the command line.  See the shell
 manual page L<sh(1)> for details.
 

+=head1 EXIT STATUS
+
+This program returns 0 if successful, or non-zero if there was an
+error.
+

 =head1 SEE ALSO
 
 L<virt-filesystems(1)>,
 =head1 SEE ALSO
 
 L<virt-filesystems(1)>,


@@ -532,6 +621,7 @@ L<pvresize(8)>,
 L<lvresize(8)>,
 L<resize2fs(8)>,
 L<ntfsresize(8)>,
 L<lvresize(8)>,
 L<resize2fs(8)>,
 L<ntfsresize(8)>,

+L<btrfs(8)>,

 L<virsh(1)>,
 L<parted(8)>,
 L<truncate(1)>,
 L<virsh(1)>,
 L<parted(8)>,
 L<truncate(1)>,