(* 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 autosync mode",
"\
If C<autosync> is true, this enables autosync. Libguestfs will make a
-best effort attempt to run C<guestfs_umount_all> followed by
-C<guestfs_sync> when the handle is closed
+best effort attempt to make filesystems consistent and synchronized
+when the handle is closed
(also if the program exits without closing handles).
This is enabled by default (since libguestfs 1.5.24, previously it was
[],
"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, [],
[],
Arch Linux.
+=item \"centos\"
+
+CentOS.
+
=item \"debian\"
Debian.
=item \"rhel\"
-Red Hat Enterprise Linux and some derivatives.
+Red Hat Enterprise Linux.
+
+=item \"scientificlinux\"
+
+Scientific Linux.
+
+=item \"slackware\"
+
+Slackware.
=item \"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>.");
*)
Please read L<guestfs(3)/INSPECTION> for more details.");
+ ("set_attach_method", (RErr, [String "attachmethod"], []), -1, [FishAlias "attach-method"],
+ [],
+ "set the attach method",
+ "\
+Set the method that libguestfs uses to connect to the back end
+guestfsd daemon. Possible methods are:
+
+=over 4
+
+=item C<appliance>
+
+Launch an appliance and connect to it. This is the ordinary method
+and the default.
+
+=item C<unix:I<path>>
+
+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. For more information, see
+L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>.
+
+=back");
+
+ ("get_attach_method", (RString "attachmethod", [], []), -1, [],
+ [InitNone, Always, TestOutput (
+ [["get_attach_method"]], "appliance")],
+ "get the attach method",
+ "\
+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",
For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503>
Autosync [see C<guestfs_set_autosync>, this is set by default on
-handles] means that C<guestfs_umount_all> is called when the handle
+handles] can cause C<guestfs_umount_all> to be called when the handle
is closed which can also trigger these issues.");
("rmmountpoint", (RErr, [String "exemptpath"], []), 149, [],
See also C<guestfs_is_lv>.");
- ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"]), 278, [],
+ ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"; String "features"]), 278, [],
[InitEmpty, Always, TestOutput (
[["part_disk"; "/dev/sda"; "mbr"];
- ["mkfs_opts"; "ext2"; "/dev/sda1"; "4096"];
+ ["mkfs_opts"; "ext2"; "/dev/sda1"; "4096"; ""];
["mount_options"; ""; "/dev/sda1"; "/"];
["write"; "/new"; "new file contents"];
["cat"; "/new"]], "new file contents")],
For UFS block sizes, please see L<mkfs.ufs(8)>.
+=item C<features>
+
+This passes the C<-O> parameter to the external mkfs program.
+
+For certain filesystem types, this allows extra filesystem
+features to be selected. See L<mke2fs(8)> and L<mkfs.ufs(8)>
+for more details.
+
+You cannot use this optional parameter with the C<gfs> or
+C<gfs2> filesystem type.
+
=back");
("getxattr", (RBufferOut "xattr", [Pathname "path"; String "name"], []), 279, [Optional "linuxxattrs"],
values. These two numbers, multiplied together, give the
resulting size of the minimal filesystem in bytes.");
+ ("internal_autosync", (RErr, [], []), 282, [NotInFish; NotInDocs],
+ [],
+ "internal autosync operation",
+ "\
+This command performs the autosync operation just before the
+handle is closed. You should not call this command directly.
+Instead, use the autosync flag (C<guestfs_set_autosync>) to
+control whether or not this operation is performed when the
+handle is closed.");
+
]
let all_functions = non_daemon_functions @ daemon_functions
git.annexia.org / libguestfs.git / blobdiff