=head1 НАЗВА

guestfs — бібліотека для доступу та внесення змін до образів віртуальних
машин

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

 #include <guestfs.h>
 
 guestfs_h *g = guestfs_create ();
 guestfs_add_drive (g, "guest.img");
 guestfs_launch (g);
 guestfs_mount (g, "/dev/sda1", "/");
 guestfs_touch (g, "/hello");
 guestfs_umount (g, "/");
 guestfs_shutdown (g);
 guestfs_close (g);

 cc prog.c -o prog -lguestfs
або:
 cc prog.c -o prog `pkg-config libguestfs --cflags --libs`

=head1 ОПИС

Libguestfs є бібліотекою для доступу до образів дисків та віртуальних машин
і внесення зміни до них.

Цю сторінку підручника присвячено документації щодо програмного інтерфейсу
мовою програмування C.

Якщо вам потрібна якась вступна інформація щодо libguestfs, зверніться до
цього сайта: L<http://libguestfs.org/>

У кожного інструмента віртуалізації є власна сторінка підручника (повний
список наведено у розділі L</ДИВ. ТАКОЖ> наприкінці цього файла).

Інші сторінки підручника, які присвячено libguestfs:

=over 4

=item L<guestfs-faq(1)>

Поширені питання (ЧаП).

=item L<guestfs-examples(3)>

Приклади використання програмного інтерфейсу з C. Приклади іншими мовами
програмування можна знайти у розділі L</ВИКОРИСТАННЯ LIBGUESTFS ЗА ДОПОМОГОЮ
ІНШИХ МОВ ПРОГРАМУВАННЯ> нижче.

=item L<guestfs-recipes(1)>

Підказки і рецепти.

=item L<guestfs-performance(1)>

Настанови та рішення, які пов’язано із швидкодією.

=item L<libguestfs-test-tool(1)>

=item L<guestfs-testing(1)>

Допомога у тестуванні libguestfs.

=item L<guestfs-building(1)>

Настанови щодо збирання libguestfs з початкових кодів.

=item L<guestfs-hacking(1)>

Надсилання коду до libguestfs.

=item L<guestfs-internals(1)>

Опис принципів роботи libguestfs.

=item L<guestfs-security(1)>

Дані щодо безпеки, зокрема список CVE, пов’язаних із libguestfs.

=back

=head1 ОГЛЯД API

У цьому розділі наведено поверхневий огляд програмного інтерфейсу
libguestfs. Ми також намагалися згрупувати виклики програмного інтерфейсу,
де це не очевидно з матеріалів щодо окремих викликів у основному розділі
цього підручника.

=head2 ОБРОБНИКИ

Перш ніж ви зможете скористатися викликами libguestfs, вам слід створити
дескриптор. Далі, вам слід додати до дескриптора принаймні один образ диска,
потім запустити дескриптор, далі виконати потрібні вам дії і, нарешті,
закрити дескриптор. За угодою щодо синтаксису ми використовуємо одну літеру
C<g> для іменування змінної дескриптора, хоча, звичайно ж, ви можете вибрати
будь-яку іншу назву.

Загальна структуру усіх програм, де використовується libguestfs, є подібною
до такої:

 guestfs_h *g = guestfs_create ();
 
 /* Викликаємо guestfs_add_drive додаткові рази, якщо
  * образів дисків декілька.
  */
 guestfs_add_drive (g, "guest.img");
 
 /* Більшість викликів з обробки не працюватимуть, доки ви
  * не запустите дескриптор «g». Вам слід зробити це _після_ додавання
  * дисків і _до_ інших команд.
  */
 guestfs_launch (g);
 
 /* Або визначити розділи, логічні томи тощо, які є доступними: */
 char **partitions = guestfs_list_partitions (g);
 char **logvols = guestfs_lvs (g);
 
 /* Або наказати libguestfs знайти для вас файлові системи: */
 char **filesystems = guestfs_list_filesystems (g);
 
 /* Або скористатися інспекцією (див. розділ щодо інспекції нижче). */
 
 /* Щоб отримати доступ до файлової системи у образі, вам слід її змонтувати. */
 guestfs_mount (g, "/dev/sda1", "/");
 
 /* Тепер ви можете виконувати дії з файловою системою на
  * образі диска операційної системи.
  */
 guestfs_touch (g, "/hello");
 
 /* Синхронізуємо диск. Це дія, протилежна до guestfs_launch. */
 guestfs_shutdown (g);
 
 /* Закрити і звільнити дескриптор «g». */
 guestfs_close (g);

До наведеного вище коду не включено обробник помилок. У справжньому коді
слід ретельно перевіряти повернуті значення на помилки. Загалом, усі
функції, які повертають цілі числа, повертають C<-1>, якщо станеться
помилка, а усі функції, які повертають вказівники, якщо станеться помилка,
повертають C<NULL>. Див. розділ L</ОБРОБКА ПОМИЛОК> нижче, щоб дізнатися про
те, як обробляти помилки. Також ознайомтеся із документацією щодо кожного
виклику функції, щоб дізнатися більше про те, як функції повідомляють про
помилки.

У наведеному вище коді не виконується L<free(3)> для рядків та масивів, які
повертаються функціями. Зверніться до документації з відповідної функції,
щоб дізнатися більше про те, як звільнити повернуте значення.

Повноцінні робочі приклади можна знайти у підручнику L<guestfs-examples(3)>.

=head2 ОБРАЗИ ДИСКІВ

Назва файла образу (C<"guest.img"> у наведеному вище прикладі) може бути
назвою образу диска з віртуальної машини, створеної за допомогою L<dd(1)>
копії фізичного диска, справжнього блокового пристрою або просто назвою
порожнього файла, заповненого нулями, який можна створити за допомогою
L<posix_fallocate(3)>. Libguestfs надає вам змогу виконувати корисні
операції із усіма такими образами.

Викликом, яким вам слід користуватися у сучасному коді для додавання дисків,
є L</guestfs_add_drive_opts>. Щоб додати образ диска з можливістю запису і
вказати його формат (raw), скористайтеся таким кодом:

 guestfs_add_drive_opts (g, filename,
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         -1);

Ви можете додати диск у режимі лише читання:

 guestfs_add_drive_opts (g, filename,
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
                         -1);

або скористатися викликом старішої функції L</guestfs_add_drive_ro>. Якщо ви
використовуєте прапорець лише читання, libguestfs не зможе вносити зміни до
файла. (Див. також L</ФОРМАТИ ОБРАЗІВ ДИСКІВ> нижче).

Будьте дуже обережні із дисками, які використовуються, наприклад,
віртуальною машиною. Додавання таких дисків у режимі читання-запису майже
напевне призведе до пошкодження вмісту, але додавання у режимі лише читання
є безпечним.

Слід обов'язково додати принаймні один образ диска. Якщо потрібно, можна
додати декілька образів. Якщо додається декілька образів дисків, вони,
зазвичай, мають бути «пов'язані», тобто походити із однієї гостьової
системи. У програмному інтерфейсі на образи дисків, зазвичай, посилаються у
форматі F</dev/sda> (для першого доданого диска), F</dev/sdb> (для другого
доданого диска) тощо.

Після виклику L</guestfs_launch> додавати нові образи вже не можна. Ви
можете викликати L</guestfs_list_devices>, щоб отримати список назв
пристроїв у порядку, за яким їх було додано. Див. також L</ІМЕНУВАННЯ
БЛОКОВИХ ПРИСТРОЇВ> нижче.

Правила з'єднання дисків у «гарячому» режимі (у libguestfs E<ge> 1.20) є
дещо іншими. Див. L</З'ЄДНАННЯ У «ГАРЯЧОМУ» РЕЖИМІ> нижче.

=head2 МОНТУВАННЯ

Перш ніж ви зможете читати або записувати файли, створювати каталоги та
виконувати інші дії на образі диска, який містить файлові системи, вам слід
змонтувати ці файлові системи за допомогою L</guestfs_mount> або
L</guestfs_mount_ro>. Якщо ви вже знаєте, що на образі диска (наприклад)
міститься один розділ із файловою системою, ви можете змонтувати її
безпосередньо:

 guestfs_mount (g, "/dev/sda1", "/");

де F</dev/sda1> означає буквально «перший розділ (C<1>) першого образу
диска, який було додано (F</dev/sda>)».
 Якщо на диску містяться логічні томи LVM2 Linux, ви можете посилатися на
них (наприклад, F</dev/VG/LV>). Зауважте, що вказані пристрої є віртуальними
пристроями libguestfs, які не мають нічого спільного із пристроями основної
системи.

Якщо у вас є образ диска, і ви не знаєте, що саме на ньому міститься, вам
доведеться спочатку все це з'ясувати. Libguestfs теж може це робити:
скористайтеся L</guestfs_list_partitions> або L</guestfs_lvs> для отримання
списку можливих розділів і логічних томів, а потім або спробуйте змонтувати
кожен з них, щоб визначити, які з них придатні до монтування, або у якийсь
інший спосіб вивчіть їх за допомогою L</guestfs_vfs_type> або
L</guestfs_file>. Щоб просто отримати список файлових систем, скористайтеся
L</guestfs_list_filesystems>.

Крім того, у libguestfs передбачено набір програмних інтерфейсів для
інспектування невідомих образів дисків (див. L</ІНСПЕКТУВАННЯ> нижче). Ви
також можете скористатися високорівневими програмами, побудованими на основі
libguestfs, зокрема L<virt-inspector(1)>.

Щоб змонтувати файлову систему у режимі лише читання, скористайтеся
L</guestfs_mount_ro>. Передбачено декілька інших варіантів викликів
C<guestfs_mount_*>.

=head2 ДОСТУП ТА ВНЕСЕННЯ ЗМІН ДО ФАЙЛОВИХ СИСТЕМ

Більша частина програмного інтерфейсу libguestfs складається із
низькорівневих викликів для доступу до файлів та внесення змін до файлів,
каталогів, символічних посилань тощо на змонтованих файлових
системах. Передбачено понад сотню таких викликів, список яких із докладним
описом наведено нижче на цій сторінці підручника. Ми навіть не
намагатимемося повністю описати їх у цьому короткому огляді.

Вказуйте адреси і назви файлів повністю, починаючи з C<"/">, разом з точкою
монтування.

Наприклад, якщо вами змонтовано файлову систему до C<"/">, і ви бажаєте
виконати читання файла з назвою C<"etc/passwd">, ви можете скористатися
таким кодом:

 char *data = guestfs_cat (g, "/etc/passwd");

Ця функція повертає дані C<data> як новорозміщений буфер, що містить усі
дані з файла (із певними умовами; див. також L</ОТРИМАННЯ> нижче) або
C<NULL>, якщо сталася помилка.

Ще один приклад: для створення каталогу верхнього рівня із назвою C<"var">
на цій файловій системі можна скористатися такою командою:

 guestfs_mkdir (g, "/var");

Щоб створити символічне посилання, ви можете скористатися таким кодом:

 guestfs_ln_s (g, "/etc/init.d/portmap",
               "/etc/rc3.d/S30portmap");

Libguestfs відкидатиме спроби скористатися відносними шляхами. Крім того, не
передбачено поняття поточного робочого каталогу.

Libguestfs може повертати помилки у багатьох випадках: наприклад, якщо
файлова система не придатна до запису або якщо потрібного вам файла або
каталогу не існує. Якщо ви користуєтеся програмним інтерфейсом C
(документовано тут), вам слід перевіряти умову наявності помилки після
кожного виклику. (У інших прив'язках до мов програмування ці помилки
перетворюються на виключення.)

Запис до файлів визначається окремою для кожного дескриптора umask, як
встановлюється викликом L</guestfs_umask> і має типове значення
022. Див. L</UMASK>.

Починаючи з версії libguestfs 1.18, можна монтувати файлову систему
libguestfs до локального каталогу із деякими обмеженнями. Див. L</ЛОКАЛЬНЕ
МОНТУВАННЯ> нижче.

=head2 ПОДІЛ НА РОЗДІЛИ

У libguestfs передбачено виклики програмного інтерфейсу для читання,
створення та внесення змін до таблиць розділів на образах дисків.

У типовому випадку, коли вам потрібно створити єдиний розділ на увесь диск,
вам слід скористатися викликом L</guestfs_part_disk>:

 const char *parttype = "mbr";
 if (disk_is_larger_than_2TB)
   parttype = "gpt";
 guestfs_part_disk (g, "/dev/sda", parttype);

Очевидно, цей виклик призведе до витирання усіх даних, які раніше
зберігалися на цьому образі диска.

=head2 LVM2

Libguestfs надає доступ до великої частини програмного інтерфейсу LVM2,
зокрема L</guestfs_lvcreate> і L</guestfs_vgremove>. Але цей доступ не
матиме великого сенсу, якщо ви не ознайомитеся докладно із поняттями
фізичних томів, груп томів та логічних томів.

Автор цього підручника наполегливо рекомендує ознайомитися із настановами
щодо LVM HOWTO, які наведено у інтернеті:
L<http://tldp.org/HOWTO/LVM-HOWTO/>.

=head2 ОТРИМАННЯ ДАНИХ

Для отримання невеличких текстових файлів скористайтеся L</guestfs_cat>. Цей
виклик не може обробляти файли, які містять символи ASCII NUL (C<\0>). Втім,
програмний інтерфейс цього виклику є дуже простим у використанні.

L</guestfs_read_file> можна скористатися для читання файлів, які містять
довільні 8-бітові дані, оскільки цей виклик повертає пару (вказівник,
розмір).

L</guestfs_download> можна скористатися для отримання будь-якого файла без
обмежень на вміст або розмір.

Для отримання одразу декількох файлів скористайтеся L</guestfs_tar_out> і
L</guestfs_tgz_out>.

=head2 ВИВАНТАЖЕННЯ

Для запису невеличкого файла із фіксованим вмістом скористайтеся
L</guestfs_write>. Для створення файла, який заповнено нулями, скористайтеся
L</guestfs_truncate_size> (розріджений файл) або L</guestfs_fallocate64>
(файл, для якого розподілено усі блоки на диску). Передбачено багато інших
функцій для створення тестових файлів, наприклад L</guestfs_fill> і
L</guestfs_fill_pattern>.

Для вивантаження окремого файла скористайтеся L</guestfs_upload>. У цього
виклику немає обмежень на вміст і розмір файла.

Для вивантаження одразу декількох файлів скористайтеся L</guestfs_tar_in> і
L</guestfs_tgz_in>.

Втім, найшвидшим способом вивантаження I<великої кількості довільних файлів>
є перетворення їх на squashfs або ISO компакт-диска (див. L<mksquashfs(8)> і
L<mkisofs(8)>) і долучення до системи за допомогою
L</guestfs_add_drive_ro>. Якщо ви додасте диск у передбачуваний спосіб
(наприклад, додасте його після усіх інших дисків), назву пристрою можна буде
отримати з L</guestfs_list_devices>, а диск можна буде безпосередньо
змонтувати за допомогою L</guestfs_mount_ro>. Зауважте, що для образів
squashfs іноді порушується сумісність із ядрами системи, у них не
передбачено підтримки міток та UUID. Якщо ви хочете попередньо зібрати образ
або хочете змонтувати його із міткою або UUID, вам слід скористатися
форматом образу ISO.

=head2 КОПІЮВАННЯ

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

=over 4

=item B<файл> у B<файл>

Скористайтеся L</guestfs_cp> для копіювання окремого файла або
L</guestfs_cp_a> для рекурсивного копіювання каталогів.

Для копіювання частини файла (з визначенням відступу та розміру даних)
скористайтеся L</guestfs_copy_file_to_file>.

=item B<файл> на B<пристрій>

=item B<пристрій> до B<файла>

=item B<пристрій> на B<пристрій>

Скористайтеся L</guestfs_copy_file_to_device>,
L</guestfs_copy_device_to_file> або L</guestfs_copy_device_to_device>.

Приклад: дублювання вмісту логічного тому:

 guestfs_copy_device_to_device (g,
         "/dev/VG/Original", "/dev/VG/Copy",
         /* -1 позначає завершення списку необов'язкових параметрів */
         -1);

Призначення (F</dev/VG/Copy>) має бути не меншого розміру за джерело
(F</dev/VG/Original>). Для копіювання обсягу даних, який є меншим за увесь
пристрій джерела, скористайтеся додатковим параметром C<size>:

 guestfs_copy_device_to_device (g,
         "/dev/VG/Original", "/dev/VG/Copy",
         GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
         -1);

=item B<файл на вузлі> на B<файл або пристрій>

Скористайтеся L</guestfs_upload>. Див. L</ВИВАНТАЖЕННЯ> вище.

=item B<файл або пристрій> у B<файл на вузлі>

Скористайтеся L</guestfs_download>. Див. L</ОТРИМАННЯ> вище.

=back

=head2 ВИВАНТАЖЕННЯ І ОТРИМАННЯ ДАНИХ З КАНАЛІВ ТА ДЕСКРИПТОРІВ ФАЙЛІВ

Виклики, подібні до L</guestfs_upload>, L</guestfs_download>,
L</guestfs_tar_in>, L</guestfs_tar_out> тощо, як може здатися, приймають як
аргументи лише назви файлів, тому, як може здатися, ви можете вивантажувати
дані лише до файлів і отримувати дані лише з файлів. Втім, у багатьох
Un*x-подібних основних системах можна використовувати спеціальні файли
пристроїв F</dev/stdin>, F</dev/stdout>, F</dev/stderr> і F</dev/fd/N> для
читання і записування даних з stdin, stdout, stderr та файла з довільним
дескриптором N.

Наприклад, L<virt-cat(1)> можна змусити записувати виведені дані до stdout у
такий спосіб:

 guestfs_download (g, filename, "/dev/stdout");

а виведений архів tar можна записати до файла із вказаним дескриптором C<fd>
ось так:

 char devfd[64];
 snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
 guestfs_tar_out (g, "/", devfd);

=head2 СПИСКИ ФАЙЛІВ

L</guestfs_ll> призначено лише для створення зручних для читання даних (в
основному, якщо використано еквівалент C<ll> у L<guestfish(1)>).

