perl/lib/Sys/Guestfs.pm

   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.
   4 #
   5 # Copyright (C) 2009 Red Hat Inc.
   6 #
   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.
  11 #
  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.
  16 #
  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
  20
  21 =pod
  22
  23 =head1 NAME
  24
  25 Sys::Guestfs - Perl bindings for libguestfs
  26
  27 =head1 SYNOPSIS
  28
  29  use Sys::Guestfs;
  30
  31  my $h = Sys::Guestfs->new ();
  32  $h->add_drive ('guest.img');
  33  $h->launch ();
  34  $h->wait_ready ();
  35  $h->mount ('/dev/sda1', '/');
  36  $h->touch ('/hello');
  37  $h->sync ();
  38
  39 =head1 DESCRIPTION
  40
  41 The C<Sys::Guestfs> module provides a Perl XS binding to the
  42 libguestfs API for examining and modifying virtual machine
  43 disk images.
  44
  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
  50 much else besides.
  51
  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.
  56
  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.
  60
  61 =head1 ERRORS
  62
  63 All errors turn into calls to C<croak> (see L<Carp(3)>).
  64
  65 =head1 METHODS
  66
  67 =over 4
  68
  69 =cut
  70
  71 package Sys::Guestfs;
  72
  73 use strict;
  74 use warnings;
  75
  76 require XSLoader;
  77 XSLoader::load ('Sys::Guestfs');
  78
  79 =item $h = Sys::Guestfs->new ();
  80
  81 Create a new guestfs handle.
  82
  83 =cut
  84
  85 sub new {
  86   my $proto = shift;
  87   my $class = ref ($proto) || $proto;
  88
  89   my $self = Sys::Guestfs::_create ();
  90   bless $self, $class;
  91   return $self;
  92 }
  93
  94 =item $content = $h->cat (path);
  95
  96 Return the contents of the file named C<path>.
  97
  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.
 102
 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
 105 FTP.
 106
 107 =item @devices = $h->list_devices ();
 108
 109 List all the block devices.
 110
 111 The full block device names are returned, eg. C</dev/sda>
 112
 113 =item @partitions = $h->list_partitions ();
 114
 115 List all the partitions detected on all block devices.
 116
 117 The full partition device names are returned, eg. C</dev/sda1>
 118
 119 This does not return logical volumes.  For that you will need to
 120 call C<$h-E<gt>lvs>.
 121
 122 =item $listing = $h->ll (directory);
 123
 124 List the files in C<directory> (relative to the root directory,
 125 there is no cwd) in the format of 'ls -la'.
 126
 127 This command is mostly useful for interactive sessions.  It
 128 is I<not> intended that you try to parse the output string.
 129
 130 =item @listing = $h->ls (directory);
 131
 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.
 135
 136 This command is mostly useful for interactive sessions.  Programs
 137 should probably use C<$h-E<gt>readdir> instead.
 138
 139 =item @logvols = $h->lvs ();
 140
 141 List all the logical volumes detected.  This is the equivalent
 142 of the L<lvs(8)> command.
 143
 144 This returns a list of the logical volume device names
 145 (eg. C</dev/VolGroup00/LogVol00>).
 146
 147 See also C<$h-E<gt>lvs_full>.
 148
 149 =item @logvols = $h->lvs_full ();
 150
 151 List all the logical volumes detected.  This is the equivalent
 152 of the L<lvs(8)> command.  The "full" version includes all fields.
 153
 154 =item $h->mount (device, mountpoint);
 155
 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
 160 names can be used.
 161
 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
 165 exist.
 166
 167 The mounted filesystem is writable, if we have sufficient permissions
 168 on the underlying device.
 169
 170 The filesystem options C<sync> and C<noatime> are set with this
 171 call, in order to improve reliability.
 172
 173 =item @physvols = $h->pvs ();
 174
 175 List all the physical volumes detected.  This is the equivalent
 176 of the L<pvs(8)> command.
 177
 178 This returns a list of just the device names that contain
 179 PVs (eg. C</dev/sda2>).
 180
 181 See also C<$h-E<gt>pvs_full>.
 182
 183 =item @physvols = $h->pvs_full ();
 184
 185 List all the physical volumes detected.  This is the equivalent
 186 of the L<pvs(8)> command.  The "full" version includes all fields.
 187
 188 =item $h->sync ();
 189
 190 This syncs the disk, so that any writes are flushed through to the
 191 underlying disk image.
 192
 193 You should always call this if you have modified a disk image, before
 194 closing the handle.
 195
 196 =item $h->touch (path);
 197
 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.
 201
 202 =item @volgroups = $h->vgs ();
 203
 204 List all the volumes groups detected.  This is the equivalent
 205 of the L<vgs(8)> command.
 206
 207 This returns a list of just the volume group names that were
 208 detected (eg. C<VolGroup00>).
 209
 210 See also C<$h-E<gt>vgs_full>.
 211
 212 =item @volgroups = $h->vgs_full ();
 213
 214 List all the volumes groups detected.  This is the equivalent
 215 of the L<vgs(8)> command.  The "full" version includes all fields.
 216
 217 =cut
 218
 219 1;
 220
 221 =back
 222
 223 =head1 COPYRIGHT
 224
 225 Copyright (C) 2009 Red Hat Inc.
 226
 227 =head1 LICENSE
 228
 229 Please see the file COPYING.LIB for the full license.
 230
 231 =head1 SEE ALSO
 232
 233 L<guestfs(3)>, L<guestfish(1)>.
 234
 235 =cut