fish: Allow suffixes on number parameters (eg. 1M)

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index b4cde81..a6d341e 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -27,10 +27,11 @@ guestfish - the libguestfs Filesystem Interactive SHell
  Welcome to guestfish, the libguestfs filesystem interactive shell for
  editing virtual machine filesystems.
  
- Type: 'help' for help with commands
+ Type: 'help' for a list of commands
+       'man' to read the manual
        'quit' to quit the shell
  
- ><fs> help
+ ><fs> man
 
 =head2 From shell scripts
 
@@ -40,7 +41,7 @@ Create a new C</etc/motd> file in a guest:
  add disk.img
  run
  mount /dev/vg_guest/lv_root /
- write_file /etc/motd "Welcome, new users" 0
+ write /etc/motd "Welcome, new users"
  _EOF_
 
 List the LVM logical volumes in a guest:
@@ -56,7 +57,7 @@ Update C</etc/resolv.conf> in a guest:
 
  guestfish \
    add disk.img : run : mount /dev/vg_guest/lv_root / : \
-   write-file /etc/resolv.conf "nameserver 1.2.3.4" 0
+   write /etc/resolv.conf "nameserver 1.2.3.4"
 
 Edit C</boot/grub/grub.conf> interactively:
 
@@ -319,9 +320,97 @@ must be escaped with a backslash.
 
 =head1 NUMBERS
 
-Commands which take integers as parameters use the C convention which
-is to use C<0> to prefix an octal number or C<0x> to prefix a
-hexadecimal number.  For example:
+This section applies to all commands which can take integers
+as parameters.
+
+=head2 SIZE SUFFIX
+
+When the command takes a parameter measured in bytes, you can use one
+of the following suffixes to specify kilobytes, megabytes and larger
+sizes:
+
+=over 4
+
+=item B<k> or B<K> or B<KiB>
+
+The size in kilobytes (multiplied by 1024).
+
+=item B<KB>
+
+The size in SI 1000 byte units.
+
+=item B<M> or B<MiB>
+
+The size in megabytes (multiplied by 1048576).
+
+=item B<MB>
+
+The size in SI 1000000 byte units.
+
+=item B<G> or B<GiB>
+
+The size in gigabytes (multiplied by 2**30).
+
+=item B<GB>
+
+The size in SI 10**9 byte units.
+
+=item B<T> or B<TiB>
+
+The size in terabytes (multiplied by 2**40).
+
+=item B<TB>
+
+The size in SI 10**12 byte units.
+
+=item B<P> or B<PiB>
+
+The size in petabytes (multiplied by 2**50).
+
+=item B<PB>
+
+The size in SI 10**15 byte units.
+
+=item B<E> or B<EiB>
+
+The size in exabytes (multiplied by 2**60).
+
+=item B<EB>
+
+The size in SI 10**18 byte units.
+
+=item B<Z> or B<ZiB>
+
+The size in zettabytes (multiplied by 2**70).
+
+=item B<ZB>
+
+The size in SI 10**21 byte units.
+
+=item B<Y> or B<YiB>
+
+The size in yottabytes (multiplied by 2**80).
+
+=item B<YB>
+
+The size in SI 10**24 byte units.
+
+=back
+
+For example:
+
+ truncate-size /file 1G
+
+would truncate the file to 1 gigabyte.
+
+Be careful because a few commands take sizes in kilobytes or megabytes
+(eg. the parameter to L</memsize> is specified in megabytes already).
+Adding a suffix will probably not do what you expect.
+
+=head2 OCTAL AND HEXADECIMAL NUMBERS
+
+For specifying the radix (base) use the C convention: C<0> to prefix
+an octal number or C<0x> to prefix a hexadecimal number.  For example:
 
  1234      decimal number 1234
  02322     octal number, equivalent to decimal 1234
@@ -550,7 +639,7 @@ multiple times (and can be mixed with I<-a>).
 
 The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
 for the second and so on.  Existing files in the current directory are
-not overwritten, so you may need to do C<rm -f test1.img>.
+I<overwritten>.
 
 The type briefly describes how the disk should be sized, partitioned,
 how filesystem(s) should be created, and how content should be added.
@@ -599,39 +688,7 @@ so it can be further examined.
 
 For more advanced image creation, see L<qemu-img(1)> utility.
 
-Size can be specified (where C<nn> means a number):
-
-=over 4
-
-=item C<nn> or C<nn>K or C<nn>KB
-
-number of kilobytes, eg: C<1440> = standard 3.5in floppy
-
-=item C<nn>M or C<nn>MB
-
-number of megabytes
-
-=item C<nn>G or C<nn>GB
-
-number of gigabytes
-
-=item C<nn>T or C<nn>TB
-
-number of terabytes
-
-=item C<nn>P or C<nn>PB
-
-number of petabytes
-
-=item C<nn>E or C<nn>EB
-
-number of exabytes
-
-=item C<nn>sects
-
-number of 512 byte sectors
-
-=back
+Size can be specified using standard suffixes, eg. C<1M>.
 
 =head2 echo
 
@@ -679,6 +736,12 @@ itself.
 
 Note that C<!cd> won't do what you might expect.
 
+=head2 man | manual
+
+ man
+
+Opens the manual page for guestfish.
+
 =head2 more | less
 
  more filename
@@ -720,39 +783,7 @@ danger you could run out of real disk space during a write operation.
 
 For more advanced image creation, see L<qemu-img(1)> utility.
 
-Size can be specified (where C<nn> means a number):
-
-=over 4
-
-=item C<nn> or C<nn>K or C<nn>KB
-
-number of kilobytes, eg: C<1440> = standard 3.5in floppy
-
-=item C<nn>M or C<nn>MB
-
-number of megabytes
-
-=item C<nn>G or C<nn>GB
-
-number of gigabytes
-
-=item C<nn>T or C<nn>TB
-
-number of terabytes
-
-=item C<nn>P or C<nn>PB
-
-number of petabytes
-
-=item C<nn>E or C<nn>EB
-
-number of exabytes
-
-=item C<nn>sects
-
-number of 512 byte sectors
-
-=back
+Size can be specified using standard suffixes, eg. C<1M>.
 
 =head2 time