L</guestfs_ls> — швидкий спосіб отримати список файлів у каталозі від
програм у форматі простого списку рядків.

L</guestfs_readdir> — програмний спосіб отримання списку файлів у каталозі
разом із додатковою інформацією щодо кожного з файлів. Це дуже схоже на
використання виклику L<readdir(3)> у локальних файлових системах.

L</guestfs_find> і L</guestfs_find0> можна скористатися для рекурсивної
побудови списку файлів.

=head2 ВИКОНАННЯ КОМАНД

Хоча програмний інтерфейс libguestfs в основному призначено для керування
файлами всередині образів гостьових операційних систем, у ньому передбачено
і обмежені можливості для запуску команд у гостьових операційних системах.

Існує багато обмежень щодо цього:

=over 4

=item *

Версія ядра системи відрізнятиметься від тієї, на яку може покладатися код
програми.

=item *

Якщо програмі потрібно буде обмінятися даними із фоновими службами,
найімовірніше, ці фонові служби не працюватимуть.

=item *

Програму буде запущено з обмеженим обсягом доступної пам'яті.

=item *

Мережа буде недоступною, якщо ви її не увімкнете
(див. L</guestfs_set_network>).

=item *

Передбачено підтримку лише гостьових систем Linux (не Windows, BSD тощо).

=item *

Обмеження щодо архітектури (наприклад, не працює для гостьової системи PPC
на основній системі X86).

=item *

У гостьових системах із SELinux може виникнути потреба у повторному
створенні міток після створення файлів. Див.  розділ L</SELINUX> нижче.

=item *

I<Безпека:> запускати програми із гостьових систем із невідомим походженням,
гостьових систем, які може бути створено зловмисниками, небезпечно. Програми
з таких систем можуть намагатися скористатися вразливостями у вашій
програмі, надсилаючи їй спеціально сформовані дані. Також ці програми можуть
намагатися скористатися вразливостями у ядрі Linux або qemu, які надаються
базовою системою libguestfs. Програми можуть скористатися доступом до
мережі, який надається базовою системою libguestfs для виходу за межі
звичайних мережевих розділів та брандмауерів. Програми можуть намагатися
розширити права доступу або змінити контекст SELinux вашої програми для
виконання задумів зловмисників.

Безпечною альтернативою є використання libguestfs для встановлення скрипту
«firstboot» (скрипту, який запускається, коли гостьова система
завантажується у звичайному режимі) таким чином, що цей скрипт запускав
потрібні вам команди, у звичайному контексті запущеної гостьової системи, зі
звичайним захистом мережі тощо. Щоб дізнатися більше про проблеми, пов'язані
із захистом, ознайомтеся зі сторінкою підручника щодо
L<guestfs-security(1)>.

=back

Двома основними програмними інтерфейсами для запуску програм є
L</guestfs_command> і L</guestfs_sh> (передбачено також певні варіанти цих
інтерфейсів).

Відмінність двох інтерфейсів полягає у тому, що L</guestfs_sh> виконує
команди за допомогою командної оболонки, отже, працюють усі
символи-замінники, переспрямовування тощо.

=head2 ФАЙЛИ НАЛАШТУВАННЯ

Для читання і запису файлів налаштувань у файлових системах гостьових
операційних систем Linux ми наполегливо рекомендуємо скористатися
Augeas. Наприклад, Augeas знає, як читати і записувати, скажімо, файл
паролів Linux shadow або файл налаштувань X.org, отже, вам не доведеться
писати для цього додатковий код.

Основні виклики Augeas виконуються за допомогою програмних інтерфейсів
C<guestfs_aug_*>. Тут ми не наводимо документації щодо самої Augeas,
оскільки існує чудова документація, викладена на сайті
L<http://augeas.net/>.

Якщо ви не хочете користуватися Augeas (ну який же ви неслухняний!),
спробуйте викликати L</guestfs_read_lines> для отримання файла у форматі
списку рядків, які ви ітеративно зможете обробити у коді програми.

=head2 ФАЙЛИ ЖУРНАЛУ SYSTEMD

Для читання журналу systemd з гостьової системи Linux скористайтеся
програмними інтерфейсами C<guestfs_journal_*>, починаючи з
L</guestfs_journal_open>.

Із документацією щодо журналу можна ознайомитися за допомогою таких сторінок
підручника: L<sd-journal(3)>, L<sd_journal_open(3)>.

=head2 SELINUX

Ми передбачили підтримку гостьових систем із SELinux. Втім, неможливо
завантажити правила SELinux гостьової системи до ядра базової системи. Тому
стратегія роботи з гостьовими системами із SELinux є повторне встановлення у
них міток після внесення змін.

У libguestfs E<ge> 1.34 передбачено новий програмний інтерфейс,
L</guestfs_setfiles>, яким можна скористатися для виконання цього
завдання. Щоб належним чином скористатися цим програмним інтерфейсом, вам
слід обробити налаштування SELinux гостьової системи. Див. модульe
L<virt-customize(1)> F<customize/SELinux_relabel.ml>, щоб дізнатися більше
про це.

Простішою, але повільнішою альтернативою є виконання touch F</.autorelabel>
у гостьовій системі, що означатиме, що гостьовій системі доведеться повторно
встановити усі мітки під час наступного завантаження.

У libguestfs E<le> 1.32 було передбачено програмні інтерфейси
C<guestfs_set_selinux>, C<guestfs_get_selinux>, C<guestfs_setcon> and
C<guestfs_getcon>. Ці програмні інтерфейси не працювали як слід, вони
вважаються застарілими. Не використовуйте їх у новому коді.

=head2 UMASK

На деякі виклики впливає маска режиму створення поточного файла
(«umask»). Це, зокрема, виклики, які створюють файли або каталоги, наприклад
L</guestfs_touch>, L</guestfs_mknod> і L</guestfs_mkdir>. Маска впливає або
на типовий режим створення файла, або змінює режим доступу, який ви
встановлюєте.

Типовим значенням umask є C<022>. Отже, файли створюватимуться із правами
доступу, які подібні до C<0644>, а каталоги — C<0755>.

Існує два способи уникнути впливу umask. Можна або встановити для umask
значення 0 (викликати C<guestfs_umask (g, 0)> одразу після запуску), або
викликати L</guestfs_chmod> після створення кожного файла або каталогу.

Докладніший опис umask можна знайти на сторінці підручника щодо L<umask(2)>.

=head2 МІТКИ І UUID

У багатьох файлових системах, на пристроях або логічних томах передбачено
підтримку міток (коротких рядків, подібних до «BOOT», які можуть
повторюватися) і/або UUID (унікальних на загальному рівні ідентифікаторів).

Для файлових систем користуйтеся L</guestfs_vfs_label> або
L</guestfs_vfs_uuid> для читання мітки або UUID. У деяких файлових системах
можна викликати L</guestfs_set_label> або L</guestfs_set_uuid> для зміни
мітки або UUID.

Ви можете знайти файлову систему за міткою або UUID за допомогою виклику
L</guestfs_findfs_label> або L</guestfs_findfs_uuid>.

Для LVM2 (де передбачено підтримку лише UUID) передбачено широкий спектр
інструментів програмного інтерфейсу для отримання UUID, отримання UUID
об'єктів контейнерів і зміни UUID. Див. L</guestfs_lvuuid>,
L</guestfs_vguuid>, L</guestfs_pvuuid>, L</guestfs_vglvuuids>,
L</guestfs_vgpvuuids>, L</guestfs_vgchange_uuid>,
L</guestfs_vgchange_uuid_all>, L</guestfs_pvchange_uuid>,
L</guestfs_pvchange_uuid_all>.

Зауважте, що при клонуванні файлової системи, пристрою або усієї гостьової
операційної системи варто встановити нові випадково створені UUID для копії.

=head2 ЗАШИФРОВАНІ ДИСКИ

Libguestfs allows you to access Linux guests which have been encrypted using
whole disk encryption that conforms to the Linux Unified Key Setup (LUKS)
standard.  This includes nearly all whole disk encryption systems used by
modern Linux guests.  Windows BitLocker is also supported.

Use L</guestfs_vfs_type> to identify encrypted block devices.  For LUKS it
returns the string C<crypto_LUKS>.  For Windows BitLocker it returns
C<BitLocker>.

Then open these devices by calling L</guestfs_cryptsetup_open>.  Obviously
you will require the passphrase!

Opening an encrypted device creates a new device mapper device called
F</dev/mapper/mapname> (where C<mapname> is the string you supply to
L</guestfs_cryptsetup_open>).  Reads and writes to this mapper device are
decrypted from and encrypted to the underlying block device respectively.

Групи томів LVM на пристрої можна зробити видимими викликом
L</guestfs_vgscan>, за яким слід викликати
L</guestfs_vg_activate_all>. Після цього логічні томи можна змонтувати у
звичний спосіб.

Use the reverse process to close an encrypted device.  Unmount any logical
volumes on it, deactivate the volume groups by calling C<guestfs_vg_activate
(g, 0, ["/dev/VG"])>.  Then close the mapper device by calling
L</guestfs_cryptsetup_close> on the F</dev/mapper/mapname> device (I<not>
the underlying encrypted block device).

=head2 ЛОКАЛЬНЕ МОНТУВАННЯ

Починаючи з версії libguestfs 1.18, можна монтувати файлову систему
libguestfs до локального каталогу і отримувати доступ до неї за допомогою
звичайних викликів і програм POSIX.

Доступність цього може бути обмежено декількома факторами: у системі має
бути встановлено FUSE (Filesystem in USErspace), а заголовкові файли libfuse
мають бути доступними під час збирання libguestfs. FUSE може потребувати
завантаження модуля ядра. Крім того, можливо, потрібно додати поточного
користувача до спеціальної групи C<fuse>. Докладніші відомості можна знайти
у документації до вашого дистрибутива та на L<http://fuse.sf.net>.

Виклик монтування файлової системи libguestfs до локального каталогу є
послідовним викликом L</guestfs_mount_local> з наступним
L</guestfs_mount_local_run>. Другий з цих викликів не повертає керування, аж
доки ви не демонтуєте файлову систему. Причиною цього є те, що виклик
входить до основного циклу обробки FUSE і обробляє запити ядра, перетворюючи
їх на виклики libguestfs. Альтернативний підхід міг би полягати у створенні
фонового потоку обробки для виконання цього завдання, але у libguestfs
pthreads не є обов'язковою залежністю. Крім того, наш підхід є гнучкішим:
наприклад, користувач може створити ще один потік обробки для
L</guestfs_mount_local_run>.

L</guestfs_mount_local> потребує певного часу на налаштовування точки
монтування. Точка монтування лишатиметься недоступною, доки цей виклик не
поверне керування. До цього моменту спроби доступу до файлової системи
блокуватиметься, аж доки не буде здійснено вхід до основного циклу обробки
(тобто передано керування до L</guestfs_mount_local_run>). Отже, якщо вам
потрібно запустити процес для доступу до файлової системи, додайте
розгалуження між L</guestfs_mount_local> і L</guestfs_mount_local_run>.

=head3 СУМІСНІСТЬ ЛОКАЛЬНОГО МОНТУВАННЯ

Оскільки можливість локального монтування було додано лише після версії
libguestfs 1.18, і ця можливість може бути недоступною навіть у пізніших
версіях через особливості збирання, код варто писати так, щоб у ньому не
було жорсткої залежності від цієї можливості і щоб було передбачено резервну
можливість повернутися до використання викликів, пов'язаних із файловою
системою у libguestfs.

Якщо libguestfs було зібрано без підтримки L</guestfs_mount_local>, виклик
цієї функції призводитиме до помилки із errno, встановленим у значення
C<ENOTSUP> (див. L</guestfs_last_errno>).

=head3 ШВИДКОДІЯ ПРИ ЛОКАЛЬНОМУ МОНТУВАННІ

Обгортка libguestfs навколо FUSE має доволі низький рівень швидкодії. Якщо
вам потрібен найшвидший доступ, не використовуйте її. Замість неї
користуйтеся звичайними викликами libguestfs, пов'язаними з обробкою
файлових систем: вивантаженням і отриманням даних тощо.

=head2 З'ЄДНАННЯ У «ГАРЯЧОМУ» РЕЖИМІ

У libguestfs E<ge> 1.20 ви можете додавати і вилучати диски після виклику
L</guestfs_launch>. Втім, є декілька обмежень, опис яких наведено
нижче. Таку можливість будемо називати I<з'єднанням у «гарячому» режимі>.

Підтримку з'єднання у «гарячому» режимі передбачено лише у деяких модулях
обробки даних (у поточній версії таку підтримку передбачено лише у модулі
libvirt). Крім того, потрібні версії libvirt E<ge> 0.10.3 та qemu E<ge> 1.2.

Для додавання диска у «гарячому» режимі просто скористайтеся викликом
L</guestfs_add_drive_opts> після L</guestfs_launch>. Має бути обов'язково
вказано параметр C<label>, щоб новий доданий диск мав передбачувану
назву. Приклад:

 if (guestfs_launch (g) == -1)
   error ("launch failed");
 
 if (guestfs_add_drive_opts (g, filename,
                             GUESTFS_ADD_DRIVE_OPTS_LABEL, "newdisk",
                             -1) == -1)
   error ("hot-add of disk failed");
 
 if (guestfs_part_disk ("/dev/disk/guestfs/newdisk", "mbr") == -1)
   error ("partitioning of hot-added disk failed");

Для вилучення диска у «гарячому» режимі скористайтеся викликом
L</guestfs_remove_drive>. Цей виклик можна використовувати до або після
L</guestfs_launch>. Вилучати диски у такий спосіб можна, лише якщо їх раніше
було додано із міткою.

У модулях обробки, де передбачено підтримку з'єднання у «гарячому» режимі не
обов'язково додавати один або більше дисків до виклику launch. Якщо
передбачено підтримку з'єднання у «гарячому» режимі, ви можете взагалі не
додавати жодних дисків.

=head2 ВІДДАЛЕНЕ СХОВИЩЕ ДАНИХ

=head3 CEPH

Libguestfs може отримувати доступ до дисків Ceph (librbd/RBD).

Для цього встановіть необов'язкові параметри C<protocol> і C<server> у
виклику L</guestfs_add_drive_opts>, ось так:

 char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
 guestfs_add_drive_opts (g, "pool/image",
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
                         GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
                         GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
                         GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
                         -1);

C<servers> (параметр C<server>) — список з одного або декількох серверів
Ceph. Документацію щодо рядка server наведено у описі
L</guestfs_add_drive_opts>. Параметри C<username> та C<secret> є
необов'язковими. Якщо їх не вказано, розпізнавання не виконуватиметься.

=head3 FTP, HTTP ТА TFTP

Libguestfs може отримувати доступ до віддалених дисків за допомогою
протоколів FTP, FTPS, HTTP, HTTPS та TFTP.

Для цього встановіть необов'язкові параметри C<protocol> і C<server> у
виклику L</guestfs_add_drive_opts>, ось так:

 char **servers = { "www.example.org", NULL };
 guestfs_add_drive_opts (g, "/disk.img",
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "http",
                         GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
                         -1);

Значенням параметра C<protocol> може бути один з таких рядків: C<"ftp">,
C<"ftps">, C<"http">, C<"https"> або C<"tftp">.

C<servers> (параметр C<server>) — список, який має складатися з одного
запису. Цей єдиний запис є рядком, який визначає вебсервер або сервер FTP чи
TFTP. Документацію щодо рядка server наведено у описі
L</guestfs_add_drive_opts>.

=head3 GLUSTER

Libguestfs може отримувати доступ до дисків Gluster.

Для цього встановіть необов'язкові параметри C<protocol> і C<server> у
виклику L</guestfs_add_drive_opts>, ось так:

 char **servers = { "gluster.example.org:24007", NULL };
 guestfs_add_drive_opts (g, "volname/image",
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "gluster",
                         GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
                         -1);

C<servers> (параметр C<server>) — список, який має складатися з одного
запису. Цей єдиний запис є рядком, який визначає сервер
Gluster. Документацію щодо рядка server наведено у описі
L</guestfs_add_drive_opts>.

Зауважте, що, зазвичай, gluster потребує запуску клієнтського процесу (тобто
libguestfs) від імені користувача B<root> і повідомляє про незрозумілі
помилки, якщо процес запущено від звичайного користувача (наприклад, «No
data available» або «Дані недоступні»).

=head3 ISCSI

Libguestfs може отримувати віддалений доступ до дисків iSCSI.

Для цього встановіть необов'язкові параметри C<protocol> і C<server> у
виклику ось так:

 char **server = { "iscsi.example.org:3000", NULL };
 guestfs_add_drive_opts (g, "target-iqn-name/lun",
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "iscsi",
                         GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
                         -1);

C<servers> (параметр C<server>) — список, який має складатися з одного
запису. Цей єдиний запис є рядком, який визначає сервер iSCSI. Документацію
щодо рядка server наведено у описі L</guestfs_add_drive_opts>.

=head3 NETWORK BLOCK DEVICE

Libguestfs може отримувати віддалений доступ до дисків Network Block Device
(NBD).

Для цього встановіть необов'язкові параметри C<protocol> і C<server> у
виклику L</guestfs_add_drive_opts>, ось так:

 char **server = { "nbd.example.org:3000", NULL };
 guestfs_add_drive_opts (g, "" /* export name - see below */,
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
                         GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
                         -1);

Нотатки:

=over 4

=item *

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

=item *

Документацію щодо рядка C<сервер> можна знайти у розділі
L</guestfs_add_drive_opts>. Що встановити з'єднання із локальним екземпляром
qemu-nbd за допомогою сокета домену UNIX, скористайтеся записом
C<"unix:/шлях/до/сокета">.

=item *

Значенням параметра C<filename> має бути назва експортування NBD.
Скористайтеся порожнім рядком, якщо слід використовувати типове
експортування. У багатьох реалізаціях серверів NBD, зокрема qemu-nbd, не
передбачено підтримки назв експортування.

=item *

