5 files changed, 267 insertions, 0 deletions
diff --git a/lua/examples/LICENSE b/lua/examples/LICENSE
new file mode 100644
index 00000000..c5976b51
--- /dev/null
+++ b/lua/examples/LICENSE
@@ -0,0 +1,2 @@
+All the examples in the lua/examples/ subdirectory may be freely
+copied without any restrictions.
diff --git a/lua/examples/Makefile.am b/lua/examples/Makefile.am
new file mode 100644
index 00000000..8dc4650c
--- /dev/null
+++ b/lua/examples/Makefile.am
@@ -0,0 +1,40 @@
+# libguestfs Lua examples
+# Copyright (C) 2012 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+EXTRA_DIST = \
+	LICENSE \
+	create_disk.lua \
+	inspect_vm.lua \
+	guestfs-lua.pod
+
+CLEANFILES = stamp-guestfs-lua.pod
+
+man_MANS = guestfs-lua.3
+noinst_DATA = $(top_builddir)/html/guestfs-lua.3.html
+
+guestfs-lua.3 $(top_builddir)/html/guestfs-lua.3.html: stamp-guestfs-lua.pod
+
+stamp-guestfs-lua.pod: guestfs-lua.pod create_disk.lua inspect_vm.lua
+	$(PODWRAPPER) \
+	  --section 3 \
+	  --man guestfs-lua.3 \
+	  --html $(top_builddir)/html/guestfs-lua.3.html \
+	  --verbatim $(srcdir)/create_disk.lua:@EXAMPLE1@ \
+	  --verbatim $(srcdir)/inspect_vm.lua:@EXAMPLE2@ \
+	  --license examples \
+	  $<
+	touch $@
diff --git a/lua/examples/create_disk.lua b/lua/examples/create_disk.lua
new file mode 100644
index 00000000..2dfc1fc2
--- /dev/null
+++ b/lua/examples/create_disk.lua
@@ -0,0 +1,66 @@
+-- Example showing how to create a disk image.
+
+require "guestfs"
+
+output = "disk.img"
+
+g = Guestfs.create ()
+
+-- Create a raw-format sparse disk image, 512 MB in size.
+file = io.open (output, "w")
+file:seek ("set", 512 * 1024 * 1024)
+file:write (' ')
+file:close ()
+
+-- Set the trace flag so that we can see each libguestfs call.
+g:set_trace (true)
+
+-- Attach the disk image to libguestfs.
+g:add_drive (output, { format = "raw", readonly = false })
+
+-- 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 table.getn (devices) ~= 1 then
+   error "expected a single device from list-devices"
+end
+
+-- Partition the disk as one single MBR partition.
+g:part_disk (devices[1], "mbr")
+
+-- Get the list of partitions.  We expect a single element, which
+-- is the partition we have just created.
+partitions = g:list_partitions ()
+if table.getn (partitions) ~= 1 then
+   error "expected a single partition from list-partitions"
+end
+
+-- Create a filesystem on the partition.
+g:mkfs ("ext4", partitions[1])
+
+-- Now mount the filesystem so that we can add files.
+g:mount (partitions[1], "/")
+
+-- Create some files and directories.
+g:touch ("/empty")
+message = "Hello, world\n"
+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 we wrote to the disk and we want to detect write
+-- errors, call g:shutdown.  You don't need to do this:
+-- g:close will do it implicitly.
+g:shutdown ()
+
+-- Note also that handles are automatically closed if they are
+-- reaped by the garbage collector.  You only need to call close
+-- if you want to close the handle right away.
+g:close ()
diff --git a/lua/examples/guestfs-lua.pod b/lua/examples/guestfs-lua.pod
new file mode 100644
index 00000000..33c9b811
--- /dev/null
+++ b/lua/examples/guestfs-lua.pod
@@ -0,0 +1,97 @@
+=encoding utf8
+
+=head1 NAME
+
+guestfs-lua - How to use libguestfs from Lua
+
+=head1 SYNOPSIS
+
+ require "guestfs"
+ g = Guestfs.create ()
+ g:add_drive ("test.img", { format = "raw", readonly = "true" })
+ g:launch ()
+ devices = g:list_devices ()
+ g:close ()
+
+=head1 DESCRIPTION
+
+This manual page documents how to call libguestfs from the Lua
+programming language.  This page just documents the differences from
+the C API and gives some examples.  If you are not familiar with using
+libguestfs, you also need to read L<guestfs(3)>.
+
+=head2 OPENING AND CLOSING THE HANDLE
+
+To create a new handle, call:
+
+ g = Guestfs.create ()
+
+You can also use the optional arguments:
+
+ g = Guestfs.create { environment = 0, close_on_exit = 0 }
+
+to set the flags C<GUESTFS_CREATE_NO_ENVIRONMENT>
+and/or C<GUESTFS_CREATE_NO_CLOSE_ON_EXIT>.
+
+The handle will be closed by the garbage collector, but you can
+also close it explicitly by doing:
+
+ g:close ()
+
+=head2 CALLING METHODS
+
+Use the ordinary Lua convention for calling methods on the handle.
+For example:
+
+ g:set_verbose (true)
+
+=head2 FUNCTIONS WITH OPTIONAL ARGUMENTS
+
+For functions that take optional arguments, the first arguments are
+the non-optional ones.  The optional final argument is a table
+supplying the optional arguments.
+
+ g:add_drive ("test.img")
+
+or:
+
+ g:add_drive ("test.img", { format = "raw", readonly = "true" })
+
+=head2 64 BIT VALUES
+
+Currently 64 bit values must be passed as strings, and are returned as
+strings.  This is because 32 bit Lua cannot handle 64 bit integers
+properly.  We hope to come up with a better solution later.
+
+=head2 ERRORS
+
+Errors are converted into exceptions.  Use C<pcall> to catch these.
+
+=head1 EXAMPLE 1: CREATE A DISK IMAGE
+
+@EXAMPLE1@
+
+=head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE
+
+@EXAMPLE2@
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfs-examples(3)>,
+L<guestfs-java(3)>,
+L<guestfs-ocaml(3)>,
+L<guestfs-perl(3)>,
+L<guestfs-python(3)>,
+L<guestfs-recipes(1)>,
+L<guestfs-ruby(3)>,
+L<http://www.erlang.org/>.
+L<http://libguestfs.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2012 Red Hat Inc.
diff --git a/lua/examples/inspect_vm.lua b/lua/examples/inspect_vm.lua
new file mode 100644
index 00000000..1bee10b3
--- /dev/null
+++ b/lua/examples/inspect_vm.lua
@@ -0,0 +1,62 @@
+-- Example showing how to inspect a virtual machine disk.
+
+require "guestfs"
+
+if table.getn (arg) == 1 then
+   disk = arg[1]
+else
+   error ("usage: inspect_vm disk.img")
+end
+
+g = Guestfs.create ()
+
+-- Attach the disk image read-only to libguestfs.
+g:add_drive (disk, { -- format:"raw"
+                     readonly = true })
+
+-- Run the libguestfs back-end.
+g:launch ()
+
+-- Ask libguestfs to inspect for operating systems.
+roots = g:inspect_os ()
+if table.getn (roots) == 0 then
+   error ("inspect_vm: no operating systems found")
+end
+
+for _, root in ipairs (roots) do
+   print ("Root device: ", root)
+
+   -- Print basic information about the operating system.
+   print ("  Product name: ", g:inspect_get_product_name (root))
+   print ("  Version:      ",
+          g:inspect_get_major_version (root),
+          g:inspect_get_minor_version (root))
+   print ("  Type:         ", g:inspect_get_type (root))
+   print ("  Distro:       ", 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)
+   table.sort (mps,
+               function (a, b)
+                  return string.len (a) < string.len (b)
+               end)
+   for mp,dev in pairs (mps) do
+      pcall (function () g:mount_ro (dev, mp) end)
+   end
+
+   -- If /etc/issue.net file exists, print up to 3 lines.
+   filename = "/etc/issue.net"
+   if g:is_file (filename) then
+      print ("--- ", filename, " ---")
+      lines = g:head_n (3, filename)
+      for _, line in ipairs (lines) do
+         print (line)
+      end
+   end
+
+   -- Unmount everything.
+   g:umount_all ()
+end