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 $content = $h->cat (path);
96 Return the contents of the file named C<path>.
98 Note that this function cannot correctly handle binary files
99 (specifically, files containing C<\0> character which is treated
100 as end of string). For those you need to use the C<$h-E<gt>read_file>
101 function which has a more complex interface.
103 Because of the message protocol, there is a transfer limit
104 of somewhere between 2MB and 4MB. To transfer large files you should use
107 =item @devices = $h->list_devices ();
109 List all the block devices.
111 The full block device names are returned, eg. C</dev/sda>
113 =item @partitions = $h->list_partitions ();
115 List all the partitions detected on all block devices.
117 The full partition device names are returned, eg. C</dev/sda1>
119 This does not return logical volumes. For that you will need to
122 =item $listing = $h->ll (directory);
124 List the files in C<directory> (relative to the root directory,
125 there is no cwd) in the format of 'ls -la'.
127 This command is mostly useful for interactive sessions. It
128 is I<not> intended that you try to parse the output string.
130 =item @listing = $h->ls (directory);
132 List the files in C<directory> (relative to the root directory,
133 there is no cwd). The '.' and '..' entries are not returned, but
134 hidden files are shown.
136 This command is mostly useful for interactive sessions. Programs
137 should probably use C<$h-E<gt>readdir> instead.
139 =item @logvols = $h->lvs ();
141 List all the logical volumes detected. This is the equivalent
142 of the L<lvs(8)> command.
144 This returns a list of the logical volume device names
145 (eg. C</dev/VolGroup00/LogVol00>).
147 See also C<$h-E<gt>lvs_full>.
149 =item @logvols = $h->lvs_full ();
151 List all the logical volumes detected. This is the equivalent
152 of the L<lvs(8)> command. The "full" version includes all fields.
154 =item $h->mount (device, mountpoint);
156 Mount a guest disk at a position in the filesystem. Block devices
157 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
158 the guest. If those block devices contain partitions, they will have
159 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
162 The rules are the same as for L<mount(2)>: A filesystem must
163 first be mounted on C</> before others can be mounted. Other
164 filesystems can only be mounted on directories which already
167 The mounted filesystem is writable, if we have sufficient permissions
168 on the underlying device.
170 The filesystem options C<sync> and C<noatime> are set with this
171 call, in order to improve reliability.
173 =item @physvols = $h->pvs ();
175 List all the physical volumes detected. This is the equivalent
176 of the L<pvs(8)> command.
178 This returns a list of just the device names that contain
179 PVs (eg. C</dev/sda2>).
181 See also C<$h-E<gt>pvs_full>.
183 =item @physvols = $h->pvs_full ();
185 List all the physical volumes detected. This is the equivalent
186 of the L<pvs(8)> command. The "full" version includes all fields.
190 This syncs the disk, so that any writes are flushed through to the
191 underlying disk image.
193 You should always call this if you have modified a disk image, before
196 =item $h->touch (path);
198 Touch acts like the L<touch(1)> command. It can be used to
199 update the timestamps on a file, or, if the file does not exist,
200 to create a new zero-length file.
202 =item @volgroups = $h->vgs ();
204 List all the volumes groups detected. This is the equivalent
205 of the L<vgs(8)> command.
207 This returns a list of just the volume group names that were
208 detected (eg. C<VolGroup00>).
210 See also C<$h-E<gt>vgs_full>.
212 =item @volgroups = $h->vgs_full ();
214 List all the volumes groups detected. This is the equivalent
215 of the L<vgs(8)> command. The "full" version includes all fields.
225 Copyright (C) 2009 Red Hat Inc.
229 Please see the file COPYING.LIB for the full license.
233 L<guestfs(3)>, L<guestfish(1)>.