Якщо ви використовуєте як сервер qemu-nbd, вам слід завжди передавати
параметр C<-t>. Причина полягає у тому, що libguestfs може відкривати одразу
декілька з'єднань із сервером.

=item *

При користуванні модулем обробки libvirt обов'язково слід точно вказати
параметр C<format> L</guestfs_add_drive_opts>, якщо ви використовуєте
придатні до запису диски NBD.

=item *

У модулі обробки libvirt є вада, яка заважає з'єднанням із сокетом домену
UNIX працювати: L<https://bugzilla.redhat.com/show_bug.cgi?id=922888>

=item *

У модулі безпосередньої обробки не передбачено підтримки з'єднань лише для
читання даних через ваду у qemu:
L<https://bugs.launchpad.net/qemu/+bug/1155677>

=back

=head3 SHEEPDOG

Libguestfs може отримувати доступ до дисків Sheepdog.

Для цього встановіть необов'язкові параметри C<protocol> і C<server> у
виклику L</guestfs_add_drive_opts>, ось так:

 char **servers = { /* optional servers ... */ NULL };
 guestfs_add_drive_opts (g, "volume",
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "sheepdog",
                         GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
                         -1);

Необов'язковий список C<servers> має складатися із нуля або якоїсь кількості
адрес серверів (C<"назва_вузла:порт">). Формат рядків server описано у
документації з L</guestfs_add_drive_opts>.

=head3 SSH

Libguestfs може отримувати доступ до дисків за допомогою з'єднань Secure
Shell (SSH).

Для цього встановіть необов'язкові параметри C<protocol>, C<server> та
(необов'язково) C<username> у виклику L</guestfs_add_drive_opts>, ось так:

 char **server = { "remote.example.com", NULL };
 guestfs_add_drive_opts (g, "/path/to/disk.img",
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                         GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "ssh",
                         GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
                         GUESTFS_ADD_DRIVE_OPTS_USERNAME, "remoteuser",
                         -1);

Формат рядка сервера документовано у розділі щодо
L</guestfs_add_drive_opts>.

=head2 ПЕРЕВІРКА

У libguestfs передбачено програмні інтерфейси для інспектування невідомих
образів дисків для визначення, чи міститься у образі операційна система,
дані для встановлення з компакт-диска або портативна система.

Додайте усі диски, що належать до невідомої віртуальної машини і викличте
L</guestfs_launch> у звичний спосіб.

Далі, викличте L</guestfs_inspect_os>. Ця функція використовує інші виклики
libguestfs та певну евристику і повертає список знайдених операційних
систем. Якщо список виявиться порожнім, значить операційних систем не
знайдено. Окремий запис списку визначатиме кореневу файлову систему
операційної системи. Для гостьових операційних систем із варіантами
завантаження може бути повернуто декілька кореневих записів, кожен з яких
відповідає окремій операційній системі. (Віртуальні машини із варіантами
завантаження є дуже рідкісними у світі віртуалізації, але оскільки такий
сценарій можливий, нам довелося реалізувати його у libguestfs.)

Для кожної кореневої файлової системи ви можете скористатися різноманітними
функціями C<guestfs_inspect_get_*> для отримання додаткових відомостей щодо
операційної системи. Наприклад, викличте L</guestfs_inspect_get_type>, щоб
отримати рядок C<windows> або C<linux> для Windows та заснованих на Linux
операційних системах, відповідно.

Un*x-подібні та засновані на Linux операційні системи зазвичай складаються з
декількох файлових систем, які монтуються під час завантаження (наприклад,
окремого розділу для завантаження, який змонтовано до F</boot>). Правила
інспектування уможливлюють визначення, як саме файлові системи пов'язано із
точками монтування. Викличте C<guestfs_inspect_get_mountpoints>, щоб
отримати дані щодо цієї прив'язки. У відповідь може бути повернуто
хеш-таблицю, подібну до такої:

 /boot => /dev/sda1
 /     => /dev/vg_guest/lv_root
 /usr  => /dev/vg_guest/lv_usr

Далі, можна викликати L</guestfs_mount> для відповідного монтування файлових
систем.

Файлові системи слід монтувати у належному порядку (наприклад, F</> має бути
змонтовано перед F</usr>). Для визначення порядку можна упорядкувати
хеш-записи за довжиною так, щоб першими у списку були найкоротші.

Засіб інспектування у поточній версії може працювати лише з декількома
поширеними операційними системами. Будемо раді вашим латкам, які
реалізуватимуть підтримку інших операційних систем, які ще не може бути
визначено програмно.

Шифровані диски слід відкривати до інспектування. Докладніше про це можна
дізнатися з розділу L</ЗАШИФРОВАНІ ДИСКИ>. Функція L</guestfs_inspect_os>
просто ігноруватиме усі знайдені зашифровані пристрої.

Зауваження щодо реалізації: виклик L</guestfs_inspect_os> виконує
інспектування та кешує результати у дескрипторі гостьової системи. Наступні
виклики C<guestfs_inspect_get_*> повертатимуть кешовані відомості, але I<не
виконуватимуть> повторного читання дисків. Якщо ви зміните вміст дисків
гостьової системи, ви можете змусити програму повторно виконати
інспектування, викликавши L</guestfs_inspect_os> ще
раз. (L</guestfs_inspect_list_applications2> працює дещо інакше, якщо
порівнювати з іншими викликами, і виконує читання дисків. Див. документацію
з цієї функції, щоб дізнатися більше).

=head3 ВИВЧЕННЯ ДИСКІВ ДЛЯ ВСТАНОВЛЕННЯ

Libguestfs (з версії 1.9.4) може виявляти деякі диски для встановлення,
компакт-диски для встановлення, компакт-диски із портативними системами
тощо.

Докладну інформацію щодо операційних систем на дисках для встановлення можна
отримати за допомогою звичайних програмних інтерфейсів вивчення, зокрема
L</guestfs_inspect_get_product_name>, L</guestfs_inspect_get_major_version>
тощо.

=head2 ДОДАТКОВІ ЗАУВАЖЕННЯ ЩОДО ГОСТЬОВИХ СИСТЕМ WINDOWS

Libguestfs може монтувати розділи NTFS. Це завдання виконується за допомогою
драйвера L<http://www.ntfs-3g.org/>.

=head3 ЛІТЕРИ ДИСКІВ ТА ШЛЯХИ

У DOS та Windows для позначення дисків усе ще використовуються літери, а
назви у файлових системах самою Windows обробляються як незалежні від
регістру символів, тому можлива ситуація, коли файл налаштувань Windows
посилається на каталог із назвою подібною до C<c:\windows\system32>. Коли ж
файлову систему змонтовано у libguestfs, той самий каталог може мати назву
F</WINDOWS/System32>.

Визначити прив'язку дисків до літер можна за допомогою засобу інспектування
(див. L</ІНСПЕКТУВАННЯ> та L</guestfs_inspect_get_drive_mappings>)

Обробка символів-роздільників у шляхах (символів зворотної чи прямої похилої
риски) не виконується самою libguestfs, але, зазвичай, для цього можна
просто скористатися автоматичною заміною символів на відповідні.

Щоб усунути проблему із неврахуванням регістру літер у шляхах, скористайтеся
викликом L</guestfs_case_sensitive_path>.

=head3 ДОВГІ НАЗВИ ФАЙЛІВ У NTFS

У NTFS назви файлів обмежено довжиною у 255 символів. «Символ» означає
2-байтову позицію у таблиці UTF-16, яка містить більшість типових символів
Unicode.

У більшості файлових систем Linux передбачено підтримку назв файлів довжиною
до 255 I<байтів>. Це означає, що ви можете отримати повідомлення про
помилку:

 File name too long

коли копіюватимете файл з NTFS на файлову систему Linux, якщо назва, коли її
буде перекодовано у UTF-8, перевищить за довжиною 255 байтів.

Найчастіше таке трапляється, коли використовуються довші за ~127 символів
назви із символами, які не належать до ASCII, (наприклад, назви кирилицею
або грецькою) або використовуються довші за ~85 символів назви азійськими
мовами із ієрогліфічним записом.

Обійти проблему можна, намагаючись не зберігати файли із такими довгими
назвами у файлових системах Linux. Оскільки у форматі L<tar(1)> передбачено
можливість зберігання назв файлів без будь-яких обмежень, такі файли можна
зберігати у архівах tar.

=head3 ДОСТУП ДО РЕГІСТРУ WINDOWS

У libguestfs також передбачено допоміжні можливості із декодування файлів
реєстрів Windows, «hive», на основі окремої бібліотеки мовою C, яка
називається L<hivex(3)>.

До версії libguestfs 1.19.35 вам потрібно було отримати файл рою (hive),
обробити його локально за допомогою hivex і вивантажити його
назад. Починаючи з вказаної версії, нами було включено основні програмні
інтерфейси hivex безпосередньо до програмного інтерфейсу libguestfs
(див. L</guestfs_hivex_open>). Це означає, що якщо ви відкрили гостьову
систему Windows, ви можете читати і записувати реєстр безпосередньо.

Див. також L<virt-win-reg(1)>.

=head3 СИМВОЛІЧНІ ПОСИЛАННЯ У ФАЙЛОВИХ СИСТЕМАХ NTFS-3G

Ntfs-3g намагається переписати «точки з'єднання» та «символічні посилання»
NTFS для створення чогось схожого на символічне посилання Linux. Спосіб, у
який виконується переписування, описано тут:

L<http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/>

Основною проблемою є те, що ntfs-3g просто немає достатньо відомостей для
того, щоб виконати роботу правильно. Посилання NTFS можуть містити літери
дисків і посилання на GUID зовнішніх пристроїв, які не може бути оброблено у
ntfs-3g. У цьому випадку, майже завжди, функції, які викликають libguestfs,
мають ігнорувати дії ntfs-3g (тобто не використовувати L</guestfs_readlink>
на томах NTFS).

Замість цього, якщо у файловій системі ntfs-3g трапиться символічне
посилання, слід скористатися L</guestfs_lgetxattr> для читання розширеного
атрибута C<system.ntfs_reparse_data> і прочитати дані повторної обробки з
нього (формат документовано у багатьох місцях в інтернеті).

=head3 РОЗШИРЕНІ АТРИБУТИ НА ФАЙЛОВИХ СИСТЕМАХ NTFS-3G

Існують інші корисні атрибути, які можна читати з файлових систем ntfs-3g
(за допомогою L</guestfs_getxattr>). Див.:

L<http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>

=head3 ПРИСИПЛЯННЯ WINDOWS  ТА ШВИДКИЙ ЗАПУСК WINDOWS 8

Гостьові системи Windows, які було приспано (замість повного вимикання) не
можна монтувати. Це обмеження ntfs-3g. Ви побачите ось таке повідомлення про
помилку:

 The disk contains an unclean file system (0, 0).
 Metadata kept in Windows cache, refused to mount.
 Failed to mount '/dev/sda2': Operation not permitted
 The NTFS partition is in an unsafe state. Please resume
 and shutdown Windows fully (no hibernation or fast
 restarting), or mount the volume read-only with the
 'ro' mount option.

У Windows 8 кнопка вимикання не вимикає гостьову систему. Замість цього, ця
кнопка присипляє гостьову систему. Ця можливість відома як «швидкий запуск».

Ось пропоновані шляхи обійти проблему:

=over 4

=item *

Монтування у режимі лише читання (наприклад, L</guestfs_mount_ro>).

=item *

У Windows 8 вимкніть швидкий запуск. Відповідним пунктом є такий: Панель
керування → Живлення → Виберіть дію для кнопки живлення → Змінити параметри,
які зараз недоступні → Увімкнути швидкий запуск.

=item *

У Windows 7 та попередніх версіях вимкніть гостьову систему належним чином
замість присипляння системи.

=back

=head2 ПОМИЛКИ RESIZE2FS

Для зміни розмірів файлових систем ext2/3/4 використовуються виклики
L</guestfs_resize2fs>, L</guestfs_resize2fs_size> і L</guestfs_resize2fs_M>.

Базова програма (L<resize2fs(8)>) потребує, щоб файлова система не мала
прапорця змін і була нещодавно перевірена fsck, перш ніж ви зможете змінити
її розмір. Крім того, якщо дія зі зміни розміру завершується помилкою з
якоїсь причини, вам слід викликати fsck для файлової системи, щоб виправити
її.

У libguestfs C<lt> 1.17.14 вам, зазвичай, потрібно було викликати
L</guestfs_e2fsck_f> до зміни розміру. Втім, у C<ge> 1.17.14 L<e2fsck(8)>
викликається автоматично до зміни розміру, отже потреби у явному виклику вже
немає.

Робота програми L<resize2fs(8)> все ще може завершитися помилкою. У цьому
випадку програма виводить повідомлення про помилку, подібне до такого:

 Будь ласка, запустіть «e2fsck -fy <пристрій>», щоб виправити файлову систему
 після переривання дії зі зміни розмірів.

Ви можете зробити це, викликавши L</guestfs_e2fsck> з параметром
C<forceall>. Втім, у контексті образів дисків, зазвичай, краще уникати таких
ситуацій, наприклад, поверненням до попереднього знімка або копіюванням і
зміною розміру і поверненням до початкового стану, якщо станеться помилка.

=head2 ВИКОРИСТАННЯ LIBGUESTFS ЗА ДОПОМОГОЮ ІНШИХ МОВ ПРОГРАМУВАННЯ

Хоча у нас немає намірів забороняти вам використовувати програмний інтерфейс
C, тут ми будемо нагадувати, що той самий програмний інтерфейс також
доступний іншими мовами програмування.

Загалом, програмний інтерфейс усіма підтримуваними мовами є ідентичним. Це
означає, що виклик мовою C C<guestfs_add_drive_ro(g,file)> ідентичний до
C<$g-E<gt>add_drive_ro($file)> у Perl, C<g.add_drive_ro(file)> у Python, і
C<g#add_drive_ro file> в OCaml. Іншими словами, існує прямий, передбачуваний
ізоморфізм між усіма мовами.

Повідомлення про помилки буде автоматично перетворено на виключення, якщо
підтримку таких передбачено у відповідній мові програмування.

Ми не намагаємося виконати «об'єктне орієнтування» частин програмного
інтерфейсу у об'єктно орієнтованих мовах програмування, хоча ми будемо раді,
якщо учасники розробки, якщо це потрібно, зможуть написати високорівневі
програмні інтерфейси до вказаних вище програмних інтерфейсів, які ми
надаємо, їхніми улюбленими мовами програмування.

=over 4

=item B<C++>

Ви можете скористатися файлом заголовків I<guestfs.h> з програм
C++. Програмний інтерфейс C++ є ідентичним до програмного інтерфейсу
C. Класи і виключення C++ не використовуються.

=item B<C#>

Прив'язки до C# є досить експериментальними. Будь ласка, ознайомтеся із
попередженнями на початку файла F<csharp/Libguestfs.cs>.

=item B<Erlang>

Див. L<guestfs-erlang(3)>.

=item B<GObject>

Доступні експериментальні прив'язки GObject (з підтримкою інтроспекції
GObject).

Див. L<guestfs-gobject(3)>

=item B<Go>

Див. L<guestfs-golang(3)>

=item B<Haskell>

Ця прив’язка до мови працює, але є неповною:

=over 4

=item *

Функції із необов'язковими аргументами не включено до прив'язок. Реалізація
необов'язкових параметрів у Haskell, здається, є доволі складною справою.

=item *

Події не обмежено.

=item *

Не передбачено прив'язок для функцій із такими повернутими типами:

=over 4

=item *

Будь-яка функція повертає структуру.

=item *

Будь-яка функція повертає список структур.

=item *

Декілька функцій, які повертають буфери фіксованої довжини (зокрема ті, які
оголошено як C<RBufferOut> у генераторі).

=item *

Незначна кількість прихованих функцій, які повертають сталі рядки (зокрема
функцій, оголошених як C<RConstOptString> у генераторі).

=back

=back

=item B<Java>

Повна документація міститься у Javadoc, який поширюється разом із
libguestfs. Приклади наведено на сторінці L<guestfs-java(3)>.

=item B<Lua>

Див. L<guestfs-lua(3)>.

=item B<OCaml>

Див. L<guestfs-ocaml(3)>.

=item B<Perl>

Див. L<guestfs-perl(3)> та L<Sys::Guestfs(3)>.

=item B<PHP>

Документацію наведено у файлі C<README-PHP>, який постачається разом із
початковим кодом libguestfs або у пакунку php-libguestfs для вашого
дистрибутива.

Прив'язки до PHP працюють належним чином лише у 64-бітових операційних
системах.

=item B<Python>

Див. L<guestfs-python(3)>.

=item B<Ruby>

Див. L<guestfs-ruby(3)>.

Щоб скористатися JRuby, використовуйте прив'язки до Java.

=item B<скрипти оболонки>

Див. L<guestfish(1)>.

=back

=head2 ПРОБЛЕМНІ МІСЦЯ LIBGUESTFS

L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: «Можливість системи
[...], яка працює у документований спосіб, але не є інтуїтивно зрозумілою і
неначебто запрошує до помилок.»

З часу створення libguestfs та пов'язаних інструментів існує декілька речей,
які зараз ми б зробили інакше, але мусимо дотримуватися зворотної сумісності
або не можемо їх змінити з інших причин. Якщо колись відбудеться випуск
libguestfs 2.0, ми можемо змінити ці речі. Майте це на увазі.

=over 4

=item Типовим режимом має бути «лише читання».

У L<guestfish(3)> параметр I<--ro> має бути типовим. Вам слід вказувати
параметр I<--rw> явним чином, якщо ви хочете внести зміни до образу.

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

Зауважте, що до багатьох файлових систем зміни вносяться простим монтуванням
із наступним демонтуванням, навіть якщо до файлової системи нічого не
записується. Вам слід використовувати L</guestfs_add_drive_ro>, щоб
гарантувати, що диск не буде змінено.

=item Командним рядком guestfish важко користуватися.

