1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
=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
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
Note that some errors can also be thrown as plain strings. You
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<Guestfs.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-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.
|
