1 # libguestfs generated file
2 # WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.
3 # ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.
5 # Copyright (C) 2009 Red Hat Inc.
7 # This library is free software; you can redistribute it and/or
8 # modify it under the terms of the GNU Lesser General Public
9 # License as published by the Free Software Foundation; either
10 # version 2 of the License, or (at your option) any later version.
12 # This library is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 # Lesser General Public License for more details.
17 # You should have received a copy of the GNU Lesser General Public
18 # License along with this library; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 Sys::Guestfs - Perl bindings for libguestfs
31 my $h = Sys::Guestfs->new ();
32 $h->add_drive ('guest.img');
35 $h->mount ('/dev/sda1', '/');
41 The C<Sys::Guestfs> module provides a Perl XS binding to the
42 libguestfs API for examining and modifying virtual machine
45 Amongst the things this is good for: making batch configuration
46 changes to guests, getting disk used/free statistics (see also:
47 virt-df), migrating between virtualization systems (see also:
48 virt-p2v), performing partial backups, performing partial guest
49 clones, cloning guests and changing registry/UUID/hostname info, and
52 Libguestfs uses Linux kernel and qemu code, and can access any type of
53 guest filesystem that Linux and qemu can, including but not limited
54 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
55 schemes, qcow, qcow2, vmdk.
57 Libguestfs provides ways to enumerate guest storage (eg. partitions,
58 LVs, what filesystem is in each LV, etc.). It can also run commands
59 in the context of the guest. Also you can access filesystems over FTP.
63 All errors turn into calls to C<croak> (see L<Carp(3)>).
77 XSLoader::load ('Sys::Guestfs');
79 =item $h = Sys::Guestfs->new ();
81 Create a new guestfs handle.
87 my $class = ref ($proto) || $proto;
89 my $self = Sys::Guestfs::_create ();
94 =item $h->add_cdrom (filename);
96 This function adds a virtual CD-ROM disk image to the guest.
98 This is equivalent to the qemu parameter C<-cdrom filename>.
100 =item $h->add_drive (filename);
102 This function adds a virtual machine disk image C<filename> to the
103 guest. The first time you call this function, the disk appears as IDE
104 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
107 You don't necessarily need to be root when using libguestfs. However
108 you obviously do need sufficient permissions to access the filename
109 for whatever operations you want to perform (ie. read access if you
110 just want to read the image or write access if you want to modify the
113 This is equivalent to the qemu parameter C<-drive file=filename>.
115 =item $content = $h->cat (path);
117 Return the contents of the file named C<path>.
119 Note that this function cannot correctly handle binary files
120 (specifically, files containing C<\0> character which is treated
121 as end of string). For those you need to use the C<$h-E<gt>read_file>
122 function which has a more complex interface.
124 Because of the message protocol, there is a transfer limit
125 of somewhere between 2MB and 4MB. To transfer large files you should use
128 =item $h->config (qemuparam, qemuvalue);
130 This can be used to add arbitrary qemu command line parameters
131 of the form C<-param value>. Actually it's not quite arbitrary - we
132 prevent you from setting some parameters which would interfere with
133 parameters that we use.
135 The first character of C<param> string must be a C<-> (dash).
137 C<value> can be NULL.
139 =item $autosync = $h->get_autosync ();
141 Get the autosync flag.
143 =item $path = $h->get_path ();
145 Return the current search path.
147 This is always non-NULL. If it wasn't set already, then this will
148 return the default path.
150 =item $verbose = $h->get_verbose ();
152 This returns the verbose messages flag.
154 =item $h->kill_subprocess ();
156 This kills the qemu subprocess. You should never need to call this.
160 Internally libguestfs is implemented by running a virtual machine
163 You should call this after configuring the handle
164 (eg. adding drives) but before performing any actions.
166 =item @devices = $h->list_devices ();
168 List all the block devices.
170 The full block device names are returned, eg. C</dev/sda>
172 =item @partitions = $h->list_partitions ();
174 List all the partitions detected on all block devices.
176 The full partition device names are returned, eg. C</dev/sda1>
178 This does not return logical volumes. For that you will need to
181 =item $listing = $h->ll (directory);
183 List the files in C<directory> (relative to the root directory,
184 there is no cwd) in the format of 'ls -la'.
186 This command is mostly useful for interactive sessions. It
187 is I<not> intended that you try to parse the output string.
189 =item @listing = $h->ls (directory);
191 List the files in C<directory> (relative to the root directory,
192 there is no cwd). The '.' and '..' entries are not returned, but
193 hidden files are shown.
195 This command is mostly useful for interactive sessions. Programs
196 should probably use C<$h-E<gt>readdir> instead.
198 =item @logvols = $h->lvs ();
200 List all the logical volumes detected. This is the equivalent
201 of the L<lvs(8)> command.
203 This returns a list of the logical volume device names
204 (eg. C</dev/VolGroup00/LogVol00>).
206 See also C<$h-E<gt>lvs_full>.
208 =item @logvols = $h->lvs_full ();
210 List all the logical volumes detected. This is the equivalent
211 of the L<lvs(8)> command. The "full" version includes all fields.
213 =item $h->mount (device, mountpoint);
215 Mount a guest disk at a position in the filesystem. Block devices
216 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
217 the guest. If those block devices contain partitions, they will have
218 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
221 The rules are the same as for L<mount(2)>: A filesystem must
222 first be mounted on C</> before others can be mounted. Other
223 filesystems can only be mounted on directories which already
226 The mounted filesystem is writable, if we have sufficient permissions
227 on the underlying device.
229 The filesystem options C<sync> and C<noatime> are set with this
230 call, in order to improve reliability.
232 =item @physvols = $h->pvs ();
234 List all the physical volumes detected. This is the equivalent
235 of the L<pvs(8)> command.
237 This returns a list of just the device names that contain
238 PVs (eg. C</dev/sda2>).
240 See also C<$h-E<gt>pvs_full>.
242 =item @physvols = $h->pvs_full ();
244 List all the physical volumes detected. This is the equivalent
245 of the L<pvs(8)> command. The "full" version includes all fields.
247 =item @lines = $h->read_lines (path);
249 Return the contents of the file named C<path>.
251 The file contents are returned as a list of lines. Trailing
252 C<LF> and C<CRLF> character sequences are I<not> returned.
254 Note that this function cannot correctly handle binary files
255 (specifically, files containing C<\0> character which is treated
256 as end of line). For those you need to use the C<$h-E<gt>read_file>
257 function which has a more complex interface.
259 =item $h->set_autosync (autosync);
261 If C<autosync> is true, this enables autosync. Libguestfs will make a
262 best effort attempt to run C<$h-E<gt>sync> when the handle is closed
263 (also if the program exits without closing handles).
265 =item $h->set_path (path);
267 Set the path that libguestfs searches for kernel and initrd.img.
269 The default is C<$libdir/guestfs> unless overridden by setting
270 C<LIBGUESTFS_PATH> environment variable.
272 The string C<path> is stashed in the libguestfs handle, so the caller
273 must make sure it remains valid for the lifetime of the handle.
275 Setting C<path> to C<NULL> restores the default path.
277 =item $h->set_verbose (verbose);
279 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
281 Verbose messages are disabled unless the environment variable
282 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
286 This syncs the disk, so that any writes are flushed through to the
287 underlying disk image.
289 You should always call this if you have modified a disk image, before
292 =item $h->touch (path);
294 Touch acts like the L<touch(1)> command. It can be used to
295 update the timestamps on a file, or, if the file does not exist,
296 to create a new zero-length file.
298 =item @volgroups = $h->vgs ();
300 List all the volumes groups detected. This is the equivalent
301 of the L<vgs(8)> command.
303 This returns a list of just the volume group names that were
304 detected (eg. C<VolGroup00>).
306 See also C<$h-E<gt>vgs_full>.
308 =item @volgroups = $h->vgs_full ();
310 List all the volumes groups detected. This is the equivalent
311 of the L<vgs(8)> command. The "full" version includes all fields.
313 =item $h->wait_ready ();
315 Internally libguestfs is implemented by running a virtual machine
318 You should call this after C<$h-E<gt>launch> to wait for the launch
329 Copyright (C) 2009 Red Hat Inc.
333 Please see the file COPYING.LIB for the full license.
337 L<guestfs(3)>, L<guestfish(1)>.