Команда F<guestfish образ.диска> не виконує тих дій, на які сподіваються
користувачі (відкриття образу F<образ.диска> для вивчення). Ця команда
намагається виконати команду guestfish F<образ.диска>, якої не існує, отже,
виводиться повідомлення про помилку. У ранніх версіях guestfish це
повідомлення було незрозумілим, але з того часу його було
виправлено. Подібно до bash, варто було б використовувати команду
C<guestfish -c команда> для виконання команд.

=item Модифікатори вимірювання у мегабайтах guestfish не працюють як слід для усіх
команд

У свіжих версіях guestfish ви можете скористатися записом C<1M> на
позначення 1 мегабайта (та подібних одиниць виміру пам'яті). Насправді,
guestfish просто множить числову частину запису на частину модифікатора і
передає результат програмному інтерфейсу C. Втім, це не працює для декількох
програмних інтерфейсів, яким передаються не значення у байтах, а значення у
якихось інших одиницях (наприклад, у мегабайтах).

Найпоширенішим прикладом є L</guestfs_lvcreate>. Ось така команда guestfish:

 lvcreate LV VG 100M

не виконує тих дій, на які слід було б сподіватися. Замість цього, оскільки
L</guestfs_lvcreate> вже передаються розміри у мегабайтах, виконується
спроба створити логічний том у 100 I<терабайтів> (100 мегабайтів *
мегабайтів). Повідомлення про помилку, яке ви побачите у відповідь на цю
команду, теж дещо незрозуміле.

Цю ваду можна було б виправити у генераторі спеціальним позначенням
параметрів і поверненням значень у байтах чи інших одиницях.

=item Двозначність між пристроями і шляхами

У програмному інтерфейсі є певна неоднозначність між назвою пристрою
(наприклад F</dev/sdb2>) і подібною до неї назвою шляху. Файл у каталозі
F</dev> також можна викликати за допомогою C<sdb2> (якщо розглядати якийсь
образ віртуальної машини, відмінної від Unix).

У поточному програмному інтерфейсі ми, зазвичай, усуваємо цю неоднозначність
використанням двох окремих викликів, наприклад L</guestfs_checksum> і
L</guestfs_checksum_device>. Деякі з викликів програмного інтерфейсу є
неоднозначними і вирішують (неправильно) проблему, визначаючи, чи наданий
шлях починається з F</dev/>.

Щоб уникнути неоднозначностей та потреби у дублюванні викликів, можна
перетворити шляхи/пристрої на структуровані назви. Одним зі способів досягти
цього є використання позначень у стилі (C<hd(0,0)>), хоча мало кому
подобається цей аспект роботи grub. Іншим способом, яким можна було б
скористатися, є використання структурованого типу, еквівалентного до такого
типу OCaml:

 type path = Path of string | Device of int | Partition of int * int

що надало б вам змогу передавати аргументи ось так:

 Path "/foo/bar"
 Device 1            (* /dev/sdb або, можливо, /dev/sda *)
 Partition (1, 2)    (* /dev/sdb2 (або /dev/sda2, або /dev/sdb3?) *)
 Path "/dev/sdb2"    (* не є пристроєм *)

Як бачите, у визначенні шляхів є проблема навіть у такому
представленні. Також можете поміркувати над тим, як це може працювати у
guestfish.

=back

=head2 КЛЮЧІ І ПАРОЛІ

Деяким викликам libguestfs передаються параметри, які містять конфіденційні
дані ключів у форматі звичайного рядка C.

У майбутньому ми сподіваємося змінити реалізацію у libguestfs так, щоб ключі
оброблялися L<mlock(2)> у фізичній пам'яті системи і тому ніколи не
опинялися у файлі резервної пам'яті на диску. Втім, дотепер цього I<не>
зроблено через складність такої реалізації.

Тому вам слід мати на увазі, що будь-який параметр ключа, який ви передали
libguestfs, може бути записано на розділ резервної пам'яті. Якщо ви цим дуже
занепокоєні, витирайте файл резервної пам'яті або не використовуйте
libguestfs на зашифрованих пристроях.

=head2 ОБРОБКА У ДЕКІЛЬКА ДЕСКРПИТОРІВ І ПОТОКІВ

Усі операції високого рівня у libguestfs синхронізуються. Якщо ви хочете
використовувати libguestfs у асинхронний спосіб, вам слід створити потік
обробки.

=head3 Потоки у libguestfs E<ge> 1.38

У libguestfs E<ge> 1.38 кожен дескриптор (C<guestfs_h>) містить блокування,
яке встановлюється автоматично, коли ви викликаєте функцію
libguestfs. Практичним наслідком цього є те, що ви можете викликати функції
libguestfs для одного дескриптора з різних потоків обробки без потреби у
блокуванні.

Крім того, починаючи з версії libguestfs E<ge> 1.38, остання помилка у
обробці дескриптора (L</guestfs_last_error>, L</guestfs_last_errno>)
зберігається у локальному сховищі даних потоку, тому написання такого ось
коду є безпечним:

 if (guestfs_add_drive_ro (g, drive) == -1)
   fprintf (stderr, "error was: %s\n", guestfs_last_error (g));

навіть коли інші потоки обробки можуть конкурувати за використання одного
дескриптора C<g>.

=head3 Потоки у libguestfs E<lt> 1.38

У libguestfs E<lt> 1.38 вам слід використовувати дескриптор лише у одному
потоці обробки. Або використовуйте дескриптор виключно з одного потоку, або
впровадьте власний семафор так, щоб два потоки не могли видавати виклики для
одного дескриптора одночасно. Навіть доволі невинні функції, подібні до
L</guestfs_get_trace> I<не можна> безпечно викликати без семафора з
декількох потоків обробки одночасно, якщо ви користуєтеся libguestfs E<lt>
1.38.

Скористайтеся L</guestfs_set_identifier> для спрощення ідентифікації потоків
у даних, виведених засобом трасування.

=head2 ШЛЯХ

Libguestfs потрібна базова система supermin, яку бібліотека шукає за
внутрішнім шляхом.

Типово, пошук відбувається у каталозі C<$libdir/guestfs> (наприклад
F</usr/local/lib/guestfs> або F</usr/lib64/guestfs>).

Скористайтеся L</guestfs_set_path> або встановіть значення змінної
середовища L</LIBGUESTFS_PATH>, щоб змінити каталоги, у який вестиме пошук
libguestfs. Значенням має бути список шляхів, відокремлених
двокрапками. Пошук у поточному каталозі I<не> виконуватиметься, якщо у
записі шляхів не буде порожнього елемента або елемента C<.>. Наприклад,
C<LIBGUESTFS_PATH=:/usr/lib/guestfs> означає, що пошук виконуватиметься
спочатку у поточному каталозі, а потім у каталозі F</usr/lib/guestfs>.

=head2 ОБГОРТКИ QEMU

Якщо ви хочете зібрати власну версію qemu, запускати qemu із нестандартного
каталогу або передавати qemu додаткові аргументи, ви можете написати
скрипт-обгортку для командної оболонки для запуску qemu.

Існує одне важливе правило, про яке слід пам'ятати: вам I<слід виконати
C<exec qemu>> як останню команду у скрипті оболонки (отже, qemu заміняє
командну оболонку і стає безпосереднім дочірнім процесом програми, яка
використовує libguestfs). Якщо ви цього не зробите, процес qemu не буде
належним чином очищено.

Ось приклад обгортки, де використано зібрану власну копію qemu:

 #!/bin/sh -
 qemudir=/home/rjones/d/qemu
 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"

Збережіть цей скрипт як F</tmp/qemu.wrapper> (або під якоюсь іншою назвою),
C<chmod +x>, а далі скористайтеся ним для встановлення значення змінної
середовища LIBGUESTFS_HV. Приклад:

 LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish

Зауважте, що libguestfs також викликає qemu із параметрами -help і -version
з метою визначення переліку можливостей програми.

Обгортками також можна скористатися для редагування параметрів, які
передаються qemu. У наведеному нижче прикладі параметр C<-machine ...>
(параметр C<-machine> і наступний за ним аргумент) вилучається з рядка
команди і замінюється на C<-machine pc,accel=tcg>. Цикл while виконує
ітерацію параметрами, аж доки не буде знайдено належний параметр для
вилучення, розташовуючи решту параметрів у масиві C<args>.

 #!/bin/bash -
 
 i=0
 while [ $# -gt 0 ]; do
     case "$1" in
     -machine)
         shift 2;;
     *)
         args[i]="$1"
         (( i++ ))
         shift ;;
     esac
 done
 
 exec qemu-kvm -machine pc,accel=tcg "${args[@]}"

=begin html

<!-- old anchor for the next section --> <a name="attach-method"/>

=end html

=head2 МОДУЛЬ

Модуль обробки (раніше ми його називали «метод долучення») керує тим, як
libguestfs створює і/або з'єднується із фоновою службою модуля обробки,
наприклад, запускаючи qemu безпосередньо або використовуючи libvirt для
керування базовою системою, запускаючи User-Mode Linux або з'єднуючись із
вже запущеною фоновою службою.

Встановити цей модуль можна викликом L</guestfs_set_backend> або
встановленням значення змінної середовища C<LIBGUESTFS_BACKEND>.

Можливі модуля описано нижче:

=over 4

=item C<direct>

=item C<appliance>

Запустити qemu безпосередньо для запуску базової системи.

C<direct> і C<appliance> є синонімами.

Це звичайний метод і за звичних умов цей метод є типовим, але зверніть увагу
на наведену нижче нотатку.

=item C<libvirt>

=item C<libvirt:null>

=item C<libvirt:I<адреса>>

Скористатися libvirt для запуску і керування базовою системою.

C<libvirt> спричиняє вибір libguestfs відповідної адреси для створення
гостьових операційних систем сеансу. Якщо використовується модуль обробки
libvirt, вам майже завжди слід це використовувати.

C<libvirt:null> спричиняє вибір libguestfs використання C<NULL> як адреси
з'єднання, що призводить до того, що libvirt намагається вгадати наміри
користувача. Ймовірно, вам не слід використовувати таку адресу.

C<libvirt:I<адреса>> спричиняє використання адреси I<адреса> як адреси
з'єднання libvirt (див. L<http://libvirt.org/uri.html>). Типовим модулем
libvirt із вказаною адресою буде C<libvirt:qemu:///session>

У модулі обробки libvirt передбачено більше можливостей, зокрема можливість
з'єднання у «гарячому» режимі (див. L</З'ЄДНАННЯ У «ГАРЯЧОМУ» РЕЖИМІ>) та
sVirt.

=item C<uml>

Запустити ядро User-Mode Linux. Розташування ядра встановлюється за
допомогою C<$LIBGUESTFS_HV> або за допомогою програмного інтерфейсу
L</guestfs_set_qemu> (зауважте, що qemu не задіяно, ми просто повторно
використовуємо ту саму змінну середовища у дескрипторі для зручності).

User-Mode Linux може бути набагато швидшим, простішим і невибагливішим до
ресурсів за повноцінну віртуальну машину, але у нього є певні
недоліки. Див. L</МОДУЛЬ USER-MODE LINUX> нижче.

=item C<unix:I<шлях>>

Встановити з’єднання з сокетом домену Unix I<шлях>.

Цей метод надає вам змогу з'єднуватися із наявною фоновою службою або (за
допомогою virtio-serial) із запущеною гостьовою системою. Щоб дізнатися
більше, див. L</ДОЛУЧЕННЯ ДО ЗАПУЩЕНИХ ФОНОВИХ СЛУЖБ>.

=back

C<direct>, зазвичай є типовим модулем обробки. Втім, починаючи з версії
libguestfs E<ge> 1.19.24, libguestfs можна зібрати із іншим типовим модулем
за допомогою такого параметра скрипту налаштовування збирання:

 ./configure --with-default-backend=...

Щоб визначити, чи було libguestfs зібрано із іншим типовим модулем обробки,
віддайте такі команди:

 unset LIBGUESTFS_BACKEND
 guestfish get-backend

=head2 ПАРАМЕТРИ МОДУЛІВ

Кожен модуль обробки можна налаштувати передаванням списку рядків. Ви можете
або викликати L</guestfs_set_backend_settings> зі списком рядків, або
встановити для змінної середовища C<LIBGUESTFS_BACKEND_SETTINGS> значення,
яке є списком рядків, які відокремлено двокрапками (до створення
дескриптора).

=head3 force_tcg

Використовується:

 export LIBGUESTFS_BACKEND_SETTINGS=force_tcg

примусово визначить для модулів обробки direct та libvirt використання TCG
(програмної емуляції) замість KVM (апаратно прискореної віртуалізації).

=head3 gdb

У модулі direct передбачено підтримку:

 export LIBGUESTFS_BACKEND_SETTINGS=gdb

Якщо встановлено таке значення змінної середовища, qemu не розпочинатиме
негайний запуск базової системи. Програма очікуватиме, доки ви з'єднаєтеся
із нею за допомогою gdb:

 $ gdb
 (gdb) symbol-file /path/to/vmlinux
 (gdb) target remote tcp::1234
 (gdb) cont

Далі, ви можете виконувати діагностику ядра базової системи, чим можна
скористатися для дослідження проблем із завантаженням (особливо таких
проблем, за яких не виводиться діагностичних повідомлень — підказка: шукайте
у C<log_buf> ядра).

У Fedora встановіть C<kernel-debuginfo> для файла C<vmlinux> (який містить
символи). Переконайтеся, що символи точно відповідають використаному ядру.

=head2 ДОЛУЧЕННЯ ДО ЗАПУЩЕНИХ ФОНОВИХ СЛУЖБ

I<Зауваження (1):> це B<дуже експериментальна> можливість, яка може
призводити до пошкодження даних. Будьте обережні.

I<Нотатка (2):> у цьому розділі наведено відомості щодо долучення до
запущеної фонової служби з низькорівневою перспективою. Для більшості
користувачів просте використання засобів віртуалізації, зокрема
L<guestfish(1)>, з параметром I<--live> має «просто працювати».

=head3 Використання guestfs_set_backend

За допомогою виклику L</guestfs_set_backend> ви можете змінити спосіб
з'єднання бібліотеки з фоновою службою C<guestfsd> у L</guestfs_launch>
(ознайомтеся із розділом L<guestfs-internals(1)/АРХІТЕКТУРА>, щоб дізнатися
більше про основи).

Звичайним модулем обробки є C<direct>, де створюється мала базова система,
яка містить фонову службу, з якою згодом з'єднується бібліотека. C<libvirt>
або C<libvirt:I<адреса>> є альтернативами, які використовують libvirt для
запуску базової системи.

Встановлення для модуля обробки значення C<unix:I<шлях>> (де I<шлях> — це
шлях до сокета домену Unix) призводить до того, що L</guestfs_launch>
з'єднується із наявною фоновою службою за допомогою сокета домену Unix.

Звичним використанням цього є встановлення з'єднання з запущеною віртуальною
машиною, які містить фонову службу C<guestfsd>, і надсилання команд, щоб
можна було читати і записувати файли у запущеній віртуальній машині.

=head3 За допомогою guestfs_add_domain з прапорцем live

L</guestfs_add_domain> надає певну допомогу у отриманні відповідного модуля
обробки. Якщо ви передаєте параметр C<live> цій функції, тоді (якщо
віртуальну машину запущено) вона вивчить XML libvirt, шукаючи канал
virtio-serial для з'єднання:

 <domain>
   ...
   <devices>
     ...
     <channel type='unix'>
       <source mode='bind' path='/path/to/socket'/>
       <target type='virtio' name='org.libguestfs.channel.0'/>
     </channel>
     ...
   </devices>
 </domain>

L</guestfs_add_domain> видобуває F</шлях/до/сокета> і встановлює для модуля
обробки шлях C<unix:/шлях/до/сокета>.

У деяких із засобів libguestfs (зокрема guestfish) передбачено підтримку
параметра I<--live>, який передається до L</guestfs_add_domain>, таким чином
надаючи вам змогу з'єднуватися і змінювати запущені віртуальні машини.

Віртуальну машину слід попередньо налаштувати так, щоб у ній був канал
virtio-serial і у ній було запущено guestfsd.

=head2 МОДУЛЬ USER-MODE LINUX

Встановлення вказаних нижче змінних середовища (або використання відповідних
програмних інтерфейсів) вибирає модуль обробки User-Mode Linux:

 export LIBGUESTFS_BACKEND=uml
 export LIBGUESTFS_HV=/шлях/до/vmlinux

C<vmlinux> (іншою назвою може бути C<linux>) — виконуваний файл Linux,
зібраний для запуску як процес у просторі користувача. Зауважте, що ми
повторно використали змінну qemu у дескрипторі для зручності; qemu вона не
стосується.

Використання User-Mode Linux може пришвидшити роботу і зменшити вибагливість
до ресурсів системи, порівняно із запуском повноцінної віртуальної машини
для модуля обробки (особливо, якщо ви вже запустили libguestfs у віртуальній
машині або у екземплярі системи в обчислювальній «хмарі»), але цей спосіб
також має певні недоліки, якщо порівнювати його зі звичайним модулем обробки
на основі qemu або KVM.

=head3 ЗБИРАННЯ USER-MODE LINUX З ПОЧАТКОВИХ КОДІВ

У вашому дистрибутиві Linux можуть бути готові пакунки UML. Якщо це так,
можете пропустити цей розділ.

Інструкції запозичено з
L<http://user-mode-linux.sourceforge.net/source.html>

=over 4

=item 1. Отримати початкові коди Linux

Клонуйте сховище коду git Linux або отримайте архів tar із початковим кодом
Linux.

=item 2. Налаштувати збирання ядра

B<Зауваження:> до усіх команд «make» слід додавати C<ARCH=um>.

 make menuconfig ARCH=um

Переконайтеся, що усі потрібні вам драйвери файлових систем вкомпільовано до
ядра.

B<У поточній версії потрібні значні додаткові зусилля, щоб змусити працювати
модулі>. Рекомендуємо вам вимкнути підтримку модулів у налаштуваннях
ядра. Вимикання підтримки призведе до того, що усі можливості буде зібрано у
одному образі ядра.

=item 3. Зібрати ядро

 make ARCH=um

