Sys::Guestfs::Lib(3) User Contributed Perl Documentation Sys::Guestfs::Lib(3)NAMESys::Guestfs::Lib - Useful functions for using libguestfs from Perl
SYNOPSIS
use Sys::Guestfs::Lib qw(open_guest ...);
$g = open_guest ($name);
DESCRIPTION
"Sys::Guestfs::Lib" is an extra library of useful functions for using
the libguestfs API from Perl. It also provides tighter integration
with libvirt.
The basic libguestfs API is not covered by this manpage. Please refer
instead to Sys::Guestfs(3) and guestfs(3). The libvirt API is also not
covered. For that, see Sys::Virt(3).
DEPRECATION OF SOME FUNCTIONS
This module contains functions and code to perform inspection of guest
images. Since libguestfs 1.5.3 this ability has moved into the core
API (see "INSPECTION" in guestfs(3)). The inspection functions in this
module are deprecated and will not be updated. Each deprecated
function is marked in the documentation below.
BASIC FUNCTIONS
open_guest
$g = open_guest ($name);
$g = open_guest ($name, rw => 1, ...);
$g = open_guest ($name, address => $uri, ...);
$g = open_guest ([$img1, $img2, ...], address => $uri, format => $format, ...);
($g, $conn, $dom, @images) = open_guest ($name);
This function opens a libguestfs handle for either the libvirt domain
called $name, or the disk image called $name. Any disk images found
through libvirt or specified explicitly are attached to the libguestfs
handle.
The "Sys::Guestfs" handle $g is returned, or if there was an error it
throws an exception. To catch errors, wrap the call in an eval block.
The first parameter is either a string referring to a libvirt domain or
a disk image, or (if a guest has several disk images) an arrayref
"[$img1, $img2, ...]". For disk images, if the "format" parameter is
specified then that format is forced.
The handle is read-only by default. Use the optional parameter "rw =>
1" to open a read-write handle. However if you open a read-write
handle, this function will refuse to use active libvirt domains.
The handle is still in the config state when it is returned, so you
have to call "$g->launch ()".
The optional "address" parameter can be added to specify the libvirt
URI.
The implicit libvirt handle is closed after this function, unless you
call the function in "wantarray" context, in which case the function
returns a tuple of: the open libguestfs handle, the open libvirt
handle, and the open libvirt domain handle, and a list of
[image,format] pairs. (This is useful if you want to do other things
like pulling the XML description of the guest). Note that if this is a
straight disk image, then $conn and $dom will be "undef".
If the "Sys::Virt" module is not available, then libvirt is bypassed,
and this function can only open disk images.
The optional "interface" parameter can be used to open devices with a
specified qemu interface. See "guestfs_add_drive" in Sys::Guestfs for
more details.
feature_available
$bool = feature_available ($g, $feature [, $feature ...]);
This function is a useful wrapper around the basic "$g->available"
call.
"$g->available" tests for availability of a list of features and dies
with an error if any is not available.
This call tests for the list of features and returns true if all are
available, or false otherwise.
For a list of features you can test for, see "AVAILABILITY" in
guestfs(3).
get_partitions
This function is deprecated. It will not be updated in future versions
of libguestfs. New code should not use this function. Use the core
API function "list_filesystems" in Sys::Guestfs(3) instead.
resolve_windows_path
$path = resolve_windows_path ($g, $path);
$path = resolve_windows_path ($g, "/windows/system");
==> "/WINDOWS/System"
or undef if no path exists
This function, which is specific to FAT/NTFS filesystems (ie. Windows
guests), lets you look up a case insensitive $path in the filesystem
and returns the true, case sensitive path as required by the underlying
kernel or NTFS-3g driver.
If $path does not exist then this function returns "undef".
The $path parameter must begin with "/" character and be separated by
"/" characters. Do not use "\", drive names, etc.
file_architecture
Deprecated function. Replace any calls to this function with:
$g->file_architecture ($path);
OPERATING SYSTEM INSPECTION FUNCTIONS
inspect_all_partitions
This function is deprecated. It will not be updated in future versions
of libguestfs. New code should not use this function. Use the core
API functions instead, see "INSPECTION" in guestfs(3).
inspect_partition
This function is deprecated. It will not be updated in future versions
of libguestfs. New code should not use this function. Use the core
API functions instead, see "INSPECTION" in guestfs(3).
inspect_operating_systems
This function is deprecated. It will not be updated in future versions
of libguestfs. New code should not use this function. Use the core
API functions instead, see "INSPECTION" in guestfs(3).
mount_operating_system
This function is deprecated. It will not be updated in future versions
of libguestfs. New code should not use this function. Use the core
API functions instead, see "INSPECTION" in guestfs(3).
inspect_in_detail
This function is deprecated. It will not be updated in future versions
of libguestfs. New code should not use this function. Use the core
API functions instead, see "INSPECTION" in guestfs(3).
inspect_linux_kernel
This function is deprecated. It will not be updated in future versions
of libguestfs. New code should not use this function. Use the core
API functions instead, see "INSPECTION" in guestfs(3).
COPYRIGHT
Copyright (C) 2009-2013 Red Hat Inc.
LICENSE
Please see the file COPYING.LIB for the full license.
SEE ALSOvirt-inspector(1), Sys::Guestfs(3), guestfs(3),
<http://libguestfs.org/>, Sys::Virt(3), <http://libvirt.org/>,
guestfish(1).
perl v5.10.1 2013-11-21 Sys::Guestfs::Lib(3)
