New API: part-to-partnum

[libguestfs.git] / generator / generator_actions.ml

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index 56976dd..ce3382f 100644 (file)
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -743,6 +743,10 @@ Any Microsoft Windows operating system.
 
 FreeBSD.
 
 
 FreeBSD.
 

+=item \"netbsd\"
+
+NetBSD.
+

 =item \"unknown\"
 
 The operating system type could not be determined.
 =item \"unknown\"
 
 The operating system type could not be determined.


@@ -802,6 +806,10 @@ Gentoo.
 
 Linux Mint.
 
 
 Linux Mint.
 

+=item \"mageia\"
+
+Mageia.
+

 =item \"mandriva\"
 
 Mandriva.
 =item \"mandriva\"
 
 Mandriva.


@@ -810,6 +818,10 @@ Mandriva.
 
 MeeGo.
 
 
 MeeGo.
 

+=item \"opensuse\"
+
+OpenSUSE.
+

 =item \"pardus\"
 
 Pardus.
 =item \"pardus\"
 
 Pardus.


@@ -830,6 +842,10 @@ Scientific Linux.
 
 Slackware.
 
 
 Slackware.
 

+=item \"ttylinux\"
+
+ttylinux.
+

 =item \"ubuntu\"
 
 Ubuntu.
 =item \"ubuntu\"
 
 Ubuntu.


@@ -991,7 +1007,7 @@ be mountable but require special options.  Filesystems may
 not all belong to a single logical operating system
 (use C<guestfs_inspect_os> to look for OSes).");
 
 not all belong to a single logical operating system
 (use C<guestfs_inspect_os> to look for OSes).");
 

-  ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"]), -1, [FishAlias "add"],
+  ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"; String "name"]), -1, [FishAlias "add"],

    [],
    "add an image to examine or modify",
    "\
    [],
    "add an image to examine or modify",
    "\


@@ -1034,6 +1050,11 @@ this security hole.
 This rarely-used option lets you emulate the behaviour of the
 deprecated C<guestfs_add_drive_with_if> call (q.v.)
 
 This rarely-used option lets you emulate the behaviour of the
 deprecated C<guestfs_add_drive_with_if> call (q.v.)
 