Ви отримаєте файл із назвою C<linux> або C<vmlinux> у каталозі верхнього
рівня. Цей файл і є ядром UML. Вам слід встановити значення
C<LIBGUESTFS_HV>, яке вказуватиме на цей файл.

=back

=head3 ВІДМІННОСТІ USER-MODE LINUX ВІД KVM

=over 4

=item У UML передбачено підтримку лише образів у форматі raw

Працюватимуть лише прості образи у форматі raw. Не можна користуватися ні
qcow2, ні файлами резервних копій.

=item У UML не передбачено підтримки будь-яких віддалених дисків

Не можна користуватися NBD тощо.

=item UML працює лише на ix86 та x86-64

=item UML є експериментальною можливістю

Зокрема, підтримка UML у libguestfs залежить від підтримки UML у основній
гілці розробки ядра. Якщо UML буде вилучено із основного коду ядра Linux,
ймовірно, нам доведеться вилучити його підтримку і з libguestfs.

=back

=head2 ГАРАНТІЯ ЩОДО ABI

Ми гарантуємо незмінність ABI (двійкового інтерфейсу) libguestfs для
загальних (public) високорівневих дій, як це описано у цьому розділі. Хоча
ми вважаємо деякі з дій застарілими, наприклад, якщо їх замінено новішими
викликами, ми зберігаємо ці дії у двійковому інтерфейсі. Це надає змогу
розробникам програм бути певними у незмінності програмного інтерфейсу
libguestfs.

=head2 ІМЕНУВАННЯ БЛОКОВИХ ПРИСТРОЇВ

Libguestfs визначає F</dev/sd*> як I<стандартну схему іменування> для
пристроїв, які передаються викликам програмного інтерфейсу. Отже,
F</dev/sda> означає «перший пристрій, який додано за допомогою
L</guestfs_add_drive_opts>», а F</dev/sdb3> означає «третій розділ на
другому пристрої».

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

=head3 МІТКИ ДИСКІВ

Починаючи з libguestfs E<ge> 1.20, ви можете надати диску мітку під час
додавання за допомогою необов'язкового параметра C<label> функції
L</guestfs_add_drive_opts>.  (Зауважте, що мітки дисків є самостійними
об'єктами і можуть відрізнятися від міток файлової системи.)

Підтримку встановлення міток дисків передбачено не в усіх версіях
libguestfs. Якщо підтримку передбачено, то мітку обмежено 20 символами ASCII
C<[a-zA-Z]>.

Після додавання мітки до диска ви можете використовувати як його адресу або
F</dev/sd*>, або F</dev/disk/guestfs/I<мітка>>. Вказувати на розділи диска
можна за допомогою адреси F</dev/disk/guestfs/I<мітка>I<номер_розділу>>.

Команди виведення списку пристроїв (L</guestfs_list_devices>) та розділів
(L</guestfs_list_partitions>) повертають назви блокових пристроїв. Втім, ви
можете скористатися L</guestfs_list_disk_labels> для прив'язування міток
дисків до назв блокових пристроїв і розділів.

=head2 НУЛЬОВІ ДИСКИ

При додавання диска за допомогою, наприклад, L</guestfs_add_drive>, ви
можете встановити для назви файла значення C<"/dev/null">. Цей рядок у
libguestfs обробляється особливо, спричиняючи додавання «нуль-диска».

Нуль-диск має такі властивості:

=over 4

=item *

Нуль-диск буде показано як звичайний пристрій, наприклад, у викликах
L</guestfs_list_devices>.

=item *

Ви можете додавати пристрій C<"/dev/null"> декілька разів.

=item *

Вам не слід намагатися отримати доступ до нуль-диска у будь-який
спосіб. Наприклад, не варто намагатися прочитати з нього дані або змонтувати
його.

=back

Передбачено три основних призначення нульових дисків:

=over 4

=item 1.

Тестування швидкодії libguestfs (див. L<guestfs-performance(1)>).

=item 2.

Вбудований комплекс для перевірки.

=item 3.

Якщо ви хочете скористатися програмними інтерфейсами libguestfs, які не
посилаються на диски, оскільки libguestfs вимагає додавання принаймні одного
диска, вам слід додати нуль-диск.

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

 guestfs_h *g;
 char **groups = [ "btrfs", NULL ];
 
 g = guestfs_create ();
 guestfs_add_drive (g, "/dev/null");
 guestfs_launch (g);
 if (guestfs_available (g, groups) == 0) {
   // group(s) are available
 } else {
   // group(s) are not available
 }
 guestfs_close (g);

=back

=head2 ФОРМАТИ ОБРАЗІВ ДИСКІВ

Віртуальні диски зберігаються у декількох форматах. Нижче наведено список
найпоширеніших форматів.

Зауважте, що за роботу із форматами дисків сама libguestfs не відповідає:
усю роботу виконує L<qemu(1)>. Якщо не передбачено підтримки якогось формату
або у підтримці формату буде виявлено вади, виправляти це слід у qemu.

=head3 ТИПОВІ ФОРМАТИ ОБРАЗІВ ВІРТУАЛЬНИХ ДИСКІВ

=over 4

=item I<raw>

Простий формат (raw) — це просто дамп послідовних байтів віртуального
диска. У ньому немає заголовка, контейнера, стискання, він не є результатом
будь-якої обробки цього набору байтів.

Оскільки для читання або запису даних простий формат не потребує ніякої
проміжної обробки, робота з ним дуже швидка, а підтримка його у qemu та усіх
інших гіпервізорах є дуже доброю. Цей формат можна вважати універсальним,
доступ до даних у якому зможе отримати будь-який гіпервізор.

Дані у простому форматі (raw) не стискаються, отже займають на диску рівно
стільки місця, скільки займає початковий образ диска, навіть якщо на ньому
зовсім немає даних. У різновиді цього формату (принаймні у Linux/Unix)
усунено потребу у зберіганні діапазонів нульових байтів шляхом використання
так званих розріджених файлів. Цей варіант формату іноді називають «простим
розрідженим» (I<raw sparse>). Багато інструментів, зокрема
L<virt-sparsify(1)>, можуть перетворювати прості образи дисків у розріджені.

=item I<qcow2>

Qcow2 — природний формат образів дисків, який використовується у qemu. На
внутрішньому рівні використовується дворівнева структура каталогів, отже, у
файлі зберігаються лише блоки, які містять дані. Також передбачено багато
інших можливостей, зокрема стискання даних, знімки та резервне копіювання
файлів.

Існує принаймні два різних варіанти цього формату. Втім, qemu (а отже,
libguestfs) обробляє обидва формати прозоро для користувача.

=item I<vmdk>

VMDK — природний формат образів дисків VMware. Існує багато варіацій. У
сучасних версіях qemu (а отже, і у libguestfs) передбачено підтримку
більшості варіацій, але вам слід мати на увазі те, що у застарілих версіях
qemu у цьому аспекті є серйозні вади, які можуть призводити до пошкодження
даних.

Зауважте, що ESX VMware надає файли із назвою F<guest-flat.vmdk>.  Це не
файли у форматі VMDK. Це дані у простому форматі (raw), які просто записано
до файла із суфіксом назви C<.vmdk>.

=item I<vdi>

VDI — є природним форматом образів дисків VirtualBox. У qemu (а отже і у
libguestfs) передбачено загалом непогану підтримку даних у цьому форматі.

=item I<vpc>

=item I<vhd>

VPC (застарілий) та VHD (сучасний) — формати образів дисків, які розроблено
Microsoft (а перед тим, Connectix) для Virtual PC та Hyper-V.

=item Застарілі формати

Наведені далі формати є застарілими. Вам не слід ними користуватися: I<qcow>
(або I<qcow1>), I<cow>, I<bochs>.

=back

=head3 ВИЗНАЧЕННЯ ФОРМАТУ ОБРАЗУ ДИСКА

По-перше, зверніть увагу на прогалину у захисті, пов'язану із автоматичним
визначенням формату образу диска.  Вона може стосуватися вашого процесу
використання. Див. розділ L</CVE-2010-3851> нижче.

У libguestfs передбачено програмний інтерфейс для отримання даних щодо
формату образу диска (L</guestfs_disk_format>), і найбезпечніше
користуватися саме ним.

I<Не> захоплюйтесь спробами обробки тексту або виведених для зручного
читання даних C<qemu-img>, оскільки ці дані не можна обробити надійним і
безпечним чином. Не використовуйте команду C<file>, оскільки виведені нею
дані є різними для різних версій бібліотеки.

=head1 КЕРУВАННЯ З’ЄДНАННЯМ

=head2 guestfs_h *

C<guestfs_h> є непрозорим типом, який представляє дескриптор
з'єднання. Створіть дескриптор викликом L</guestfs_create> або
L</guestfs_create_flags>.  Викличте L</guestfs_close>, щоб звільнити
дескриптор і усі використані ним ресурси.

Щоб дізнатися більше про обробку у декілька дескрипторів і у декілька
потоків, ознайомтеся із розділом L</ОБРОБКА У ДЕКІЛЬКА ДЕСКРПИТОРІВ І
ПОТОКІВ> вище.

=head2 guestfs_create

 guestfs_h *guestfs_create (void);

Створити дескриптор з’єднання.

Якщо виконано успішно, повертає непорожній вказівник на дескриптор. Якщо
станеться помилка, повертає NULL.

Після створення дескриптор слід «налаштувати». Для цього слід викликати
L</guestfs_add_drive_opts> (або одну з інших еквівалентних функцій) для
дескриптора принаймні один раз.

Після налаштовування дескриптора вам слід викликати L</guestfs_launch>.

Ви також можете налаштувати обробку помилок для дескриптора. Див. розділ
L</ОБРОБКА ПОМИЛОК> нижче.

=head2 guestfs_create_flags

 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);

Створює дескриптор з'єднання, надаючи додаткові прапорці та аргументи для
керування створенням дескриптора.

Якщо виконано успішно, повертає непорожній вказівник на дескриптор. Якщо
станеться помилка, повертає NULL.

L</guestfs_create> еквівалентна виклику C<guestfs_create_flags(0)>.

Наведені нижче прапорці може бути поєднано за допомогою логічного АБО (у
поточній версії додаткові аргументи не використовуються).

=over 4

=item C<GUESTFS_CREATE_NO_ENVIRONMENT>

Не обробляти змінні середовища (зокрема C<LIBGUESTFS_DEBUG>).

Згодом ви можете викликати L</guestfs_parse_environment> або
L</guestfs_parse_environment_list> для обробки змінних середовища. Крім
того, можна I<не> викликати ці функції, якщо ви не хочете, щоб на роботу
дескриптора впливали змінні середовища. Див. наведений нижче приклад.

Типовою поведінкою (якщо цей прапорець не встановлено явно) є неявний виклик
L</guestfs_parse_environment>.

=item C<GUESTFS_CREATE_NO_CLOSE_ON_EXIT>

Не намагатися закрити дескриптор у обробнику L<atexit(3)>, якщо програма
завершує роботу без закриття дескриптора явним чином.

Типовою поведінкою (якщо цей прапорець не встановлено явно) є встановлення
також обробника atexit.

=back

=head3 ВИКОРИСТАННЯ C<GUESTFS_CREATE_NO_ENVIRONMENT>

Ви можете скористатися C<GUESTFS_CREATE_NO_ENVIRONMENT> і явним викликом
L</guestfs_parse_environment> ось так:

 guestfs_h *g;
 int r;
 
 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
 if (!g) {
   perror ("guestfs_create_flags");
   exit (EXIT_FAILURE);
 }
 r = guestfs_parse_environment (g);
 if (r == -1)
   exit (EXIT_FAILURE);

Крім того, для створення дескриптора, на який не впливатимуть змінні
середовища, усуньте виклики C<guestfs_parse_environment> з наведеного вище
коду.

У наведеного вище коду є ще одна перевага: усі помилки під час обробки
середовища передаються обробнику помилок, тоді як C<guestfs_create> виводить
повідомлення про помилки до stderr і ігнорує помилки.

=head2 guestfs_close

 void guestfs_close (guestfs_h *g);

Закриває дескриптор з'єднання і звільняє усі використані ресурси. Якщо для
дескриптора було встановлено зворотний виклик закриття, його буде виконано.

Правильний спосіб закриття дескриптора ось такий:

 if (guestfs_shutdown (g) == -1) {
   /* тут обробляємо помилки запису */
 }
 guestfs_close (g);

Потреба у L</guestfs_shutdown> виникає, лише якщо виконуються B<усі> з
наведених нижче умов:

=over 4

=item 1

у режимі читання-запису було додано один або декілька дисків I<і>

=item 2

було викликано guestfs_launch, I<і>

=item 3

вами було внесено якісь зміни, I<і>

=item 4

ви можете обробляти помилки запису (наприклад, завершенням виконання із
кодом помилки або звітуванням про помилку користувачеві).

=back

=head1 ОБРОБКА ПОМИЛОК

Функції програмного інтерфейсу можуть повертати помилки. Наприклад, майже
усі функції, які повертають C<int>, повертатимуть C<-1> для позначення
помилки.

Для помилок надається додаткова інформація: рядок повідомлення про помилку
і, необов'язково, номер помилки (errno), якщо помилку було пов'язано із
загальносистемним викликом.

Ви можете отримати додаткову інформацію щодо останньої помилки для
дескриптора за допомогою виклику L</guestfs_last_error>,
L</guestfs_last_errno> і/або встановлення обробника помилок за допомогою
L</guestfs_set_error_handler>.

Під час створення дескриптора встановлюється типовий обробник помилок, який
виводить рядок повідомлення про помилку до C<stderr>. Для невеличких
програм, які виконуються швидко і керуються з командного рядка, достатньо
зробити ось що:

 if (guestfs_launch (g) == -1)
   exit (EXIT_FAILURE);

оскільки типовий обробник помилок забезпечить виведення повідомлення про
помилку до C<stderr> до завершення роботи програми.

Для інших програм, майже напевно, слід встановити альтернативний обробник
помилок або обробляти помилки всередині, як у наведеному нижче прикладі. У
прив'язках до мов програмування, відмінних від C, усюди встановлюються
NULL-обробники помилок, а помилки перетворюються на виключення за допомогою
коду, подібного до такого:

 const char *msg;
 int errnum;
 
 /* Це вимикає типову поведінку при виведенні помилок
    до stderr. */
 guestfs_set_error_handler (g, NULL, NULL);
 
 if (guestfs_launch (g) == -1) {
   /* Вивчаємо повідомлення про помилку і виводимо його, надсилаємо його
      тощо. */
   msg = guestfs_last_error (g);
   errnum = guestfs_last_errno (g);
 
   fprintf (stderr, "%s", msg);
   if (errnum != 0)
     fprintf (stderr, ": %s", strerror (errnum));
   fprintf (stderr, "\n");
 
   /* ... */
 }

L</guestfs_create> повертає C<NULL>, якщо дескриптор неможливо створити, а
оскільки, якщо таке трапиться, дескриптора не буде, неможливо буде отримати
додаткові відомості щодо помилки. Починаючи з libguestfs E<ge> 1.20, ви
можете скористатися L</guestfs_create_flags> для належної обробки помилок
під час створення дескрипторів, хоча у переважній частині програм можна
продовжувати користуватися L</guestfs_create> і не перейматися особливо цим
випадком.

Помилки, пов'язані із нестачею пам'яті, обробляються інакше. Типовою дією є
виклик L<abort(3)>. Якщо такий виклик є небажаним, ви можете встановити
обробник за допомогою функції L</guestfs_set_out_of_memory_handler>.

=head2 guestfs_last_error

 const char *guestfs_last_error (guestfs_h *g);

Повертає повідомлення про останню помилку, яка трапилася для C<g>. Якщо з
часу створення дескриптора помилок не траплялося, повертає C<NULL>.

Зауважте, що у повернутому рядку I<не> буде символу нового рядка
наприкінці. Більшість повідомлень про помилки є однорядковими. Деякі
поділено на декілька рядків, вони містять символи C<\n> усередині рядка, але
не наприкінці.

Повернутий рядок лишається актуальним, аж доки не станеться наступна помилка
для того самого дескриптора або не буде викликано L</guestfs_close>. Якщо
цей рядок потрібен вам на довший термін, скопіюйте його.

=head2 guestfs_last_errno

 int guestfs_last_errno (guestfs_h *g);

Повертає номер останньої помилки (errno), яка сталася для C<g>.

Якщо виконано успішно, буде повернуто ненульове ціле число errno.

У багатьох випадках повертається спеціальне значення errno C<ENOTSUP>, якщо
ви намагаєтеся викликати функцію або скористатися можливістю, підтримки якої
не передбачено.

Якщо номер помилки недоступний, функція повертає 0. Виклик може повертати 0
у трьох випадках:

=over 4

=item 1.

Для дескриптора не було зафіксовано жодних помилок.

=item 2.

Сталася помилка, але отримання errno не має сенсу. Таке трапляється у
випадках, коли повідомлення про помилку надійшло не від загальносистемного
виклику, отже причина помилки була якоюсь іншою.

=item 3.

Сталася помилка у загальносистемному виклику, але з якоїсь причини errno не
було перехоплено і повернуто. Це, зазвичай, пов'язано із вадою у libguestfs.

=back

Libguestfs намагається перетворити errno із внутрішнього для базової системи
у відповідне значення errno для функції виклику (це завдання не є простим: у
базовій системі може бути запущено зовсім іншу операційну систему з
бібліотеки, а номери помилок у Un*x не стандартизовано). Якщо перетворення є
неможливим, повідомлення про помилку перетворюється до C<EINVAL>. На
практиці такі випадки є дуже рідкісними.

=head2 guestfs_set_error_handler

 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
                                           void *opaque,
                                           const char *msg);
 void guestfs_set_error_handler (guestfs_h *g,
                                 guestfs_error_handler_cb cb,
                                 void *opaque);

Якщо станеться помилка, буде викликано зворотний виклик C<cb>. Параметрами,
які передаються зворотному виклику, є непрозорий вказівник на дані і рядок
повідомлення про помилку.

C<errno> зворотному виклику не передається. Щоб отримати це значення у
зворотному виклику, вам слід викликати L</guestfs_last_errno>.

