.\" 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-ruby 3"
.TH guestfs-ruby 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\-ruby \- How to use libguestfs from Ruby
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& require \*(Aqguestfs\*(Aq
\& g = Guestfs::Guestfs.new()
\& g.add_drive_opts("disk.img",
\&                  :readonly => 1, :format => "raw")
\& g.launch()
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This manual page documents how to call libguestfs from the Ruby
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).
.SS "\s-1EXCEPTIONS\s0"
.IX Subsection "EXCEPTIONS"
Errors from libguestfs functions are mapped into the \f(CW\*(C`Error\*(C'\fR
exception.  This has a single parameter which is the error message (a
string).
.SH "EXAMPLE 1: CREATE A DISK IMAGE"
.IX Header "EXAMPLE 1: CREATE A DISK IMAGE"
.Vb 1
\& # Example showing how to create a disk image.
\& 
\& require \*(Aqguestfs\*(Aq
\& 
\& output = "disk.img"
\& 
\& g = Guestfs::Guestfs.new()
\& 
\& # Create a raw\-format sparse disk image, 512 MB in size.
\& File.open(output, "w") {
\&   |f| f.truncate(512 * 1024 * 1024)
\& }
\& 
\& # 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")
\& 
\& # 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.
\& devices = g.list_devices()
\& if devices.length != 1 then
\&   raise "error: expected a single device from list\-devices"
\& end
\& 
\& # 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.
\& partitions = g.list_partitions()
\& if partitions.length != 1 then
\&   raise "error: expected a single partition from list\-partitions"
\& end
\& 
\& # 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")
\& 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 close the handle
\& # and the disk contents will be synchronized.  You can also do
\& # this manually by calling g#umount_all and g#sync.
\& g.close()
.Ve
.SH "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.IX Header "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.Vb 1
\& # Example showing how to inspect a virtual machine disk.
\& 
\& require \*(Aqguestfs\*(Aq
\& 
\& if ARGV.length == 0
\&   puts "usage: inspect_vm disk.img"
\&   exit 1
\& end
\& disk = ARGV[0]
\& 
\& g = Guestfs::Guestfs.new()
\& 
\& # Attach the disk image read\-only to libguestfs.
\& g.add_drive_opts(disk, :readonly => 1)
\& 
\& # Run the libguestfs back\-end.
\& g.launch()
\& 
\& # Ask libguestfs to inspect for operating systems.
\& roots = g.inspect_os()
\& if roots.length == 0
\&   puts "inspect_vm: no operating systems found"
\&   exit 1
\& end
\& 
\& for root in roots do
\&   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.
\&   mps = g.inspect_get_mountpoints(root)
\&   mps = mps.sort {|a,b| a[0].length <=> b[0].length}
\&   for mp in mps do
\&     begin
\&       g.mount_ro(mp[1], mp[0])
\&     rescue Guestfs::Error => msg
\&       printf("%s (ignored)\en", msg)
\&     end
\&   end
\& 
\&   # If /etc/issue.net file exists, print up to 3 lines.
\&   filename = "/etc/issue.net"
\&   if g.is_file filename then
\&     printf("\-\-\- %s \-\-\-\en", filename)
\&     lines = g.head_n(3, filename)
\&     for line in lines do
\&       puts line
\&     end
\&   end
\& 
\&   # Unmount everything.
\&   g.umount_all()
\& end
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIguestfs\fR\|(3),
\&\fIguestfs\-examples\fR\|(3),
\&\fIguestfs\-erlang\fR\|(3),
\&\fIguestfs\-java\fR\|(3),
\&\fIguestfs\-ocaml\fR\|(3),
\&\fIguestfs\-perl\fR\|(3),
\&\fIguestfs\-python\fR\|(3),
\&\fIguestfs\-recipes\fR\|(1),
<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) 2010 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