(* libguestfs
- * Copyright (C) 2009-2010 Red Hat Inc.
+ * Copyright (C) 2009-2011 Red Hat Inc.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
*)
let non_daemon_functions = test_functions @ [
- ("launch", (RErr, [], []), -1, [FishAlias "run"],
+ ("launch", (RErr, [], []), -1, [FishAlias "run"; Progress],
[],
"launch the qemu subprocess",
"\
[],
"set verbose mode",
"\
-If C<verbose> is true, this turns on verbose messages (to C<stderr>).
+If C<verbose> is true, this turns on verbose messages.
Verbose messages are disabled unless the environment variable
-C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
+C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
+
+Verbose messages are normally sent to C<stderr>, unless you
+register a callback to send them somewhere else (see
+C<guestfs_set_event_callback>).");
("get_verbose", (RBool "verbose", [], []), -1, [],
[],
["get_trace"]])],
"enable or disable command traces",
"\
-If the command trace flag is set to 1, then commands are
-printed on stderr before they are executed in a format
-which is very similar to the one used by guestfish. In
-other words, you can run a program with this enabled, and
-you will get out a script which you can feed to guestfish
-to perform the same set of actions.
+If the command trace flag is set to 1, then libguestfs
+calls, parameters and return values are traced.
If you want to trace C API calls into libguestfs (and
other libraries) then possibly a better way is to use
the external ltrace(1) command.
Command traces are disabled unless the environment variable
-C<LIBGUESTFS_TRACE> is defined and set to C<1>.");
+C<LIBGUESTFS_TRACE> is defined and set to C<1>.
+
+Trace messages are normally sent to C<stderr>, unless you
+register a callback to send them somewhere else (see
+C<guestfs_set_event_callback>).");
("get_trace", (RBool "trace", [], []), -1, [],
[],
Red Hat Enterprise Linux and some derivatives.
+=item \"slackware\"
+
+Slackware.
+
=item \"ubuntu\"
Ubuntu.
Non-mounted devices such as swap devices are I<not>
returned in this list.
+For operating systems like Windows which still use drive
+letters, this call will only return an entry for the first
+drive \"mounted on\" C</>. For information about the
+mapping of drive letters to partitions, see
+C<guestfs_inspect_get_drive_mappings>.
+
Please read L<guestfs(3)/INSPECTION> for more details.
See also C<guestfs_inspect_get_filesystems>.");
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.");
- ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"]), -1, [FishAlias "domain"],
+ ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"]), -1, [FishAlias "domain"],
[],
"add the disk(s) from a named libvirt domain",
"\
environment variable, see the libvirt documentation for full
details).
+The optional C<live> flag controls whether this call will try
+to connect to a running virtual machine C<guestfsd> process if
+it sees a suitable E<lt>channelE<gt> element in the libvirt
+XML definition. The default (if the flag is omitted) is never
+to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
+information.
+
The other optional parameters are passed directly through to
C<guestfs_add_drive_opts>.");
(*
This interface is not quite baked yet. -- RWMJ 2010-11-11
- ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"]), -1, [NotInFish],
+ ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"]), -1, [NotInFish],
[],
"add the disk(s) from a libvirt domain",
"\
will fail unless those disks are accessible via the same device path
locally too.
-The optional parameters are passed directly through to
+The optional C<live> flag controls whether this call will try
+to connect to a running virtual machine C<guestfsd> process if
+it sees a suitable E<lt>channelE<gt> element in the libvirt
+XML definition. The default (if the flag is omitted) is never
+to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
+information.
+
+The other optional parameters are passed directly through to
C<guestfs_add_drive_opts>.");
*)
Connect to the Unix domain socket I<path>.
This method lets you connect to an existing daemon or (using
-virtio-serial) to a live guest.
+virtio-serial) to a live guest. For more information, see
+L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>.
=back");
"\
Return the current attach method. See C<guestfs_set_attach_method>.");
+ ("inspect_get_product_variant", (RString "variant", [Device "root"], []), -1, [],
+ [],
+ "get product variant of inspected operating system",
+ "\
+This function should only be called with a root device string
+as returned by C<guestfs_inspect_os>.
+
+This returns the product variant of the inspected operating
+system.
+
+For Windows guests, this returns the contents of the Registry key
+C<HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion>
+C<InstallationType> which is usually a string such as
+C<Client> or C<Server> (other values are possible). This
+can be used to distinguish consumer and enterprise versions
+of Windows that have the same version number (for example,
+Windows 7 and Windows 2008 Server are both version 6.1,
+but the former is C<Client> and the latter is C<Server>).
+
+For enterprise Linux guests, in future we intend this to return
+the product variant such as C<Desktop>, C<Server> and so on. But
+this is not implemented at present.
+
+If the product variant could not be determined, then the
+string C<unknown> is returned.
+
+Please read L<guestfs(3)/INSPECTION> for more details.
+See also C<guestfs_inspect_get_product_name>,
+C<guestfs_inspect_get_major_version>.");
+
+ ("inspect_get_windows_current_control_set", (RString "controlset", [Device "root"], []), -1, [],
+ [],
+ "get Windows CurrentControlSet of inspected operating system",
+ "\
+This function should only be called with a root device string
+as returned by C<guestfs_inspect_os>.
+
+This returns the Windows CurrentControlSet of the inspected guest.
+The CurrentControlSet is a registry key name such as C<ControlSet001>.
+
+This call assumes that the guest is Windows and that the
+Registry could be examined by inspection. If this is not
+the case then an error is returned.
+
+Please read L<guestfs(3)/INSPECTION> for more details.");
+
+ ("inspect_get_drive_mappings", (RHashtable "drives", [Device "root"], []), -1, [],
+ [],
+ "get drive letter mappings",
+ "\
+This function should only be called with a root device string
+as returned by C<guestfs_inspect_os>.
+
+This call is useful for Windows which uses a primitive system
+of assigning drive letters (like \"C:\") to partitions.
+This inspection API examines the Windows Registry to find out
+how disks/partitions are mapped to drive letters, and returns
+a hash table as in the example below:
+
+ C => /dev/vda2
+ E => /dev/vdb1
+ F => /dev/vdc1
+
+Note that keys are drive letters. For Windows, the key is
+case insensitive and just contains the drive letter, without
+the customary colon separator character.
+
+In future we may support other operating systems that also used drive
+letters, but the keys for those might not be case insensitive
+and might be longer than 1 character. For example in OS-9,
+hard drives were named C<h0>, C<h1> etc.
+
+For Windows guests, currently only hard drive mappings are
+returned. Removable disks (eg. DVD-ROMs) are ignored.
+
+For guests that do not use drive mappings, or if the drive mappings
+could not be determined, this returns an empty hash table.
+
+Please read L<guestfs(3)/INSPECTION> for more details.
+See also C<guestfs_inspect_get_mountpoints>,
+C<guestfs_inspect_get_filesystems>.");
+
]
(* daemon_functions are any functions which cause some action
is I<not> intended that you try to parse the output string.
Use C<guestfs_statvfs> from programs.");
- ("du", (RInt64 "sizekb", [Pathname "path"], []), 127, [],
+ ("du", (RInt64 "sizekb", [Pathname "path"], []), 127, [Progress],
[InitISOFS, Always, TestOutputInt (
[["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))],
"estimate file space usage",