Зауважте, що рядок повідомлення C<msg> звільняється, щойно повертається
керування з функції зворотного виклику, отже, якщо ви хочете його десь
зберегти, вам слід зробити його копію.

Типовий обробник виводить повідомлення до C<stderr>.

Якщо ви встановите для C<cb> значення C<NULL>, обробник I<не>
викликатиметься.

=head2 guestfs_get_error_handler

 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
                                                     void **opaque_rtn);

Повертає зворотний виклик поточного обробника помилок.

=head2 guestfs_push_error_handler

 void guestfs_push_error_handler (guestfs_h *g,
                                  guestfs_error_handler_cb cb,
                                  void *opaque);

Ця функція виконує ті самі дії, що і L</guestfs_set_error_handler>, але
застарілий обробник помилок додається до стеку у самому дескрипторі. Ви
можете відновити попередній обробник помилок за допомогою виклику
L</guestfs_pop_error_handler>.

Скористайтеся таким кодом, щоб тимчасово вимкнути помилки навколо функції:

 guestfs_push_error_handler (g, NULL, NULL);
 guestfs_mkdir (g, "/foo"); /* Нам все одно, якщо спроба буде невдалою. */
 guestfs_pop_error_handler (g);

=head2 guestfs_pop_error_handler

 void guestfs_pop_error_handler (guestfs_h *g);

Відновити попередній обробник помилок (див. L</guestfs_push_error_handler>).

Якщо ви виштовхуватимете обробники зі стосу достатню кількість разів, буде
відновлено типовий обробник помилок.

=head2 guestfs_set_out_of_memory_handler

 typedef void (*guestfs_abort_cb) (void);
 void guestfs_set_out_of_memory_handler (guestfs_h *g,
                                         guestfs_abort_cb);

Зворотний виклик C<cb> буде викликано, якщо станеться нестача
пам'яті. I<Зауважте, що цей зворотний виклик не повинен повертати
керування>.

Типовим є виклик L<abort(3)>.

Не можна встановлювати для C<cb> значення C<NULL>. Ви не можете ігнорувати
випадки, коли не вистачає пам'яті.

=head2 guestfs_get_out_of_memory_handler

 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);

Повертає поточний обробник випадків нестачі пам'яті.

=head1 ВИКЛИКИ API

__ACTIONS__

=head1 СТРУКТУРИ

__STRUCTS__

=head1 ДОСТУПНІСТЬ

=head2 ГРУПИ ФУНКЦІОНАЛЬНИХ МОЖЛИВОСТЕЙ У ОБРАЗІ ОСНОВНОЇ СИСТЕМИ

За допомогою L</guestfs_available> ви можете перевірити доступність вказаних
нижче груп функцій. Засіб тестування опитає базову систему для визначення,
чи передбачено у ній підтримку функціональних можливостей.

__AVAILABILITY__

=head2 ДОСТУПНІ ФАЙЛОВІ СИСТЕМИ

Функція L</guestfs_filesystem_available> викликає засоби тестування для
визначення, чи доступна підтримка певного типу файлової системи у ядрі
базової операційної системи.

Головним чином корисне для перевірки того, що підтримки не передбачено. Те,
що команда повертає true, ще не означає, що певну файлову систему може бути
змонтовано, оскільки помилки можуть траплятися через інші причини, зокрема
невідповідність версії файлової системи, несумісність можливостей.

=head2 КОМАНДА GUESTFISH supported

У L<guestfish(3)> передбачено зручну інтерактивну команду C<supported>, яка
виводить доступні групи, а також дані щодо їхньої підтримки у збірці
libguestfs. Втім, слід зауважити, спочатку слід виконати команду C<run>.

=head2 ОКРЕМІ ВИКЛИКИ ПІД ЧАС КОМПІЛЯЦІЇ

Починаючи з версії 1.5.8, C<E<lt>guestfs.hE<gt>> визначає символи для кожної
функції програмного інтерфейсу C, зокрема:

 #define GUESTFS_HAVE_DD 1

якщо доступна L</guestfs_dd>.

До версії 1.5.8, якщо вам потрібно було перевірити, чи доступна окрема
функція libguestfs під час компіляції, ми рекомендували скористатися
засобами збирання, зокрема autoconf або cmake. Наприклад, у autotools ви
могли скористатися таким кодом:

 AC_CHECK_LIB([guestfs],[guestfs_create])
 AC_CHECK_FUNCS([guestfs_dd])

який призводив до того, що C<HAVE_GUESTFS_DD> було або визначено, або не
визначено у вашій програмі.

=head2 ОКРЕМІ ВИКЛИКИ ПІД ЧАС РОБОТИ

Перевірка під час компіляції не гарантує існування функції у
бібліотеці. Причиною є те, що можливе динамічне компонування із попереднім
варіантом I<libguestfs.so> (динамічної бібліотеки), у якому немає потрібного
виклику. На жаль, така ситуація призводить до помилки сегментації, що є
загальним недоліком системи динамічного компонування у C.

Під час роботи програми ви можете скористатися L<dlopen(3)> для перевірки
того, чи доступна функція. Ось приклад програми (зауважте, що вам все одно
слід виконати перевірку під час компіляції):

 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h>
 #include <dlfcn.h>
 #include <guestfs.h>
 
 main ()
 {
 #ifdef GUESTFS_HAVE_DD
   void *dl;
   int has_function;
 
   /* Перевіряємо, чи дійсно функція guestfs_dd є доступною. */
   dl = dlopen (NULL, RTLD_LAZY);
   if (!dl) {
     fprintf (stderr, "dlopen: %s\n", dlerror ());
     exit (EXIT_FAILURE);
   }
   has_function = dlsym (dl, "guestfs_dd") != NULL;
   dlclose (dl);
 
   if (!has_function)
     printf ("this libguestfs.so does NOT have guestfs_dd function\n");
   else {
     printf ("this libguestfs.so has guestfs_dd function\n");
     /* Now it's safe to call
     guestfs_dd (g, "foo", "bar");
     */
   }
 #else
   printf ("guestfs_dd function was not found at compile time\n");
 #endif
  }

Вам може здатися, що у наведеному вище прикладі реалізовано доволі марудну
перевірку, і це насправді так. Існують інші способи поза системою
компонування C, які надають змогу гарантувати те, що такого роду
несумісність ніколи не трапиться. Зокрема, можна скористатися системою
визначення версій пакунків:

 Потрібна версія: libguestfs >= 1.0.80

=head1 ВИКЛИКИ ІЗ НЕОБОВ'ЯЗКОВИМИ АРГУМЕНТАМИ

Нещодавно реалізованою у програмному інтерфейсі можливістю є впровадження
викликів, які приймають необов'язкові аргументи. У C такі виклики
оголошуються у 3 способи. Основним способом є виклик, який приймає змінні
аргументи (тобто C<...>), як у цьому прикладі:

 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);

Викличте цю функцію зі списком необов'язкових аргументів, який
завершуватиметься C<-1>. Отже, щоб викликати функцію без необов'язкових
аргументів, зробіть так:

 guestfs_add_drive_opts (g, filename, -1);

З одним додатковим аргументом:

 guestfs_add_drive_opts (g, filename,
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
                         -1);

З двома аргументами:

 guestfs_add_drive_opts (g, filename,
                         GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
                         GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
                         -1);

і так далі. Не забувайте завершувати список C<-1>, інакше можливі дуже
печальні наслідки!

=head2 ВИКОРИСТАННЯ va_list ДЛЯ НЕОБОВ'ЯЗКОВИХ АРГУМЕНТІВ

Другий варіант має ту саму назву із суфіксом C<_va>. Він працює так само,
але отримує C<va_list>. Див. підручник з C, щоб дізнатися більше. Приклад
функції з оголошенням:

 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
                                va_list args);

=head2 ПОБУДОВА ДОДАТКОВИХ АРГУМЕНТІВ

Третій варіант корисний там, де вам потрібно побудувати ці виклики. Ви
передаєте структуру, у якій ви заповнюєте необов'язкові поля. Структура
містить бітову маску як перший елемент. Ви маєте встановити цю маску для
позначення того, які поля вам слід заповнити. У нашому прикладі функції
оголошено структуру і виклик:

 struct guestfs_add_drive_opts_argv {
   uint64_t bitmask;
   int readonly;
   const char *format;
   /* ... */
 };
 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
              const struct guestfs_add_drive_opts_argv *optargs);

Ви можете викликати її ось так:

 struct guestfs_add_drive_opts_argv optargs = {
   .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
              GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
   .readonly = 1,
   .format = "qcow2"
 };
 
 guestfs_add_drive_opts_argv (g, filename, &optargs);

Нотатки:

=over 4

=item *

Суфікс C<_BITMASK> при назві кожного параметр, якщо вказуємо бітову маску.

=item *

Вам не слід заповнювати усі поля структури.

=item *

Має існувати однозначна відповідність між полями структури, які
заповнюються, і набором бітів у бітовій масці.

=back

=head2 ДОДАТКОВІ АРГУМЕНТИ ІНШИМИ МОВАМИ

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

Щодо guestfish, див. L<guestfish(1)/НЕОБОВ'ЯЗКОВІ АРГУМЕНТИ>.

=head1 ПОДІЇ

=head2 ВСТАНОВЛЕННЯ ЗВОРОТНИХ ВИКЛИКІВ ДЛЯ ОБРОБКИ ПОДІЙ

B<Зауваження:> у цьому розділі наведено документацію загальний механізм
обробки подій, впроваджений у libguestfs 1.10, яким ви маєте користуватися у
новому коді, якщо це можливо. Застарілі функції
C<guestfs_set_log_message_callback>,
C<guestfs_set_subprocess_quit_callback>,
C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> і
C<guestfs_set_progress_callback> більше не документуються на цій сторінці
підручника. Оскільки сталість ABI гарантовано, застарілі функції лишаються
працездатнними.

Дескриптори породжують події, коли трапляються певні речі, зокрема
створюються повідомлення журналу, повідомлення щодо поступу під час
довготривалих дій або закривається дескриптор. Виклики програмного
інтерфейсу, описані нижче, надають вам змогу реєструвати зворотні виклики,
які викликатимуться, коли трапляються події. Ви можете зареєструвати
декілька зворотних викликів (для тих самих, інших або перекритих наборів
подій) і окремо вилучати зворотні виклики. Якщо зворотні виклики не
вилучено, тоді вони лишаються працездатними, аж доки дескриптор не буде
закрито.

У поточній реалізації події створюються лише синхронно: це означає, що події
(а отже, зворотні виклики) можуть траплятися, доки ви перебуваєте у іншому
виклику libguestfs. Зворотний виклик викликається у тому самому потоці
обробки.

Записи подій можуть містити дані, зазвичай, нічого (void), масив 64-бітових
цілих чисел без знаку або буфер повідомлень. Дані вмісту обговорено нижче.

=head2 КЛАСИ ПОДІЙ

=over 4

=item GUESTFS_EVENT_CLOSE (тип вмісту: void)

Функцію зворотного виклику буде викликано під час закриття дескриптора
(синхронно з L</guestfs_close>).

Зауважте, що libguestfs встановлює обробник L<atexit(3)> для виконання
спроби вилучення дескрипторів, які було відкрито, під час завершення роботи
програми. Це означає, що цей зворотний виклик може бути викликано
опосередковано з L<exit(3)>, що може спричинити неочікувані проблеми у
високорівневих мовах програмування (наприклад, якщо ваш інтерпретатор
високорівневої мови програмування вже було очищено на час виклику і якщо
зворотний виклик переводить до якоїсь функції високорівневої мови
програмування).

Якщо зворотних викликів не зареєстровано: дескриптор закривається без
будь-яких зворотних викликів.

=item GUESTFS_EVENT_SUBPROCESS_QUIT (тип вмісту: void)

Функцію зворотного виклику буде викликано, коли завершує роботу дочірній
процес, або асинхронно, або внаслідок роботи
L</guestfs_kill_subprocess>. (Це відповідає переходу з будь-якого стану до
стану CONFIG).

Якщо зворотних викликів не зареєстровано: подія ігнорується.

=item GUESTFS_EVENT_LAUNCH_DONE (тип вмісту: void)

Функцію зворотного виклику буде викликано, коли дочірній процес буде готовим
вперше після його запуску. (Це відповідає переходу зі стану LAUNCHING до
стану READY.)

Якщо зворотних викликів не зареєстровано: подія ігнорується.

=item GUESTFS_EVENT_PROGRESS (тип вмісту: масив з 4-х uint64_t)

Частина довготривалих дій може створювати повідомлення про поступ. Якщо цей
зворотний виклик зареєстровано, його буде викликано кожного разу при
створенні повідомлення про поступ (зазвичай, за дві секунди після початку
виконання дії і три рази за секунду після цього, аж доки виконання дії не
буде завершено, хоча частоту може буде змінено у майбутніх версіях).

Зворотний виклик отримує у даних вмісту чотири 64-бітових чисел без знаку,
якими є (саме у такому порядку): C<proc_nr>, C<serial>, C<position>,
C<total>.

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

Єдиними визначеними і стабільними частинами програмного інтерфейсу є:

=over 4

=item *

Зворотний виклик може показувати користувачеві певний тип смужки поступу або
індикатора, який показуватиме відношення C<position>:C<total>.

=item *

0 E<lt>= C<position> E<lt>= C<total>

=item *

Якщо під час виклику надсилаються якість сповіщення щодо поступу, остаточне
сповіщення щодо поступу завжди надсилається, коли C<position> = C<total>
(I<якщо> виклик не завершується помилкою).

Так зроблено для спрощення коду функції виклику, отже функції виклику можуть
просто встановити для індикатора поступу «100%» наприкінці виконання дії,
без потреби у реалізації у коді виявлення цієї ситуації.

=item *

Для деяких викликів неможливо оцінити поступ виклику, але ми можемо
створювати повідомлення щодо поступу для позначення виконання дії. Такий
режим відомий як «режим пульсації», підтримку якого безпосередньо
передбачено у деяких реалізаціях смужок поступу (наприклад GtkProgressBar).

Для цих викликів нуль або декілька повідомлень поступу створюються для
C<position = 0> і C<total = 1>, за якими слідує остаточне повідомлення з
C<position = total = 1>.

Як зауважено вище, якщо виклик завершується помилкою, остаточне повідомлення
може бути не створено.

=back

Крім того, зворотний виклик отримує номер процедури (C<proc_nr>) і серійний
номер (C<serial>) виклику. Ці дані корисні лише для діагностики проблем із
протоколом, а зворотний виклик, за звичайних умов, може їх
ігнорувати. Зворотний виклик може вивести ці числові дані у повідомленнях
про помилки або діагностичних повідомленнях.

Якщо зворотних викликів не зареєстровано, повідомлення про поступ
відкидаються.

=item GUESTFS_EVENT_APPLIANCE (тип вмісту: буфер повідомлень)

Функція зворотного виклику викликається кожного разу, коли qemu, ядро
базової системи, guestfsd (фонова служба) або допоміжні програми створюють
повідомлення журналу.

Якщо перед запуском (L</guestfs_launch>) встановлено прапорець докладних
повідомлень (L</guestfs_set_verbose>), буде створено додаткові діагностичні
повідомлення.

Якщо зворотний виклик не зареєстровано: повідомлення відкидаються, якщо не
встановлено прапорець докладних повідомлень. У цьому випадку повідомлення
надсилаються до stderr. Ви можете перевизначити виведення докладних
повідомлень до stderr встановленням зворотного виклику.

=item GUESTFS_EVENT_LIBRARY (тип вмісту: буфер повідомлень)

Функція зворотного виклику викликається кожного разу, коли бібліотечна
частина libguestfs створює повідомлення журналу.

Якщо встановлено прапорець докладних повідомлень (L</guestfs_set_verbose>),
буде створено додаткові діагностичні повідомлення.

Якщо зворотний виклик не зареєстровано: повідомлення відкидаються, якщо не
встановлено прапорець докладних повідомлень. У цьому випадку повідомлення
надсилаються до stderr. Ви можете перевизначити виведення докладних
повідомлень до stderr встановленням зворотного виклику.

=item GUESTFS_EVENT_WARNING (тип вмісту: буфер повідомлень)

Функція зворотного виклику викликається кожного разу, коли бібліотечна
частина libguestfs створює повідомлення із попередженням.

Якщо зворотний виклик не зареєстровано: повідомлення виводяться до
stderr. Ви можете перевизначити виведення повідомлень із попередженнями до
stderr встановленням зворотного виклику.

=item GUESTFS_EVENT_TRACE (тип вмісту: буфер повідомлень)

Функція зворотного виклику викликається кожного разу, коли створюється
повідомлення трасування. Це стосується лише випадків, коли встановлено
прапорець трасування (L</guestfs_set_trace>).

Якщо зворотний виклик не зареєстровано: повідомлення виводяться до
stderr. Ви можете перевизначити виведення повідомлень трасування до stderr
встановленням зворотного виклику.

=item GUESTFS_EVENT_ENTER (тип вмісту: назва функції)

Функція зворотного виклику викликається кожного разу, коли відбувається вхід
до функції libguestfs.

Дані вмісту є рядком, який містить назву функції, до якої було здійснено
вхід (без префікса C<guestfs_>).

Зауважте, що функції libguestfs можуть викликати самі себе, отже, ви можете
побачити багато подій від одного виклику. Деякі функції libguestfs не
створюють цієї події.

Якщо зворотних викликів не зареєстровано: подія ігнорується.

=item GUESTFS_EVENT_LIBVIRT_AUTH (тип вмісту: адреса libvirt)

Для будь-якої функції програмного інтерфейсу, яка відкриває з'єднання
libvirt, цю подію може бути створено для позначення того, що libvirt
потрібні дані для розпізнавання користувача. Див. L</РОЗПІЗНАВАННЯ ЗА
ДОПОМОГОЮ LIBVIRT> нижче.

Якщо зворотних викликів не зареєстровано: використовується
C<virConnectAuthPtrDefault> (пасує лише для команд, які керуються з
командного рядка).

=back

