.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "guestfs-perl 3"
.TH guestfs-perl 3 "2013-12-07" "libguestfs-1.18.1" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
guestfs\-perl \- How to use libguestfs from Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Sys::Guestfs;
\& 
\& my $h = Sys::Guestfs\->new ();
\& $h\->add_drive_opts (\*(Aqguest.img\*(Aq, format => \*(Aqraw\*(Aq);
\& $h\->launch ();
\& $h\->mount_options (\*(Aq\*(Aq, \*(Aq/dev/sda1\*(Aq, \*(Aq/\*(Aq);
\& $h\->touch (\*(Aq/hello\*(Aq);
\& $h\->sync ();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This manual page documents how to call libguestfs from the Perl
programming language.  This page just documents the differences from
the C \s-1API\s0 and gives some examples.  If you are not familiar with using
libguestfs, you also need to read \fIguestfs\fR\|(3).  To read the
full Perl \s-1API\s0, see \fISys::Guestfs\fR\|(3).
.SS "\s-1ERRORS\s0"
.IX Subsection "ERRORS"
Errors from libguestfs functions turn into calls to
\&\f(CW\*(C`croak\*(C'\fR (see \fICarp\fR\|(3)).
.SH "EXAMPLE 1: CREATE A DISK IMAGE"
.IX Header "EXAMPLE 1: CREATE A DISK IMAGE"
.Vb 1
\& #!/usr/bin/perl \-w
\& 
\& # Example showing how to create a disk image.
\& 
\& use strict;
\& use Sys::Guestfs;
\& 
\& my $output = "disk.img";
\& 
\& my $g = new Sys::Guestfs ();
\& 
\& # Create a raw\-format sparse disk image, 512 MB in size.
\& open FILE, ">$output" or die "$output: $!";
\& truncate FILE, 512 * 1024 * 1024 or die "$output: truncate: $!";
\& close FILE or die "$output: $!";
\& 
\& # Set the trace flag so that we can see each libguestfs call.
\& $g\->set_trace (1);
\& 
\& # Set the autosync flag so that the disk will be synchronized
\& # automatically when the libguestfs handle is closed.
\& $g\->set_autosync (1);
\& 
\& # Attach the disk image to libguestfs.
\& $g\->add_drive_opts ($output, format => "raw", readonly => 0);
\& 
\& # Run the libguestfs back\-end.
\& $g\->launch ();
\& 
\& # Get the list of devices.  Because we only added one drive
\& # above, we expect that this list should contain a single
\& # element.
\& my @devices = $g\->list_devices ();
\& if (@devices != 1) {
\&     die "error: expected a single device from list\-devices";
\& }
\& 
\& # Partition the disk as one single MBR partition.
\& $g\->part_disk ($devices[0], "mbr");
\& 
\& # Get the list of partitions.  We expect a single element, which
\& # is the partition we have just created.
\& my @partitions = $g\->list_partitions ();
\& if (@partitions != 1) {
\&     die "error: expected a single partition from list\-partitions";
\& }
\& 
\& # Create a filesystem on the partition.
\& $g\->mkfs ("ext4", $partitions[0]);
\& 
\& # Now mount the filesystem so that we can add files.
\& $g\->mount_options ("", $partitions[0], "/");
\& 
\& # Create some files and directories.
\& $g\->touch ("/empty");
\& my $message = "Hello, world\en";
\& $g\->write ("/hello", $message);
\& $g\->mkdir ("/foo");
\& 
\& # This one uploads the local file /etc/resolv.conf into
\& # the disk image.
\& $g\->upload ("/etc/resolv.conf", "/foo/resolv.conf");
\& 
\& # Because \*(Aqautosync\*(Aq was set (above) we can just exit here
\& # and the disk contents will be synchronized.  You can also do
\& # this manually by calling $g\->umount_all and $g\->sync.
\& exit 0
.Ve
.SH "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.IX Header "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.Vb 1
\& #!/usr/bin/perl \-w
\& 
\& # Example showing how to inspect a virtual machine disk.
\& 
\& use strict;
\& use Sys::Guestfs;
\& 
\& if (@ARGV < 1) {
\&     die "usage: inspect_vm disk.img"
\& }
\& 
\& my $disk = $ARGV[0];
\& 
\& my $g = new Sys::Guestfs ();
\& 
\& # Attach the disk image read\-only to libguestfs.
\& # You could also add an optional format => ... argument here.  This is
\& # advisable since automatic format detection is insecure.
\& $g\->add_drive_opts ($disk, readonly => 1);
\& 
\& # Run the libguestfs back\-end.
\& $g\->launch ();
\& 
\& # Ask libguestfs to inspect for operating systems.
\& my @roots = $g\->inspect_os ();
\& if (@roots == 0) {
\&     die "inspect_vm: no operating systems found";
\& }
\& 
\& for my $root (@roots) {
\&     printf "Root device: %s\en", $root;
\& 
\&     # Print basic information about the operating system.
\&     printf "  Product name: %s\en", $g\->inspect_get_product_name ($root);
\&     printf "  Version:      %d.%d\en",
\&         $g\->inspect_get_major_version ($root),
\&         $g\->inspect_get_minor_version ($root);
\&     printf "  Type:         %s\en", $g\->inspect_get_type ($root);
\&     printf "  Distro:       %s\en", $g\->inspect_get_distro ($root);
\& 
\&     # Mount up the disks, like guestfish \-i.
\&     #
\&     # Sort keys by length, shortest first, so that we end up
\&     # mounting the filesystems in the correct order.
\&     my %mps = $g\->inspect_get_mountpoints ($root);
\&     my @mps = sort { length $a <=> length $b } (keys %mps);
\&     for my $mp (@mps) {
\&         eval { $g\->mount_ro ($mps{$mp}, $mp) };
\&         if ($@) {
\&             print "$@ (ignored)\en"
\&         }
\&     }
\& 
\&     # If /etc/issue.net file exists, print up to 3 lines.
\&     my $filename = "/etc/issue.net";
\&     if ($g\->is_file ($filename)) {
\&         printf "\-\-\- %s \-\-\-\en", $filename;
\&         my @lines = $g\->head_n (3, $filename);
\&         print "$_\en" foreach @lines;
\&     }
\& 
\&     # Unmount everything.
\&     $g\->umount_all ()
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISys::Guestfs\fR\|(3),
\&\fIguestfs\fR\|(3),
\&\fIguestfs\-examples\fR\|(3),
\&\fIguestfs\-erlang\fR\|(3),
\&\fIguestfs\-java\fR\|(3),
\&\fIguestfs\-ocaml\fR\|(3),
\&\fIguestfs\-python\fR\|(3),
\&\fIguestfs\-recipes\fR\|(1),
\&\fIguestfs\-ruby\fR\|(3),
<http://libguestfs.org/>.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2011 Red Hat Inc. <http://libguestfs.org/>
.PP
The examples in this manual page may be freely copied, modified and
distributed without any restrictions.
.PP
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
.PP
This library is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0 02110\-1301 \s-1USA\s0