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

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

 local G = require "guestfs"

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

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

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

 g = G.create ()

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

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

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

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

 g:close ()

ЯК ВИКЛИКАТИ МЕТОДИ¶

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

 g:set_verbose (true)

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

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

 g:add_drive ("test.img")

або:

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

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

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

ПОМИЛКИ¶

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

msg

Повідомлення про помилку (відповідно до "guestfs_last_error" in guestfs(3)).

code

"errno" (відповідно до "guestfs_last_errno" in guestfs(3)).

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

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

ПОДІЇ¶

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

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

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

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

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

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

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

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

 g:delete_event_callback (eh)