=head2 ПРОГРАМНИЙ ІНТЕРФЕЙС ПОДІЙ

=head3 guestfs_set_event_callback

 int guestfs_set_event_callback (guestfs_h *g,
                                 guestfs_event_callback cb,
                                 uint64_t event_bitmask,
                                 int flags,
                                 void *opaque);

Ця функція реєструє зворотний виклик (C<cb>) для усіх класів подій у
C<event_bitmask>.

Наприклад, щоб зареєструвати зворотний виклик для усіх подій повідомлень
журналу, ви можете викликати цю функцію із маскою бітів
C<GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING>. Щоб
зареєструвати єдиний зворотний виклик для усіх можливих класів подій,
скористайтеся C<GUESTFS_EVENT_ALL>.

C<flags> слід завжди передавати як 0.

C<opaque> — непрозорий вказівник, який передається зворотному виклику. Ви
можете використовувати його із будь-якою метою.

Повернутим значенням є дескриптор події (ціле число), яким ви можете
скористатися для вилучення зворотного виклику (див. нижче).

Якщо сталася помилка, ця функція повертає C<-1> і встановлює стан помилки у
дескрипторі у звичний спосіб (див. L</guestfs_last_error> тощо)

Зворотні виклики діють до їхнього вилучення або до закриття дескриптора.

У випадку, коли зареєстровано декілька зворотних викликів для певного класу
подій, буде викликано усі ці виклики. Порядок виклику зворотних викликів не
визначено.

=head3 guestfs_delete_event_callback

 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);

Вилучити раніше зареєстрований зворотний виклик. Значенням параметра
C<event_handle> має бути ціле число, яке було повернуто попереднім викликом
C<guestfs_set_event_callback> для того самого дескриптора.

=head3 guestfs_event_to_string

 char *guestfs_event_to_string (uint64_t event);

C<event> — окрема подія або бітова маска подій. Ця функція повертає рядкове
представлення (корисно для діагностики або виведення подій).

Окремі події повертаються як назви у нижньому регістрі, наприклад
C<"close">.

Бітова маска декількох подій повертається як список значень, які
відокремлено комами, наприклад C<"close,progress">.

Якщо буде передано нуль, буде повернуто порожній рядок C<"">.

Якщо виконано успішно, повертає рядок. Якщо сталася помилка, повертає NULL і
встановлює значення C<errno>.

Повернутий рядок має бути вивільнено функцією, яка викликає цю функцію.

=head3 guestfs_event_callback

 typedef void (*guestfs_event_callback) (
                  guestfs_h *g,
                  void *opaque,
                  uint64_t event,
                  int event_handle,
                  int flags,
                  const char *buf, size_t buf_len,
                  const uint64_t *array, size_t array_len);

Це тип функції зворотного виклику події, яку вам слід надати.

Базові параметри: дескриптор (C<g>), непрозорий вказівник користувача
(C<opaque>), клас подій (наприклад C<GUESTFS_EVENT_PROGRESS>), дескриптор
події та C<flags>, які у поточній версії програмного інтерфейсу ви можете
ігнорувати.

Решта параметрів містить дані вмісту події (якщо такі є). У кожному записі
події можуть міститися дані вмісту, які, зазвичай, пов'язано із класом
події, але з міркувань забезпечення сумісності у майбутньому ваш код має
бути записано так, щоб він міг обробити будь-які дані вмісту для будь-якого
класу подій.

C<buf> і C<buf_len> містять буфер повідомлень (якщо C<buf_len == 0>, буфера
повідомлень не існує). Зауважте, що цей буфер повідомлень може містити
довільні 8-бітові дані, зокрема байти NUL.

C<array> і C<array_len> — масив з 64-бітових цілих чисел без знаку. У
поточній версії використовується лише для повідомлень щодо поступу.

=head2 ПРИКЛАД: ЗАХОПЛЮЄМО ПОВІДОМЛЕННЯ ЖУРНАЛУ

Робочу програму, яка демонструє це, можна знайти у
F<examples/debug-logging.c> у початковому коді libguestfs.

Однією з мотивацій для створення загального програмного інтерфейсу подій
було уможливлення для програм із графічним інтерфейсом перехоплення
діагностичних повідомлень та інших повідомлень. У libguestfs E<le> 1.8 ці
повідомлення безумовно надсилалися до C<stderr>.

Подіями, пов'язаними із повідомленнями журналу, є такі:
C<GUESTFS_EVENT_LIBRARY>, C<GUESTFS_EVENT_APPLIANCE>,
C<GUESTFS_EVENT_WARNING> і C<GUESTFS_EVENT_TRACE>. (Зауважте, що
повідомлення про помилки не є подіями; вам слід перехоплювати повідомлення
про помилки окремо).

Програмам слід встановити зворотний виклик для цікавих для них класів подій:

 int eh =
   guestfs_set_event_callback
     (g, message_callback,
      GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
      GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
      0, NULL) == -1)
 if (eh == -1) {
   // обробка помилки у звичний спосіб
 }

Далі, зворотний виклик може спрямувати повідомлення до відповідного місця. У
цьому прикладі повідомлення спрямовуються до syslog:

 static void
 message_callback (
         guestfs_h *g,
         void *opaque,
         uint64_t event,
         int event_handle,
         int flags,
         const char *buf, size_t buf_len,
         const uint64_t *array, size_t array_len)
 {
   const int priority = LOG_USER|LOG_INFO;
   if (buf_len > 0)
     syslog (priority, "event 0x%lx: %s", event, buf);
 }

=head2 РОЗПІЗНАВАННЯ ЗА ДОПОМОГОЮ LIBVIRT

Деякі виклики програмного інтерфейсу libguestfs можуть відкривати з'єднання
із libvirt. У поточній версії єдиними такими викликами є
L</guestfs_add_domain> і L</guestfs_launch>, якщо вибрано модуль обробки
libvirt. З'єднання libvirt можуть потребувати проходження розпізнавання,
наприклад, якщо вони потребують доступу до віддаленого сервера або доступу
до служб адміністратора (root) від імені неадміністративного
користувача. Розпізнавання libvirt відбувається за допомогою механізму
зворотного виклику,
див.
L<http://libvirt.org/guide/html/Application_Development_Guide-Connections.html>

Ви можете надавати дані розпізнавання libvirt, зареєструвавши зворотний
виклик для подій типу C<GUESTFS_EVENT_LIBVIRT_AUTH>.

Якщо такої події не зареєстровано, libguestfs використовує функцію libvirt,
яка надає запити командного рядка (C<virConnectAuthPtrDefault>). Пасує для
програм libguestfs, які керуються за допомогою командного рядка.

Для забезпечення розпізнавання спочатку викличте
L</guestfs_set_libvirt_supported_credentials> зі списком реєстраційних
даних, які ваша програма має вміти надавати. Далі, зареєструйте зворотний
виклик для події C<GUESTFS_EVENT_LIBVIRT_AUTH>. Обробник подій буде
викликано, коли libvirt надішле запит щодо даних для розпізнавання.

У обробнику подій викличте L</guestfs_get_libvirt_requested_credentials> для
отримання списку реєстраційних даних, які потрібні libvirt. Далі, вам слід
запитати (наприклад, користувача) щодо кожного комплекту реєстраційних даних
і викликати L</guestfs_set_libvirt_requested_credential> із
відповіддю. Зауважте, що для кожного комплекту реєстраційних даних можуть
бути доступними додаткові відомості через виклики
L</guestfs_get_libvirt_requested_credential_prompt>,
L</guestfs_get_libvirt_requested_credential_challenge> та
L</guestfs_get_libvirt_requested_credential_defresult>.

Наведений нижче приклад програми має зробити це яснішим.

Також існує суттєвіший робочий приклад програми. Він постачається із
початковими кодами libguestfs і називається F<libvirt-auth.c>.

 main ()
 {
   guestfs_h *g;
   char *creds[] = { "authname", "passphrase", NULL };
   int r, eh;
 
   g = guestfs_create ();
   if (!g) exit (EXIT_FAILURE);
 
   /* Повідомляємо libvirt, підтримку яких реєстраційних даних передбачено у програмі. */
   r = guestfs_set_libvirt_supported_credentials (g, creds);
   if (r == -1)
     exit (EXIT_FAILURE);
 
   /* Встановлюємо обробник подій. */
   eh = guestfs_set_event_callback (
       g, do_auth,
       GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
   if (eh == -1)
     exit (EXIT_FAILURE);
 
   /* Приклад виклику, який може призвести до запиту щодо реєстраційних даних. */
   r = guestfs_add_domain (
       g, "dom",
       GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
       -1);
   if (r == -1)
     exit (EXIT_FAILURE);
 
   exit (EXIT_SUCCESS);
 }
 
 static void
 do_auth (guestfs_h *g,
          void *opaque,
          uint64_t event,
          int event_handle,
          int flags,
          const char *buf, size_t buf_len,
          const uint64_t *array, size_t array_len)
 {
   char **creds;
   size_t i;
   char *prompt;
   char *reply;
   size_t replylen;
   int r;
 
   // buf буде адресою libvirt. buf_len можна ігнорувати.
   printf ("Authentication required for libvirt conn '%s'\n",
           buf);
 
   // Питаємо libguestfs, які реєстраційні дані потрібні libvirt.
   creds = guestfs_get_libvirt_requested_credentials (g);
   if (creds == NULL)
     exit (EXIT_FAILURE);
 
   // Тепер просимо користувача відповісти на питання.
   for (i = 0; creds[i] != NULL; ++i)
   {
     if (strcmp (creds[i], "authname") == 0 ||
         strcmp (creds[i], "passphrase") == 0)
     {
       prompt =
         guestfs_get_libvirt_requested_credential_prompt (g, i);
       if (prompt && strcmp (prompt, "") != 0)
         printf ("%s: ", prompt);
       free (prompt);
 
       // Тут має бути якийсь код запитів щодо реєстраційних даних.
       // ...
       // Записуємо відповідь до «reply» зі довжиною «replylen» (у байтах).
 
      r = guestfs_set_libvirt_requested_credential (g, i,
          reply, replylen);
      if (r == -1)
        exit (EXIT_FAILURE);
     }
 
     free (creds[i]);
   }
 
   free (creds);
 }

=head1 СКАСОВУВАННЯ ДОВГОТРИВАЛОГО ПЕРЕДАВАННЯ ДАНИХ

Деякі дії може бути скасовано функцією виклику, доки вони виконуються. У
поточній версії може бути скасовано лише дії із вивантаження або отримання
даних (технічно: дії, які мають параметри C<FileIn> або C<FileOut> у
генераторі).

Щоб скасувати передавання даних, викличте L</guestfs_user_cancel>. Щоб
дізнатися більше, ознайомтеся із описом L</guestfs_user_cancel>.

=head1 ОБЛАСТЬ ПРИВАТНИХ ДАНИХ

Ви можете долучати іменовані частини приватних даних до дескриптора
libguestfs, отримувати їх за назвою і обходити їх протягом часу життя
дескриптора. Ця область даних називається областю приватних даних, доступ до
неї можна отримувати лише за допомогою програмного інтерфейсу мовою C.

Щоб долучити іменовані дані, скористайтеся таким викликом:

 void guestfs_set_private (guestfs_h *g, const char *key, void *data);

C<key> — назва, яку слід пов'язати з цими даними, а C<data> — довільний
вказівник (який може бути C<NULL>). Будь-який попередній запис із тим самим
ключем буде перезаписано.

Ви можете скористатися будь-яким рядком C<key>, але уникайте ключів, назви
яких починаються з символу підкреслювання (libguestfs використовує такі
ключі для власних внутрішніх потреб, зокрема реалізації прив'язок до мов
програмування). Рекомендуємо додавати до таких ключів якийсь унікальний
рядок-префікс, щоб уникнути конфліктів із ключами інших користувачів.

Щоб отримати вказівник, скористайтеся таким:

 void *guestfs_get_private (guestfs_h *g, const char *key);

Ця функція повертає C<NULL>, якщо або не буде знайдено пов'язаних C<key>
даних, або користувачем раніше буде встановлено  для вказівника C<data>
ключа C<key> значення C<NULL>.

Libguestfs не намагається переходити чи обробляти у будь-який спосіб
вказівник C<data>. У межах libguestfs це значення взагалі не повинне бути
чинним вказівником. Зокрема, libguestfs I<не> намагатиметься звільнити
пам'ять від data, коли дескриптор буде закриватися. Якщо data слід
звільнити, функція виклику має зробити це або до виклику L</guestfs_close>,
або має встановити зворотний виклик закриття для цього
(див. L</GUESTFS_EVENT_CLOSE>).

Для обходу усіх записів скористайтеся цими двома функціями:

 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);

 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);

C<guestfs_first_private> повертає першу пару ключ, вказівник (слово «перша»
тут немає певного точного змісту — ключі повертаються без якогось
визначеного порядку). Функцією повертається вказівник на ключ у C<*key_rtn>
і відповідний вказівник на дані. Якщо у дескрипторі не зберігається ніяких
ключів, буде повернуто C<NULL>.

C<guestfs_next_private> повертає наступну пару ключ, вказівник. Ця функція
поверне C<NULL>, якщо подальших записів у списку ключів не існує.

Нотатки щодо обходу записів:

=over 4

=item *

Викликати C<guestfs_set_private> під час обходу списку записів не можна.

=item *

Дескриптор супроводжує внутрішній ітератор, значення якого буде скинуто, як
ви викличете C<guestfs_first_private>. Внутрішній ітератор втратить
чинність, якщо буде викликано C<guestfs_set_private>.

=item *

Якщо вами встановлено для вказівника на дані, пов'язаного із ключем,
значення C<NULL>, тобто:

 guestfs_set_private (g, key, NULL);

цей ключ C<key> не буде повернуто під час обходу списку.

=item *

C<*key_rtn> є чинним лише до наступного виклику C<guestfs_first_private>,
C<guestfs_next_private> або C<guestfs_set_private>.

=back

У наведеному нижче прикладі коду показано, як вивести усі ключі і вказівники
на дані, які пов'язано із дескриптором C<g>:

 const char *key;
 void *data = guestfs_first_private (g, &key);
 while (data != NULL)
   {
     printf ("key = %s, data = %p\n", key, data);
     data = guestfs_next_private (g, &key);
   }

Типово, вам потрібні будуть лише ключі, кі починаються зі специфічного для
програми префікса C<foo_>. Змініть цикл ось так:

 const char *key;
 void *data = guestfs_first_private (g, &key);
 while (data != NULL)
   {
     if (strncmp (key, "foo_", strlen ("foo_")) == 0)
       printf ("key = %s, data = %p\n", key, data);
     data = guestfs_next_private (g, &key);
   }

Якщо під час обходу ви хочете змінювати ключі, вам слід перестрибувати до
початку циклу. Наприклад, щоб вилучити усі ключі з префіксом C<foo_>,
зробіть так:

  const char *key;
  void *data;
 again:
  data = guestfs_first_private (g, &key);
  while (data != NULL)
    {
      if (strncmp (key, "foo_", strlen ("foo_")) == 0)
        {
          guestfs_set_private (g, key, NULL);
          /* зауважте, що вказівник 'key' тепер є некоректним, як і
             внутрішній ітератор */
          goto again;
        }
      data = guestfs_next_private (g, &key);
    }

Зауважте, що наведений вище цикл завжди завершуватиметься, оскільки ключі
вилучаються. Втім, інші дії з ключами у циклі можуть призвести до того, що
програма не зможе вийти з циклу, якщо не вестиметься супровід списку вже
відвіданих ключів.

=head1 SYSTEMTAP

Бібліотеку C libguestfs можна зондувати за допомогою systemtap або
DTrace. Це стосується будь-якої бібліотеки, не лише libguestfs. Втім, у
libguestfs також є статичні позначки, які спрощують зондування внутрішніх
дій.

Отримати список статичних позначок можна такою командою:

 stap -l 'process("/usr/lib*/libguestfs.so.0")
              .provider("guestfs").mark("*")'

B<Зауваження:> ці статичні позначки I<не> є частиною стабільного програмного
інтерфейсу, їх може бути змінено у майбутніх версіях.

=head2 ПРИКЛАД СКРИПТУ SYSTEMTAP

Цей скрипт містить приклади показу статичних позначок і деяких звичайних
точок входу C:

 global last;
 
 function display_time () {
       now = gettimeofday_us ();
       delta = 0;
       if (last > 0)
             delta = now - last;
       last = now;
 
       printf ("%d (+%d):", now, delta);
 }
 
 probe begin {
       last = 0;
       printf ("ready\n");
 }
 
 /* Показати усі виклики статичних маркерів. */
 probe process("/usr/lib*/libguestfs.so.0")
           .provider("guestfs").mark("*") ? {
       display_time();
       printf ("\t%s %s\n", $$name, $$parms);
 }
 
 /* Показати усі виклики функцій guestfs_mkfs*. */
 probe process("/usr/lib*/libguestfs.so.0")
           .function("guestfs_mkfs*") ? {
       display_time();
       printf ("\t%s %s\n", probefunc(), $$parms);
 }

Наведений вище скрипт можна зберегти із назвою F<test.stap> і запустити його
за допомогою програми L<stap(1)>. Зауважте, що вам знадобляться або права
доступу root, або треба буде додати вашого користувача до декількох
спеціалізованих груп stap. Зверніться до документації із systemtap, щоб
дізнатися більше.

 # stap /tmp/test.stap
 ready

У іншому терміналі запустіть програму guestfish ось так:

 guestfish -N fs

У першому терміналі виведені stap дані трасування будуть подібними до таких:

 1318248056692655 (+0):	launch_start
 1318248056692850 (+195):       launch_build_appliance_start
 1318248056818285 (+125435):    launch_build_appliance_end
 1318248056838059 (+19774):     launch_run_qemu
 1318248061071167 (+4233108):   launch_end
 1318248061280324 (+209157):    guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60

=head1 НУМЕРАЦІЯ ВЕРСІЙ LIBGUESTFS

