1 # SOME DESCRIPTIVE TITLE.
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
8 "Project-Id-Version: PACKAGE VERSION\n"
9 "Report-Msgid-Bugs-To: libguestfs@redhat.com\n"
10 "POT-Creation-Date: 2010-09-08 11:40+0200\n"
11 "PO-Revision-Date: 2010-09-02 14:46+0100\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
15 "Content-Type: text/plain; charset=UTF-8\n"
16 "Content-Transfer-Encoding: 8bit\n"
19 #: ../src/guestfs.pod:1 ../fish/guestfish.pod:1
20 #: ../test-tool/libguestfs-test-tool.pod:1 ../fuse/guestmount.pod:1
21 #: ../inspector/virt-inspector.pl:36 ../tools/virt-cat.pl:30
22 #: ../tools/virt-df.pl:32 ../tools/virt-edit.pl:31
23 #: ../tools/virt-list-filesystems.pl:28 ../tools/virt-list-partitions.pl:28
24 #: ../tools/virt-ls.pl:31 ../tools/virt-make-fs.pl:33
25 #: ../tools/virt-rescue.pl:29 ../tools/virt-resize.pl:38
26 #: ../tools/virt-tar.pl:30 ../tools/virt-win-reg.pl:34
31 #: ../src/guestfs.pod:3 ../fish/guestfish.pod:3
32 #: ../test-tool/libguestfs-test-tool.pod:3 ../fuse/guestmount.pod:3
33 #: ../inspector/virt-inspector.pl:38 ../tools/virt-cat.pl:32
34 #: ../tools/virt-df.pl:34 ../tools/virt-edit.pl:33
35 #: ../tools/virt-list-filesystems.pl:30 ../tools/virt-list-partitions.pl:30
36 #: ../tools/virt-ls.pl:33 ../tools/virt-make-fs.pl:35
37 #: ../tools/virt-rescue.pl:31 ../tools/virt-resize.pl:40
38 #: ../tools/virt-tar.pl:32 ../tools/virt-win-reg.pl:36
43 #: ../src/guestfs.pod:5
44 msgid "guestfs - Library for accessing and modifying virtual machine images"
48 #: ../src/guestfs.pod:7 ../fish/guestfish.pod:7
49 #: ../test-tool/libguestfs-test-tool.pod:7 ../fuse/guestmount.pod:7
50 #: ../inspector/virt-inspector.pl:42 ../tools/virt-cat.pl:36
51 #: ../tools/virt-df.pl:38 ../tools/virt-edit.pl:37
52 #: ../tools/virt-list-filesystems.pl:34 ../tools/virt-list-partitions.pl:34
53 #: ../tools/virt-ls.pl:37 ../tools/virt-make-fs.pl:39
54 #: ../tools/virt-rescue.pl:35 ../tools/virt-resize.pl:44
55 #: ../tools/virt-tar.pl:36 ../tools/virt-win-reg.pl:40
60 #: ../src/guestfs.pod:9
63 " #include <guestfs.h>\n"
68 #: ../src/guestfs.pod:11
71 " guestfs_h *g = guestfs_create ();\n"
72 " guestfs_add_drive (g, \"guest.img\");\n"
73 " guestfs_launch (g);\n"
74 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
75 " guestfs_touch (g, \"/hello\");\n"
76 " guestfs_umount (g, \"/\");\n"
77 " guestfs_sync (g);\n"
78 " guestfs_close (g);\n"
83 #: ../src/guestfs.pod:20
86 " cc prog.c -o prog -lguestfs\n"
88 " cc prog.c -o prog `pkg-config libguestfs --cflags --libs`\n"
93 #: ../src/guestfs.pod:24 ../fish/guestfish.pod:115
94 #: ../test-tool/libguestfs-test-tool.pod:11 ../fuse/guestmount.pod:16
95 #: ../inspector/virt-inspector.pl:48 ../tools/virt-cat.pl:42
96 #: ../tools/virt-df.pl:46 ../tools/virt-edit.pl:51
97 #: ../tools/virt-list-filesystems.pl:40 ../tools/virt-list-partitions.pl:40
98 #: ../tools/virt-ls.pl:43 ../tools/virt-make-fs.pl:47
99 #: ../tools/virt-rescue.pl:51 ../tools/virt-resize.pl:50
100 #: ../tools/virt-tar.pl:73 ../tools/virt-win-reg.pl:64
105 #: ../src/guestfs.pod:26
107 "Libguestfs is a library for accessing and modifying guest disk images. "
108 "Amongst the things this is good for: making batch configuration changes to "
109 "guests, getting disk used/free statistics (see also: virt-df), migrating "
110 "between virtualization systems (see also: virt-p2v), performing partial "
111 "backups, performing partial guest clones, cloning guests and changing "
112 "registry/UUID/hostname info, and much else besides."
116 #: ../src/guestfs.pod:34
118 "Libguestfs uses Linux kernel and qemu code, and can access any type of guest "
119 "filesystem that Linux and qemu can, including but not limited to: ext2/3/4, "
120 "btrfs, FAT and NTFS, LVM, many different disk partition schemes, qcow, "
125 #: ../src/guestfs.pod:39
127 "Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, "
128 "what filesystem is in each LV, etc.). It can also run commands in the "
129 "context of the guest. Also you can access filesystems over FUSE."
133 #: ../src/guestfs.pod:44
135 "Libguestfs is a library that can be linked with C and C++ management "
136 "programs (or management programs written in OCaml, Perl, Python, Ruby, Java, "
137 "PHP, Haskell or C#). You can also use it from shell scripts or the command "
142 #: ../src/guestfs.pod:49
144 "You don't need to be root to use libguestfs, although obviously you do need "
145 "enough permissions to access the disk images."
149 #: ../src/guestfs.pod:52
151 "Libguestfs is a large API because it can do many things. For a gentle "
152 "introduction, please read the L</API OVERVIEW> section next."
156 #: ../src/guestfs.pod:55
161 #: ../src/guestfs.pod:57
163 "This section provides a gentler overview of the libguestfs API. We also try "
164 "to group API calls together, where that may not be obvious from reading "
165 "about the individual calls in the main section of this manual."
169 #: ../src/guestfs.pod:62
174 #: ../src/guestfs.pod:64
176 "Before you can use libguestfs calls, you have to create a handle. Then you "
177 "must add at least one disk image to the handle, followed by launching the "
178 "handle, then performing whatever operations you want, and finally closing "
179 "the handle. By convention we use the single letter C<g> for the name of the "
180 "handle variable, although of course you can use any name you want."
184 #: ../src/guestfs.pod:71
185 msgid "The general structure of all libguestfs-using programs looks like this:"
189 #: ../src/guestfs.pod:74
192 " guestfs_h *g = guestfs_create ();\n"
197 #: ../src/guestfs.pod:76
200 " /* Call guestfs_add_drive additional times if there are\n"
201 " * multiple disk images.\n"
203 " guestfs_add_drive (g, \"guest.img\");\n"
208 #: ../src/guestfs.pod:81
211 " /* Most manipulation calls won't work until you've launched\n"
212 " * the handle 'g'. You have to do this _after_ adding drives\n"
213 " * and _before_ other commands.\n"
215 " guestfs_launch (g);\n"
220 #: ../src/guestfs.pod:87
223 " /* Now you can examine what partitions, LVs etc are available.\n"
225 " char **partitions = guestfs_list_partitions (g);\n"
226 " char **logvols = guestfs_lvs (g);\n"
231 #: ../src/guestfs.pod:92
234 " /* To access a filesystem in the image, you must mount it.\n"
236 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
241 #: ../src/guestfs.pod:96
244 " /* Now you can perform filesystem actions on the guest\n"
247 " guestfs_touch (g, \"/hello\");\n"
252 #: ../src/guestfs.pod:101
255 " /* You only need to call guestfs_sync if you have made\n"
256 " * changes to the guest image. (But if you've made changes\n"
257 " * then you *must* sync). See also: guestfs_umount and\n"
258 " * guestfs_umount_all calls.\n"
260 " guestfs_sync (g);\n"
265 #: ../src/guestfs.pod:108
268 " /* Close the handle 'g'. */\n"
269 " guestfs_close (g);\n"
274 #: ../src/guestfs.pod:111
276 "The code above doesn't include any error checking. In real code you should "
277 "check return values carefully for errors. In general all functions that "
278 "return integers return C<-1> on error, and all functions that return "
279 "pointers return C<NULL> on error. See section L</ERROR HANDLING> below for "
280 "how to handle errors, and consult the documentation for each function call "
281 "below to see precisely how they return error indications."
285 #: ../src/guestfs.pod:119
290 #: ../src/guestfs.pod:121
292 "The image filename (C<\"guest.img\"> in the example above) could be a disk "
293 "image from a virtual machine, a L<dd(1)> copy of a physical hard disk, an "
294 "actual block device, or simply an empty file of zeroes that you have created "
295 "through L<posix_fallocate(3)>. Libguestfs lets you do useful things to all "
300 #: ../src/guestfs.pod:127
302 "You can add a disk read-only using L</guestfs_add_drive_ro>, in which case "
303 "libguestfs won't modify the file."
307 #: ../src/guestfs.pod:130
309 "Be extremely cautious if the disk image is in use, eg. if it is being used "
310 "by a virtual machine. Adding it read-write will almost certainly cause disk "
311 "corruption, but adding it read-only is safe."
315 #: ../src/guestfs.pod:134
317 "You must add at least one disk image, and you may add multiple disk images. "
318 "In the API, the disk images are usually referred to as C</dev/sda> (for the "
319 "first one you added), C</dev/sdb> (for the second one you added), etc."
323 #: ../src/guestfs.pod:139
325 "Once L</guestfs_launch> has been called you cannot add any more images. You "
326 "can call L</guestfs_list_devices> to get a list of the device names, in the "
327 "order that you added them. See also L</BLOCK DEVICE NAMING> below."
331 #: ../src/guestfs.pod:144
336 #: ../src/guestfs.pod:146
338 "Before you can read or write files, create directories and so on in a disk "
339 "image that contains filesystems, you have to mount those filesystems using "
340 "L</guestfs_mount>. If you already know that a disk image contains (for "
341 "example) one partition with a filesystem on that partition, then you can "
346 #: ../src/guestfs.pod:152
349 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
354 #: ../src/guestfs.pod:154
356 "where C</dev/sda1> means literally the first partition (C<1>) of the first "
357 "disk image that we added (C</dev/sda>). If the disk contains Linux LVM2 "
358 "logical volumes you could refer to those instead (eg. C</dev/VG/LV>)."
362 #: ../src/guestfs.pod:158
364 "If you are given a disk image and you don't know what it contains then you "
365 "have to find out. Libguestfs can do that too: use L</"
366 "guestfs_list_partitions> and L</guestfs_lvs> to list possible partitions and "
367 "LVs, and either try mounting each to see what is mountable, or else examine "
368 "them with L</guestfs_vfs_type> or L</guestfs_file>. Libguestfs also has a "
369 "set of APIs for inspection of disk images (see L</INSPECTION> below). But "
370 "you might find it easier to look at higher level programs built on top of "
371 "libguestfs, in particular L<virt-inspector(1)>."
375 #: ../src/guestfs.pod:168
377 "To mount a disk image read-only, use L</guestfs_mount_ro>. There are "
378 "several other variations of the C<guestfs_mount_*> call."
382 #: ../src/guestfs.pod:171
383 msgid "FILESYSTEM ACCESS AND MODIFICATION"
387 #: ../src/guestfs.pod:173
389 "The majority of the libguestfs API consists of fairly low-level calls for "
390 "accessing and modifying the files, directories, symlinks etc on mounted "
391 "filesystems. There are over a hundred such calls which you can find listed "
392 "in detail below in this man page, and we don't even pretend to cover them "
393 "all in this overview."
397 #: ../src/guestfs.pod:179
399 "Specify filenames as full paths, starting with C<\"/\"> and including the "
404 #: ../src/guestfs.pod:182
406 "For example, if you mounted a filesystem at C<\"/\"> and you want to read "
407 "the file called C<\"etc/passwd\"> then you could do:"
411 #: ../src/guestfs.pod:185
414 " char *data = guestfs_cat (g, \"/etc/passwd\");\n"
419 #: ../src/guestfs.pod:187
421 "This would return C<data> as a newly allocated buffer containing the full "
422 "content of that file (with some conditions: see also L</DOWNLOADING> below), "
423 "or C<NULL> if there was an error."
427 #: ../src/guestfs.pod:191
429 "As another example, to create a top-level directory on that filesystem "
430 "called C<\"var\"> you would do:"
434 #: ../src/guestfs.pod:194
437 " guestfs_mkdir (g, \"/var\");\n"
442 #: ../src/guestfs.pod:196
443 msgid "To create a symlink you could do:"
447 #: ../src/guestfs.pod:198
450 " guestfs_ln_s (g, \"/etc/init.d/portmap\",\n"
451 " \"/etc/rc3.d/S30portmap\");\n"
456 #: ../src/guestfs.pod:201
458 "Libguestfs will reject attempts to use relative paths and there is no "
459 "concept of a current working directory."
463 #: ../src/guestfs.pod:204
465 "Libguestfs can return errors in many situations: for example if the "
466 "filesystem isn't writable, or if a file or directory that you requested "
467 "doesn't exist. If you are using the C API (documented here) you have to "
468 "check for those error conditions after each call. (Other language bindings "
469 "turn these errors into exceptions)."
473 #: ../src/guestfs.pod:210
475 "File writes are affected by the per-handle umask, set by calling L</"
476 "guestfs_umask> and defaulting to 022. See L</UMASK>."
480 #: ../src/guestfs.pod:213
485 #: ../src/guestfs.pod:215
487 "Libguestfs contains API calls to read, create and modify partition tables on "
492 #: ../src/guestfs.pod:218
494 "In the common case where you want to create a single partition covering the "
495 "whole disk, you should use the L</guestfs_part_disk> call:"
499 #: ../src/guestfs.pod:222
502 " const char *parttype = \"mbr\";\n"
503 " if (disk_is_larger_than_2TB)\n"
504 " parttype = \"gpt\";\n"
505 " guestfs_part_disk (g, \"/dev/sda\", parttype);\n"
510 #: ../src/guestfs.pod:227
512 "Obviously this effectively wipes anything that was on that disk image before."
516 #: ../src/guestfs.pod:230
521 #: ../src/guestfs.pod:232
523 "Libguestfs provides access to a large part of the LVM2 API, such as L</"
524 "guestfs_lvcreate> and L</guestfs_vgremove>. It won't make much sense unless "
525 "you familiarize yourself with the concepts of physical volumes, volume "
526 "groups and logical volumes."
530 #: ../src/guestfs.pod:237
532 "This author strongly recommends reading the LVM HOWTO, online at L<http://"
533 "tldp.org/HOWTO/LVM-HOWTO/>."
537 #: ../src/guestfs.pod:240
542 #: ../src/guestfs.pod:242
544 "Use L</guestfs_cat> to download small, text only files. This call is "
545 "limited to files which are less than 2 MB and which cannot contain any ASCII "
546 "NUL (C<\\0>) characters. However it has a very simple to use API."
550 #: ../src/guestfs.pod:247
552 "L</guestfs_read_file> can be used to read files which contain arbitrary 8 "
553 "bit data, since it returns a (pointer, size) pair. However it is still "
554 "limited to \"small\" files, less than 2 MB."
558 #: ../src/guestfs.pod:251
560 "L</guestfs_download> can be used to download any file, with no limits on "
561 "content or size (even files larger than 4 GB)."
565 #: ../src/guestfs.pod:254
567 "To download multiple files, see L</guestfs_tar_out> and L</guestfs_tgz_out>."
571 #: ../src/guestfs.pod:257
576 #: ../src/guestfs.pod:259
578 "It's often the case that you want to write a file or files to the disk image."
582 #: ../src/guestfs.pod:262
584 "To write a small file with fixed content, use L</guestfs_write>. To create "
585 "a file of all zeroes, use L</guestfs_truncate_size> (sparse) or L</"
586 "guestfs_fallocate64> (with all disk blocks allocated). There are a variety "
587 "of other functions for creating test files, for example L</guestfs_fill> and "
588 "L</guestfs_fill_pattern>."
592 #: ../src/guestfs.pod:268
594 "To upload a single file, use L</guestfs_upload>. This call has no limits on "
595 "file content or size (even files larger than 4 GB)."
599 #: ../src/guestfs.pod:271
601 "To upload multiple files, see L</guestfs_tar_in> and L</guestfs_tgz_in>."
605 #: ../src/guestfs.pod:273
607 "However the fastest way to upload I<large numbers of arbitrary files> is to "
608 "turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and L<mkisofs(8)"
609 ">), then attach this using L</guestfs_add_drive_ro>. If you add the drive "
610 "in a predictable way (eg. adding it last after all other drives) then you "
611 "can get the device name from L</guestfs_list_devices> and mount it directly "
612 "using L</guestfs_mount_ro>. Note that squashfs images are sometimes non-"
613 "portable between kernel versions, and they don't support labels or UUIDs. "
614 "If you want to pre-build an image or you need to mount it using a label or "
615 "UUID, use an ISO image instead."
619 #: ../src/guestfs.pod:284
624 #: ../src/guestfs.pod:286
626 "There are various different commands for copying between files and devices "
627 "and in and out of the guest filesystem. These are summarised in the table "
632 #: ../src/guestfs.pod:292
633 msgid "B<file> to B<file>"
637 #: ../src/guestfs.pod:294
639 "Use L</guestfs_cp> to copy a single file, or L</guestfs_cp_a> to copy "
640 "directories recursively."
644 #: ../src/guestfs.pod:297
645 msgid "B<file or device> to B<file or device>"
649 #: ../src/guestfs.pod:299
651 "Use L</guestfs_dd> which efficiently uses L<dd(1)> to copy between files and "
652 "devices in the guest."
656 #: ../src/guestfs.pod:302
657 msgid "Example: duplicate the contents of an LV:"
661 #: ../src/guestfs.pod:304
664 " guestfs_dd (g, \"/dev/VG/Original\", \"/dev/VG/Copy\");\n"
669 #: ../src/guestfs.pod:306
671 "The destination (C</dev/VG/Copy>) must be at least as large as the source "
672 "(C</dev/VG/Original>). To copy less than the whole source device, use L</"
673 "guestfs_copy_size>."
677 #: ../src/guestfs.pod:310
678 msgid "B<file on the host> to B<file or device>"
682 #: ../src/guestfs.pod:312
683 msgid "Use L</guestfs_upload>. See L</UPLOADING> above."
687 #: ../src/guestfs.pod:314
688 msgid "B<file or device> to B<file on the host>"
692 #: ../src/guestfs.pod:316
693 msgid "Use L</guestfs_download>. See L</DOWNLOADING> above."
697 #: ../src/guestfs.pod:320
698 msgid "LISTING FILES"
702 #: ../src/guestfs.pod:322
704 "L</guestfs_ll> is just designed for humans to read (mainly when using the "
705 "L<guestfish(1)>-equivalent command C<ll>)."
709 #: ../src/guestfs.pod:325
711 "L</guestfs_ls> is a quick way to get a list of files in a directory from "
712 "programs, as a flat list of strings."
716 #: ../src/guestfs.pod:328
718 "L</guestfs_readdir> is a programmatic way to get a list of files in a "
719 "directory, plus additional information about each one. It is more "
720 "equivalent to using the L<readdir(3)> call on a local filesystem."
724 #: ../src/guestfs.pod:332
726 "L</guestfs_find> and L</guestfs_find0> can be used to recursively list files."
730 #: ../src/guestfs.pod:335
731 msgid "RUNNING COMMANDS"
735 #: ../src/guestfs.pod:337
737 "Although libguestfs is a primarily an API for manipulating files inside "
738 "guest images, we also provide some limited facilities for running commands "
743 #: ../src/guestfs.pod:341
744 msgid "There are many limitations to this:"
748 #: ../src/guestfs.pod:345 ../src/guestfs.pod:350 ../src/guestfs.pod:355
749 #: ../src/guestfs.pod:359 ../src/guestfs.pod:364 ../src/guestfs.pod:368
750 #: ../src/guestfs.pod:373 ../src/guestfs.pod:1226 ../src/guestfs.pod:1231
751 #: ../src/guestfs.pod:1235 ../src/guestfs.pod:1337 ../src/guestfs.pod:1341
752 #: ../src/guestfs.pod:1345 ../src/guestfs.pod:1350 ../src/guestfs.pod:1358
753 #: ../src/guestfs.pod:1377 ../src/guestfs.pod:1385 ../src/guestfs.pod:1599
754 #: ../src/guestfs.pod:1605 ../src/guestfs.pod:1610 ../src/guestfs.pod:1616
755 #: ../src/guestfs.pod:1723 ../src/guestfs.pod:1727 ../src/guestfs.pod:1731
756 #: ../src/guestfs.pod:1735 ../src/guestfs-actions.pod:14
757 #: ../src/guestfs-actions.pod:21 ../src/guestfs-actions.pod:372
758 #: ../src/guestfs-actions.pod:380 ../src/guestfs-actions.pod:387
759 #: ../src/guestfs-actions.pod:394 ../src/guestfs-actions.pod:1257
760 #: ../src/guestfs-actions.pod:1261 ../src/guestfs-actions.pod:1265
761 #: ../src/guestfs-actions.pod:1269 ../src/guestfs-actions.pod:1277
762 #: ../src/guestfs-actions.pod:1281 ../src/guestfs-actions.pod:1285
763 #: ../src/guestfs-actions.pod:1295 ../src/guestfs-actions.pod:1299
764 #: ../src/guestfs-actions.pod:1303 ../src/guestfs-actions.pod:1426
765 #: ../src/guestfs-actions.pod:1430 ../src/guestfs-actions.pod:1435
766 #: ../src/guestfs-actions.pod:1440 ../src/guestfs-actions.pod:1492
767 #: ../src/guestfs-actions.pod:1496 ../src/guestfs-actions.pod:1501
768 #: ../fish/guestfish.pod:309 ../fish/guestfish.pod:313
769 #: ../fish/guestfish.pod:317 ../fish/guestfish.pod:321
770 #: ../fish/guestfish-actions.pod:13 ../fish/guestfish-actions.pod:20
771 #: ../fish/guestfish-actions.pod:300 ../fish/guestfish-actions.pod:308
772 #: ../fish/guestfish-actions.pod:315 ../fish/guestfish-actions.pod:322
773 #: ../fish/guestfish-actions.pod:998 ../fish/guestfish-actions.pod:1002
774 #: ../fish/guestfish-actions.pod:1006 ../fish/guestfish-actions.pod:1010
775 #: ../fish/guestfish-actions.pod:1018 ../fish/guestfish-actions.pod:1022
776 #: ../fish/guestfish-actions.pod:1026 ../fish/guestfish-actions.pod:1036
777 #: ../fish/guestfish-actions.pod:1040 ../fish/guestfish-actions.pod:1044
778 #: ../fish/guestfish-actions.pod:1134 ../fish/guestfish-actions.pod:1138
779 #: ../fish/guestfish-actions.pod:1143 ../fish/guestfish-actions.pod:1148
780 #: ../fish/guestfish-actions.pod:1190 ../fish/guestfish-actions.pod:1194
781 #: ../fish/guestfish-actions.pod:1199 ../tools/virt-resize.pl:324
782 #: ../tools/virt-resize.pl:329 ../tools/virt-resize.pl:339
787 #: ../src/guestfs.pod:347
789 "The kernel version that the command runs under will be different from what "
794 #: ../src/guestfs.pod:352
796 "If the command needs to communicate with daemons, then most likely they "
801 #: ../src/guestfs.pod:357
802 msgid "The command will be running in limited memory."
806 #: ../src/guestfs.pod:361
808 "The network may not be available unless you enable it (see L</"
809 "guestfs_set_network>)."
813 #: ../src/guestfs.pod:366
814 msgid "Only supports Linux guests (not Windows, BSD, etc)."
818 #: ../src/guestfs.pod:370
820 "Architecture limitations (eg. won't work for a PPC guest on an X86 host)."
824 #: ../src/guestfs.pod:375
826 "For SELinux guests, you may need to enable SELinux and load policy first. "
827 "See L</SELINUX> in this manpage."
831 #: ../src/guestfs.pod:380
833 "The two main API calls to run commands are L</guestfs_command> and L</"
834 "guestfs_sh> (there are also variations)."
838 #: ../src/guestfs.pod:383
840 "The difference is that L</guestfs_sh> runs commands using the shell, so any "
841 "shell globs, redirections, etc will work."
845 #: ../src/guestfs.pod:386
846 msgid "CONFIGURATION FILES"
850 #: ../src/guestfs.pod:388
852 "To read and write configuration files in Linux guest filesystems, we "
853 "strongly recommend using Augeas. For example, Augeas understands how to "
854 "read and write, say, a Linux shadow password file or X.org configuration "
855 "file, and so avoids you having to write that code."
859 #: ../src/guestfs.pod:393
861 "The main Augeas calls are bound through the C<guestfs_aug_*> APIs. We don't "
862 "document Augeas itself here because there is excellent documentation on the "
863 "L<http://augeas.net/> website."
867 #: ../src/guestfs.pod:397
869 "If you don't want to use Augeas (you fool!) then try calling L</"
870 "guestfs_read_lines> to get the file as a list of lines which you can iterate "
875 #: ../src/guestfs.pod:401
880 #: ../src/guestfs.pod:403
882 "We support SELinux guests. To ensure that labeling happens correctly in "
883 "SELinux guests, you need to enable SELinux and load the guest's policy:"
887 #: ../src/guestfs.pod:409
892 #: ../src/guestfs.pod:411
893 msgid "Before launching, do:"
897 #: ../src/guestfs.pod:413
900 " guestfs_set_selinux (g, 1);\n"
905 #: ../src/guestfs.pod:415
910 #: ../src/guestfs.pod:417
912 "After mounting the guest's filesystem(s), load the policy. This is best "
913 "done by running the L<load_policy(8)> command in the guest itself:"
917 #: ../src/guestfs.pod:421
920 " guestfs_sh (g, \"/usr/sbin/load_policy\");\n"
925 #: ../src/guestfs.pod:423
927 "(Older versions of C<load_policy> require you to specify the name of the "
932 #: ../src/guestfs.pod:426
937 #: ../src/guestfs.pod:428
939 "Optionally, set the security context for the API. The correct security "
940 "context to use can only be known by inspecting the guest. As an example:"
944 #: ../src/guestfs.pod:432
947 " guestfs_setcon (g, \"unconfined_u:unconfined_r:unconfined_t:s0\");\n"
952 #: ../src/guestfs.pod:436
953 msgid "This will work for running commands and editing existing files."
957 #: ../src/guestfs.pod:438
959 "When new files are created, you may need to label them explicitly, for "
960 "example by running the external command C<restorecon pathname>."
964 #: ../src/guestfs.pod:442
969 #: ../src/guestfs.pod:444
971 "Certain calls are affected by the current file mode creation mask (the "
972 "\"umask\"). In particular ones which create files or directories, such as "
973 "L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>. This affects "
974 "either the default mode that the file is created with or modifies the mode "
979 #: ../src/guestfs.pod:450
981 "The default umask is C<022>, so files are created with modes such as C<0644> "
982 "and directories with C<0755>."
986 #: ../src/guestfs.pod:453
988 "There are two ways to avoid being affected by umask. Either set umask to 0 "
989 "(call C<guestfs_umask (g, 0)> early after launching). Or call L</"
990 "guestfs_chmod> after creating each file or directory."
994 #: ../src/guestfs.pod:457
995 msgid "For more information about umask, see L<umask(2)>."
999 #: ../src/guestfs.pod:459 ../fish/guestfish.pod:559
1000 msgid "ENCRYPTED DISKS"
1004 #: ../src/guestfs.pod:461
1006 "Libguestfs allows you to access Linux guests which have been encrypted using "
1007 "whole disk encryption that conforms to the Linux Unified Key Setup (LUKS) "
1008 "standard. This includes nearly all whole disk encryption systems used by "
1009 "modern Linux guests."
1013 #: ../src/guestfs.pod:467
1015 "Use L</guestfs_vfs_type> to identify LUKS-encrypted block devices (it "
1016 "returns the string C<crypto_LUKS>)."
1020 #: ../src/guestfs.pod:470
1022 "Then open these devices by calling L</guestfs_luks_open>. Obviously you "
1023 "will require the passphrase!"
1027 #: ../src/guestfs.pod:473
1029 "Opening a LUKS device creates a new device mapper device called C</dev/"
1030 "mapper/mapname> (where C<mapname> is the string you supply to L</"
1031 "guestfs_luks_open>). Reads and writes to this mapper device are decrypted "
1032 "from and encrypted to the underlying block device respectively."
1036 #: ../src/guestfs.pod:479
1038 "LVM volume groups on the device can be made visible by calling L</"
1039 "guestfs_vgscan> followed by L</guestfs_vg_activate_all>. The logical volume"
1040 "(s) can now be mounted in the usual way."
1044 #: ../src/guestfs.pod:483
1046 "Use the reverse process to close a LUKS device. Unmount any logical volumes "
1047 "on it, deactivate the volume groups by caling C<guestfs_vg_activate (g, 0, "
1048 "[\"/dev/VG\"])>. Then close the mapper device by calling L</"
1049 "guestfs_luks_close> on the C</dev/mapper/mapname> device (I<not> the "
1050 "underlying encrypted block device)."
1054 #: ../src/guestfs.pod:490
1059 #: ../src/guestfs.pod:492
1061 "Libguestfs has APIs for inspecting an unknown disk image to find out if it "
1062 "contains operating systems. (These APIs used to be in a separate Perl-only "
1063 "library called L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most "
1064 "frequently used part of this library has been rewritten in C and moved into "
1069 #: ../src/guestfs.pod:498
1071 "Add all disks belonging to the unknown virtual machine and call L</"
1072 "guestfs_launch> in the usual way."
1076 #: ../src/guestfs.pod:501
1078 "Then call L</guestfs_inspect_os>. This function uses other libguestfs calls "
1079 "and certain heuristics, and returns a list of operating systems that were "
1080 "found. An empty list means none were found. A single element is the root "
1081 "filesystem of the operating system. For dual- or multi-boot guests, "
1082 "multiple roots can be returned, each one corresponding to a separate "
1083 "operating system. (Multi-boot virtual machines are extremely rare in the "
1084 "world of virtualization, but since this scenario can happen, we have built "
1085 "libguestfs to deal with it.)"
1089 #: ../src/guestfs.pod:510
1091 "For each root, you can then call various C<guestfs_inspect_get_*> functions "
1092 "to get additional details about that operating system. For example, call L</"
1093 "guestfs_inspect_get_type> to return the string C<windows> or C<linux> for "
1094 "Windows and Linux-based operating systems respectively."
1098 #: ../src/guestfs.pod:516
1100 "Un*x-like and Linux-based operating systems usually consist of several "
1101 "filesystems which are mounted at boot time (for example, a separate boot "
1102 "partition mounted on C</boot>). The inspection rules are able to detect how "
1103 "filesystems correspond to mount points. Call "
1104 "C<guestfs_inspect_get_mountpoints> to get this mapping. It might return a "
1105 "hash table like this example:"
1109 #: ../src/guestfs.pod:523
1112 " /boot => /dev/sda1\n"
1113 " / => /dev/vg_guest/lv_root\n"
1114 " /usr => /dev/vg_guest/lv_usr\n"
1119 #: ../src/guestfs.pod:527
1121 "The caller can then make calls to L</guestfs_mount_options> to mount the "
1122 "filesystems as suggested."
1126 #: ../src/guestfs.pod:530
1128 "Be careful to mount filesystems in the right order (eg. C</> before C</"
1129 "usr>). Sorting the keys of the hash by length, shortest first, should work."
1133 #: ../src/guestfs.pod:534
1135 "Inspection currently only works for some common operating systems. "
1136 "Contributors are welcome to send patches for other operating systems that we "
1137 "currently cannot detect."
1141 #: ../src/guestfs.pod:538
1143 "Encrypted disks must be opened before inspection. See L</ENCRYPTED DISKS> "
1144 "for more details. The L</guestfs_inspect_os> function just ignores any "
1145 "encrypted devices."
1149 #: ../src/guestfs.pod:542
1151 "A note on the implementation: The call L</guestfs_inspect_os> performs "
1152 "inspection and caches the results in the guest handle. Subsequent calls to "
1153 "C<guestfs_inspect_get_*> return this cached information, but I<do not> re-"
1154 "read the disks. If you change the content of the guest disks, you can redo "
1155 "inspection by calling L</guestfs_inspect_os> again."
1159 #: ../src/guestfs.pod:549
1160 msgid "SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS"
1164 #: ../src/guestfs.pod:551
1166 "Libguestfs can mount NTFS partitions. It does this using the L<http://www."
1167 "ntfs-3g.org/> driver."
1171 #: ../src/guestfs.pod:554
1173 "DOS and Windows still use drive letters, and the filesystems are always "
1174 "treated as case insensitive by Windows itself, and therefore you might find "
1175 "a Windows configuration file referring to a path like C<c:\\windows"
1176 "\\system32>. When the filesystem is mounted in libguestfs, that directory "
1177 "might be referred to as C</WINDOWS/System32>."
1181 #: ../src/guestfs.pod:560
1183 "Drive letter mappings are outside the scope of libguestfs. You have to use "
1184 "libguestfs to read the appropriate Windows Registry and configuration files, "
1185 "to determine yourself how drives are mapped (see also L<hivex(3)> and L<virt-"
1190 #: ../src/guestfs.pod:565
1192 "Replacing backslash characters with forward slash characters is also outside "
1193 "the scope of libguestfs, but something that you can easily do."
1197 #: ../src/guestfs.pod:568
1199 "Where we can help is in resolving the case insensitivity of paths. For "
1200 "this, call L</guestfs_case_sensitive_path>."
1204 #: ../src/guestfs.pod:571
1206 "Libguestfs also provides some help for decoding Windows Registry \"hive\" "
1207 "files, through the library C<hivex> which is part of the libguestfs project "
1208 "although ships as a separate tarball. You have to locate and download the "
1209 "hive file(s) yourself, and then pass them to C<hivex> functions. See also "
1210 "the programs L<hivexml(1)>, L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-"
1211 "reg(1)> for more help on this issue."
1215 #: ../src/guestfs.pod:579
1216 msgid "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES"
1220 #: ../src/guestfs.pod:581
1222 "Although we don't want to discourage you from using the C API, we will "
1223 "mention here that the same API is also available in other languages."
1227 #: ../src/guestfs.pod:584
1229 "The API is broadly identical in all supported languages. This means that "
1230 "the C call C<guestfs_mount(g,path)> is C<$g-E<gt>mount($path)> in Perl, C<g."
1231 "mount(path)> in Python, and C<Guestfs.mount g path> in OCaml. In other "
1232 "words, a straightforward, predictable isomorphism between each language."
1236 #: ../src/guestfs.pod:590
1238 "Error messages are automatically transformed into exceptions if the language "
1243 #: ../src/guestfs.pod:593
1245 "We don't try to \"object orientify\" parts of the API in OO languages, "
1246 "although contributors are welcome to write higher level APIs above what we "
1247 "provide in their favourite languages if they wish."
1251 #: ../src/guestfs.pod:599
1256 #: ../src/guestfs.pod:601
1258 "You can use the I<guestfs.h> header file from C++ programs. The C++ API is "
1259 "identical to the C API. C++ classes and exceptions are not used."
1263 #: ../src/guestfs.pod:605
1268 #: ../src/guestfs.pod:607
1270 "The C# bindings are highly experimental. Please read the warnings at the "
1271 "top of C<csharp/Libguestfs.cs>."
1275 #: ../src/guestfs.pod:610
1280 #: ../src/guestfs.pod:612
1282 "This is the only language binding that is working but incomplete. Only "
1283 "calls which return simple integers have been bound in Haskell, and we are "
1284 "looking for help to complete this binding."
1288 #: ../src/guestfs.pod:616
1293 #: ../src/guestfs.pod:618
1295 "Full documentation is contained in the Javadoc which is distributed with "
1300 #: ../src/guestfs.pod:621
1305 #: ../src/guestfs.pod:623
1306 msgid "For documentation see the file C<guestfs.mli>."
1310 #: ../src/guestfs.pod:625
1315 #: ../src/guestfs.pod:627
1316 msgid "For documentation see L<Sys::Guestfs(3)>."
1320 #: ../src/guestfs.pod:629
1325 #: ../src/guestfs.pod:631
1327 "For documentation see C<README-PHP> supplied with libguestfs sources or in "
1328 "the php-libguestfs package for your distribution."
1332 #: ../src/guestfs.pod:634
1333 msgid "The PHP binding only works correctly on 64 bit machines."
1337 #: ../src/guestfs.pod:636
1342 #: ../src/guestfs.pod:638
1343 msgid "For documentation do:"
1347 #: ../src/guestfs.pod:640
1351 " >>> import guestfs\n"
1352 " >>> help (guestfs)\n"
1357 #: ../src/guestfs.pod:644
1362 #: ../src/guestfs.pod:646
1364 "Use the Guestfs module. There is no Ruby-specific documentation, but you "
1365 "can find examples written in Ruby in the libguestfs source."
1369 #: ../src/guestfs.pod:649
1370 msgid "B<shell scripts>"
1374 #: ../src/guestfs.pod:651
1375 msgid "For documentation see L<guestfish(1)>."
1379 #: ../src/guestfs.pod:655
1380 msgid "LIBGUESTFS GOTCHAS"
1384 #: ../src/guestfs.pod:657
1386 "L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: \"A feature of a "
1387 "system [...] that works in the way it is documented but is counterintuitive "
1388 "and almost invites mistakes.\""
1392 #: ../src/guestfs.pod:661
1394 "Since we developed libguestfs and the associated tools, there are several "
1395 "things we would have designed differently, but are now stuck with for "
1396 "backwards compatibility or other reasons. If there is ever a libguestfs 2.0 "
1397 "release, you can expect these to change. Beware of them."
1401 #: ../src/guestfs.pod:669
1402 msgid "Autosync / forgetting to sync."
1406 #: ../src/guestfs.pod:671
1408 "When modifying a filesystem from C or another language, you B<must> unmount "
1409 "all filesystems and call L</guestfs_sync> explicitly before you close the "
1410 "libguestfs handle. You can also call:"
1414 #: ../src/guestfs.pod:675
1417 " guestfs_set_autosync (g, 1);\n"
1422 #: ../src/guestfs.pod:677
1424 "to have the unmount/sync done automatically for you when the handle 'g' is "
1425 "closed. (This feature is called \"autosync\", L</guestfs_set_autosync> q.v.)"
1429 #: ../src/guestfs.pod:681
1431 "If you forget to do this, then it is entirely possible that your changes "
1432 "won't be written out, or will be partially written, or (very rarely) that "
1433 "you'll get disk corruption."
1437 #: ../src/guestfs.pod:685
1439 "Note that in L<guestfish(3)> autosync is the default. So quick and dirty "
1440 "guestfish scripts that forget to sync will work just fine, which can make "
1441 "this very puzzling if you are trying to debug a problem."
1445 #: ../src/guestfs.pod:689
1446 msgid "Mount option C<-o sync> should not be the default."
1450 #: ../src/guestfs.pod:691
1452 "If you use L</guestfs_mount>, then C<-o sync,noatime> are added implicitly. "
1453 "However C<-o sync> does not add any reliability benefit, but does have a "
1454 "very large performance impact."
1458 #: ../src/guestfs.pod:695
1460 "The work around is to use L</guestfs_mount_options> and set the mount "
1461 "options that you actually want to use."
1465 #: ../src/guestfs.pod:698
1466 msgid "Read-only should be the default."
1470 #: ../src/guestfs.pod:700
1472 "In L<guestfish(3)>, I<--ro> should be the default, and you should have to "
1473 "specify I<--rw> if you want to make changes to the image."
1477 #: ../src/guestfs.pod:703
1478 msgid "This would reduce the potential to corrupt live VM images."
1482 #: ../src/guestfs.pod:705
1484 "Note that many filesystems change the disk when you just mount and unmount, "
1485 "even if you didn't perform any writes. You need to use L</"
1486 "guestfs_add_drive_ro> to guarantee that the disk is not changed."
1490 #: ../src/guestfs.pod:709
1491 msgid "guestfish command line is hard to use."
1495 #: ../src/guestfs.pod:711
1497 "C<guestfish disk.img> doesn't do what people expect (open C<disk.img> for "
1498 "examination). It tries to run a guestfish command C<disk.img> which doesn't "
1499 "exist, so it fails. In earlier versions of guestfish the error message was "
1500 "also unintuitive, but we have corrected this since. Like the Bourne shell, "
1501 "we should have used C<guestfish -c command> to run commands."
1505 #: ../src/guestfs.pod:718
1506 msgid "guestfish megabyte modifiers don't work right on all commands"
1510 #: ../src/guestfs.pod:720
1512 "In recent guestfish you can use C<1M> to mean 1 megabyte (and similarly for "
1513 "other modifiers). What guestfish actually does is to multiply the number "
1514 "part by the modifier part and pass the result to the C API. However this "
1515 "doesn't work for a few APIs which aren't expecting bytes, but are already "
1516 "expecting some other unit (eg. megabytes)."
1520 #: ../src/guestfs.pod:727
1521 msgid "The most common is L</guestfs_lvcreate>. The guestfish command:"
1525 #: ../src/guestfs.pod:729
1528 " lvcreate LV VG 100M\n"
1533 #: ../src/guestfs.pod:731
1535 "does not do what you might expect. Instead because L</guestfs_lvcreate> is "
1536 "already expecting megabytes, this tries to create a 100 I<terabyte> (100 "
1537 "megabytes * megabytes) logical volume. The error message you get from this "
1538 "is also a little obscure."
1542 #: ../src/guestfs.pod:736
1544 "This could be fixed in the generator by specially marking parameters and "
1545 "return values which take bytes or other units."
1549 #: ../src/guestfs.pod:739
1550 msgid "Library should return errno with error messages."
1554 #: ../src/guestfs.pod:741
1556 "It would be a nice-to-have to be able to get the original value of 'errno' "
1557 "from inside the appliance along error paths (where set). Currently "
1558 "L<guestmount(1)> goes through hoops to try to reverse the error message "
1559 "string into an errno, see the function error() in fuse/guestmount.c."
1563 #: ../src/guestfs.pod:747
1565 "In libguestfs 1.5.4, the protocol was changed so that the Linux errno is "
1566 "sent back from the daemon."
1570 #: ../src/guestfs.pod:752
1571 msgid "PROTOCOL LIMITS"
1575 #: ../src/guestfs.pod:754
1577 "Internally libguestfs uses a message-based protocol to pass API calls and "
1578 "their responses to and from a small \"appliance\" (see L</INTERNALS> for "
1579 "plenty more detail about this). The maximum message size used by the "
1580 "protocol is slightly less than 4 MB. For some API calls you may need to be "
1581 "aware of this limit. The API calls which may be affected are individually "
1582 "documented, with a link back to this section of the documentation."
1586 #: ../src/guestfs.pod:762
1588 "A simple call such as L</guestfs_cat> returns its result (the file data) in "
1589 "a simple string. Because this string is at some point internally encoded as "
1590 "a message, the maximum size that it can return is slightly under 4 MB. If "
1591 "the requested file is larger than this then you will get an error."
1595 #: ../src/guestfs.pod:768
1597 "In order to transfer large files into and out of the guest filesystem, you "
1598 "need to use particular calls that support this. The sections L</UPLOADING> "
1599 "and L</DOWNLOADING> document how to do this."
1603 #: ../src/guestfs.pod:772
1605 "You might also consider mounting the disk image using our FUSE filesystem "
1606 "support (L<guestmount(1)>)."
1610 #: ../src/guestfs.pod:775
1611 msgid "KEYS AND PASSPHRASES"
1615 #: ../src/guestfs.pod:777
1617 "Certain libguestfs calls take a parameter that contains sensitive key "
1618 "material, passed in as a C string."
1622 #: ../src/guestfs.pod:780
1624 "In the future we would hope to change the libguestfs implementation so that "
1625 "keys are L<mlock(2)>-ed into physical RAM, and thus can never end up in "
1626 "swap. However this is I<not> done at the moment, because of the complexity "
1627 "of such an implementation."
1631 #: ../src/guestfs.pod:785
1633 "Therefore you should be aware that any key parameter you pass to libguestfs "
1634 "might end up being written out to the swap partition. If this is a concern, "
1635 "scrub the swap partition or don't use libguestfs on encrypted devices."
1639 #: ../src/guestfs.pod:790
1640 msgid "CONNECTION MANAGEMENT"
1644 #: ../src/guestfs.pod:792
1649 #: ../src/guestfs.pod:794
1651 "C<guestfs_h> is the opaque type representing a connection handle. Create a "
1652 "handle by calling L</guestfs_create>. Call L</guestfs_close> to free the "
1653 "handle and release all resources used."
1657 #: ../src/guestfs.pod:798
1659 "For information on using multiple handles and threads, see the section L</"
1660 "MULTIPLE HANDLES AND MULTIPLE THREADS> below."
1664 #: ../src/guestfs.pod:801
1665 msgid "guestfs_create"
1669 #: ../src/guestfs.pod:803
1672 " guestfs_h *guestfs_create (void);\n"
1677 #: ../src/guestfs.pod:805
1678 msgid "Create a connection handle."
1682 #: ../src/guestfs.pod:807
1683 msgid "You have to call L</guestfs_add_drive> on the handle at least once."
1687 #: ../src/guestfs.pod:809
1689 "This function returns a non-NULL pointer to a handle on success or NULL on "
1694 #: ../src/guestfs.pod:812
1695 msgid "After configuring the handle, you have to call L</guestfs_launch>."
1699 #: ../src/guestfs.pod:814
1701 "You may also want to configure error handling for the handle. See L</ERROR "
1702 "HANDLING> section below."
1706 #: ../src/guestfs.pod:817
1707 msgid "guestfs_close"
1711 #: ../src/guestfs.pod:819
1714 " void guestfs_close (guestfs_h *g);\n"
1719 #: ../src/guestfs.pod:821
1720 msgid "This closes the connection handle and frees up all resources used."
1724 #: ../src/guestfs.pod:823
1725 msgid "ERROR HANDLING"
1729 #: ../src/guestfs.pod:825
1731 "The convention in all functions that return C<int> is that they return C<-1> "
1732 "to indicate an error. You can get additional information on errors by "
1733 "calling L</guestfs_last_error> and/or by setting up an error handler with L</"
1734 "guestfs_set_error_handler>."
1738 #: ../src/guestfs.pod:830
1739 msgid "The default error handler prints the information string to C<stderr>."
1743 #: ../src/guestfs.pod:832
1745 "Out of memory errors are handled differently. The default action is to call "
1746 "L<abort(3)>. If this is undesirable, then you can set a handler using L</"
1747 "guestfs_set_out_of_memory_handler>."
1751 #: ../src/guestfs.pod:836
1752 msgid "guestfs_last_error"
1756 #: ../src/guestfs.pod:838
1759 " const char *guestfs_last_error (guestfs_h *g);\n"
1764 #: ../src/guestfs.pod:840
1766 "This returns the last error message that happened on C<g>. If there has not "
1767 "been an error since the handle was created, then this returns C<NULL>."
1771 #: ../src/guestfs.pod:844
1773 "The lifetime of the returned string is until the next error occurs, or L</"
1774 "guestfs_close> is called."
1778 #: ../src/guestfs.pod:847
1780 "The error string is not localized (ie. is always in English), because this "
1781 "makes searching for error messages in search engines give the largest number "
1786 #: ../src/guestfs.pod:851
1787 msgid "guestfs_set_error_handler"
1791 #: ../src/guestfs.pod:853
1794 " typedef void (*guestfs_error_handler_cb) (guestfs_h *g,\n"
1796 " const char *msg);\n"
1797 " void guestfs_set_error_handler (guestfs_h *g,\n"
1798 " guestfs_error_handler_cb cb,\n"
1804 #: ../src/guestfs.pod:860
1806 "The callback C<cb> will be called if there is an error. The parameters "
1807 "passed to the callback are an opaque data pointer and the error message "
1812 #: ../src/guestfs.pod:864
1814 "Note that the message string C<msg> is freed as soon as the callback "
1815 "function returns, so if you want to stash it somewhere you must make your "
1820 #: ../src/guestfs.pod:868
1821 msgid "The default handler prints messages on C<stderr>."
1825 #: ../src/guestfs.pod:870
1826 msgid "If you set C<cb> to C<NULL> then I<no> handler is called."
1830 #: ../src/guestfs.pod:872
1831 msgid "guestfs_get_error_handler"
1835 #: ../src/guestfs.pod:874
1838 " guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,\n"
1839 " void **opaque_rtn);\n"
1844 #: ../src/guestfs.pod:877
1845 msgid "Returns the current error handler callback."
1849 #: ../src/guestfs.pod:879
1850 msgid "guestfs_set_out_of_memory_handler"
1854 #: ../src/guestfs.pod:881
1857 " typedef void (*guestfs_abort_cb) (void);\n"
1858 " int guestfs_set_out_of_memory_handler (guestfs_h *g,\n"
1859 " guestfs_abort_cb);\n"
1864 #: ../src/guestfs.pod:885
1866 "The callback C<cb> will be called if there is an out of memory situation. "
1867 "I<Note this callback must not return>."
1871 #: ../src/guestfs.pod:888
1872 msgid "The default is to call L<abort(3)>."
1876 #: ../src/guestfs.pod:890
1878 "You cannot set C<cb> to C<NULL>. You can't ignore out of memory situations."
1882 #: ../src/guestfs.pod:893
1883 msgid "guestfs_get_out_of_memory_handler"
1887 #: ../src/guestfs.pod:895
1890 " guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);\n"
1895 #: ../src/guestfs.pod:897
1896 msgid "This returns the current out of memory handler."
1900 #: ../src/guestfs.pod:899
1905 #: ../src/guestfs.pod:901
1907 "Libguestfs needs a kernel and initrd.img, which it finds by looking along an "
1912 #: ../src/guestfs.pod:904
1914 "By default it looks for these in the directory C<$libdir/guestfs> (eg. C</"
1915 "usr/local/lib/guestfs> or C</usr/lib64/guestfs>)."
1919 #: ../src/guestfs.pod:907
1921 "Use L</guestfs_set_path> or set the environment variable L</LIBGUESTFS_PATH> "
1922 "to change the directories that libguestfs will search in. The value is a "
1923 "colon-separated list of paths. The current directory is I<not> searched "
1924 "unless the path contains an empty element or C<.>. For example "
1925 "C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would search the current directory and "
1926 "then C</usr/lib/guestfs>."
1930 #: ../src/guestfs.pod:914
1931 msgid "HIGH-LEVEL API ACTIONS"
1935 #: ../src/guestfs.pod:916
1936 msgid "ABI GUARANTEE"
1940 #: ../src/guestfs.pod:918
1942 "We guarantee the libguestfs ABI (binary interface), for public, high-level "
1943 "actions as outlined in this section. Although we will deprecate some "
1944 "actions, for example if they get replaced by newer calls, we will keep the "
1945 "old actions forever. This allows you the developer to program in confidence "
1946 "against the libguestfs API."
1950 #: ../src/guestfs.pod:924 ../fish/guestfish.pod:898
1955 #: ../src/guestfs.pod:926
1960 #: ../src/guestfs.pod:928
1965 #: ../src/guestfs.pod:930
1966 msgid "AVAILABILITY"
1970 #: ../src/guestfs.pod:932
1971 msgid "GROUPS OF FUNCTIONALITY IN THE APPLIANCE"
1975 #: ../src/guestfs.pod:934
1977 "Using L</guestfs_available> you can test availability of the following "
1978 "groups of functions. This test queries the appliance to see if the "
1979 "appliance you are currently using supports the functionality."
1983 #: ../src/guestfs.pod:939
1984 msgid "@AVAILABILITY@"
1988 #: ../src/guestfs.pod:941
1989 msgid "GUESTFISH supported COMMAND"
1993 #: ../src/guestfs.pod:943
1995 "In L<guestfish(3)> there is a handy interactive command C<supported> which "
1996 "prints out the available groups and whether they are supported by this build "
1997 "of libguestfs. Note however that you have to do C<run> first."
2001 #: ../src/guestfs.pod:948
2002 msgid "SINGLE CALLS AT COMPILE TIME"
2006 #: ../src/guestfs.pod:950
2008 "Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols for each C API "
2009 "function, such as:"
2013 #: ../src/guestfs.pod:953
2016 " #define LIBGUESTFS_HAVE_DD 1\n"
2021 #: ../src/guestfs.pod:955
2022 msgid "if L</guestfs_dd> is available."
2026 #: ../src/guestfs.pod:957
2028 "Before version 1.5.8, if you needed to test whether a single libguestfs "
2029 "function is available at compile time, we recommended using build tools such "
2030 "as autoconf or cmake. For example in autotools you could use:"
2034 #: ../src/guestfs.pod:962
2037 " AC_CHECK_LIB([guestfs],[guestfs_create])\n"
2038 " AC_CHECK_FUNCS([guestfs_dd])\n"
2043 #: ../src/guestfs.pod:965
2045 "which would result in C<HAVE_GUESTFS_DD> being either defined or not defined "
2050 #: ../src/guestfs.pod:968
2051 msgid "SINGLE CALLS AT RUN TIME"
2055 #: ../src/guestfs.pod:970
2057 "Testing at compile time doesn't guarantee that a function really exists in "
2058 "the library. The reason is that you might be dynamically linked against a "
2059 "previous I<libguestfs.so> (dynamic library) which doesn't have the call. "
2060 "This situation unfortunately results in a segmentation fault, which is a "
2061 "shortcoming of the C dynamic linking system itself."
2065 #: ../src/guestfs.pod:977
2067 "You can use L<dlopen(3)> to test if a function is available at run time, as "
2068 "in this example program (note that you still need the compile time check as "
2073 #: ../src/guestfs.pod:981
2076 " #include <stdio.h>\n"
2077 " #include <stdlib.h>\n"
2078 " #include <unistd.h>\n"
2079 " #include <dlfcn.h>\n"
2080 " #include <guestfs.h>\n"
2085 #: ../src/guestfs.pod:987
2090 " #ifdef LIBGUESTFS_HAVE_DD\n"
2092 " int has_function;\n"
2097 #: ../src/guestfs.pod:993
2100 " /* Test if the function guestfs_dd is really available. */\n"
2101 " dl = dlopen (NULL, RTLD_LAZY);\n"
2103 " fprintf (stderr, \"dlopen: %s\\n\", dlerror ());\n"
2104 " exit (EXIT_FAILURE);\n"
2106 " has_function = dlsym (dl, \"guestfs_dd\") != NULL;\n"
2112 #: ../src/guestfs.pod:1002
2115 " if (!has_function)\n"
2116 " printf (\"this libguestfs.so does NOT have guestfs_dd function\\n\");\n"
2118 " printf (\"this libguestfs.so has guestfs_dd function\\n\");\n"
2119 " /* Now it's safe to call\n"
2120 " guestfs_dd (g, \"foo\", \"bar\");\n"
2124 " printf (\"guestfs_dd function was not found at compile time\\n\");\n"
2131 #: ../src/guestfs.pod:1015
2133 "You may think the above is an awful lot of hassle, and it is. There are "
2134 "other ways outside of the C linking system to ensure that this kind of "
2135 "incompatibility never arises, such as using package versioning:"
2139 #: ../src/guestfs.pod:1020
2142 " Requires: libguestfs >= 1.0.80\n"
2147 #: ../src/guestfs.pod:1022 ../src/guestfs.pod:1027
2152 #: ../src/guestfs.pod:1024
2154 "<!-- old anchor for the next section --> <a name="
2155 "\"state_machine_and_low_level_event_api\"/>"
2159 #: ../src/guestfs.pod:1029
2160 msgid "ARCHITECTURE"
2164 #: ../src/guestfs.pod:1031
2166 "Internally, libguestfs is implemented by running an appliance (a special "
2167 "type of small virtual machine) using L<qemu(1)>. Qemu runs as a child "
2168 "process of the main program."
2172 #: ../src/guestfs.pod:1035
2175 " ___________________\n"
2177 " | main program |\n"
2179 " | | child process / appliance\n"
2180 " | | __________________________\n"
2182 " +-------------------+ RPC | +-----------------+ |\n"
2183 " | libguestfs <--------------------> guestfsd | |\n"
2184 " | | | +-----------------+ |\n"
2185 " \\___________________/ | | Linux kernel | |\n"
2186 " | +--^--------------+ |\n"
2187 " \\_________|________________/\n"
2193 " \\______________/\n"
2198 #: ../src/guestfs.pod:1055
2200 "The library, linked to the main program, creates the child process and hence "
2201 "the appliance in the L</guestfs_launch> function."
2205 #: ../src/guestfs.pod:1058
2207 "Inside the appliance is a Linux kernel and a complete stack of userspace "
2208 "tools (such as LVM and ext2 programs) and a small controlling daemon called "
2209 "L</guestfsd>. The library talks to L</guestfsd> using remote procedure "
2210 "calls (RPC). There is a mostly one-to-one correspondence between libguestfs "
2211 "API calls and RPC calls to the daemon. Lastly the disk image(s) are "
2212 "attached to the qemu process which translates device access by the "
2213 "appliance's Linux kernel into accesses to the image."
2217 #: ../src/guestfs.pod:1067
2219 "A common misunderstanding is that the appliance \"is\" the virtual machine. "
2220 "Although the disk image you are attached to might also be used by some "
2221 "virtual machine, libguestfs doesn't know or care about this. (But you will "
2222 "care if both libguestfs's qemu process and your virtual machine are trying "
2223 "to update the disk image at the same time, since these usually results in "
2224 "massive disk corruption)."
2228 #: ../src/guestfs.pod:1074
2229 msgid "STATE MACHINE"
2233 #: ../src/guestfs.pod:1076
2234 msgid "libguestfs uses a state machine to model the child process:"
2238 #: ../src/guestfs.pod:1078
2250 " / | \\ \\ guestfs_launch\n"
2251 " / | _\\__V______\n"
2253 " / | | LAUNCHING |\n"
2254 " / | \\___________/\n"
2256 " / | guestfs_launch\n"
2258 " ______ / __|____V\n"
2259 " / \\ ------> / \\\n"
2260 " | BUSY | | READY |\n"
2261 " \\______/ <------ \\________/\n"
2266 #: ../src/guestfs.pod:1100
2268 "The normal transitions are (1) CONFIG (when the handle is created, but there "
2269 "is no child process), (2) LAUNCHING (when the child process is booting up), "
2270 "(3) alternating between READY and BUSY as commands are issued to, and "
2271 "carried out by, the child process."
2275 #: ../src/guestfs.pod:1105
2277 "The guest may be killed by L</guestfs_kill_subprocess>, or may die "
2278 "asynchronously at any time (eg. due to some internal error), and that causes "
2279 "the state to transition back to CONFIG."
2283 #: ../src/guestfs.pod:1109
2285 "Configuration commands for qemu such as L</guestfs_add_drive> can only be "
2286 "issued when in the CONFIG state."
2290 #: ../src/guestfs.pod:1112
2292 "The high-level API offers two calls that go from CONFIG through LAUNCHING to "
2293 "READY. L</guestfs_launch> blocks until the child process is READY to accept "
2294 "commands (or until some failure or timeout). L</guestfs_launch> internally "
2295 "moves the state from CONFIG to LAUNCHING while it is running."
2299 #: ../src/guestfs.pod:1118
2301 "High-level API actions such as L</guestfs_mount> can only be issued when in "
2302 "the READY state. These high-level API calls block waiting for the command "
2303 "to be carried out (ie. the state to transition to BUSY and then back to "
2304 "READY). But using the low-level event API, you get non-blocking versions. "
2305 "(But you can still only carry out one operation per handle at a time - that "
2306 "is a limitation of the communications protocol we use)."
2310 #: ../src/guestfs.pod:1126
2312 "Finally, the child process sends asynchronous messages back to the main "
2313 "program, such as kernel log messages. Mostly these are ignored by the high-"
2314 "level API, but using the low-level event API you can register to receive "
2319 #: ../src/guestfs.pod:1131
2320 msgid "SETTING CALLBACKS TO HANDLE EVENTS"
2324 #: ../src/guestfs.pod:1133
2326 "The child process generates events in some situations. Current events "
2327 "include: receiving a log message, the child process exits."
2331 #: ../src/guestfs.pod:1136
2333 "Use the C<guestfs_set_*_callback> functions to set a callback for different "
2338 #: ../src/guestfs.pod:1139
2340 "Only I<one callback of each type> can be registered for each handle. "
2341 "Calling C<guestfs_set_*_callback> again overwrites the previous callback of "
2342 "that type. Cancel all callbacks of this type by calling this function with "
2343 "C<cb> set to C<NULL>."
2347 #: ../src/guestfs.pod:1144
2348 msgid "guestfs_set_log_message_callback"
2352 #: ../src/guestfs.pod:1146
2355 " typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,\n"
2356 " char *buf, int len);\n"
2357 " void guestfs_set_log_message_callback (guestfs_h *g,\n"
2358 " guestfs_log_message_cb cb,\n"
2364 #: ../src/guestfs.pod:1152
2366 "The callback function C<cb> will be called whenever qemu or the guest writes "
2367 "anything to the console."
2371 #: ../src/guestfs.pod:1155
2372 msgid "Use this function to capture kernel messages and similar."
2376 #: ../src/guestfs.pod:1157
2378 "Normally there is no log message handler, and log messages are just "
2383 #: ../src/guestfs.pod:1160
2384 msgid "guestfs_set_subprocess_quit_callback"
2388 #: ../src/guestfs.pod:1162
2391 " typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);\n"
2392 " void guestfs_set_subprocess_quit_callback (guestfs_h *g,\n"
2393 " guestfs_subprocess_quit_cb cb,\n"
2399 #: ../src/guestfs.pod:1167
2401 "The callback function C<cb> will be called when the child process quits, "
2402 "either asynchronously or if killed by L</guestfs_kill_subprocess>. (This "
2403 "corresponds to a transition from any state to the CONFIG state)."
2407 #: ../src/guestfs.pod:1172
2408 msgid "guestfs_set_launch_done_callback"
2412 #: ../src/guestfs.pod:1174
2415 " typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);\n"
2416 " void guestfs_set_launch_done_callback (guestfs_h *g,\n"
2417 " guestfs_launch_done_cb cb,\n"
2423 #: ../src/guestfs.pod:1179
2425 "The callback function C<cb> will be called when the child process becomes "
2426 "ready first time after it has been launched. (This corresponds to a "
2427 "transition from LAUNCHING to the READY state)."
2431 #: ../src/guestfs.pod:1183
2432 msgid "guestfs_set_close_callback"
2436 #: ../src/guestfs.pod:1185
2439 " typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);\n"
2440 " void guestfs_set_close_callback (guestfs_h *g,\n"
2441 " guestfs_close_cb cb,\n"
2447 #: ../src/guestfs.pod:1190
2449 "The callback function C<cb> will be called while the handle is being closed "
2450 "(synchronously from L</guestfs_close>)."
2454 #: ../src/guestfs.pod:1193
2456 "Note that libguestfs installs an L<atexit(3)> handler to try to clean up "
2457 "handles that are open when the program exits. This means that this callback "
2458 "might be called indirectly from L<exit(3)>, which can cause unexpected "
2459 "problems in higher-level languages (eg. if your HLL interpreter has already "
2460 "been cleaned up by the time this is called, and if your callback then jumps "
2461 "into some HLL function)."
2465 #: ../src/guestfs.pod:1201
2466 msgid "guestfs_set_progress_callback"
2470 #: ../src/guestfs.pod:1203
2473 " typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,\n"
2474 " int proc_nr, int serial,\n"
2475 " uint64_t position, uint64_t total);\n"
2476 " void guestfs_set_progress_callback (guestfs_h *g,\n"
2477 " guestfs_progress_cb cb,\n"
2483 #: ../src/guestfs.pod:1210
2485 "Some long-running operations can generate progress messages. If this "
2486 "callback is registered, then it will be called each time a progress message "
2487 "is generated (usually two seconds after the operation started, and three "
2488 "times per second thereafter until it completes, although the frequency may "
2489 "change in future versions)."
2493 #: ../src/guestfs.pod:1216
2495 "The callback receives two numbers: C<position> and C<total>. The units of "
2496 "C<total> are not defined, although for some operations C<total> may relate "
2497 "in some way to the amount of data to be transferred (eg. in bytes or "
2498 "megabytes), and C<position> may be the portion which has been transferred."
2502 #: ../src/guestfs.pod:1222
2503 msgid "The only defined and stable parts of the API are:"
2507 #: ../src/guestfs.pod:1228
2509 "The callback can display to the user some type of progress bar or indicator "
2510 "which shows the ratio of C<position>:C<total>."
2514 #: ../src/guestfs.pod:1233
2515 msgid "0 E<lt>= C<position> E<lt>= C<total>"
2519 #: ../src/guestfs.pod:1237
2521 "If any progress notification is sent during a call, then a final progress "
2522 "notification is always sent when C<position> = C<total>."
2526 #: ../src/guestfs.pod:1240
2528 "This is to simplify caller code, so callers can easily set the progress "
2529 "indicator to \"100%\" at the end of the operation, without requiring special "
2530 "code to detect this case."
2534 #: ../src/guestfs.pod:1246
2536 "The callback also receives the procedure number and serial number of the "
2537 "call. These are only useful for debugging protocol issues, and the callback "
2538 "can normally ignore them. The callback may want to print these numbers in "
2539 "error messages or debugging messages."
2543 #: ../src/guestfs.pod:1251
2544 msgid "PRIVATE DATA AREA"
2548 #: ../src/guestfs.pod:1253
2550 "You can attach named pieces of private data to the libguestfs handle, and "
2551 "fetch them by name for the lifetime of the handle. This is called the "
2552 "private data area and is only available from the C API."
2556 #: ../src/guestfs.pod:1257
2557 msgid "To attach a named piece of data, use the following call:"
2561 #: ../src/guestfs.pod:1259
2564 " void guestfs_set_private (guestfs_h *g, const char *key, void *data);\n"
2569 #: ../src/guestfs.pod:1261
2571 "C<key> is the name to associate with this data, and C<data> is an arbitrary "
2572 "pointer (which can be C<NULL>). Any previous item with the same name is "
2577 #: ../src/guestfs.pod:1265
2579 "You can use any C<key> you want, but names beginning with an underscore "
2580 "character are reserved for internal libguestfs purposes (for implementing "
2581 "language bindings). It is recommended to prefix the name with some unique "
2582 "string to avoid collisions with other users."
2586 #: ../src/guestfs.pod:1270
2587 msgid "To retrieve the pointer, use:"
2591 #: ../src/guestfs.pod:1272
2594 " void *guestfs_get_private (guestfs_h *g, const char *key);\n"
2599 #: ../src/guestfs.pod:1274
2601 "This function returns C<NULL> if either no data is found associated with "
2602 "C<key>, or if the user previously set the C<key>'s C<data> pointer to "
2607 #: ../src/guestfs.pod:1278
2609 "Libguestfs does not try to look at or interpret the C<data> pointer in any "
2610 "way. As far as libguestfs is concerned, it need not be a valid pointer at "
2611 "all. In particular, libguestfs does I<not> try to free the data when the "
2612 "handle is closed. If the data must be freed, then the caller must either "
2613 "free it before calling L</guestfs_close> or must set up a close callback to "
2614 "do it (see L</guestfs_set_close_callback>, and note that only one callback "
2615 "can be registered for a handle)."
2619 #: ../src/guestfs.pod:1286
2621 "The private data area is implemented using a hash table, and should be "
2622 "reasonably efficient for moderate numbers of keys."
2626 #: ../src/guestfs.pod:1289
2627 msgid "BLOCK DEVICE NAMING"
2631 #: ../src/guestfs.pod:1291
2633 "In the kernel there is now quite a profusion of schemata for naming block "
2634 "devices (in this context, by I<block device> I mean a physical or virtual "
2635 "hard drive). The original Linux IDE driver used names starting with C</dev/"
2636 "hd*>. SCSI devices have historically used a different naming scheme, C</dev/"
2637 "sd*>. When the Linux kernel I<libata> driver became a popular replacement "
2638 "for the old IDE driver (particularly for SATA devices) those devices also "
2639 "used the C</dev/sd*> scheme. Additionally we now have virtual machines with "
2640 "paravirtualized drivers. This has created several different naming systems, "
2641 "such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen PV disks."
2645 #: ../src/guestfs.pod:1303
2647 "As discussed above, libguestfs uses a qemu appliance running an embedded "
2648 "Linux kernel to access block devices. We can run a variety of appliances "
2649 "based on a variety of Linux kernels."
2653 #: ../src/guestfs.pod:1307
2655 "This causes a problem for libguestfs because many API calls use device or "
2656 "partition names. Working scripts and the recipe (example) scripts that we "
2657 "make available over the internet could fail if the naming scheme changes."
2661 #: ../src/guestfs.pod:1312
2663 "Therefore libguestfs defines C</dev/sd*> as the I<standard naming scheme>. "
2664 "Internally C</dev/sd*> names are translated, if necessary, to other names as "
2665 "required. For example, under RHEL 5 which uses the C</dev/hd*> scheme, any "
2666 "device parameter C</dev/sda2> is translated to C</dev/hda2> transparently."
2670 #: ../src/guestfs.pod:1318
2672 "Note that this I<only> applies to parameters. The L</guestfs_list_devices>, "
2673 "L</guestfs_list_partitions> and similar calls return the true names of the "
2674 "devices and partitions as known to the appliance."
2678 #: ../src/guestfs.pod:1323
2679 msgid "ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION"
2683 #: ../src/guestfs.pod:1325
2685 "Usually this translation is transparent. However in some (very rare) cases "
2686 "you may need to know the exact algorithm. Such cases include where you use "
2687 "L</guestfs_config> to add a mixture of virtio and IDE devices to the qemu-"
2688 "based appliance, so have a mixture of C</dev/sd*> and C</dev/vd*> devices."
2692 #: ../src/guestfs.pod:1331
2694 "The algorithm is applied only to I<parameters> which are known to be either "
2695 "device or partition names. Return values from functions such as L</"
2696 "guestfs_list_devices> are never changed."
2700 #: ../src/guestfs.pod:1339
2701 msgid "Is the string a parameter which is a device or partition name?"
2705 #: ../src/guestfs.pod:1343
2706 msgid "Does the string begin with C</dev/sd>?"
2710 #: ../src/guestfs.pod:1347
2712 "Does the named device exist? If so, we use that device. However if I<not> "
2713 "then we continue with this algorithm."
2717 #: ../src/guestfs.pod:1352
2718 msgid "Replace initial C</dev/sd> string with C</dev/hd>."
2722 #: ../src/guestfs.pod:1354
2723 msgid "For example, change C</dev/sda2> to C</dev/hda2>."
2727 #: ../src/guestfs.pod:1356
2728 msgid "If that named device exists, use it. If not, continue."
2732 #: ../src/guestfs.pod:1360
2733 msgid "Replace initial C</dev/sd> string with C</dev/vd>."
2737 #: ../src/guestfs.pod:1362
2738 msgid "If that named device exists, use it. If not, return an error."
2742 #: ../src/guestfs.pod:1366
2743 msgid "PORTABILITY CONCERNS"
2747 #: ../src/guestfs.pod:1368
2749 "Although the standard naming scheme and automatic translation is useful for "
2750 "simple programs and guestfish scripts, for larger programs it is best not to "
2751 "rely on this mechanism."
2755 #: ../src/guestfs.pod:1372
2757 "Where possible for maximum future portability programs using libguestfs "
2758 "should use these future-proof techniques:"
2762 #: ../src/guestfs.pod:1379
2764 "Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list actual "
2765 "device names, and then use those names directly."
2769 #: ../src/guestfs.pod:1382
2771 "Since those device names exist by definition, they will never be translated."
2775 #: ../src/guestfs.pod:1387
2777 "Use higher level ways to identify filesystems, such as LVM names, UUIDs and "
2778 "filesystem labels."
2782 #: ../src/guestfs.pod:1392
2787 #: ../src/guestfs.pod:1394
2788 msgid "COMMUNICATION PROTOCOL"
2792 #: ../src/guestfs.pod:1396
2794 "Don't rely on using this protocol directly. This section documents how it "
2795 "currently works, but it may change at any time."
2799 #: ../src/guestfs.pod:1399
2801 "The protocol used to talk between the library and the daemon running inside "
2802 "the qemu virtual machine is a simple RPC mechanism built on top of XDR (RFC "
2803 "1014, RFC 1832, RFC 4506)."
2807 #: ../src/guestfs.pod:1403
2809 "The detailed format of structures is in C<src/guestfs_protocol.x> (note: "
2810 "this file is automatically generated)."
2814 #: ../src/guestfs.pod:1406
2816 "There are two broad cases, ordinary functions that don't have any C<FileIn> "
2817 "and C<FileOut> parameters, which are handled with very simple request/reply "
2818 "messages. Then there are functions that have any C<FileIn> or C<FileOut> "
2819 "parameters, which use the same request and reply messages, but they may also "
2820 "be followed by files sent using a chunked encoding."
2824 #: ../src/guestfs.pod:1413
2825 msgid "ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)"
2829 #: ../src/guestfs.pod:1415
2830 msgid "For ordinary functions, the request message is:"
2834 #: ../src/guestfs.pod:1417
2837 " total length (header + arguments,\n"
2838 " but not including the length word itself)\n"
2839 " struct guestfs_message_header (encoded as XDR)\n"
2840 " struct guestfs_<foo>_args (encoded as XDR)\n"
2845 #: ../src/guestfs.pod:1422
2847 "The total length field allows the daemon to allocate a fixed size buffer "
2848 "into which it slurps the rest of the message. As a result, the total length "
2849 "is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently 4MB), which means the "
2850 "effective size of any request is limited to somewhere under this size."
2854 #: ../src/guestfs.pod:1428
2856 "Note also that many functions don't take any arguments, in which case the "
2857 "C<guestfs_I<foo>_args> is completely omitted."
2861 #: ../src/guestfs.pod:1431
2863 "The header contains the procedure number (C<guestfs_proc>) which is how the "
2864 "receiver knows what type of args structure to expect, or none at all."
2868 #: ../src/guestfs.pod:1435
2869 msgid "The reply message for ordinary functions is:"
2873 #: ../src/guestfs.pod:1437
2876 " total length (header + ret,\n"
2877 " but not including the length word itself)\n"
2878 " struct guestfs_message_header (encoded as XDR)\n"
2879 " struct guestfs_<foo>_ret (encoded as XDR)\n"
2884 #: ../src/guestfs.pod:1442
2886 "As above the C<guestfs_I<foo>_ret> structure may be completely omitted for "
2887 "functions that return no formal return values."
2891 #: ../src/guestfs.pod:1445
2893 "As above the total length of the reply is limited to C<GUESTFS_MESSAGE_MAX>."
2897 #: ../src/guestfs.pod:1448
2899 "In the case of an error, a flag is set in the header, and the reply message "
2900 "is slightly changed:"
2904 #: ../src/guestfs.pod:1451
2907 " total length (header + error,\n"
2908 " but not including the length word itself)\n"
2909 " struct guestfs_message_header (encoded as XDR)\n"
2910 " struct guestfs_message_error (encoded as XDR)\n"
2915 #: ../src/guestfs.pod:1456
2917 "The C<guestfs_message_error> structure contains the error message as a "
2922 #: ../src/guestfs.pod:1459
2923 msgid "FUNCTIONS THAT HAVE FILEIN PARAMETERS"
2927 #: ../src/guestfs.pod:1461
2929 "A C<FileIn> parameter indicates that we transfer a file I<into> the guest. "
2930 "The normal request message is sent (see above). However this is followed by "
2931 "a sequence of file chunks."
2935 #: ../src/guestfs.pod:1465
2938 " total length (header + arguments,\n"
2939 " but not including the length word itself,\n"
2940 " and not including the chunks)\n"
2941 " struct guestfs_message_header (encoded as XDR)\n"
2942 " struct guestfs_<foo>_args (encoded as XDR)\n"
2943 " sequence of chunks for FileIn param #0\n"
2944 " sequence of chunks for FileIn param #1 etc.\n"
2949 #: ../src/guestfs.pod:1473
2950 msgid "The \"sequence of chunks\" is:"
2954 #: ../src/guestfs.pod:1475
2957 " length of chunk (not including length word itself)\n"
2958 " struct guestfs_chunk (encoded as XDR)\n"
2959 " length of chunk\n"
2960 " struct guestfs_chunk (encoded as XDR)\n"
2962 " length of chunk\n"
2963 " struct guestfs_chunk (with data.data_len == 0)\n"
2968 #: ../src/guestfs.pod:1483
2970 "The final chunk has the C<data_len> field set to zero. Additionally a flag "
2971 "is set in the final chunk to indicate either successful completion or early "
2976 #: ../src/guestfs.pod:1487
2978 "At time of writing there are no functions that have more than one FileIn "
2979 "parameter. However this is (theoretically) supported, by sending the "
2980 "sequence of chunks for each FileIn parameter one after another (from left to "
2985 #: ../src/guestfs.pod:1492
2987 "Both the library (sender) I<and> the daemon (receiver) may cancel the "
2988 "transfer. The library does this by sending a chunk with a special flag set "
2989 "to indicate cancellation. When the daemon sees this, it cancels the whole "
2990 "RPC, does I<not> send any reply, and goes back to reading the next request."
2994 #: ../src/guestfs.pod:1498
2996 "The daemon may also cancel. It does this by writing a special word "
2997 "C<GUESTFS_CANCEL_FLAG> to the socket. The library listens for this during "
2998 "the transfer, and if it gets it, it will cancel the transfer (it sends a "
2999 "cancel chunk). The special word is chosen so that even if cancellation "
3000 "happens right at the end of the transfer (after the library has finished "
3001 "writing and has started listening for the reply), the \"spurious\" cancel "
3002 "flag will not be confused with the reply message."
3006 #: ../src/guestfs.pod:1507
3008 "This protocol allows the transfer of arbitrary sized files (no 32 bit "
3009 "limit), and also files where the size is not known in advance (eg. from "
3010 "pipes or sockets). However the chunks are rather small "
3011 "(C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the daemon need "
3012 "to keep much in memory."
3016 #: ../src/guestfs.pod:1513
3017 msgid "FUNCTIONS THAT HAVE FILEOUT PARAMETERS"
3021 #: ../src/guestfs.pod:1515
3023 "The protocol for FileOut parameters is exactly the same as for FileIn "
3024 "parameters, but with the roles of daemon and library reversed."
3028 #: ../src/guestfs.pod:1518
3031 " total length (header + ret,\n"
3032 " but not including the length word itself,\n"
3033 " and not including the chunks)\n"
3034 " struct guestfs_message_header (encoded as XDR)\n"
3035 " struct guestfs_<foo>_ret (encoded as XDR)\n"
3036 " sequence of chunks for FileOut param #0\n"
3037 " sequence of chunks for FileOut param #1 etc.\n"
3042 #: ../src/guestfs.pod:1526
3043 msgid "INITIAL MESSAGE"
3047 #: ../src/guestfs.pod:1528
3049 "Because the underlying channel (QEmu -net channel) doesn't have any sort of "
3050 "connection control, when the daemon launches it sends an initial word "
3051 "(C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is "
3052 "alive. This is what L</guestfs_launch> waits for."
3056 #: ../src/guestfs.pod:1533
3057 msgid "MULTIPLE HANDLES AND MULTIPLE THREADS"
3061 #: ../src/guestfs.pod:1535
3063 "All high-level libguestfs actions are synchronous. If you want to use "
3064 "libguestfs asynchronously then you must create a thread."
3068 #: ../src/guestfs.pod:1538
3070 "Only use the handle from a single thread. Either use the handle exclusively "
3071 "from one thread, or provide your own mutex so that two threads cannot issue "
3072 "calls on the same handle at the same time."
3076 #: ../src/guestfs.pod:1542
3077 msgid "QEMU WRAPPERS"
3081 #: ../src/guestfs.pod:1544
3083 "If you want to compile your own qemu, run qemu from a non-standard location, "
3084 "or pass extra arguments to qemu, then you can write a shell-script wrapper "
3089 #: ../src/guestfs.pod:1548
3091 "There is one important rule to remember: you I<must C<exec qemu>> as the "
3092 "last command in the shell script (so that qemu replaces the shell and "
3093 "becomes the direct child of the libguestfs-using program). If you don't do "
3094 "this, then the qemu process won't be cleaned up correctly."
3098 #: ../src/guestfs.pod:1553
3100 "Here is an example of a wrapper, where I have built my own copy of qemu from "
3105 #: ../src/guestfs.pod:1556
3109 " qemudir=/home/rjones/d/qemu\n"
3110 " exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios \"$@\"\n"
3115 #: ../src/guestfs.pod:1560
3117 "Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>, and "
3118 "then use it by setting the LIBGUESTFS_QEMU environment variable. For "
3123 #: ../src/guestfs.pod:1564
3126 " LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish\n"
3131 #: ../src/guestfs.pod:1566
3133 "Note that libguestfs also calls qemu with the -help and -version options in "
3134 "order to determine features."
3138 #: ../src/guestfs.pod:1569
3139 msgid "LIBGUESTFS VERSION NUMBERS"
3143 #: ../src/guestfs.pod:1571
3145 "Since April 2010, libguestfs has started to make separate development and "
3146 "stable releases, along with corresponding branches in our git repository. "
3147 "These separate releases can be identified by version number:"
3151 #: ../src/guestfs.pod:1576
3154 " even numbers for stable: 1.2.x, 1.4.x, ...\n"
3155 " .-------- odd numbers for development: 1.3.x, 1.5.x, ...\n"
3161 " | `-------- sub-version\n"
3163 " `------ always '1' because we don't change the ABI\n"
3168 #: ../src/guestfs.pod:1587
3169 msgid "Thus \"1.3.5\" is the 5th update to the development branch \"1.3\"."
3173 #: ../src/guestfs.pod:1589
3175 "As time passes we cherry pick fixes from the development branch and backport "
3176 "those into the stable branch, the effect being that the stable branch should "
3177 "get more stable and less buggy over time. So the stable releases are ideal "
3178 "for people who don't need new features but would just like the software to "
3183 #: ../src/guestfs.pod:1595
3184 msgid "Our criteria for backporting changes are:"
3188 #: ../src/guestfs.pod:1601
3190 "Documentation changes which don't affect any code are backported unless the "
3191 "documentation refers to a future feature which is not in stable."
3195 #: ../src/guestfs.pod:1607
3197 "Bug fixes which are not controversial, fix obvious problems, and have been "
3198 "well tested are backported."
3202 #: ../src/guestfs.pod:1612
3204 "Simple rearrangements of code which shouldn't affect how it works get "
3205 "backported. This is so that the code in the two branches doesn't get too "
3206 "far out of step, allowing us to backport future fixes more easily."
3210 #: ../src/guestfs.pod:1618
3212 "We I<don't> backport new features, new APIs, new tools etc, except in one "
3213 "exceptional case: the new feature is required in order to implement an "
3214 "important bug fix."
3218 #: ../src/guestfs.pod:1624
3220 "A new stable branch starts when we think the new features in development are "
3221 "substantial and compelling enough over the current stable branch to warrant "
3222 "it. When that happens we create new stable and development versions 1.N.0 "
3223 "and 1.(N+1).0 [N is even]. The new dot-oh release won't necessarily be so "
3224 "stable at this point, but by backporting fixes from development, that branch "
3225 "will stabilize over time."
3229 #: ../src/guestfs.pod:1632 ../fish/guestfish.pod:905
3230 #: ../test-tool/libguestfs-test-tool.pod:104 ../tools/virt-edit.pl:312
3231 #: ../tools/virt-rescue.pl:226
3232 msgid "ENVIRONMENT VARIABLES"
3236 #: ../src/guestfs.pod:1636 ../fish/guestfish.pod:925
3237 msgid "LIBGUESTFS_APPEND"
3241 #: ../src/guestfs.pod:1638 ../fish/guestfish.pod:927
3242 msgid "Pass additional options to the guest kernel."
3246 #: ../src/guestfs.pod:1640 ../fish/guestfish.pod:929
3247 msgid "LIBGUESTFS_DEBUG"
3251 #: ../src/guestfs.pod:1642
3253 "Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This has the same "
3254 "effect as calling C<guestfs_set_verbose (g, 1)>."
3258 #: ../src/guestfs.pod:1645 ../fish/guestfish.pod:934
3259 msgid "LIBGUESTFS_MEMSIZE"
3263 #: ../src/guestfs.pod:1647 ../fish/guestfish.pod:936
3265 "Set the memory allocated to the qemu process, in megabytes. For example:"
3269 #: ../src/guestfs.pod:1650 ../fish/guestfish.pod:939
3272 " LIBGUESTFS_MEMSIZE=700\n"
3277 #: ../src/guestfs.pod:1652 ../fish/guestfish.pod:941
3278 msgid "LIBGUESTFS_PATH"
3282 #: ../src/guestfs.pod:1654
3284 "Set the path that libguestfs uses to search for kernel and initrd.img. See "
3285 "the discussion of paths in section PATH above."
3289 #: ../src/guestfs.pod:1657 ../fish/guestfish.pod:946
3290 msgid "LIBGUESTFS_QEMU"
3294 #: ../src/guestfs.pod:1659 ../fish/guestfish.pod:948
3296 "Set the default qemu binary that libguestfs uses. If not set, then the qemu "
3297 "which was found at compile time by the configure script is used."
3301 #: ../src/guestfs.pod:1663
3302 msgid "See also L</QEMU WRAPPERS> above."
3306 #: ../src/guestfs.pod:1665 ../fish/guestfish.pod:952
3307 msgid "LIBGUESTFS_TRACE"
3311 #: ../src/guestfs.pod:1667
3313 "Set C<LIBGUESTFS_TRACE=1> to enable command traces. This has the same "
3314 "effect as calling C<guestfs_set_trace (g, 1)>."
3318 #: ../src/guestfs.pod:1670 ../fish/guestfish.pod:961
3323 #: ../src/guestfs.pod:1672 ../fish/guestfish.pod:963
3324 msgid "Location of temporary directory, defaults to C</tmp>."
3328 #: ../src/guestfs.pod:1674 ../fish/guestfish.pod:965
3330 "If libguestfs was compiled to use the supermin appliance then each handle "
3331 "will require rather a large amount of space in this directory for short "
3332 "periods of time (~ 80 MB). You can use C<$TMPDIR> to configure another "
3333 "directory to use in case C</tmp> is not large enough."
3337 #: ../src/guestfs.pod:1682 ../fish/guestfish.pod:1023
3338 #: ../test-tool/libguestfs-test-tool.pod:109 ../fuse/guestmount.pod:178
3339 #: ../inspector/virt-inspector.pl:846 ../tools/virt-cat.pl:163
3340 #: ../tools/virt-df.pl:482 ../tools/virt-edit.pl:325
3341 #: ../tools/virt-list-filesystems.pl:191 ../tools/virt-list-partitions.pl:229
3342 #: ../tools/virt-ls.pl:210 ../tools/virt-make-fs.pl:527
3343 #: ../tools/virt-rescue.pl:231 ../tools/virt-resize.pl:1390
3344 #: ../tools/virt-tar.pl:257 ../tools/virt-win-reg.pl:461
3349 #: ../src/guestfs.pod:1684
3351 "L<guestfish(1)>, L<guestmount(1)>, L<virt-cat(1)>, L<virt-df(1)>, L<virt-edit"
3352 "(1)>, L<virt-inspector(1)>, L<virt-list-filesystems(1)>, L<virt-list-"
3353 "partitions(1)>, L<virt-ls(1)>, L<virt-make-fs(1)>, L<virt-rescue(1)>, L<virt-"
3354 "tar(1)>, L<virt-win-reg(1)>, L<qemu(1)>, L<febootstrap(1)>, L<hivex(3)>, "
3355 "L<http://libguestfs.org/>."
3359 #: ../src/guestfs.pod:1702
3361 "Tools with a similar purpose: L<fdisk(8)>, L<parted(8)>, L<kpartx(8)>, L<lvm"
3362 "(8)>, L<disktype(1)>."
3366 #: ../src/guestfs.pod:1709 ../tools/virt-make-fs.pl:541
3367 #: ../tools/virt-win-reg.pl:476
3372 #: ../src/guestfs.pod:1711
3373 msgid "To get a list of bugs against libguestfs use this link:"
3377 #: ../src/guestfs.pod:1713
3379 "L<https://bugzilla.redhat.com/buglist.cgi?"
3380 "component=libguestfs&product=Virtualization+Tools>"
3384 #: ../src/guestfs.pod:1715
3385 msgid "To report a new bug against libguestfs use this link:"
3389 #: ../src/guestfs.pod:1717
3391 "L<https://bugzilla.redhat.com/enter_bug.cgi?"
3392 "component=libguestfs&product=Virtualization+Tools>"
3396 #: ../src/guestfs.pod:1719
3397 msgid "When reporting a bug, please check:"
3401 #: ../src/guestfs.pod:1725
3402 msgid "That the bug hasn't been reported already."
3406 #: ../src/guestfs.pod:1729
3407 msgid "That you are testing a recent version."
3411 #: ../src/guestfs.pod:1733
3412 msgid "Describe the bug accurately, and give a way to reproduce it."
3416 #: ../src/guestfs.pod:1737
3418 "Run libguestfs-test-tool and paste the B<complete, unedited> output into the "
3423 #: ../src/guestfs.pod:1742 ../fish/guestfish.pod:1039
3424 #: ../test-tool/libguestfs-test-tool.pod:115 ../fuse/guestmount.pod:189
3425 #: ../inspector/virt-inspector.pl:855
3430 #: ../src/guestfs.pod:1744 ../fish/guestfish.pod:1041
3431 #: ../test-tool/libguestfs-test-tool.pod:117 ../fuse/guestmount.pod:191
3432 msgid "Richard W.M. Jones (C<rjones at redhat dot com>)"
3436 #: ../src/guestfs.pod:1746 ../fish/guestfish.pod:1043
3437 #: ../test-tool/libguestfs-test-tool.pod:119 ../fuse/guestmount.pod:193
3438 #: ../inspector/virt-inspector.pl:861 ../tools/virt-cat.pl:177
3439 #: ../tools/virt-df.pl:495 ../tools/virt-edit.pl:341
3440 #: ../tools/virt-list-filesystems.pl:207 ../tools/virt-list-partitions.pl:244
3441 #: ../tools/virt-ls.pl:225 ../tools/virt-make-fs.pl:556
3442 #: ../tools/virt-rescue.pl:245 ../tools/virt-resize.pl:1411
3443 #: ../tools/virt-tar.pl:272 ../tools/virt-win-reg.pl:491
3448 #: ../src/guestfs.pod:1748 ../fish/guestfish.pod:1045
3449 msgid "Copyright (C) 2009-2010 Red Hat Inc. L<http://libguestfs.org/>"
3453 #: ../src/guestfs.pod:1751
3455 "This library is free software; you can redistribute it and/or modify it "
3456 "under the terms of the GNU Lesser General Public License as published by the "
3457 "Free Software Foundation; either version 2 of the License, or (at your "
3458 "option) any later version."
3462 #: ../src/guestfs.pod:1756
3464 "This library is distributed in the hope that it will be useful, but WITHOUT "
3465 "ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or "
3466 "FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License "
3471 #: ../src/guestfs.pod:1761
3473 "You should have received a copy of the GNU Lesser General Public License "
3474 "along with this library; if not, write to the Free Software Foundation, "
3475 "Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA"
3479 #: ../src/guestfs-actions.pod:1
3480 msgid "guestfs_add_cdrom"
3484 #: ../src/guestfs-actions.pod:3
3487 " int guestfs_add_cdrom (guestfs_h *g,\n"
3488 "\t\tconst char *filename);\n"
3493 #: ../src/guestfs-actions.pod:6 ../fish/guestfish-actions.pod:5
3494 msgid "This function adds a virtual CD-ROM disk image to the guest."
3498 #: ../src/guestfs-actions.pod:8 ../fish/guestfish-actions.pod:7
3499 msgid "This is equivalent to the qemu parameter C<-cdrom filename>."
3503 #: ../src/guestfs-actions.pod:10 ../src/guestfs-actions.pod:1488
3504 #: ../fish/guestfish-actions.pod:9 ../fish/guestfish-actions.pod:1186
3509 #: ../src/guestfs-actions.pod:16
3511 "This call checks for the existence of C<filename>. This stops you from "
3512 "specifying other types of drive which are supported by qemu such as C<nbd:> "
3513 "and C<http:> URLs. To specify those, use the general C<guestfs_config> call "
3518 #: ../src/guestfs-actions.pod:23
3520 "If you just want to add an ISO file (often you use this as an efficient way "
3521 "to transfer large files into the guest), then you should probably use "
3522 "C<guestfs_add_drive_ro> instead."
3526 #: ../src/guestfs-actions.pod:29 ../src/guestfs-actions.pod:63
3527 #: ../src/guestfs-actions.pod:92 ../src/guestfs-actions.pod:103
3528 #: ../src/guestfs-actions.pod:114 ../src/guestfs-actions.pod:124
3529 #: ../src/guestfs-actions.pod:135 ../src/guestfs-actions.pod:238
3530 #: ../src/guestfs-actions.pod:255 ../src/guestfs-actions.pod:266
3531 #: ../src/guestfs-actions.pod:302 ../src/guestfs-actions.pod:324
3532 #: ../src/guestfs-actions.pod:339 ../src/guestfs-actions.pod:403
3533 #: ../src/guestfs-actions.pod:430 ../src/guestfs-actions.pod:441
3534 #: ../src/guestfs-actions.pod:453 ../src/guestfs-actions.pod:534
3535 #: ../src/guestfs-actions.pod:549 ../src/guestfs-actions.pod:560
3536 #: ../src/guestfs-actions.pod:571 ../src/guestfs-actions.pod:717
3537 #: ../src/guestfs-actions.pod:734 ../src/guestfs-actions.pod:749
3538 #: ../src/guestfs-actions.pod:824 ../src/guestfs-actions.pod:839
3539 #: ../src/guestfs-actions.pod:855 ../src/guestfs-actions.pod:866
3540 #: ../src/guestfs-actions.pod:883 ../src/guestfs-actions.pod:916
3541 #: ../src/guestfs-actions.pod:974 ../src/guestfs-actions.pod:996
3542 #: ../src/guestfs-actions.pod:1027 ../src/guestfs-actions.pod:1115
3543 #: ../src/guestfs-actions.pod:1146 ../src/guestfs-actions.pod:1346
3544 #: ../src/guestfs-actions.pod:1365 ../src/guestfs-actions.pod:1446
3545 #: ../src/guestfs-actions.pod:1794 ../src/guestfs-actions.pod:1917
3546 #: ../src/guestfs-actions.pod:1972 ../src/guestfs-actions.pod:2002
3547 #: ../src/guestfs-actions.pod:2349 ../src/guestfs-actions.pod:2361
3548 #: ../src/guestfs-actions.pod:2378 ../src/guestfs-actions.pod:2443
3549 #: ../src/guestfs-actions.pod:2454 ../src/guestfs-actions.pod:2464
3550 #: ../src/guestfs-actions.pod:2475 ../src/guestfs-actions.pod:2487
3551 #: ../src/guestfs-actions.pod:2517 ../src/guestfs-actions.pod:2581
3552 #: ../src/guestfs-actions.pod:2598 ../src/guestfs-actions.pod:2612
3553 #: ../src/guestfs-actions.pod:2632 ../src/guestfs-actions.pod:2652
3554 #: ../src/guestfs-actions.pod:2681 ../src/guestfs-actions.pod:2697
3555 #: ../src/guestfs-actions.pod:2713 ../src/guestfs-actions.pod:2725
3556 #: ../src/guestfs-actions.pod:2734 ../src/guestfs-actions.pod:2767
3557 #: ../src/guestfs-actions.pod:2780 ../src/guestfs-actions.pod:2790
3558 #: ../src/guestfs-actions.pod:2802 ../src/guestfs-actions.pod:2816
3559 #: ../src/guestfs-actions.pod:2896 ../src/guestfs-actions.pod:2913
3560 #: ../src/guestfs-actions.pod:2923 ../src/guestfs-actions.pod:2968
3561 #: ../src/guestfs-actions.pod:2983 ../src/guestfs-actions.pod:2998
3562 #: ../src/guestfs-actions.pod:3011 ../src/guestfs-actions.pod:3022
3563 #: ../src/guestfs-actions.pod:3033 ../src/guestfs-actions.pod:3047
3564 #: ../src/guestfs-actions.pod:3059 ../src/guestfs-actions.pod:3076
3565 #: ../src/guestfs-actions.pod:3107 ../src/guestfs-actions.pod:3135
3566 #: ../src/guestfs-actions.pod:3151 ../src/guestfs-actions.pod:3167
3567 #: ../src/guestfs-actions.pod:3176 ../src/guestfs-actions.pod:3190
3568 #: ../src/guestfs-actions.pod:3200 ../src/guestfs-actions.pod:3212
3569 #: ../src/guestfs-actions.pod:3224 ../src/guestfs-actions.pod:3256
3570 #: ../src/guestfs-actions.pod:3268 ../src/guestfs-actions.pod:3285
3571 #: ../src/guestfs-actions.pod:3296 ../src/guestfs-actions.pod:3310
3572 #: ../src/guestfs-actions.pod:3350 ../src/guestfs-actions.pod:3381
3573 #: ../src/guestfs-actions.pod:3392 ../src/guestfs-actions.pod:3417
3574 #: ../src/guestfs-actions.pod:3431 ../src/guestfs-actions.pod:3446
3575 #: ../src/guestfs-actions.pod:3568 ../src/guestfs-actions.pod:3620
3576 #: ../src/guestfs-actions.pod:3639 ../src/guestfs-actions.pod:3654
3577 #: ../src/guestfs-actions.pod:3665 ../src/guestfs-actions.pod:3699
3578 #: ../src/guestfs-actions.pod:3713 ../src/guestfs-actions.pod:3723
3579 #: ../src/guestfs-actions.pod:3734 ../src/guestfs-actions.pod:3966
3580 #: ../src/guestfs-actions.pod:3982 ../src/guestfs-actions.pod:3993
3581 #: ../src/guestfs-actions.pod:4002 ../src/guestfs-actions.pod:4013
3582 #: ../src/guestfs-actions.pod:4022 ../src/guestfs-actions.pod:4033
3583 #: ../src/guestfs-actions.pod:4046 ../src/guestfs-actions.pod:4064
3584 #: ../src/guestfs-actions.pod:4080 ../src/guestfs-actions.pod:4096
3585 #: ../src/guestfs-actions.pod:4111 ../src/guestfs-actions.pod:4131
3586 #: ../src/guestfs-actions.pod:4146 ../src/guestfs-actions.pod:4162
3587 #: ../src/guestfs-actions.pod:4180 ../src/guestfs-actions.pod:4196
3588 #: ../src/guestfs-actions.pod:4210 ../src/guestfs-actions.pod:4235
3589 #: ../src/guestfs-actions.pod:4256 ../src/guestfs-actions.pod:4272
3590 #: ../src/guestfs-actions.pod:4293 ../src/guestfs-actions.pod:4305
3591 #: ../src/guestfs-actions.pod:4317 ../src/guestfs-actions.pod:4333
3592 #: ../src/guestfs-actions.pod:4367 ../src/guestfs-actions.pod:4387
3593 #: ../src/guestfs-actions.pod:4410 ../src/guestfs-actions.pod:4500
3594 #: ../src/guestfs-actions.pod:4606 ../src/guestfs-actions.pod:4615
3595 #: ../src/guestfs-actions.pod:4625 ../src/guestfs-actions.pod:4635
3596 #: ../src/guestfs-actions.pod:4654 ../src/guestfs-actions.pod:4664
3597 #: ../src/guestfs-actions.pod:4674 ../src/guestfs-actions.pod:4684
3598 #: ../src/guestfs-actions.pod:4696 ../src/guestfs-actions.pod:4746
3599 #: ../src/guestfs-actions.pod:4760 ../src/guestfs-actions.pod:4773
3600 #: ../src/guestfs-actions.pod:4786 ../src/guestfs-actions.pod:4800
3601 #: ../src/guestfs-actions.pod:4810 ../src/guestfs-actions.pod:4827
3602 #: ../src/guestfs-actions.pod:4857 ../src/guestfs-actions.pod:4868
3603 #: ../src/guestfs-actions.pod:4903 ../src/guestfs-actions.pod:4913
3604 #: ../src/guestfs-actions.pod:4928 ../src/guestfs-actions.pod:4956
3605 #: ../src/guestfs-actions.pod:5060 ../src/guestfs-actions.pod:5075
3606 #: ../src/guestfs-actions.pod:5086 ../src/guestfs-actions.pod:5132
3607 #: ../src/guestfs-actions.pod:5142 ../src/guestfs-actions.pod:5179
3608 #: ../src/guestfs-actions.pod:5206 ../src/guestfs-actions.pod:5248
3609 #: ../src/guestfs-actions.pod:5271 ../src/guestfs-actions.pod:5328
3610 #: ../src/guestfs-actions.pod:5344 ../src/guestfs-actions.pod:5370
3611 msgid "This function returns 0 on success or -1 on error."
3615 #: ../src/guestfs-actions.pod:31
3616 msgid "guestfs_add_drive"
3620 #: ../src/guestfs-actions.pod:33
3623 " int guestfs_add_drive (guestfs_h *g,\n"
3624 "\t\tconst char *filename);\n"
3629 #: ../src/guestfs-actions.pod:36 ../fish/guestfish-actions.pod:32
3631 "This function adds a virtual machine disk image C<filename> to the guest. "
3632 "The first time you call this function, the disk appears as IDE disk 0 (C</"
3633 "dev/sda>) in the guest, the second time as C</dev/sdb>, and so on."
3637 #: ../src/guestfs-actions.pod:41 ../fish/guestfish-actions.pod:37
3639 "You don't necessarily need to be root when using libguestfs. However you "
3640 "obviously do need sufficient permissions to access the filename for whatever "
3641 "operations you want to perform (ie. read access if you just want to read the "
3642 "image or write access if you want to modify the image)."
3646 #: ../src/guestfs-actions.pod:47 ../fish/guestfish-actions.pod:43
3648 "This is equivalent to the qemu parameter C<-drive file=filename,cache=off,"
3653 #: ../src/guestfs-actions.pod:50 ../fish/guestfish-actions.pod:46
3655 "C<cache=off> is omitted in cases where it is not supported by the underlying "
3660 #: ../src/guestfs-actions.pod:53 ../src/guestfs-actions.pod:82
3662 "C<if=...> is set at compile time by the configuration option C<./configure --"
3663 "with-drive-if=...>. In the rare case where you might need to change this at "
3664 "run time, use C<guestfs_add_drive_with_if> or "
3665 "C<guestfs_add_drive_ro_with_if>."
3669 #: ../src/guestfs-actions.pod:58 ../src/guestfs-actions.pod:87
3671 "Note that this call checks for the existence of C<filename>. This stops you "
3672 "from specifying other types of drive which are supported by qemu such as "
3673 "C<nbd:> and C<http:> URLs. To specify those, use the general "
3674 "C<guestfs_config> call instead."
3678 #: ../src/guestfs-actions.pod:65
3679 msgid "guestfs_add_drive_ro"
3683 #: ../src/guestfs-actions.pod:67
3686 " int guestfs_add_drive_ro (guestfs_h *g,\n"
3687 "\t\tconst char *filename);\n"
3692 #: ../src/guestfs-actions.pod:70 ../fish/guestfish-actions.pod:63
3693 msgid "This adds a drive in snapshot mode, making it effectively read-only."
3697 #: ../src/guestfs-actions.pod:73 ../fish/guestfish-actions.pod:66
3699 "Note that writes to the device are allowed, and will be seen for the "
3700 "duration of the guestfs handle, but they are written to a temporary file "
3701 "which is discarded as soon as the guestfs handle is closed. We don't "
3702 "currently have any method to enable changes to be committed, although qemu "
3707 #: ../src/guestfs-actions.pod:79 ../fish/guestfish-actions.pod:72
3709 "This is equivalent to the qemu parameter C<-drive file=filename,snapshot=on,"
3714 #: ../src/guestfs-actions.pod:94
3715 msgid "guestfs_add_drive_ro_with_if"
3719 #: ../src/guestfs-actions.pod:96
3722 " int guestfs_add_drive_ro_with_if (guestfs_h *g,\n"
3723 "\t\tconst char *filename,\n"
3724 "\t\tconst char *iface);\n"
3729 #: ../src/guestfs-actions.pod:100
3731 "This is the same as C<guestfs_add_drive_ro> but it allows you to specify the "
3732 "QEMU interface emulation to use at run time."
3736 #: ../src/guestfs-actions.pod:105
3737 msgid "guestfs_add_drive_with_if"
3741 #: ../src/guestfs-actions.pod:107
3744 " int guestfs_add_drive_with_if (guestfs_h *g,\n"
3745 "\t\tconst char *filename,\n"
3746 "\t\tconst char *iface);\n"
3751 #: ../src/guestfs-actions.pod:111
3753 "This is the same as C<guestfs_add_drive> but it allows you to specify the "
3754 "QEMU interface emulation to use at run time."
3758 #: ../src/guestfs-actions.pod:116
3759 msgid "guestfs_aug_clear"
3763 #: ../src/guestfs-actions.pod:118
3766 " int guestfs_aug_clear (guestfs_h *g,\n"
3767 "\t\tconst char *augpath);\n"
3772 #: ../src/guestfs-actions.pod:121 ../fish/guestfish-actions.pod:103
3774 "Set the value associated with C<path> to C<NULL>. This is the same as the "
3775 "L<augtool(1)> C<clear> command."
3779 #: ../src/guestfs-actions.pod:126
3780 msgid "guestfs_aug_close"
3784 #: ../src/guestfs-actions.pod:128
3787 " int guestfs_aug_close (guestfs_h *g);\n"
3792 #: ../src/guestfs-actions.pod:130
3794 "Close the current Augeas handle and free up any resources used by it. After "
3795 "calling this, you have to call C<guestfs_aug_init> again before you can use "
3796 "any other Augeas functions."
3800 #: ../src/guestfs-actions.pod:137
3801 msgid "guestfs_aug_defnode"
3805 #: ../src/guestfs-actions.pod:139
3808 " struct guestfs_int_bool *guestfs_aug_defnode (guestfs_h *g,\n"
3809 "\t\tconst char *name,\n"
3810 "\t\tconst char *expr,\n"
3811 "\t\tconst char *val);\n"
3816 #: ../src/guestfs-actions.pod:144 ../fish/guestfish-actions.pod:119
3818 "Defines a variable C<name> whose value is the result of evaluating C<expr>."
3822 #: ../src/guestfs-actions.pod:147
3824 "If C<expr> evaluates to an empty nodeset, a node is created, equivalent to "
3825 "calling C<guestfs_aug_set> C<expr>, C<value>. C<name> will be the nodeset "
3826 "containing that single node."
3830 #: ../src/guestfs-actions.pod:151 ../fish/guestfish-actions.pod:126
3832 "On success this returns a pair containing the number of nodes in the "
3833 "nodeset, and a boolean flag if a node was created."
3837 #: ../src/guestfs-actions.pod:155
3839 "This function returns a C<struct guestfs_int_bool *>, or NULL if there was "
3840 "an error. I<The caller must call C<guestfs_free_int_bool> after use>."
3844 #: ../src/guestfs-actions.pod:159
3845 msgid "guestfs_aug_defvar"
3849 #: ../src/guestfs-actions.pod:161
3852 " int guestfs_aug_defvar (guestfs_h *g,\n"
3853 "\t\tconst char *name,\n"
3854 "\t\tconst char *expr);\n"
3859 #: ../src/guestfs-actions.pod:165 ../fish/guestfish-actions.pod:134
3861 "Defines an Augeas variable C<name> whose value is the result of evaluating "
3862 "C<expr>. If C<expr> is NULL, then C<name> is undefined."
3866 #: ../src/guestfs-actions.pod:169 ../fish/guestfish-actions.pod:138
3868 "On success this returns the number of nodes in C<expr>, or C<0> if C<expr> "
3869 "evaluates to something which is not a nodeset."
3873 #: ../src/guestfs-actions.pod:172 ../src/guestfs-actions.pod:313
3874 #: ../src/guestfs-actions.pod:467 ../src/guestfs-actions.pod:492
3875 #: ../src/guestfs-actions.pod:507 ../src/guestfs-actions.pod:523
3876 #: ../src/guestfs-actions.pod:1013 ../src/guestfs-actions.pod:1328
3877 #: ../src/guestfs-actions.pod:1510 ../src/guestfs-actions.pod:1591
3878 #: ../src/guestfs-actions.pod:1622 ../src/guestfs-actions.pod:1665
3879 #: ../src/guestfs-actions.pod:1682 ../src/guestfs-actions.pod:1907
3880 #: ../src/guestfs-actions.pod:2119 ../src/guestfs-actions.pod:2137
3881 #: ../src/guestfs-actions.pod:3370 ../src/guestfs-actions.pod:3477
3882 #: ../src/guestfs-actions.pod:3793 ../src/guestfs-actions.pod:4892
3883 #: ../src/guestfs-actions.pod:5216 ../src/guestfs-actions.pod:5226
3884 #: ../src/guestfs-actions.pod:5236
3885 msgid "On error this function returns -1."
3889 #: ../src/guestfs-actions.pod:174
3890 msgid "guestfs_aug_get"
3894 #: ../src/guestfs-actions.pod:176
3897 " char *guestfs_aug_get (guestfs_h *g,\n"
3898 "\t\tconst char *augpath);\n"
3903 #: ../src/guestfs-actions.pod:179 ../fish/guestfish-actions.pod:145
3905 "Look up the value associated with C<path>. If C<path> matches exactly one "
3906 "node, the C<value> is returned."
3910 #: ../src/guestfs-actions.pod:182 ../src/guestfs-actions.pod:610
3911 #: ../src/guestfs-actions.pod:625 ../src/guestfs-actions.pod:682
3912 #: ../src/guestfs-actions.pod:695 ../src/guestfs-actions.pod:786
3913 #: ../src/guestfs-actions.pod:899 ../src/guestfs-actions.pod:928
3914 #: ../src/guestfs-actions.pod:942 ../src/guestfs-actions.pod:958
3915 #: ../src/guestfs-actions.pod:1041 ../src/guestfs-actions.pod:1205
3916 #: ../src/guestfs-actions.pod:1314 ../src/guestfs-actions.pod:1459
3917 #: ../src/guestfs-actions.pod:1473 ../src/guestfs-actions.pod:1549
3918 #: ../src/guestfs-actions.pod:1567 ../src/guestfs-actions.pod:1701
3919 #: ../src/guestfs-actions.pod:1840 ../src/guestfs-actions.pod:2021
3920 #: ../src/guestfs-actions.pod:2071 ../src/guestfs-actions.pod:2187
3921 #: ../src/guestfs-actions.pod:2222 ../src/guestfs-actions.pod:2432
3922 #: ../src/guestfs-actions.pod:2853 ../src/guestfs-actions.pod:2949
3923 #: ../src/guestfs-actions.pod:3492 ../src/guestfs-actions.pod:3771
3924 #: ../src/guestfs-actions.pod:3909 ../src/guestfs-actions.pod:3952
3925 #: ../src/guestfs-actions.pod:4428 ../src/guestfs-actions.pod:4441
3926 #: ../src/guestfs-actions.pod:4455 ../src/guestfs-actions.pod:4476
3927 #: ../src/guestfs-actions.pod:5009 ../src/guestfs-actions.pod:5025
3928 #: ../src/guestfs-actions.pod:5040 ../src/guestfs-actions.pod:5188
3929 #: ../src/guestfs-actions.pod:5418
3931 "This function returns a string, or NULL on error. I<The caller must free "
3932 "the returned string after use>."
3936 #: ../src/guestfs-actions.pod:185
3937 msgid "guestfs_aug_init"
3941 #: ../src/guestfs-actions.pod:187
3944 " int guestfs_aug_init (guestfs_h *g,\n"
3945 "\t\tconst char *root,\n"
3951 #: ../src/guestfs-actions.pod:191 ../fish/guestfish-actions.pod:152
3953 "Create a new Augeas handle for editing configuration files. If there was "
3954 "any previous Augeas handle associated with this guestfs session, then it is "
3959 #: ../src/guestfs-actions.pod:195
3960 msgid "You must call this before using any other C<guestfs_aug_*> commands."
3964 #: ../src/guestfs-actions.pod:198 ../fish/guestfish-actions.pod:159
3966 "C<root> is the filesystem root. C<root> must not be NULL, use C</> instead."
3970 #: ../src/guestfs-actions.pod:201 ../fish/guestfish-actions.pod:162
3972 "The flags are the same as the flags defined in E<lt>augeas.hE<gt>, the "
3973 "logical I<or> of the following integers:"
3977 #: ../src/guestfs-actions.pod:207 ../fish/guestfish-actions.pod:168
3978 msgid "C<AUG_SAVE_BACKUP> = 1"
3982 #: ../src/guestfs-actions.pod:209 ../fish/guestfish-actions.pod:170
3983 msgid "Keep the original file with a C<.augsave> extension."
3987 #: ../src/guestfs-actions.pod:211 ../fish/guestfish-actions.pod:172
3988 msgid "C<AUG_SAVE_NEWFILE> = 2"
3992 #: ../src/guestfs-actions.pod:213 ../fish/guestfish-actions.pod:174
3994 "Save changes into a file with extension C<.augnew>, and do not overwrite "
3995 "original. Overrides C<AUG_SAVE_BACKUP>."
3999 #: ../src/guestfs-actions.pod:216 ../fish/guestfish-actions.pod:177
4000 msgid "C<AUG_TYPE_CHECK> = 4"
4004 #: ../src/guestfs-actions.pod:218 ../fish/guestfish-actions.pod:179
4005 msgid "Typecheck lenses (can be expensive)."
4009 #: ../src/guestfs-actions.pod:220 ../fish/guestfish-actions.pod:181
4010 msgid "C<AUG_NO_STDINC> = 8"
4014 #: ../src/guestfs-actions.pod:222 ../fish/guestfish-actions.pod:183
4015 msgid "Do not use standard load path for modules."
4019 #: ../src/guestfs-actions.pod:224 ../fish/guestfish-actions.pod:185
4020 msgid "C<AUG_SAVE_NOOP> = 16"
4024 #: ../src/guestfs-actions.pod:226 ../fish/guestfish-actions.pod:187
4025 msgid "Make save a no-op, just record what would have been changed."
4029 #: ../src/guestfs-actions.pod:228 ../fish/guestfish-actions.pod:189
4030 msgid "C<AUG_NO_LOAD> = 32"
4034 #: ../src/guestfs-actions.pod:230
4035 msgid "Do not load the tree in C<guestfs_aug_init>."
4039 #: ../src/guestfs-actions.pod:234
4040 msgid "To close the handle, you can call C<guestfs_aug_close>."
4044 #: ../src/guestfs-actions.pod:236 ../fish/guestfish-actions.pod:197
4045 msgid "To find out more about Augeas, see L<http://augeas.net/>."
4049 #: ../src/guestfs-actions.pod:240
4050 msgid "guestfs_aug_insert"
4054 #: ../src/guestfs-actions.pod:242
4057 " int guestfs_aug_insert (guestfs_h *g,\n"
4058 "\t\tconst char *augpath,\n"
4059 "\t\tconst char *label,\n"
4060 "\t\tint before);\n"
4065 #: ../src/guestfs-actions.pod:247 ../fish/guestfish-actions.pod:203
4067 "Create a new sibling C<label> for C<path>, inserting it into the tree before "
4068 "or after C<path> (depending on the boolean flag C<before>)."
4072 #: ../src/guestfs-actions.pod:251 ../fish/guestfish-actions.pod:207
4074 "C<path> must match exactly one existing node in the tree, and C<label> must "
4075 "be a label, ie. not contain C</>, C<*> or end with a bracketed index C<[N]>."
4079 #: ../src/guestfs-actions.pod:257
4080 msgid "guestfs_aug_load"
4084 #: ../src/guestfs-actions.pod:259
4087 " int guestfs_aug_load (guestfs_h *g);\n"
4092 #: ../src/guestfs-actions.pod:261 ../fish/guestfish-actions.pod:215
4093 msgid "Load files into the tree."
4097 #: ../src/guestfs-actions.pod:263 ../fish/guestfish-actions.pod:217
4098 msgid "See C<aug_load> in the Augeas documentation for the full gory details."
4102 #: ../src/guestfs-actions.pod:268
4103 msgid "guestfs_aug_ls"
4107 #: ../src/guestfs-actions.pod:270
4110 " char **guestfs_aug_ls (guestfs_h *g,\n"
4111 "\t\tconst char *augpath);\n"
4116 #: ../src/guestfs-actions.pod:273
4118 "This is just a shortcut for listing C<guestfs_aug_match> C<path/*> and "
4119 "sorting the resulting nodes into alphabetical order."
4123 #: ../src/guestfs-actions.pod:276 ../src/guestfs-actions.pod:289
4124 #: ../src/guestfs-actions.pod:417 ../src/guestfs-actions.pod:802
4125 #: ../src/guestfs-actions.pod:1053 ../src/guestfs-actions.pod:1069
4126 #: ../src/guestfs-actions.pod:1157 ../src/guestfs-actions.pod:1173
4127 #: ../src/guestfs-actions.pod:1404 ../src/guestfs-actions.pod:1738
4128 #: ../src/guestfs-actions.pod:1751 ../src/guestfs-actions.pod:1767
4129 #: ../src/guestfs-actions.pod:1804 ../src/guestfs-actions.pod:1825
4130 #: ../src/guestfs-actions.pod:1887 ../src/guestfs-actions.pod:1927
4131 #: ../src/guestfs-actions.pod:2093 ../src/guestfs-actions.pod:2259
4132 #: ../src/guestfs-actions.pod:2402 ../src/guestfs-actions.pod:2417
4133 #: ../src/guestfs-actions.pod:2501 ../src/guestfs-actions.pod:2830
4134 #: ../src/guestfs-actions.pod:3337 ../src/guestfs-actions.pod:3748
4135 #: ../src/guestfs-actions.pod:3834 ../src/guestfs-actions.pod:3940
4136 #: ../src/guestfs-actions.pod:4489 ../src/guestfs-actions.pod:4538
4137 #: ../src/guestfs-actions.pod:4590 ../src/guestfs-actions.pod:4706
4138 #: ../src/guestfs-actions.pod:4727 ../src/guestfs-actions.pod:5101
4139 #: ../src/guestfs-actions.pod:5118 ../src/guestfs-actions.pod:5156
4140 #: ../src/guestfs-actions.pod:5292 ../src/guestfs-actions.pod:5308
4141 #: ../src/guestfs-actions.pod:5381 ../src/guestfs-actions.pod:5397
4142 #: ../src/guestfs-actions.pod:5437 ../src/guestfs-actions.pod:5453
4144 "This function returns a NULL-terminated array of strings (like L<environ(3)"
4145 ">), or NULL if there was an error. I<The caller must free the strings and "
4146 "the array after use>."
4150 #: ../src/guestfs-actions.pod:280
4151 msgid "guestfs_aug_match"
4155 #: ../src/guestfs-actions.pod:282
4158 " char **guestfs_aug_match (guestfs_h *g,\n"
4159 "\t\tconst char *augpath);\n"
4164 #: ../src/guestfs-actions.pod:285 ../fish/guestfish-actions.pod:231
4166 "Returns a list of paths which match the path expression C<path>. The "
4167 "returned paths are sufficiently qualified so that they match exactly one "
4168 "node in the current tree."
4172 #: ../src/guestfs-actions.pod:293
4173 msgid "guestfs_aug_mv"
4177 #: ../src/guestfs-actions.pod:295
4180 " int guestfs_aug_mv (guestfs_h *g,\n"
4181 "\t\tconst char *src,\n"
4182 "\t\tconst char *dest);\n"
4187 #: ../src/guestfs-actions.pod:299 ../fish/guestfish-actions.pod:239
4189 "Move the node C<src> to C<dest>. C<src> must match exactly one node. "
4190 "C<dest> is overwritten if it exists."
4194 #: ../src/guestfs-actions.pod:304
4195 msgid "guestfs_aug_rm"
4199 #: ../src/guestfs-actions.pod:306
4202 " int guestfs_aug_rm (guestfs_h *g,\n"
4203 "\t\tconst char *augpath);\n"
4208 #: ../src/guestfs-actions.pod:309 ../fish/guestfish-actions.pod:246
4209 msgid "Remove C<path> and all of its children."
4213 #: ../src/guestfs-actions.pod:311 ../fish/guestfish-actions.pod:248
4214 msgid "On success this returns the number of entries which were removed."
4218 #: ../src/guestfs-actions.pod:315
4219 msgid "guestfs_aug_save"
4223 #: ../src/guestfs-actions.pod:317
4226 " int guestfs_aug_save (guestfs_h *g);\n"
4231 #: ../src/guestfs-actions.pod:319 ../fish/guestfish-actions.pod:254
4232 msgid "This writes all pending changes to disk."
4236 #: ../src/guestfs-actions.pod:321
4238 "The flags which were passed to C<guestfs_aug_init> affect exactly how files "
4243 #: ../src/guestfs-actions.pod:326
4244 msgid "guestfs_aug_set"
4248 #: ../src/guestfs-actions.pod:328
4251 " int guestfs_aug_set (guestfs_h *g,\n"
4252 "\t\tconst char *augpath,\n"
4253 "\t\tconst char *val);\n"
4258 #: ../src/guestfs-actions.pod:332 ../fish/guestfish-actions.pod:263
4259 msgid "Set the value associated with C<path> to C<val>."
4263 #: ../src/guestfs-actions.pod:334
4265 "In the Augeas API, it is possible to clear a node by setting the value to "
4266 "NULL. Due to an oversight in the libguestfs API you cannot do that with "
4267 "this call. Instead you must use the C<guestfs_aug_clear> call."
4271 #: ../src/guestfs-actions.pod:341
4272 msgid "guestfs_available"
4276 #: ../src/guestfs-actions.pod:343
4279 " int guestfs_available (guestfs_h *g,\n"
4280 "\t\tchar *const *groups);\n"
4285 #: ../src/guestfs-actions.pod:346 ../fish/guestfish-actions.pod:274
4287 "This command is used to check the availability of some groups of "
4288 "functionality in the appliance, which not all builds of the libguestfs "
4289 "appliance will be able to provide."
4293 #: ../src/guestfs-actions.pod:350
4295 "The libguestfs groups, and the functions that those groups correspond to, "
4296 "are listed in L<guestfs(3)/AVAILABILITY>. You can also fetch this list at "
4297 "runtime by calling C<guestfs_available_all_groups>."
4301 #: ../src/guestfs-actions.pod:355 ../fish/guestfish-actions.pod:283
4303 "The argument C<groups> is a list of group names, eg: C<[\"inotify\", \"augeas"
4304 "\"]> would check for the availability of the Linux inotify functions and "
4305 "Augeas (configuration file editing) functions."
4309 #: ../src/guestfs-actions.pod:360 ../fish/guestfish-actions.pod:288
4310 msgid "The command returns no error if I<all> requested groups are available."
4314 #: ../src/guestfs-actions.pod:362 ../fish/guestfish-actions.pod:290
4316 "It fails with an error if one or more of the requested groups is unavailable "
4321 #: ../src/guestfs-actions.pod:365 ../fish/guestfish-actions.pod:293
4323 "If an unknown group name is included in the list of groups then an error is "
4328 #: ../src/guestfs-actions.pod:368 ../fish/guestfish-actions.pod:296
4333 #: ../src/guestfs-actions.pod:374
4334 msgid "You must call C<guestfs_launch> before calling this function."
4338 #: ../src/guestfs-actions.pod:376 ../fish/guestfish-actions.pod:304
4340 "The reason is because we don't know what groups are supported by the "
4341 "appliance/daemon until it is running and can be queried."
4345 #: ../src/guestfs-actions.pod:382 ../fish/guestfish-actions.pod:310
4347 "If a group of functions is available, this does not necessarily mean that "
4348 "they will work. You still have to check for errors when calling individual "
4349 "API functions even if they are available."
4353 #: ../src/guestfs-actions.pod:389 ../fish/guestfish-actions.pod:317
4355 "It is usually the job of distro packagers to build complete functionality "
4356 "into the libguestfs appliance. Upstream libguestfs, if built from source "
4357 "with all requirements satisfied, will support everything."
4361 #: ../src/guestfs-actions.pod:396
4363 "This call was added in version C<1.0.80>. In previous versions of "
4364 "libguestfs all you could do would be to speculatively execute a command to "
4365 "find out if the daemon implemented it. See also C<guestfs_version>."
4369 #: ../src/guestfs-actions.pod:405
4370 msgid "guestfs_available_all_groups"
4374 #: ../src/guestfs-actions.pod:407
4377 " char **guestfs_available_all_groups (guestfs_h *g);\n"
4382 #: ../src/guestfs-actions.pod:409
4384 "This command returns a list of all optional groups that this daemon knows "
4385 "about. Note this returns both supported and unsupported groups. To find "
4386 "out which ones the daemon can actually support you have to call "
4387 "C<guestfs_available> on each member of the returned list."
4391 #: ../src/guestfs-actions.pod:415
4392 msgid "See also C<guestfs_available> and L<guestfs(3)/AVAILABILITY>."
4396 #: ../src/guestfs-actions.pod:421
4397 msgid "guestfs_base64_in"
4401 #: ../src/guestfs-actions.pod:423
4404 " int guestfs_base64_in (guestfs_h *g,\n"
4405 "\t\tconst char *base64file,\n"
4406 "\t\tconst char *filename);\n"
4411 #: ../src/guestfs-actions.pod:427 ../fish/guestfish-actions.pod:347
4413 "This command uploads base64-encoded data from C<base64file> to C<filename>."
4417 #: ../src/guestfs-actions.pod:432
4418 msgid "guestfs_base64_out"
4422 #: ../src/guestfs-actions.pod:434
4425 " int guestfs_base64_out (guestfs_h *g,\n"
4426 "\t\tconst char *filename,\n"
4427 "\t\tconst char *base64file);\n"
4432 #: ../src/guestfs-actions.pod:438 ../fish/guestfish-actions.pod:356
4434 "This command downloads the contents of C<filename>, writing it out to local "
4435 "file C<base64file> encoded as base64."
4439 #: ../src/guestfs-actions.pod:443
4440 msgid "guestfs_blockdev_flushbufs"
4444 #: ../src/guestfs-actions.pod:445
4447 " int guestfs_blockdev_flushbufs (guestfs_h *g,\n"
4448 "\t\tconst char *device);\n"
4453 #: ../src/guestfs-actions.pod:448 ../fish/guestfish-actions.pod:365
4455 "This tells the kernel to flush internal buffers associated with C<device>."
4459 #: ../src/guestfs-actions.pod:451 ../src/guestfs-actions.pod:465
4460 #: ../src/guestfs-actions.pod:477 ../src/guestfs-actions.pod:490
4461 #: ../src/guestfs-actions.pod:505 ../src/guestfs-actions.pod:521
4462 #: ../src/guestfs-actions.pod:532 ../src/guestfs-actions.pod:547
4463 #: ../src/guestfs-actions.pod:558 ../src/guestfs-actions.pod:569
4464 #: ../fish/guestfish-actions.pod:368 ../fish/guestfish-actions.pod:379
4465 #: ../fish/guestfish-actions.pod:388 ../fish/guestfish-actions.pod:398
4466 #: ../fish/guestfish-actions.pod:410 ../fish/guestfish-actions.pod:423
4467 #: ../fish/guestfish-actions.pod:431 ../fish/guestfish-actions.pod:442
4468 #: ../fish/guestfish-actions.pod:450 ../fish/guestfish-actions.pod:458
4469 msgid "This uses the L<blockdev(8)> command."
4473 #: ../src/guestfs-actions.pod:455
4474 msgid "guestfs_blockdev_getbsz"
4478 #: ../src/guestfs-actions.pod:457
4481 " int guestfs_blockdev_getbsz (guestfs_h *g,\n"
4482 "\t\tconst char *device);\n"
4487 #: ../src/guestfs-actions.pod:460 ../fish/guestfish-actions.pod:374
4488 msgid "This returns the block size of a device."
4492 #: ../src/guestfs-actions.pod:462 ../src/guestfs-actions.pod:544
4493 #: ../fish/guestfish-actions.pod:376 ../fish/guestfish-actions.pod:439
4495 "(Note this is different from both I<size in blocks> and I<filesystem block "
4500 #: ../src/guestfs-actions.pod:469
4501 msgid "guestfs_blockdev_getro"
4505 #: ../src/guestfs-actions.pod:471
4508 " int guestfs_blockdev_getro (guestfs_h *g,\n"
4509 "\t\tconst char *device);\n"
4514 #: ../src/guestfs-actions.pod:474 ../fish/guestfish-actions.pod:385
4516 "Returns a boolean indicating if the block device is read-only (true if read-"
4517 "only, false if not)."
4521 #: ../src/guestfs-actions.pod:479 ../src/guestfs-actions.pod:1087
4522 #: ../src/guestfs-actions.pod:1099 ../src/guestfs-actions.pod:1531
4523 #: ../src/guestfs-actions.pod:1539 ../src/guestfs-actions.pod:1599
4524 #: ../src/guestfs-actions.pod:1642 ../src/guestfs-actions.pod:1654
4525 #: ../src/guestfs-actions.pod:1673 ../src/guestfs-actions.pod:1690
4526 #: ../src/guestfs-actions.pod:2272 ../src/guestfs-actions.pod:2283
4527 #: ../src/guestfs-actions.pod:2296 ../src/guestfs-actions.pod:2309
4528 #: ../src/guestfs-actions.pod:2320 ../src/guestfs-actions.pod:2330
4529 #: ../src/guestfs-actions.pod:2341 ../src/guestfs-actions.pod:3462
4530 msgid "This function returns a C truth value on success or -1 on error."
4534 #: ../src/guestfs-actions.pod:481
4535 msgid "guestfs_blockdev_getsize64"
4539 #: ../src/guestfs-actions.pod:483
4542 " int64_t guestfs_blockdev_getsize64 (guestfs_h *g,\n"
4543 "\t\tconst char *device);\n"
4548 #: ../src/guestfs-actions.pod:486 ../fish/guestfish-actions.pod:394
4549 msgid "This returns the size of the device in bytes."
4553 #: ../src/guestfs-actions.pod:488
4554 msgid "See also C<guestfs_blockdev_getsz>."
4558 #: ../src/guestfs-actions.pod:494
4559 msgid "guestfs_blockdev_getss"
4563 #: ../src/guestfs-actions.pod:496
4566 " int guestfs_blockdev_getss (guestfs_h *g,\n"
4567 "\t\tconst char *device);\n"
4572 #: ../src/guestfs-actions.pod:499 ../fish/guestfish-actions.pod:404
4574 "This returns the size of sectors on a block device. Usually 512, but can be "
4575 "larger for modern devices."
4579 #: ../src/guestfs-actions.pod:502
4581 "(Note, this is not the size in sectors, use C<guestfs_blockdev_getsz> for "
4586 #: ../src/guestfs-actions.pod:509
4587 msgid "guestfs_blockdev_getsz"
4591 #: ../src/guestfs-actions.pod:511
4594 " int64_t guestfs_blockdev_getsz (guestfs_h *g,\n"
4595 "\t\tconst char *device);\n"
4600 #: ../src/guestfs-actions.pod:514 ../fish/guestfish-actions.pod:416
4602 "This returns the size of the device in units of 512-byte sectors (even if "
4603 "the sectorsize isn't 512 bytes ... weird)."
4607 #: ../src/guestfs-actions.pod:517
4609 "See also C<guestfs_blockdev_getss> for the real sector size of the device, "
4610 "and C<guestfs_blockdev_getsize64> for the more useful I<size in bytes>."
4614 #: ../src/guestfs-actions.pod:525
4615 msgid "guestfs_blockdev_rereadpt"
4619 #: ../src/guestfs-actions.pod:527
4622 " int guestfs_blockdev_rereadpt (guestfs_h *g,\n"
4623 "\t\tconst char *device);\n"
4628 #: ../src/guestfs-actions.pod:530 ../fish/guestfish-actions.pod:429
4629 msgid "Reread the partition table on C<device>."
4633 #: ../src/guestfs-actions.pod:536
4634 msgid "guestfs_blockdev_setbsz"
4638 #: ../src/guestfs-actions.pod:538
4641 " int guestfs_blockdev_setbsz (guestfs_h *g,\n"
4642 "\t\tconst char *device,\n"
4643 "\t\tint blocksize);\n"
4648 #: ../src/guestfs-actions.pod:542 ../fish/guestfish-actions.pod:437
4649 msgid "This sets the block size of a device."
4653 #: ../src/guestfs-actions.pod:551
4654 msgid "guestfs_blockdev_setro"
4658 #: ../src/guestfs-actions.pod:553
4661 " int guestfs_blockdev_setro (guestfs_h *g,\n"
4662 "\t\tconst char *device);\n"
4667 #: ../src/guestfs-actions.pod:556 ../fish/guestfish-actions.pod:448
4668 msgid "Sets the block device named C<device> to read-only."
4672 #: ../src/guestfs-actions.pod:562
4673 msgid "guestfs_blockdev_setrw"
4677 #: ../src/guestfs-actions.pod:564
4680 " int guestfs_blockdev_setrw (guestfs_h *g,\n"
4681 "\t\tconst char *device);\n"
4686 #: ../src/guestfs-actions.pod:567 ../fish/guestfish-actions.pod:456
4687 msgid "Sets the block device named C<device> to read-write."
4691 #: ../src/guestfs-actions.pod:573
4692 msgid "guestfs_case_sensitive_path"
4696 #: ../src/guestfs-actions.pod:575
4699 " char *guestfs_case_sensitive_path (guestfs_h *g,\n"
4700 "\t\tconst char *path);\n"
4705 #: ../src/guestfs-actions.pod:578 ../fish/guestfish-actions.pod:464
4707 "This can be used to resolve case insensitive paths on a filesystem which is "
4708 "case sensitive. The use case is to resolve paths which you have read from "
4709 "Windows configuration files or the Windows Registry, to the true path."
4713 #: ../src/guestfs-actions.pod:583 ../fish/guestfish-actions.pod:469
4715 "The command handles a peculiarity of the Linux ntfs-3g filesystem driver "
4716 "(and probably others), which is that although the underlying filesystem is "
4717 "case-insensitive, the driver exports the filesystem to Linux as case-"
4722 #: ../src/guestfs-actions.pod:588 ../fish/guestfish-actions.pod:474
4724 "One consequence of this is that special directories such as C<c:\\windows> "
4725 "may appear as C</WINDOWS> or C</windows> (or other things) depending on the "
4726 "precise details of how they were created. In Windows itself this would not "
4731 #: ../src/guestfs-actions.pod:594 ../fish/guestfish-actions.pod:480
4733 "Bug or feature? You decide: L<http://www.tuxera.com/community/ntfs-3g-faq/"
4738 #: ../src/guestfs-actions.pod:597 ../fish/guestfish-actions.pod:483
4740 "This function resolves the true case of each element in the path and returns "
4741 "the case-sensitive path."
4745 #: ../src/guestfs-actions.pod:600
4747 "Thus C<guestfs_case_sensitive_path> (\"/Windows/System32\") might return C<"
4748 "\"/WINDOWS/system32\"> (the exact return value would depend on details of "
4749 "how the directories were originally created under Windows)."
4753 #: ../src/guestfs-actions.pod:605 ../fish/guestfish-actions.pod:491
4754 msgid "I<Note>: This function does not handle drive names, backslashes etc."
4758 #: ../src/guestfs-actions.pod:608
4759 msgid "See also C<guestfs_realpath>."
4763 #: ../src/guestfs-actions.pod:613
4768 #: ../src/guestfs-actions.pod:615
4771 " char *guestfs_cat (guestfs_h *g,\n"
4772 "\t\tconst char *path);\n"
4777 #: ../src/guestfs-actions.pod:618 ../src/guestfs-actions.pod:3824
4778 #: ../fish/guestfish-actions.pod:500 ../fish/guestfish-actions.pod:2944
4779 msgid "Return the contents of the file named C<path>."
4783 #: ../src/guestfs-actions.pod:620
4785 "Note that this function cannot correctly handle binary files (specifically, "
4786 "files containing C<\\0> character which is treated as end of string). For "
4787 "those you need to use the C<guestfs_read_file> or C<guestfs_download> "
4788 "functions which have a more complex interface."
4792 #: ../src/guestfs-actions.pod:628 ../src/guestfs-actions.pod:789
4793 #: ../src/guestfs-actions.pod:806 ../src/guestfs-actions.pod:1057
4794 #: ../src/guestfs-actions.pod:1073 ../src/guestfs-actions.pod:1161
4795 #: ../src/guestfs-actions.pod:1177 ../src/guestfs-actions.pod:1408
4796 #: ../src/guestfs-actions.pod:1755 ../src/guestfs-actions.pod:1771
4797 #: ../src/guestfs-actions.pod:1808 ../src/guestfs-actions.pod:1829
4798 #: ../src/guestfs-actions.pod:1843 ../src/guestfs-actions.pod:1869
4799 #: ../src/guestfs-actions.pod:3687 ../src/guestfs-actions.pod:3795
4800 #: ../src/guestfs-actions.pod:3816 ../src/guestfs-actions.pod:4542
4801 #: ../src/guestfs-actions.pod:4594 ../src/guestfs-actions.pod:4710
4802 #: ../src/guestfs-actions.pod:4731 ../src/guestfs-actions.pod:5250
4803 #: ../src/guestfs-actions.pod:5273 ../src/guestfs-actions.pod:5296
4804 #: ../src/guestfs-actions.pod:5312 ../src/guestfs-actions.pod:5385
4805 #: ../src/guestfs-actions.pod:5401 ../src/guestfs-actions.pod:5441
4806 #: ../src/guestfs-actions.pod:5457 ../fish/guestfish-actions.pod:507
4807 #: ../fish/guestfish-actions.pod:642 ../fish/guestfish-actions.pod:654
4808 #: ../fish/guestfish-actions.pod:836 ../fish/guestfish-actions.pod:846
4809 #: ../fish/guestfish-actions.pod:913 ../fish/guestfish-actions.pod:923
4810 #: ../fish/guestfish-actions.pod:1118 ../fish/guestfish-actions.pod:1391
4811 #: ../fish/guestfish-actions.pod:1401 ../fish/guestfish-actions.pod:1429
4812 #: ../fish/guestfish-actions.pod:1444 ../fish/guestfish-actions.pod:1454
4813 #: ../fish/guestfish-actions.pod:1473 ../fish/guestfish-actions.pod:2846
4814 #: ../fish/guestfish-actions.pod:2922 ../fish/guestfish-actions.pod:2937
4815 #: ../fish/guestfish-actions.pod:3498 ../fish/guestfish-actions.pod:3544
4816 #: ../fish/guestfish-actions.pod:3629 ../fish/guestfish-actions.pod:3644
4817 #: ../fish/guestfish-actions.pod:4027 ../fish/guestfish-actions.pod:4045
4818 #: ../fish/guestfish-actions.pod:4062 ../fish/guestfish-actions.pod:4072
4819 #: ../fish/guestfish-actions.pod:4120 ../fish/guestfish-actions.pod:4130
4820 #: ../fish/guestfish-actions.pod:4159 ../fish/guestfish-actions.pod:4169
4822 "Because of the message protocol, there is a transfer limit of somewhere "
4823 "between 2MB and 4MB. See L<guestfs(3)/PROTOCOL LIMITS>."
4827 #: ../src/guestfs-actions.pod:631
4828 msgid "guestfs_checksum"
4832 #: ../src/guestfs-actions.pod:633
4835 " char *guestfs_checksum (guestfs_h *g,\n"
4836 "\t\tconst char *csumtype,\n"
4837 "\t\tconst char *path);\n"
4842 #: ../src/guestfs-actions.pod:637 ../fish/guestfish-actions.pod:514
4844 "This call computes the MD5, SHAx or CRC checksum of the file named C<path>."
4848 #: ../src/guestfs-actions.pod:640 ../fish/guestfish-actions.pod:517
4850 "The type of checksum to compute is given by the C<csumtype> parameter which "
4851 "must have one of the following values:"
4855 #: ../src/guestfs-actions.pod:645 ../fish/guestfish-actions.pod:522
4860 #: ../src/guestfs-actions.pod:647 ../fish/guestfish-actions.pod:524
4862 "Compute the cyclic redundancy check (CRC) specified by POSIX for the "
4867 #: ../src/guestfs-actions.pod:650 ../fish/guestfish-actions.pod:527
4872 #: ../src/guestfs-actions.pod:652 ../fish/guestfish-actions.pod:529
4873 msgid "Compute the MD5 hash (using the C<md5sum> program)."
4877 #: ../src/guestfs-actions.pod:654 ../fish/guestfish-actions.pod:531
4882 #: ../src/guestfs-actions.pod:656 ../fish/guestfish-actions.pod:533
4883 msgid "Compute the SHA1 hash (using the C<sha1sum> program)."
4887 #: ../src/guestfs-actions.pod:658 ../fish/guestfish-actions.pod:535
4892 #: ../src/guestfs-actions.pod:660 ../fish/guestfish-actions.pod:537
4893 msgid "Compute the SHA224 hash (using the C<sha224sum> program)."
4897 #: ../src/guestfs-actions.pod:662 ../fish/guestfish-actions.pod:539
4902 #: ../src/guestfs-actions.pod:664 ../fish/guestfish-actions.pod:541
4903 msgid "Compute the SHA256 hash (using the C<sha256sum> program)."
4907 #: ../src/guestfs-actions.pod:666 ../fish/guestfish-actions.pod:543
4912 #: ../src/guestfs-actions.pod:668 ../fish/guestfish-actions.pod:545
4913 msgid "Compute the SHA384 hash (using the C<sha384sum> program)."
4917 #: ../src/guestfs-actions.pod:670 ../fish/guestfish-actions.pod:547
4922 #: ../src/guestfs-actions.pod:672 ../fish/guestfish-actions.pod:549
4923 msgid "Compute the SHA512 hash (using the C<sha512sum> program)."
4927 #: ../src/guestfs-actions.pod:676 ../fish/guestfish-actions.pod:553
4928 msgid "The checksum is returned as a printable string."