mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-22 07:03:38 +00:00
f30b2065a2
Since we removed gtk doc, we might as well replace it with a manual page explaining the basics of how to run gjs.
159 lines
3.7 KiB
Plaintext
159 lines
3.7 KiB
Plaintext
=head1 NAME
|
|
|
|
guestfs-lua - How to use libguestfs from Lua
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
local G = require "guestfs"
|
|
g = G.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 REQUIRING THE MODULE
|
|
|
|
C<require "guestfs"> returns the module, so you have to assign it
|
|
to a local variable. Typical usage is:
|
|
|
|
local G = require "guestfs"
|
|
|
|
(you can use any name you want instead of C<G>, but in the examples
|
|
in this man page we always use C<G>).
|
|
|
|
=head2 OPENING AND CLOSING THE HANDLE
|
|
|
|
To create a new handle, call:
|
|
|
|
g = G.create ()
|
|
|
|
You can also use the optional arguments:
|
|
|
|
g = G.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
|
|
|
|
Most (but not all) errors are converted into objects (ie. tables)
|
|
containing the following fields:
|
|
|
|
=over 4
|
|
|
|
=item msg
|
|
|
|
The error message (corresponding to L<guestfs(3)/guestfs_last_error>).
|
|
|
|
=item code
|
|
|
|
The C<errno> (corresponding to L<guestfs(3)/guestfs_last_errno>).
|
|
|
|
=back
|
|
|
|
These objects also have C<__tostring> functions attached to them
|
|
so you can use C<tostring> (or implicit conversion) to convert them
|
|
into printable strings.
|
|
|
|
Note that the library also throws some errors as plain strings. You
|
|
may need to check the type.
|
|
|
|
=head2 EVENTS
|
|
|
|
Events can be registered by calling C<set_event_callback>:
|
|
|
|
eh = g:set_event_callback (cb, "close")
|
|
|
|
or to register a single callback for multiple events make the
|
|
second argument a list:
|
|
|
|
eh = g:set_event_callback (cb, { "appliance", "library", "trace" })
|
|
|
|
A list of all valid event types (strings) is in the global variable
|
|
C<G.event_all>.
|
|
|
|
The callback (C<cb>) is called with the following parameters:
|
|
|
|
function cb (g, event, eh, flags, buf, array)
|
|
-- g is the guestfs handle
|
|
-- event is a string which is the name of the event that fired
|
|
-- flags is always zero
|
|
-- buf is the data buffer (eg. log message etc)
|
|
-- array is the array of 64 bit ints (eg. progress bar status etc)
|
|
...
|
|
end
|
|
|
|
You can also remove a callback using the event handle (C<eh>) that was
|
|
returned when you registered the callback:
|
|
|
|
g:delete_event_callback (eh)
|
|
|
|
=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-erlang(3)>,
|
|
L<guestfs-gobject(3)>,
|
|
L<guestfs-golang(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.lua.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.
|