+=item C<name>
+
+The name the drive had in the original guest, e.g. /dev/sdb. This is used as a
+hint to the guest inspection process if it is available.
+

 =back");
 
   ("inspect_get_windows_systemroot", (RString "systemroot", [Device "root"], []), -1, [],
 =back");
 
   ("inspect_get_windows_systemroot", (RString "systemroot", [Device "root"], []), -1, [],


@@ -1069,6 +1090,13 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
 This returns the internal QEMU command line.  'debug' commands are
 not part of the formal API and can be removed or changed at any time.");
 
 This returns the internal QEMU command line.  'debug' commands are
 not part of the formal API and can be removed or changed at any time.");
 

+  ("debug_drives", (RStringList "cmdline", [], []), -1, [NotInDocs],
+   [],
+   "debug the drives (internal use only)",
+   "\
+This returns the internal list of drives.  'debug' commands are
+not part of the formal API and can be removed or changed at any time.");
+

   ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"; Bool "allowuuid"]), -1, [FishAlias "domain"],
    [],
    "add the disk(s) from a named libvirt domain",
   ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"; Bool "allowuuid"]), -1, [FishAlias "domain"],
    [],
    "add the disk(s) from a named libvirt domain",


@@ -1161,7 +1189,8 @@ This returns the string C<unknown> if we could not determine the
 package format I<or> if the operating system does not have
 a real packaging system (eg. Windows).
 
 package format I<or> if the operating system does not have
 a real packaging system (eg. Windows).
 

-Possible strings include: C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>.
+Possible strings include:
+C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>, C<pkgsrc>.

 Future versions of libguestfs may return other strings.
 
 Please read L<guestfs(3)/INSPECTION> for more details.");
 Future versions of libguestfs may return other strings.
 
 Please read L<guestfs(3)/INSPECTION> for more details.");


@@ -1182,7 +1211,7 @@ a real packaging system (eg. Windows).
 
 Possible strings include: C<yum>, C<up2date>,
 C<apt> (for all Debian derivatives),
 
 Possible strings include: C<yum>, C<up2date>,
 C<apt> (for all Debian derivatives),

-C<portage>, C<pisi>, C<pacman>, C<urpmi>.
+C<portage>, C<pisi>, C<pacman>, C<urpmi>, C<zypper>.

 Future versions of libguestfs may return other strings.
 
 Please read L<guestfs(3)/INSPECTION> for more details.");
 Future versions of libguestfs may return other strings.
 
 Please read L<guestfs(3)/INSPECTION> for more details.");


@@ -1545,6 +1574,22 @@ C<^C> to kill the subprocess.");
    "\
 This returns the process group flag.");
 
    "\
 This returns the process group flag.");
 

+  ("set_smp", (RErr, [Int "smp"], []), -1, [FishAlias "smp"],
+   [],
+   "set number of virtual CPUs in appliance",
+   "\
+Change the number of virtual CPUs assigned to the appliance.  The
+default is C<1>.  Increasing this may improve performance, though
+often it has no effect.
+
+This function must be called before C<guestfs_launch>.");
+
+  ("get_smp", (RInt "smp", [], []), -1, [],
+   [],
+   "get number of virtual CPUs in appliance",
+   "\
+This returns the number of virtual CPUs assigned to the appliance.");
+

 ]
 
 (* daemon_functions are any functions which cause some action
 ]
 
 (* daemon_functions are any functions which cause some action


@@ -1552,7 +1597,7 @@ This returns the process group flag.");
  *)
 
 let daemon_functions = [
  *)
 
 let daemon_functions = [

-  ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [DeprecatedBy "mount_options"],
+  ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [],

    [InitEmpty, Always, TestOutput (
       [["part_disk"; "/dev/sda"; "mbr"];
        ["mkfs"; "ext2"; "/dev/sda1"];
    [InitEmpty, Always, TestOutput (
       [["part_disk"; "/dev/sda"; "mbr"];
        ["mkfs"; "ext2"; "/dev/sda1"];


@@ -1575,15 +1620,12 @@ exist.
 The mounted filesystem is writable, if we have sufficient permissions
 on the underlying device.
 
 The mounted filesystem is writable, if we have sufficient permissions
 on the underlying device.
 

-B<Important note:>
-When you use this call, the filesystem options C<sync> and C<noatime>
-are set implicitly.  This was originally done because we thought it
-would improve reliability, but it turns out that I<-o sync> has a
-very large negative performance impact and negligible effect on
-reliability.  Therefore we recommend that you avoid using
-C<guestfs_mount> in any code that needs performance, and instead
-use C<guestfs_mount_options> (use an empty string for the first
-parameter if you don't want any options).");
+Before libguestfs 1.13.16, this call implicitly added the options
+C<sync> and C<noatime>.  The C<sync> option greatly slowed
+writes and caused many problems for users.  If your program
+might need to work with older versions of libguestfs, use
+C<guestfs_mount_options> instead (using an empty string for the
+first parameter if you don't want any options).");

 
   ("sync", (RErr, [], []), 2, [],
    [ InitEmpty, Always, TestRun [["sync"]]],
 
   ("sync", (RErr, [], []), 2, [],
    [ InitEmpty, Always, TestRun [["sync"]]],


@@ -1821,7 +1863,12 @@ do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
 
 =item C<AUG_TYPE_CHECK> = 4
 
 
 =item C<AUG_TYPE_CHECK> = 4
 

-Typecheck lenses (can be expensive).
+Typecheck lenses.
+
+This option is only useful when debugging Augeas lenses.  Use
+of this option may require additional memory for the libguestfs
+appliance.  You may need to set the C<LIBGUESTFS_MEMSIZE>
+environment variable or call C<guestfs_set_memsize>.

 
 =item C<AUG_NO_STDINC> = 8
 
 
 =item C<AUG_NO_STDINC> = 8
 


@@ -3001,10 +3048,14 @@ How many blocks are zeroed isn't specified (but it's I<not> enough
 to securely wipe the device).  It should be sufficient to remove
 any partition tables, filesystem superblocks and so on.
 
 to securely wipe the device).  It should be sufficient to remove
 any partition tables, filesystem superblocks and so on.
 

+If blocks are already zero, then this command avoids writing
+zeroes.  This prevents the underlying device from becoming non-sparse
+or growing unnecessarily.
+

 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>,
 C<guestfs_is_zero_device>");
 
 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>,
 C<guestfs_is_zero_device>");
 

-  ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
+  ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [Optional "grub"],

    (* See:
     * https://bugzilla.redhat.com/show_bug.cgi?id=484986
     * https://bugzilla.redhat.com/show_bug.cgi?id=479760
    (* See:
     * https://bugzilla.redhat.com/show_bug.cgi?id=484986
     * https://bugzilla.redhat.com/show_bug.cgi?id=479760


@@ -3014,12 +3065,32 @@ C<guestfs_is_zero_device>");
        ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
        ["grub_install"; "/"; "/dev/vda"];
        ["is_dir"; "/boot"]])],
        ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
        ["grub_install"; "/"; "/dev/vda"];
        ["is_dir"; "/boot"]])],

-   "install GRUB",
+   "install GRUB 1",

    "\
    "\

-This command installs GRUB (the Grand Unified Bootloader) on
+This command installs GRUB 1 (the Grand Unified Bootloader) on

 C<device>, with the root directory being C<root>.
 
 C<device>, with the root directory being C<root>.
 

-Note: If grub-install reports the error
+Notes:
+
+=over 4
+
+=item *
+
+There is currently no way in the API to install grub2, which
+is used by most modern Linux guests.  It is possible to run
+the grub2 command from the guest, although see the
+caveats in L<guestfs(3)/RUNNING COMMANDS>.
+
+=item *
+
+This uses C<grub-install> from the host.  Unfortunately grub is
+not always compatible with itself, so this only works in rather
+narrow circumstances.  Careful testing with each guest version
+is advisable.
+
+=item *
+
+If grub-install reports the error

 \"No suitable drive was found in the generated device map.\"
 it may be that you need to create a C</boot/grub/device.map>
 file first that contains the mapping between grub device names
 \"No suitable drive was found in the generated device map.\"
 it may be that you need to create a C</boot/grub/device.map>
 file first that contains the mapping between grub device names


@@ -3028,7 +3099,9 @@ a file containing:
 
  (hd0) /dev/vda
 
 
  (hd0) /dev/vda
 

-replacing C</dev/vda> with the name of the installation device.");
+replacing C</dev/vda> with the name of the installation device.
+
+=back");

 
   ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
    [InitScratchFS, Always, TestOutput (
 
   ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
    [InitScratchFS, Always, TestOutput (


@@ -5224,7 +5297,11 @@ is not large enough.");
    "\
 This command writes zeroes over the entire C<device>.  Compare
 with C<guestfs_zero> which just zeroes the first few blocks of
    "\
 This command writes zeroes over the entire C<device>.  Compare
 with C<guestfs_zero> which just zeroes the first few blocks of

-a device.");
+a device.
+
+If blocks are already zero, then this command avoids writing
+zeroes.  This prevents the underlying device from becoming non-sparse
+or growing unnecessarily.");

 
   ("txz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 229, [Optional "xz"],
    [InitScratchFS, Always, TestOutput (
 
   ("txz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 229, [Optional "xz"],
    [InitScratchFS, Always, TestOutput (


@@ -5773,7 +5850,9 @@ removes the partition number, returning the device name
 (eg. \"/dev/sdb\").
 
 The named partition must exist, for example as a string returned
 (eg. \"/dev/sdb\").
 
 The named partition must exist, for example as a string returned

-from C<guestfs_list_partitions>.");
+from C<guestfs_list_partitions>.
+
+See also C<guestfs_part_to_partnum>.");

 
   ("upload_offset", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"], []), 273, [Progress],
    (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in
 
   ("upload_offset", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"], []), 273, [Progress],
    (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in


@@ -6107,6 +6186,47 @@ C<path> does not exist, then a new file is created.
 
 See also C<guestfs_write>.");
 
 
 See also C<guestfs_write>.");
 

+  ("compress_out", (RErr, [String "ctype"; Pathname "file"; FileOut "zfile"], [Int "level"]), 291, [],
+   [],
+   "output compressed file",
+   "\
+This command compresses C<file> and writes it out to the local
+file C<zfile>.
+
+The compression program used is controlled by the C<ctype> parameter.
+Currently this includes: C<compress>, C<gzip>, C<bzip2>, C<xz> or C<lzop>.
+Some compression types may not be supported by particular builds of
+libguestfs, in which case you will get an error containing the
+substring \"not supported\".
+
+The optional C<level> parameter controls compression level.  The
+meaning and default for this parameter depends on the compression
+program being used.");
+
+  ("compress_device_out", (RErr, [String "ctype"; Device "device"; FileOut "zdevice"], [Int "level"]), 292, [],
+   [],
+   "output compressed device",
+   "\
+This command compresses C<device> and writes it out to the local
+file C<zdevice>.
+
+The C<ctype> and optional C<level> parameters have the same meaning
+as in C<guestfs_compress_out>.");
+
+  ("part_to_partnum", (RInt "partnum", [Device "partition"], []), 293, [],
+   [InitPartition, Always, TestOutputInt (
+      [["part_to_partnum"; "/dev/sda1"]], 1);
+    InitEmpty, Always, TestLastFail (
+      [["part_to_partnum"; "/dev/sda"]])],
+   "convert partition name to partition number",
+   "\
+This function takes a partition name (eg. \"/dev/sdb1\") and
+returns the partition number (eg. C<1>).
+
+The named partition must exist, for example as a string returned
+from C<guestfs_list_partitions>.
+
+See also C<guestfs_part_to_dev>.");

 ]
 
 let all_functions = non_daemon_functions @ daemon_functions
 ]
 
 let all_functions = non_daemon_functions @ daemon_functions


@@ -6295,6 +6415,17 @@ Close and reopen the libguestfs handle.  It is not necessary to use
 this normally, because the handle is closed properly when guestfish
 exits.  However this is occasionally useful for testing.");
 
 this normally, because the handle is closed properly when guestfish
 exits.  However this is occasionally useful for testing.");
 

+  ("setenv", (RErr,[], []), -1, [], [],
+   "set an environment variable",
+   "  setenv VAR value
+
+Set the environment variable C<VAR> to the string C<value>.
+
+To print the value of an environment variable use a shell command
+such as:
+
+ !echo $VAR");
+

   ("sparse", (RErr,[], []), -1, [], [],
    "create a sparse disk image and add",
    " sparse filename size
   ("sparse", (RErr,[], []), -1, [], [],
    "create a sparse disk image and add",
    " sparse filename size


@@ -6329,4 +6460,10 @@ See also L<guestfs(3)/AVAILABILITY>.");
 Run the command as usual, but print the elapsed time afterwards.  This
 can be useful for benchmarking operations.");
 
 Run the command as usual, but print the elapsed time afterwards.  This
 can be useful for benchmarking operations.");
 

+  ("unsetenv", (RErr,[], []), -1, [], [],
+   "unset an environment variable",
+   "  unsetenv VAR
+
+Remove C<VAR> from the environment.");
+

 ]
 ]