Sys::Guestfs::Lib(3pm)

1Sys::Guestfs::Lib(3)  User Contributed Perl Documentation Sys::Guestfs::Lib(3)
2
3
4

NAME

6       Sys::Guestfs::Lib - Useful functions for using libguestfs from Perl
7

SYNOPSIS

9        use Sys::Guestfs::Lib qw(open_guest ...);
10
11        $g = open_guest ($name);
12

DESCRIPTION

14       "Sys::Guestfs::Lib" is an extra library of useful functions for using
15       the libguestfs API from Perl.  It also provides tighter integration
16       with libvirt.
17
18       The basic libguestfs API is not covered by this manpage.  Please refer
19       instead to Sys::Guestfs(3) and guestfs(3).  The libvirt API is also not
20       covered.  For that, see Sys::Virt(3).
21

DEPRECATION OF SOME FUNCTIONS

23       This module contains functions and code to perform inspection of guest
24       images.  Since libguestfs 1.5.3 this ability has moved into the core
25       API (see "INSPECTION" in guestfs(3)).  The inspection functions in this
26       module are deprecated and will not be updated.  Each deprecated
27       function is marked in the documentation below.
28

BASIC FUNCTIONS

30   open_guest
31        $g = open_guest ($name);
32
33        $g = open_guest ($name, rw => 1, ...);
34
35        $g = open_guest ($name, address => $uri, ...);
36
37        $g = open_guest ([$img1, $img2, ...], address => $uri, format => $format, ...);
38
39        ($g, $conn, $dom, @images) = open_guest ($name);
40
41       This function opens a libguestfs handle for either the libvirt domain
42       called $name, or the disk image called $name.  Any disk images found
43       through libvirt or specified explicitly are attached to the libguestfs
44       handle.
45
46       The "Sys::Guestfs" handle $g is returned, or if there was an error it
47       throws an exception.  To catch errors, wrap the call in an eval block.
48
49       The first parameter is either a string referring to a libvirt domain or
50       a disk image, or (if a guest has several disk images) an arrayref
51       "[$img1, $img2, ...]".  For disk images, if the "format" parameter is
52       specified then that format is forced.
53
54       The handle is read-only by default.  Use the optional parameter "rw =>
55       1" to open a read-write handle.  However if you open a read-write
56       handle, this function will refuse to use active libvirt domains.
57
58       The handle is still in the config state when it is returned, so you
59       have to call "$g->launch ()".
60
61       The optional "address" parameter can be added to specify the libvirt
62       URI.
63
64       The implicit libvirt handle is closed after this function, unless you
65       call the function in "wantarray" context, in which case the function
66       returns a tuple of: the open libguestfs handle, the open libvirt
67       handle, and the open libvirt domain handle, and a list of
68       [image,format] pairs.  (This is useful if you want to do other things
69       like pulling the XML description of the guest).  Note that if this is a
70       straight disk image, then $conn and $dom will be "undef".
71
72       If the "Sys::Virt" module is not available, then libvirt is bypassed,
73       and this function can only open disk images.
74
75       The optional "interface" parameter can be used to open devices with a
76       specified qemu interface.  See "guestfs_add_drive_opts" in Sys::Guestfs
77       for more details.
78
79   feature_available
80        $bool = feature_available ($g, $feature [, $feature ...]);
81
82       This function is a useful wrapper around the basic "$g->available"
83       call.
84
85       "$g->available" tests for availability of a list of features and dies
86       with an error if any is not available.
87
88       This call tests for the list of features and returns true if all are
89       available, or false otherwise.
90
91       For a list of features you can test for, see "AVAILABILITY" in
92       guestfs(3).
93
94   get_partitions
95       This function is deprecated.  It will not be updated in future versions
96       of libguestfs.  New code should not use this function.  Use the core
97       API function "list_filesystems" in Sys::Guestfs(3) instead.
98
99   resolve_windows_path
100        $path = resolve_windows_path ($g, $path);
101
102        $path = resolve_windows_path ($g, "/windows/system");
103          ==> "/WINDOWS/System"
104              or undef if no path exists
105
106       This function, which is specific to FAT/NTFS filesystems (ie.  Windows
107       guests), lets you look up a case insensitive $path in the filesystem
108       and returns the true, case sensitive path as required by the underlying
109       kernel or NTFS-3g driver.
110
111       If $path does not exist then this function returns "undef".
112
113       The $path parameter must begin with "/" character and be separated by
114       "/" characters.  Do not use "\", drive names, etc.
115
116   file_architecture
117       Deprecated function.  Replace any calls to this function with:
118
119        $g->file_architecture ($path);
120

OPERATING SYSTEM INSPECTION FUNCTIONS

122   inspect_all_partitions
123       This function is deprecated.  It will not be updated in future versions
124       of libguestfs.  New code should not use this function.  Use the core
125       API functions instead, see "INSPECTION" in guestfs(3).
126
127   inspect_partition
128       This function is deprecated.  It will not be updated in future versions
129       of libguestfs.  New code should not use this function.  Use the core
130       API functions instead, see "INSPECTION" in guestfs(3).
131
132   inspect_operating_systems
133       This function is deprecated.  It will not be updated in future versions
134       of libguestfs.  New code should not use this function.  Use the core
135       API functions instead, see "INSPECTION" in guestfs(3).
136
137   mount_operating_system
138       This function is deprecated.  It will not be updated in future versions
139       of libguestfs.  New code should not use this function.  Use the core
140       API functions instead, see "INSPECTION" in guestfs(3).
141
142   inspect_in_detail
143       This function is deprecated.  It will not be updated in future versions
144       of libguestfs.  New code should not use this function.  Use the core
145       API functions instead, see "INSPECTION" in guestfs(3).
146
147   inspect_linux_kernel
148       This function is deprecated.  It will not be updated in future versions
149       of libguestfs.  New code should not use this function.  Use the core
150       API functions instead, see "INSPECTION" in guestfs(3).
151

COPYRIGHT

153       Copyright (C) 2009-2010 Red Hat Inc.
154

LICENSE

156       Please see the file COPYING.LIB for the full license.
157