З квітня 2010 року розпочалася окрема історія розробки libguestfs і
стабільні випуски бібліотеки, які позначалися відповідними гілками у нашому
сховищі коду git. Ці окремі випуски можна визначити за номерами версій:

                 парні номери для стабільних: 1.2.x, 1.4.x, ...
       .-------- непарні номери для тестових: 1.3.x, 1.5.x, ...
       |
       v
 1  .  3  .  5
 ^           ^
 |           |
 |           `-------- підверсія
 |
 `------ завжди «1», оскільки ми не міняємо ABI

Таким чином, «1.3.5» — це п'яте оновлення у гілці для розробки «1.3».

З часом ми переносимо виправлення із гілки для розробки і портуємо їх на
стабільну гілку. У результаті з часом стабільна гілка стає стабільнішою, у
ній стає менше вад. Отже, стабільні випуски ідеальні для тих, кому не
потрібні нові можливості, а потрібне лише завжди працездатне програмне
забезпечення.

Наші критерії для зворотного портування змін:

=over 4

=item *

Зміни до документації, які не змінюють код, портуються до попередніх версій,
якщо документація стосується не майбутніх можливостей, якщо таких
можливостей немає у стабільній гілці.

=item *

Портуються до попередніх версій виправлення вад, які не є суперечливими,
виправляють очевидні проблеми і є належним чином перевіреними.

=item *

Портуються до попередніх версії прості переупорядкування коду, які не
стосуються його працездатності. Це ми робимо для того, щоб дві гілки
розробки не дуже різнилися між собою. Це спрощує зворотне портування
майбутніх виправлень.

=item *

Ми I<не> портуємо до попередніх версій нові можливості, нові інструменти
тощо, окрім одного виключного випадку: нова можливість потрібна для
реалізації виправлення важливої вади.

=back

Нова стабільна гілка започатковується тоді, коли ми вважаємо нові можливості
у розробці суттєвими і достатньо новаторськими щодо поточної стабільної
гілки. Коли виконуються ці умови, ми створюємо нову стабільну гілку і нову
гілку для розробки із версіями 1.N.0 і 1.(N+1).0, відповідно [N — парне
число]. На цьому етапі новий стабільний випуск із нуликом наприкінці номера
версії не обов'язково є аж надто стабільним, але з портуванням виправлень із
гілки для розробки стабільна гілка стає все стабільнішою з часом.

=head1 ОБМЕЖЕННЯ

=head2 ОБМЕЖЕННЯ ПРОТОКОЛУ

На внутрішньому рівні libguestfs використовує заснований на повідомленнях
протокол для передавання викликів програмного інтерфейсу і відповідей на них
до малої «базової системи» та з неї (на сторінці підручника
L<guestfs-internals(1)> наведено докладний опис цього). Максимальний розмір
повідомлення, яке використовується у протоколі, трохи менший за 4 МБ. Для
деяких викликів програмного інтерфейсу слід зважати на це обмеження. Виклики
програмного інтерфейсу, яких це стосується, документовано окремо зі
зворотним посиланням на цей розділ документації.

У libguestfs E<lt> 1.19.32 декільком викликам доводилося або кодувати увесь
список аргументів, або кодувати усе повернуте значення (а іноді, і обидва
цих елементи виклику) у єдине повідомлення протоколу. Це призводило до
довільного обмеження щодо об'єму даних, з яким могли впоратися ці
виклики. Наприклад, функція L</guestfs_cat> могла отримати файл, лише якщо
його розмір був меншим за близьке до 4 МБ значення. У пізніших версіях
libguestfs деякі з цих обмежень було знято. Програмні інтерфейси, які раніше
було обмежено, а тепер не обмежено (окрім, можливо, доступної пам'яті у
системі), наведено у списку нижче. Щоб визначити, чи підлягає певний
програмний інтерфейс обмеженням за протоколом, пошукайте у документації із
програмного інтерфейсу попередження із посиланням на цей розділ. Не
забувайте також користуватися версією документації, яка збігається із
версією libguestfs, якою ви користуєтеся.

L</guestfs_cat>, L</guestfs_find>, L</guestfs_read_file>,
L</guestfs_read_lines>, L</guestfs_write>, L</guestfs_write_append>,
L</guestfs_lstatlist>, L</guestfs_lxattrlist>, L</guestfs_readlinklist>,
L</guestfs_ls>.

Див. також розділи L</ВИВАНТАЖЕННЯ> і L</ОТРИМАННЯ>, щоб дізнатися більше
про копіювання значних обсягів даних до файлової системи та з неї.

=head2 МАКСИМАЛЬНА КІЛЬКІСТЬ ДИСКІВ

У libguestfs E<ge> 1.19.7 ви можете отримати максимальну кількість дисків,
які може бути додано, за допомогою команди L</guestfs_max_disks>. У
попередніх версіях libguestfs (тобто версіях, де цієї команди не було) вам
слід користуватися типовим значенням цієї кількості — 25.

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

Якщо використовуються диски virtio-scsi (типовий режим, якщо він доступний,
у qemu), поточним обмеженням є кількість у B<255> дисків. Якщо
використовуються диски virtio-blk (типовий режим у застарілих версіях)
кількість дисків обмежено B<27>. Останнє обмеження може бути іншим, залежно
від подробиць реалізації та того, чи увімкнено роботу у мережі.

Virtio-scsi, як воно використовується у libguestfs, налаштовано на
використання одного диска призначення, доступними є 256 призначень.

Virtio-blk споживає 1 віртуальний слот PCI на диск, а кількість слотів PCI
обмежено значенням 31, але деякі зі слотів використовуються для інших
потреб.

Один віртуальний диск використовується libguestfs для виконання внутрішніх
завдань.

До версії libguestfs 1.19.7 назви дисків мали складатися із одного символу
(наприклад, від F</dev/sda> до F</dev/sdz>), а оскільки один диск було
зарезервовано, це означало, що дисків могло бути не більше 25. Цю ваду
виправлено у новіших версіях бібліотеки.

У libguestfs E<ge> 1.20 передбачено можливість з'єднання дисків у «гарячому»
режимі. Див. L</З'ЄДНАННЯ У «ГАРЯЧОМУ» РЕЖИМІ>.

=head2 МАКСИМАЛЬНА КІЛЬКІСТЬ РОЗДІЛІВ НА ОДНОМУ ДИСКУ

Virtio обмежує максимальну кількість розділів на диску значенням B<15>.

Причиною є те, що інтерфейс резервує 4 біти для номера підлеглого пристрою
(отже, F</dev/vda> може містити розділи від F</dev/vda1> до F</dev/vda15>).

Якщо ви долучите диски, на яких понад 15 розділів, «зайві» розділи
ігноруватимуться у libguestfs.

=head2 МАКСИМАЛЬНИЙ РОЗМІР ДИСКА

Ймовірно, верхня межа перебуває між 2**63-1 і 2**64-1 байтами.

Нами було перевірено працездатність блокових пристроїв аж до 1 ексабайта
(2**60 або 1.152.921.504.606.846.976 байтів) із використанням розріджених
файлів, що зберігалися на файловій системі XFS основної операційної системи.

Хоча, ймовірно, libguestfs не накладає жодних обмежень, базове сховище даних
у основній операційній системі може накладати такі обмеження. Якщо ви
зберігаєте образи дисків на файловій системі ext4 у основній операційній
системі, максимальний розмір образу буде обмежено максимальним розміром
файла у ext4 (у поточній версії — 16 ТБ). Якщо ви зберігаєте образи дисків
як логічні томи у основній операційній системі, розмір образу буде обмежено
максимальним розміром логічного тому.

Для величезних файлів образів дисків ми рекомендуємо використовувати XFS для
збереження даних у основній операційній системі.

=head2 МАКСИМАЛЬНИЙ РОЗМІР РОЗДІЛУ

Схема поділу на розділи MBR (тобто класична для MS-DOS схема) використовує
32-бітові номери секторів. Якщо розмір сектору дорівнює 512 байтів, у MBR не
можна буде записати адреси розділів, розташовані за межею у  2 ТБ на диску.

Якщо розмір диска перевищує 2 ТБ, рекомендуємо вам використовувати таблицю
розділів GPT. У GPT використовуються 64-бітові номери секторів, отже,
теоретично, можна адресувати диски, об'єм яких перевищує найбільший
підтримуваний у нашій бібліотеці розмір.

=head2 МАКСИМАЛЬНИЙ РОЗМІР ФАЙЛОВОЇ СИСТЕМИ, ФАЙЛІВ, КАТАЛОГІВ

Це залежить від типу файлової системи. Сама libguestfs не накладає жодних
відомих обмежень. Зверніться до Вікіпедії та документації із файлової
системи, щоб ознайомитися із обмеженнями, які накладає файлова система.

=head2 МАКСИМАЛЬНІ ОБСЯГИ ВИВАНТАЖЕННЯ І ОТРИМАННЯ ДАНИХ

Функції програмного інтерфейсу L</guestfs_upload>, L</guestfs_download>,
L</guestfs_tar_in>, L</guestfs_tar_out> та подібні до них функції не
обмежують обсяги вивантаження та отримання даних.

=head2 ОБМЕЖЕННЯ ІНСПЕКТУВАННЯ

У коді засобу інспектування передбачено декілька довільних обмежень на речі,
подібні до розміру рою реєстру Windows, який він може прочитати, та довжини
назви продукту. Ці обмеження введено навмисно, щоб запобігти можливості
споживання довільних обсягів пам'яті та місця на диску в основній системі
для створених зловмисниками образів систем. Втім, на практиці ці обмеження
ніколи не перевищуються. Ознайомтеся із початковим кодом бібліотеки, щоб
дізнатися більше.

=head1 РОЗШИРЕНЕ ПРИДАТНЕ ДО ЧИТАННЯ КОМП'ЮТЕРОМ ВИВЕДЕННЯ

У деяких з програм передбачено параметр I<--machine-readable>, який загалом
використовується для виведення даних у зручнішому для машинної обробки
форматі. Типово, виведені дані спрямовуватимуться до stdout.

When using the I<--machine-readable> option, the progress, information,
warning, and error messages are also printed in JSON format for easier log
tracking.  Thus, it is highly recommended to redirect the machine-readable
output to a different stream.  The format of these JSON messages is like the
following (actually printed within a single line, below it is indented for
readability):

 {
   "message": "Finishing off",
   "timestamp": "2019-03-22T14:46:49.067294446+01:00",
   "type": "message"
 }

C<type> can be: C<message> for progress messages, C<info> for information
messages, C<warning> for warning messages, and C<error> for error message.
C<timestamp> is the L<RFC 3339|https://www.ietf.org/rfc/rfc3339.txt>
timestamp of the message.

Крім того, у деяких програмах передбачено підтримку додаткового рядка, який
передається параметру I<--machine-readable>: цей рядок, визначає, куди слід
спрямовувати виведення зручних для машинної обробки даних.

Можливі значення:

=over 4

=item B<fd:>I<fd>

The output goes to the specified I<fd>, which is a file descriptor already
opened for writing.

=item B<file:>F<назва_файла>

Дані буде виведено до вказаного файла F<назва_файла>.

=item B<stream:stdout>

Виведені дані спрямовуються до stdout. Загалом, те саме, що і типова
поведінка I<--machine-readable> без параметра, але тут stdout вказується для
виведення явним чином.

=item B<stream:stderr>

Виведення спрямовується до stderr.

=back

=head1 ЗМІННІ СЕРЕДОВИЩА

=over 4

=item LIBGUESTFS_APPEND

Передати додаткові параметри ядру гостьової системи.

=item LIBGUESTFS_ATTACH_METHOD

Це старий спосіб визначити C<LIBGUESTFS_BACKEND>.

=item LIBGUESTFS_BACKEND

Вибрати типовий спосіб створення базової
системи. Див. L</guestfs_set_backend> і L</МОДУЛЬ>.

=item LIBGUESTFS_BACKEND_SETTINGS

Список відокремлених двокрапками параметрів, специфічних для модуля
обробки. Див. L</МОДУЛЬ>, L</ПАРАМЕТРИ МОДУЛЯ>.

=item LIBGUESTFS_CACHEDIR

Місце, де зберігатиметься кеш базової системи libguestfs, якщо
використовується базова система supermin. Базова система кешується і спільно
використовується усіма дескрипторами, які мають однаковий ідентифікатор
ефективного користувача.

Якщо значення C<LIBGUESTFS_CACHEDIR> не встановлено, буде використано
C<TMPDIR>. Якщо не встановлено значення C<TMPDIR>, буде використано
F</var/tmp>.

Див. також L</LIBGUESTFS_TMPDIR>, L</guestfs_set_cachedir>.

=item LIBGUESTFS_DEBUG

Встановіть значення C<LIBGUESTFS_DEBUG=1>, щоб увімкнути режим докладних
повідомлень. Той самий ефект має виклик C<guestfs_set_verbose (g, 1)>.

=item LIBGUESTFS_HV

Встановити типовий виконуваний файл гіпервізору (зазвичай, qemu), яким
користуватиметься libguestfs. Якщо не встановлено, буде використано qemu,
знайдений скриптом налаштовування під час збирання.

Див. також L</ОБГОРТКИ QEMU> вище.

=item LIBGUESTFS_MEMSIZE

Встановлює обсяг пам'яті, який надається процесу qemu, у
мегабайтах. Приклад:

 LIBGUESTFS_MEMSIZE=700

=item LIBGUESTFS_PATH

Встановити шлях, яким libguestfs користуватиметься для пошуку базової
системи supermin. Ознайомтеся із обговоренням щодо шляхів у розділі L</ШЛЯХ>
вище.

=item LIBGUESTFS_QEMU

Це застарілий спосіб встановлення C<LIBGUESTFS_HV>.

=item LIBGUESTFS_TMPDIR

Місце, де libguestfs зберігатиме тимчасові файли, які використовуються
кожним з дескрипторів.

Якщо значення C<LIBGUESTFS_TMPDIR> не встановлено, буде використано
C<TMPDIR>. Якщо не встановлено значення C<TMPDIR>, буде використано F</tmp>.

Див. також L</LIBGUESTFS_CACHEDIR>, L</guestfs_set_tmpdir>.

=item LIBGUESTFS_TRACE

Встановіть значення C<LIBGUESTFS_TRACE=1>, щоб увімкнути трасування
команд. Той самий ефект має виклик C<guestfs_set_trace (g, 1)>.

=item ШЛЯХ

Libguestfs може запускати зовнішні програми. Бібліотека покладається на те,
що вміст змінної C<$PATH> встановлено належним чином. Якщо використовується
модуль обробки libvirt, libvirt не працюватиме взагалі, якщо у C<$PATH> не
міститиметься шляху до qemu/KVM. Зауважте, що типово PHP вилучає C<$PATH> з
середовища, що може зруйнувати усі зв'язки у ньому.

=item SUPERMIN_KERNEL

=item SUPERMIN_KERNEL_VERSION

=item SUPERMIN_MODULES

За допомогою цих трьох змінних середовища можна вибрати ядро, яке libguestfs
використовуватиме у базовій системі. Якщо не встановлено
C<$SUPERMIN_KERNEL>, буде вибрано найсвіжіше з ядер основної
системи. Докладніший опис вибору ядра можна знайти на сторінці підручника
щодо L<supermin(1)>.

=item ТИМЧАСОВИЙ КАТАЛОГ

Див. L</LIBGUESTFS_CACHEDIR>, L</LIBGUESTFS_TMPDIR>.

=item XDG_RUNTIME_DIR

Цей каталог є специфічним каталогом користувача, який призначено для
зберігання неважливих файлів під час роботи.

Якщо встановлено, використовується для зберігання тимчасових сокетів. Якщо
не встановлено, використовується F</tmp>.

Див. також L</get-sockdir>,
L<http://www.freedesktop.org/wiki/Specifications/basedir-spec/>.

=back

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

Приклади мовою програмування C: L<guestfs-examples(3)>.

Прив'язки до мов програмування: L<guestfs-erlang(3)>, L<guestfs-gobject(3)>,
L<guestfs-golang(3)>, L<guestfs-java(3)>, L<guestfs-lua(3)>,
L<guestfs-ocaml(3)>, L<guestfs-perl(3)>, L<guestfs-python(3)>,
L<guestfs-ruby(3)>.

Інструменти: L<guestfish(1)>, L<guestmount(1)>, L<virt-alignment-scan(1)>,
L<virt-builder(1)>, L<virt-builder-repository(1)>, L<virt-cat(1)>,
L<virt-copy-in(1)>, L<virt-copy-out(1)>, L<virt-customize(1)>,
L<virt-df(1)>, L<virt-diff(1)>, L<virt-edit(1)>, L<virt-filesystems(1)>,
L<virt-format(1)>, L<virt-inspector(1)>, L<virt-list-filesystems(1)>,
L<virt-list-partitions(1)>, L<virt-log(1)>, L<virt-ls(1)>,
L<virt-make-fs(1)>, L<virt-p2v(1)>, L<virt-rescue(1)>, L<virt-resize(1)>,
L<virt-sparsify(1)>, L<virt-sysprep(1)>, L<virt-tail(1)>, L<virt-tar(1)>,
L<virt-tar-in(1)>, L<virt-tar-out(1)>, L<virt-v2v(1)>, L<virt-win-reg(1)>.

Інші питання щодо libguestfs: L<guestfs-building(1)>, L<guestfs-faq(1)>,
L<guestfs-hacking(1)>, L<guestfs-internals(1)>, L<guestfs-performance(1)>,
L<guestfs-release-notes(1)>, L<guestfs-security(1)>, L<guestfs-testing(1)>,
L<libguestfs-test-tool(1)>, L<libguestfs-make-fixed-appliance(1)>.

Пов’язані сторінки підручника: L<supermin(1)>, L<qemu(1)>, L<hivex(3)>,
L<stap(1)>, L<sd-journal(3)>.

Сайт: L<http://libguestfs.org/>

Інструменти подібного призначення: L<fdisk(8)>, L<parted(8)>, L<kpartx(8)>,
L<lvm(8)>, L<disktype(1)>.

=head1 АВТОРИ

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

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

Copyright (C) 2009-2020 Red Hat Inc.