
=head1 НАЗВА

guestfs-lua — як використовувати libguestfs з Lua

=head1 КОРОТКИЙ ОПИС

 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 ОПИС

На цій сторінці підручника наведено документацію щодо викликів libguestfs з
коду мовою програмування Lua. На сторінці задокументовано відмінності від
програмного інтерфейсу C та подано декілька прикладів. Якщо ви не дуже
знайомі із користуванням libguestfs, вам також слід прочитати підручник з
L<guestfs(3)>.

=head2 ВСТАНОВЛЕННЯ ВИМОГИ ЩОДО МОДУЛЯ

C<require "guestfs"> повертає модуль, тому вам слід пов'язати це значення із
локальною змінною. Типове використання:

 local G = require "guestfs"

(ви можете використовувати будь-яку назву замість C<G>, але у прикладах на
цій сторінці підручника ми завжди використовуватимемо C<G>).

=head2 ВІДКРИТТЯ І ЗАКРИТТЯ ДЕСКРИПТОРА

Для створення дескриптора викличте:

 g = G.create ()

Ви також можете скористатися необов'язковими аргументами:

 g = G.create { environment = 0, close_on_exit = 0 }

для встановлення прапорців C<GUESTFS_CREATE_NO_ENVIRONMENT> і/або
C<GUESTFS_CREATE_NO_CLOSE_ON_EXIT>.

Дескриптор буде закрито засобом збирання сміття, але ви також можете закрити
його явним чином, ось так:

 g:close ()

=head2 ЯК ВИКЛИКАТИ МЕТОДИ

Скористайтеся звичайною методикою Lua для виклику методів для
дескриптора. Приклад:

 g:set_verbose (true)

=head2 ФУНКЦІЇ І НЕОБОВ'ЯЗКОВІ ПАРАМЕТРИ

Для функцій, які приймають необов'язкові аргументи, першими аргументами
мають бути обов'язкові. Необов'язковим останнім аргументом є таблиця із
необов'язковими аргументами.

 g:add_drive ("test.img")

або:

 g:add_drive ("test.img", { format = "raw", readonly = true })

=head2 64-БІТОВІ ЗНАЧЕННЯ

У поточній версії 64-бітові значення має бути передано як рядки, також ці
значення повертаються функціями як рядки. Причиною є те, що у 32-бітовому
інтерпретаторі Lua неможлива належна обробка цілих 64-бітових
чисел. Сподіваємося, згодом нами буде знайдено прийнятніше рішення.

=head2 ПОМИЛКИ

Більшість (але не усі) помилок перетворюються на об'єкти (тобто таблиці), що
містять такі поля:

=over 4

=item msg

Повідомлення про помилку (відповідно до L<guestfs(3)/guestfs_last_error>).

=item code

C<errno> (відповідно до L<guestfs(3)/guestfs_last_errno>).

=back

Із цими об'єктами також пов'язано з функціями C<__tostring>, отже ви можете
скористатися функцією C<tostring> (або неявним перетворенням) для
перетворення їх на придатні до виведення рядки.

Зауважте, що бібліотека також виводить деякі помилки як прості
рядки. Можливо, вам слід перевірити тип цих даних.

=head2 ПОДІЇ

Реєструвати події можна за допомогою викликів C<set_event_callback>:

 eh = g:set_event_callback (cb, "close")

або можна зареєструвати єдиний зворотний виклик для декількох подій,
зробивши другим аргументом список:

 eh = g:set_event_callback (cb, { "appliance", "library", "trace" })

Список усіх чинних типів подій (рядків) зберігається у загальній змінній
C<G.event_all>.

Зворотний виклик (C<cb>) викликається із такими параметрами:

 function cb (g, event, eh, flags, buf, array)
   -- g i— дескриптор guestfs
   -- event — рядок, який є назвою події, яка сталася
   -- flags — завжди нуль
   -- buf — буфер даних (наприклад, повідомлення журналу тощо)
   -- array — масив з 64-бітових цілих чисел (наприклад, стан смужки поступу тощо)
   ...
 end

Ви також можете вилучити зворотний виклик за допомогою дескриптора події
(C<eh>), який було повернуто, коли ви реєстрували зворотний виклик:

 g:delete_event_callback (eh)

=head1 ПРИКЛАД 1. СТВОРЕННЯ ОБРАЗУ ДИСКА

@EXAMPLE1@

=head1 ПРИКЛАД 2. ПЕРЕВІРКА ОБРАЗУ ДИСКА ВІРТУАЛЬНОЇ МАШИНИ

@EXAMPLE2@

=head1 ТАКОЖ ПЕРЕГЛЯНЬТЕ

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 АВТОРИ

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 АВТОРСЬКІ ПРАВА

© Red Hat Inc., 2012

