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-26 22: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"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: ../src/guestfs.pod:1 ../fish/guestfish.pod:1
21 #: ../test-tool/libguestfs-test-tool.pod:1 ../fuse/guestmount.pod:1
22 #: ../inspector/virt-inspector.pl:36 ../tools/virt-edit.pl:31
23 #: ../tools/virt-win-reg.pl:34 ../tools/virt-df.pl:32 ../tools/virt-ls.pl:31
24 #: ../tools/virt-resize.pl:38 ../tools/virt-list-filesystems.pl:28
25 #: ../tools/virt-cat.pl:30 ../tools/virt-tar.pl:30 ../tools/virt-rescue.pl:29
26 #: ../tools/virt-make-fs.pl:33 ../tools/virt-list-partitions.pl:28
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-edit.pl:33
34 #: ../tools/virt-win-reg.pl:36 ../tools/virt-df.pl:34 ../tools/virt-ls.pl:33
35 #: ../tools/virt-resize.pl:40 ../tools/virt-list-filesystems.pl:30
36 #: ../tools/virt-cat.pl:32 ../tools/virt-tar.pl:32 ../tools/virt-rescue.pl:31
37 #: ../tools/virt-make-fs.pl:35 ../tools/virt-list-partitions.pl:30
42 #: ../src/guestfs.pod:5
43 msgid "guestfs - Library for accessing and modifying virtual machine images"
47 #: ../src/guestfs.pod:7 ../fish/guestfish.pod:7
48 #: ../test-tool/libguestfs-test-tool.pod:7 ../fuse/guestmount.pod:7
49 #: ../inspector/virt-inspector.pl:42 ../tools/virt-edit.pl:37
50 #: ../tools/virt-win-reg.pl:40 ../tools/virt-df.pl:38 ../tools/virt-ls.pl:37
51 #: ../tools/virt-resize.pl:44 ../tools/virt-list-filesystems.pl:34
52 #: ../tools/virt-cat.pl:36 ../tools/virt-tar.pl:36 ../tools/virt-rescue.pl:35
53 #: ../tools/virt-make-fs.pl:39 ../tools/virt-list-partitions.pl:34
58 #: ../src/guestfs.pod:9
61 " #include <guestfs.h>\n"
66 #: ../src/guestfs.pod:11
69 " guestfs_h *g = guestfs_create ();\n"
70 " guestfs_add_drive (g, \"guest.img\");\n"
71 " guestfs_launch (g);\n"
72 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
73 " guestfs_touch (g, \"/hello\");\n"
74 " guestfs_umount (g, \"/\");\n"
75 " guestfs_sync (g);\n"
76 " guestfs_close (g);\n"
81 #: ../src/guestfs.pod:20
84 " cc prog.c -o prog -lguestfs\n"
86 " cc prog.c -o prog `pkg-config libguestfs --cflags --libs`\n"
91 #: ../src/guestfs.pod:24 ../fish/guestfish.pod:30
92 #: ../test-tool/libguestfs-test-tool.pod:11 ../fuse/guestmount.pod:16
93 #: ../inspector/virt-inspector.pl:48 ../tools/virt-edit.pl:51
94 #: ../tools/virt-win-reg.pl:64 ../tools/virt-df.pl:46 ../tools/virt-ls.pl:43
95 #: ../tools/virt-resize.pl:50 ../tools/virt-list-filesystems.pl:40
96 #: ../tools/virt-cat.pl:42 ../tools/virt-tar.pl:73 ../tools/virt-rescue.pl:51
97 #: ../tools/virt-make-fs.pl:47 ../tools/virt-list-partitions.pl:40
102 #: ../src/guestfs.pod:26
104 "Libguestfs is a library for accessing and modifying guest disk images. "
105 "Amongst the things this is good for: making batch configuration changes to "
106 "guests, getting disk used/free statistics (see also: virt-df), migrating "
107 "between virtualization systems (see also: virt-p2v), performing partial "
108 "backups, performing partial guest clones, cloning guests and changing "
109 "registry/UUID/hostname info, and much else besides."
113 #: ../src/guestfs.pod:34
115 "Libguestfs uses Linux kernel and qemu code, and can access any type of guest "
116 "filesystem that Linux and qemu can, including but not limited to: ext2/3/4, "
117 "btrfs, FAT and NTFS, LVM, many different disk partition schemes, qcow, "
122 #: ../src/guestfs.pod:39
124 "Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, "
125 "what filesystem is in each LV, etc.). It can also run commands in the "
126 "context of the guest. Also you can access filesystems over FUSE."
130 #: ../src/guestfs.pod:44
132 "Libguestfs is a library that can be linked with C and C++ management "
133 "programs (or management programs written in OCaml, Perl, Python, Ruby, Java, "
134 "PHP, Haskell or C#). You can also use it from shell scripts or the command "
139 #: ../src/guestfs.pod:49
141 "You don't need to be root to use libguestfs, although obviously you do need "
142 "enough permissions to access the disk images."
146 #: ../src/guestfs.pod:52
148 "Libguestfs is a large API because it can do many things. For a gentle "
149 "introduction, please read the L</API OVERVIEW> section next."
153 #: ../src/guestfs.pod:55
158 #: ../src/guestfs.pod:57
160 "This section provides a gentler overview of the libguestfs API. We also try "
161 "to group API calls together, where that may not be obvious from reading "
162 "about the individual calls in the main section of this manual."
166 #: ../src/guestfs.pod:62
171 #: ../src/guestfs.pod:64
173 "Before you can use libguestfs calls, you have to create a handle. Then you "
174 "must add at least one disk image to the handle, followed by launching the "
175 "handle, then performing whatever operations you want, and finally closing "
176 "the handle. By convention we use the single letter C<g> for the name of the "
177 "handle variable, although of course you can use any name you want."
181 #: ../src/guestfs.pod:71
182 msgid "The general structure of all libguestfs-using programs looks like this:"
186 #: ../src/guestfs.pod:74
189 " guestfs_h *g = guestfs_create ();\n"
194 #: ../src/guestfs.pod:76
197 " /* Call guestfs_add_drive additional times if there are\n"
198 " * multiple disk images.\n"
200 " guestfs_add_drive (g, \"guest.img\");\n"
205 #: ../src/guestfs.pod:81
208 " /* Most manipulation calls won't work until you've launched\n"
209 " * the handle 'g'. You have to do this _after_ adding drives\n"
210 " * and _before_ other commands.\n"
212 " guestfs_launch (g);\n"
217 #: ../src/guestfs.pod:87
220 " /* Now you can examine what partitions, LVs etc are available.\n"
222 " char **partitions = guestfs_list_partitions (g);\n"
223 " char **logvols = guestfs_lvs (g);\n"
228 #: ../src/guestfs.pod:92
231 " /* To access a filesystem in the image, you must mount it.\n"
233 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
238 #: ../src/guestfs.pod:96
241 " /* Now you can perform filesystem actions on the guest\n"
244 " guestfs_touch (g, \"/hello\");\n"
249 #: ../src/guestfs.pod:101
252 " /* You only need to call guestfs_sync if you have made\n"
253 " * changes to the guest image. (But if you've made changes\n"
254 " * then you *must* sync). See also: guestfs_umount and\n"
255 " * guestfs_umount_all calls.\n"
257 " guestfs_sync (g);\n"
262 #: ../src/guestfs.pod:108
265 " /* Close the handle 'g'. */\n"
266 " guestfs_close (g);\n"
271 #: ../src/guestfs.pod:111
273 "The code above doesn't include any error checking. In real code you should "
274 "check return values carefully for errors. In general all functions that "
275 "return integers return C<-1> on error, and all functions that return "
276 "pointers return C<NULL> on error. See section L</ERROR HANDLING> below for "
277 "how to handle errors, and consult the documentation for each function call "
278 "below to see precisely how they return error indications."
282 #: ../src/guestfs.pod:119
287 #: ../src/guestfs.pod:121
289 "The image filename (C<\"guest.img\"> in the example above) could be a disk "
290 "image from a virtual machine, a L<dd(1)> copy of a physical hard disk, an "
291 "actual block device, or simply an empty file of zeroes that you have created "
292 "through L<posix_fallocate(3)>. Libguestfs lets you do useful things to all "
297 #: ../src/guestfs.pod:127
299 "You can add a disk read-only using L</guestfs_add_drive_ro>, in which case "
300 "libguestfs won't modify the file."
304 #: ../src/guestfs.pod:130
306 "Be extremely cautious if the disk image is in use, eg. if it is being used "
307 "by a virtual machine. Adding it read-write will almost certainly cause disk "
308 "corruption, but adding it read-only is safe."
312 #: ../src/guestfs.pod:134
314 "You must add at least one disk image, and you may add multiple disk images. "
315 "In the API, the disk images are usually referred to as C</dev/sda> (for the "
316 "first one you added), C</dev/sdb> (for the second one you added), etc."
320 #: ../src/guestfs.pod:139
322 "Once L</guestfs_launch> has been called you cannot add any more images. You "
323 "can call L</guestfs_list_devices> to get a list of the device names, in the "
324 "order that you added them. See also L</BLOCK DEVICE NAMING> below."
328 #: ../src/guestfs.pod:144
333 #: ../src/guestfs.pod:146
335 "Before you can read or write files, create directories and so on in a disk "
336 "image that contains filesystems, you have to mount those filesystems using "
337 "L</guestfs_mount>. If you already know that a disk image contains (for "
338 "example) one partition with a filesystem on that partition, then you can "
343 #: ../src/guestfs.pod:152
346 " guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
351 #: ../src/guestfs.pod:154
353 "where C</dev/sda1> means literally the first partition (C<1>) of the first "
354 "disk image that we added (C</dev/sda>). If the disk contains Linux LVM2 "
355 "logical volumes you could refer to those instead (eg. C</dev/VG/LV>)."
359 #: ../src/guestfs.pod:158
361 "If you are given a disk image and you don't know what it contains then you "
362 "have to find out. Libguestfs can do that too: use L</"
363 "guestfs_list_partitions> and L</guestfs_lvs> to list possible partitions and "
364 "LVs, and either try mounting each to see what is mountable, or else examine "
365 "them with L</guestfs_vfs_type> or L</guestfs_file>. Libguestfs also has a "
366 "set of APIs for inspection of disk images (see L</INSPECTION> below). But "
367 "you might find it easier to look at higher level programs built on top of "
368 "libguestfs, in particular L<virt-inspector(1)>."
372 #: ../src/guestfs.pod:168
374 "To mount a disk image read-only, use L</guestfs_mount_ro>. There are "
375 "several other variations of the C<guestfs_mount_*> call."
379 #: ../src/guestfs.pod:171
380 msgid "FILESYSTEM ACCESS AND MODIFICATION"
384 #: ../src/guestfs.pod:173
386 "The majority of the libguestfs API consists of fairly low-level calls for "
387 "accessing and modifying the files, directories, symlinks etc on mounted "
388 "filesystems. There are over a hundred such calls which you can find listed "
389 "in detail below in this man page, and we don't even pretend to cover them "
390 "all in this overview."
394 #: ../src/guestfs.pod:179
396 "Specify filenames as full paths, starting with C<\"/\"> and including the "
401 #: ../src/guestfs.pod:182
403 "For example, if you mounted a filesystem at C<\"/\"> and you want to read "
404 "the file called C<\"etc/passwd\"> then you could do:"
408 #: ../src/guestfs.pod:185
411 " char *data = guestfs_cat (g, \"/etc/passwd\");\n"
416 #: ../src/guestfs.pod:187
418 "This would return C<data> as a newly allocated buffer containing the full "
419 "content of that file (with some conditions: see also L</DOWNLOADING> below), "
420 "or C<NULL> if there was an error."
424 #: ../src/guestfs.pod:191
426 "As another example, to create a top-level directory on that filesystem "
427 "called C<\"var\"> you would do:"
431 #: ../src/guestfs.pod:194
434 " guestfs_mkdir (g, \"/var\");\n"
439 #: ../src/guestfs.pod:196
440 msgid "To create a symlink you could do:"
444 #: ../src/guestfs.pod:198
447 " guestfs_ln_s (g, \"/etc/init.d/portmap\",\n"
448 " \"/etc/rc3.d/S30portmap\");\n"
453 #: ../src/guestfs.pod:201
455 "Libguestfs will reject attempts to use relative paths and there is no "
456 "concept of a current working directory."
460 #: ../src/guestfs.pod:204
462 "Libguestfs can return errors in many situations: for example if the "
463 "filesystem isn't writable, or if a file or directory that you requested "
464 "doesn't exist. If you are using the C API (documented here) you have to "
465 "check for those error conditions after each call. (Other language bindings "
466 "turn these errors into exceptions)."
470 #: ../src/guestfs.pod:210
472 "File writes are affected by the per-handle umask, set by calling L</"
473 "guestfs_umask> and defaulting to 022. See L</UMASK>."
477 #: ../src/guestfs.pod:213
482 #: ../src/guestfs.pod:215
484 "Libguestfs contains API calls to read, create and modify partition tables on "
489 #: ../src/guestfs.pod:218
491 "In the common case where you want to create a single partition covering the "
492 "whole disk, you should use the L</guestfs_part_disk> call:"
496 #: ../src/guestfs.pod:222
499 " const char *parttype = \"mbr\";\n"
500 " if (disk_is_larger_than_2TB)\n"
501 " parttype = \"gpt\";\n"
502 " guestfs_part_disk (g, \"/dev/sda\", parttype);\n"
507 #: ../src/guestfs.pod:227
509 "Obviously this effectively wipes anything that was on that disk image before."
513 #: ../src/guestfs.pod:230
518 #: ../src/guestfs.pod:232
520 "Libguestfs provides access to a large part of the LVM2 API, such as L</"
521 "guestfs_lvcreate> and L</guestfs_vgremove>. It won't make much sense unless "
522 "you familiarize yourself with the concepts of physical volumes, volume "
523 "groups and logical volumes."
527 #: ../src/guestfs.pod:237
529 "This author strongly recommends reading the LVM HOWTO, online at L<http://"
530 "tldp.org/HOWTO/LVM-HOWTO/>."
534 #: ../src/guestfs.pod:240
539 #: ../src/guestfs.pod:242
541 "Use L</guestfs_cat> to download small, text only files. This call is "
542 "limited to files which are less than 2 MB and which cannot contain any ASCII "
543 "NUL (C<\\0>) characters. However it has a very simple to use API."
547 #: ../src/guestfs.pod:247
549 "L</guestfs_read_file> can be used to read files which contain arbitrary 8 "
550 "bit data, since it returns a (pointer, size) pair. However it is still "
551 "limited to \"small\" files, less than 2 MB."
555 #: ../src/guestfs.pod:251
557 "L</guestfs_download> can be used to download any file, with no limits on "
558 "content or size (even files larger than 4 GB)."
562 #: ../src/guestfs.pod:254
564 "To download multiple files, see L</guestfs_tar_out> and L</guestfs_tgz_out>."
568 #: ../src/guestfs.pod:257
573 #: ../src/guestfs.pod:259
575 "It's often the case that you want to write a file or files to the disk image."
579 #: ../src/guestfs.pod:262
581 "To write a small file with fixed content, use L</guestfs_write>. To create "
582 "a file of all zeroes, use L</guestfs_truncate_size> (sparse) or L</"
583 "guestfs_fallocate64> (with all disk blocks allocated). There are a variety "
584 "of other functions for creating test files, for example L</guestfs_fill> and "
585 "L</guestfs_fill_pattern>."
589 #: ../src/guestfs.pod:268
591 "To upload a single file, use L</guestfs_upload>. This call has no limits on "
592 "file content or size (even files larger than 4 GB)."
596 #: ../src/guestfs.pod:271
598 "To upload multiple files, see L</guestfs_tar_in> and L</guestfs_tgz_in>."
602 #: ../src/guestfs.pod:273
604 "However the fastest way to upload I<large numbers of arbitrary files> is to "
605 "turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and L<mkisofs(8)"
606 ">), then attach this using L</guestfs_add_drive_ro>. If you add the drive "
607 "in a predictable way (eg. adding it last after all other drives) then you "
608 "can get the device name from L</guestfs_list_devices> and mount it directly "
609 "using L</guestfs_mount_ro>. Note that squashfs images are sometimes non-"
610 "portable between kernel versions, and they don't support labels or UUIDs. "
611 "If you want to pre-build an image or you need to mount it using a label or "
612 "UUID, use an ISO image instead."
616 #: ../src/guestfs.pod:284
621 #: ../src/guestfs.pod:286
623 "There are various different commands for copying between files and devices "
624 "and in and out of the guest filesystem. These are summarised in the table "
629 #: ../src/guestfs.pod:292
630 msgid "B<file> to B<file>"
634 #: ../src/guestfs.pod:294
636 "Use L</guestfs_cp> to copy a single file, or L</guestfs_cp_a> to copy "
637 "directories recursively."
641 #: ../src/guestfs.pod:297
642 msgid "B<file or device> to B<file or device>"
646 #: ../src/guestfs.pod:299
648 "Use L</guestfs_dd> which efficiently uses L<dd(1)> to copy between files and "
649 "devices in the guest."
653 #: ../src/guestfs.pod:302
654 msgid "Example: duplicate the contents of an LV:"
658 #: ../src/guestfs.pod:304
661 " guestfs_dd (g, \"/dev/VG/Original\", \"/dev/VG/Copy\");\n"
666 #: ../src/guestfs.pod:306
668 "The destination (C</dev/VG/Copy>) must be at least as large as the source "
669 "(C</dev/VG/Original>). To copy less than the whole source device, use L</"
670 "guestfs_copy_size>."
674 #: ../src/guestfs.pod:310
675 msgid "B<file on the host> to B<file or device>"
679 #: ../src/guestfs.pod:312
680 msgid "Use L</guestfs_upload>. See L</UPLOADING> above."
684 #: ../src/guestfs.pod:314
685 msgid "B<file or device> to B<file on the host>"
689 #: ../src/guestfs.pod:316
690 msgid "Use L</guestfs_download>. See L</DOWNLOADING> above."
694 #: ../src/guestfs.pod:320
695 msgid "LISTING FILES"
699 #: ../src/guestfs.pod:322
701 "L</guestfs_ll> is just designed for humans to read (mainly when using the "
702 "L<guestfish(1)>-equivalent command C<ll>)."
706 #: ../src/guestfs.pod:325
708 "L</guestfs_ls> is a quick way to get a list of files in a directory from "
709 "programs, as a flat list of strings."
713 #: ../src/guestfs.pod:328
715 "L</guestfs_readdir> is a programmatic way to get a list of files in a "
716 "directory, plus additional information about each one. It is more "
717 "equivalent to using the L<readdir(3)> call on a local filesystem."
721 #: ../src/guestfs.pod:332
723 "L</guestfs_find> and L</guestfs_find0> can be used to recursively list files."
727 #: ../src/guestfs.pod:335
728 msgid "RUNNING COMMANDS"
732 #: ../src/guestfs.pod:337
734 "Although libguestfs is primarily an API for manipulating files inside guest "
735 "images, we also provide some limited facilities for running commands inside "
740 #: ../src/guestfs.pod:341
741 msgid "There are many limitations to this:"
745 #: ../src/guestfs.pod:345 ../src/guestfs.pod:350 ../src/guestfs.pod:355
746 #: ../src/guestfs.pod:359 ../src/guestfs.pod:364 ../src/guestfs.pod:368
747 #: ../src/guestfs.pod:373 ../src/guestfs.pod:1254 ../src/guestfs.pod:1259
748 #: ../src/guestfs.pod:1263 ../src/guestfs.pod:1365 ../src/guestfs.pod:1369
749 #: ../src/guestfs.pod:1373 ../src/guestfs.pod:1378 ../src/guestfs.pod:1386
750 #: ../src/guestfs.pod:1405 ../src/guestfs.pod:1413 ../src/guestfs.pod:1643
751 #: ../src/guestfs.pod:1649 ../src/guestfs.pod:1654 ../src/guestfs.pod:1660
752 #: ../src/guestfs.pod:1767 ../src/guestfs.pod:1771 ../src/guestfs.pod:1775
753 #: ../src/guestfs.pod:1779 ../src/guestfs-actions.pod:14
754 #: ../src/guestfs-actions.pod:21 ../src/guestfs-actions.pod:372
755 #: ../src/guestfs-actions.pod:380 ../src/guestfs-actions.pod:387
756 #: ../src/guestfs-actions.pod:394 ../src/guestfs-actions.pod:1285
757 #: ../src/guestfs-actions.pod:1289 ../src/guestfs-actions.pod:1293
758 #: ../src/guestfs-actions.pod:1297 ../src/guestfs-actions.pod:1305
759 #: ../src/guestfs-actions.pod:1309 ../src/guestfs-actions.pod:1313
760 #: ../src/guestfs-actions.pod:1323 ../src/guestfs-actions.pod:1327
761 #: ../src/guestfs-actions.pod:1331 ../src/guestfs-actions.pod:1454
762 #: ../src/guestfs-actions.pod:1458 ../src/guestfs-actions.pod:1463
763 #: ../src/guestfs-actions.pod:1468 ../src/guestfs-actions.pod:1520
764 #: ../src/guestfs-actions.pod:1524 ../src/guestfs-actions.pod:1529
765 #: ../fish/guestfish.pod:338 ../fish/guestfish.pod:342
766 #: ../fish/guestfish.pod:346 ../fish/guestfish.pod:350
767 #: ../fish/guestfish-actions.pod:15 ../fish/guestfish-actions.pod:22
768 #: ../fish/guestfish-actions.pod:306 ../fish/guestfish-actions.pod:314
769 #: ../fish/guestfish-actions.pod:321 ../fish/guestfish-actions.pod:328
770 #: ../fish/guestfish-actions.pod:1023 ../fish/guestfish-actions.pod:1027
771 #: ../fish/guestfish-actions.pod:1031 ../fish/guestfish-actions.pod:1035
772 #: ../fish/guestfish-actions.pod:1043 ../fish/guestfish-actions.pod:1047
773 #: ../fish/guestfish-actions.pod:1051 ../fish/guestfish-actions.pod:1061
774 #: ../fish/guestfish-actions.pod:1065 ../fish/guestfish-actions.pod:1069
775 #: ../fish/guestfish-actions.pod:1159 ../fish/guestfish-actions.pod:1163
776 #: ../fish/guestfish-actions.pod:1168 ../fish/guestfish-actions.pod:1173
777 #: ../fish/guestfish-actions.pod:1215 ../fish/guestfish-actions.pod:1219
778 #: ../fish/guestfish-actions.pod:1224 ../tools/virt-df.pl:144
779 #: ../tools/virt-df.pl:150 ../tools/virt-resize.pl:324
780 #: ../tools/virt-resize.pl:329 ../tools/virt-resize.pl:339
785 #: ../src/guestfs.pod:347
787 "The kernel version that the command runs under will be different from what "
792 #: ../src/guestfs.pod:352
794 "If the command needs to communicate with daemons, then most likely they "
799 #: ../src/guestfs.pod:357
800 msgid "The command will be running in limited memory."
804 #: ../src/guestfs.pod:361
806 "The network may not be available unless you enable it (see L</"
807 "guestfs_set_network>)."
811 #: ../src/guestfs.pod:366
812 msgid "Only supports Linux guests (not Windows, BSD, etc)."
816 #: ../src/guestfs.pod:370
818 "Architecture limitations (eg. won't work for a PPC guest on an X86 host)."
822 #: ../src/guestfs.pod:375
824 "For SELinux guests, you may need to enable SELinux and load policy first. "
825 "See L</SELINUX> in this manpage."
829 #: ../src/guestfs.pod:380
831 "The two main API calls to run commands are L</guestfs_command> and L</"
832 "guestfs_sh> (there are also variations)."
836 #: ../src/guestfs.pod:383
838 "The difference is that L</guestfs_sh> runs commands using the shell, so any "
839 "shell globs, redirections, etc will work."
843 #: ../src/guestfs.pod:386
844 msgid "CONFIGURATION FILES"
848 #: ../src/guestfs.pod:388
850 "To read and write configuration files in Linux guest filesystems, we "
851 "strongly recommend using Augeas. For example, Augeas understands how to "
852 "read and write, say, a Linux shadow password file or X.org configuration "
853 "file, and so avoids you having to write that code."
857 #: ../src/guestfs.pod:393
859 "The main Augeas calls are bound through the C<guestfs_aug_*> APIs. We don't "
860 "document Augeas itself here because there is excellent documentation on the "
861 "L<http://augeas.net/> website."
865 #: ../src/guestfs.pod:397
867 "If you don't want to use Augeas (you fool!) then try calling L</"
868 "guestfs_read_lines> to get the file as a list of lines which you can iterate "
873 #: ../src/guestfs.pod:401
878 #: ../src/guestfs.pod:403
880 "We support SELinux guests. To ensure that labeling happens correctly in "
881 "SELinux guests, you need to enable SELinux and load the guest's policy:"
885 #: ../src/guestfs.pod:409
890 #: ../src/guestfs.pod:411
891 msgid "Before launching, do:"
895 #: ../src/guestfs.pod:413
898 " guestfs_set_selinux (g, 1);\n"
903 #: ../src/guestfs.pod:415
908 #: ../src/guestfs.pod:417
910 "After mounting the guest's filesystem(s), load the policy. This is best "
911 "done by running the L<load_policy(8)> command in the guest itself:"
915 #: ../src/guestfs.pod:421
918 " guestfs_sh (g, \"/usr/sbin/load_policy\");\n"
923 #: ../src/guestfs.pod:423
925 "(Older versions of C<load_policy> require you to specify the name of the "
930 #: ../src/guestfs.pod:426
935 #: ../src/guestfs.pod:428
937 "Optionally, set the security context for the API. The correct security "
938 "context to use can only be known by inspecting the guest. As an example:"
942 #: ../src/guestfs.pod:432
945 " guestfs_setcon (g, \"unconfined_u:unconfined_r:unconfined_t:s0\");\n"
950 #: ../src/guestfs.pod:436
951 msgid "This will work for running commands and editing existing files."
955 #: ../src/guestfs.pod:438
957 "When new files are created, you may need to label them explicitly, for "
958 "example by running the external command C<restorecon pathname>."
962 #: ../src/guestfs.pod:442
967 #: ../src/guestfs.pod:444
969 "Certain calls are affected by the current file mode creation mask (the "
970 "\"umask\"). In particular ones which create files or directories, such as "
971 "L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>. This affects "
972 "either the default mode that the file is created with or modifies the mode "
977 #: ../src/guestfs.pod:450
979 "The default umask is C<022>, so files are created with modes such as C<0644> "
980 "and directories with C<0755>."
984 #: ../src/guestfs.pod:453
986 "There are two ways to avoid being affected by umask. Either set umask to 0 "
987 "(call C<guestfs_umask (g, 0)> early after launching). Or call L</"
988 "guestfs_chmod> after creating each file or directory."
992 #: ../src/guestfs.pod:457
993 msgid "For more information about umask, see L<umask(2)>."
997 #: ../src/guestfs.pod:459 ../fish/guestfish.pod:589
998 msgid "ENCRYPTED DISKS"
1002 #: ../src/guestfs.pod:461
1004 "Libguestfs allows you to access Linux guests which have been encrypted using "
1005 "whole disk encryption that conforms to the Linux Unified Key Setup (LUKS) "
1006 "standard. This includes nearly all whole disk encryption systems used by "
1007 "modern Linux guests."
1011 #: ../src/guestfs.pod:467
1013 "Use L</guestfs_vfs_type> to identify LUKS-encrypted block devices (it "
1014 "returns the string C<crypto_LUKS>)."
1018 #: ../src/guestfs.pod:470
1020 "Then open these devices by calling L</guestfs_luks_open>. Obviously you "
1021 "will require the passphrase!"
1025 #: ../src/guestfs.pod:473
1027 "Opening a LUKS device creates a new device mapper device called C</dev/"
1028 "mapper/mapname> (where C<mapname> is the string you supply to L</"
1029 "guestfs_luks_open>). Reads and writes to this mapper device are decrypted "
1030 "from and encrypted to the underlying block device respectively."
1034 #: ../src/guestfs.pod:479
1036 "LVM volume groups on the device can be made visible by calling L</"
1037 "guestfs_vgscan> followed by L</guestfs_vg_activate_all>. The logical volume"
1038 "(s) can now be mounted in the usual way."
1042 #: ../src/guestfs.pod:483
1044 "Use the reverse process to close a LUKS device. Unmount any logical volumes "
1045 "on it, deactivate the volume groups by caling C<guestfs_vg_activate (g, 0, "
1046 "[\"/dev/VG\"])>. Then close the mapper device by calling L</"
1047 "guestfs_luks_close> on the C</dev/mapper/mapname> device (I<not> the "
1048 "underlying encrypted block device)."
1052 #: ../src/guestfs.pod:490
1057 #: ../src/guestfs.pod:492
1059 "Libguestfs has APIs for inspecting an unknown disk image to find out if it "
1060 "contains operating systems. (These APIs used to be in a separate Perl-only "
1061 "library called L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most "
1062 "frequently used part of this library has been rewritten in C and moved into "
1067 #: ../src/guestfs.pod:498
1069 "Add all disks belonging to the unknown virtual machine and call L</"
1070 "guestfs_launch> in the usual way."
1074 #: ../src/guestfs.pod:501
1076 "Then call L</guestfs_inspect_os>. This function uses other libguestfs calls "
1077 "and certain heuristics, and returns a list of operating systems that were "
1078 "found. An empty list means none were found. A single element is the root "
1079 "filesystem of the operating system. For dual- or multi-boot guests, "
1080 "multiple roots can be returned, each one corresponding to a separate "
1081 "operating system. (Multi-boot virtual machines are extremely rare in the "
1082 "world of virtualization, but since this scenario can happen, we have built "
1083 "libguestfs to deal with it.)"
1087 #: ../src/guestfs.pod:510
1089 "For each root, you can then call various C<guestfs_inspect_get_*> functions "
1090 "to get additional details about that operating system. For example, call L</"
1091 "guestfs_inspect_get_type> to return the string C<windows> or C<linux> for "
1092 "Windows and Linux-based operating systems respectively."
1096 #: ../src/guestfs.pod:516
1098 "Un*x-like and Linux-based operating systems usually consist of several "
1099 "filesystems which are mounted at boot time (for example, a separate boot "
1100 "partition mounted on C</boot>). The inspection rules are able to detect how "
1101 "filesystems correspond to mount points. Call "
1102 "C<guestfs_inspect_get_mountpoints> to get this mapping. It might return a "
1103 "hash table like this example:"
1107 #: ../src/guestfs.pod:523
1110 " /boot => /dev/sda1\n"
1111 " / => /dev/vg_guest/lv_root\n"
1112 " /usr => /dev/vg_guest/lv_usr\n"
1117 #: ../src/guestfs.pod:527
1119 "The caller can then make calls to L</guestfs_mount_options> to mount the "
1120 "filesystems as suggested."
1124 #: ../src/guestfs.pod:530
1126 "Be careful to mount filesystems in the right order (eg. C</> before C</"
1127 "usr>). Sorting the keys of the hash by length, shortest first, should work."
1131 #: ../src/guestfs.pod:534
1133 "Inspection currently only works for some common operating systems. "
1134 "Contributors are welcome to send patches for other operating systems that we "
1135 "currently cannot detect."
1139 #: ../src/guestfs.pod:538
1141 "Encrypted disks must be opened before inspection. See L</ENCRYPTED DISKS> "
1142 "for more details. The L</guestfs_inspect_os> function just ignores any "
1143 "encrypted devices."
1147 #: ../src/guestfs.pod:542
1149 "A note on the implementation: The call L</guestfs_inspect_os> performs "
1150 "inspection and caches the results in the guest handle. Subsequent calls to "
1151 "C<guestfs_inspect_get_*> return this cached information, but I<do not> re-"
1152 "read the disks. If you change the content of the guest disks, you can redo "
1153 "inspection by calling L</guestfs_inspect_os> again."
1157 #: ../src/guestfs.pod:549
1158 msgid "SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS"
1162 #: ../src/guestfs.pod:551
1164 "Libguestfs can mount NTFS partitions. It does this using the L<http://www."
1165 "ntfs-3g.org/> driver."
1169 #: ../src/guestfs.pod:554
1171 "DOS and Windows still use drive letters, and the filesystems are always "
1172 "treated as case insensitive by Windows itself, and therefore you might find "
1173 "a Windows configuration file referring to a path like C<c:\\windows"
1174 "\\system32>. When the filesystem is mounted in libguestfs, that directory "
1175 "might be referred to as C</WINDOWS/System32>."
1179 #: ../src/guestfs.pod:560
1181 "Drive letter mappings are outside the scope of libguestfs. You have to use "
1182 "libguestfs to read the appropriate Windows Registry and configuration files, "
1183 "to determine yourself how drives are mapped (see also L<hivex(3)> and L<virt-"
1188 #: ../src/guestfs.pod:565
1190 "Replacing backslash characters with forward slash characters is also outside "
1191 "the scope of libguestfs, but something that you can easily do."
1195 #: ../src/guestfs.pod:568
1197 "Where we can help is in resolving the case insensitivity of paths. For "
1198 "this, call L</guestfs_case_sensitive_path>."
1202 #: ../src/guestfs.pod:571
1204 "Libguestfs also provides some help for decoding Windows Registry \"hive\" "
1205 "files, through the library C<hivex> which is part of the libguestfs project "
1206 "although ships as a separate tarball. You have to locate and download the "
1207 "hive file(s) yourself, and then pass them to C<hivex> functions. See also "
1208 "the programs L<hivexml(1)>, L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-"
1209 "reg(1)> for more help on this issue."
1213 #: ../src/guestfs.pod:579
1214 msgid "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES"
1218 #: ../src/guestfs.pod:581
1220 "Although we don't want to discourage you from using the C API, we will "
1221 "mention here that the same API is also available in other languages."
1225 #: ../src/guestfs.pod:584
1227 "The API is broadly identical in all supported languages. This means that "
1228 "the C call C<guestfs_mount(g,path)> is C<$g-E<gt>mount($path)> in Perl, C<g."
1229 "mount(path)> in Python, and C<Guestfs.mount g path> in OCaml. In other "
1230 "words, a straightforward, predictable isomorphism between each language."
1234 #: ../src/guestfs.pod:590
1236 "Error messages are automatically transformed into exceptions if the language "
1241 #: ../src/guestfs.pod:593
1243 "We don't try to \"object orientify\" parts of the API in OO languages, "
1244 "although contributors are welcome to write higher level APIs above what we "
1245 "provide in their favourite languages if they wish."
1249 #: ../src/guestfs.pod:599
1254 #: ../src/guestfs.pod:601
1256 "You can use the I<guestfs.h> header file from C++ programs. The C++ API is "
1257 "identical to the C API. C++ classes and exceptions are not used."
1261 #: ../src/guestfs.pod:605
1266 #: ../src/guestfs.pod:607
1268 "The C# bindings are highly experimental. Please read the warnings at the "
1269 "top of C<csharp/Libguestfs.cs>."
1273 #: ../src/guestfs.pod:610
1278 #: ../src/guestfs.pod:612
1280 "This is the only language binding that is working but incomplete. Only "
1281 "calls which return simple integers have been bound in Haskell, and we are "
1282 "looking for help to complete this binding."
1286 #: ../src/guestfs.pod:616
1291 #: ../src/guestfs.pod:618
1293 "Full documentation is contained in the Javadoc which is distributed with "
1298 #: ../src/guestfs.pod:621
1303 #: ../src/guestfs.pod:623
1304 msgid "For documentation see the file C<guestfs.mli>."
1308 #: ../src/guestfs.pod:625
1313 #: ../src/guestfs.pod:627
1314 msgid "For documentation see L<Sys::Guestfs(3)>."
1318 #: ../src/guestfs.pod:629
1323 #: ../src/guestfs.pod:631
1325 "For documentation see C<README-PHP> supplied with libguestfs sources or in "
1326 "the php-libguestfs package for your distribution."
1330 #: ../src/guestfs.pod:634
1331 msgid "The PHP binding only works correctly on 64 bit machines."
1335 #: ../src/guestfs.pod:636
1340 #: ../src/guestfs.pod:638
1341 msgid "For documentation do:"
1345 #: ../src/guestfs.pod:640
1349 " >>> import guestfs\n"
1350 " >>> help (guestfs)\n"
1355 #: ../src/guestfs.pod:644
1360 #: ../src/guestfs.pod:646
1362 "Use the Guestfs module. There is no Ruby-specific documentation, but you "
1363 "can find examples written in Ruby in the libguestfs source."
1367 #: ../src/guestfs.pod:649
1368 msgid "B<shell scripts>"
1372 #: ../src/guestfs.pod:651
1373 msgid "For documentation see L<guestfish(1)>."
1377 #: ../src/guestfs.pod:655
1378 msgid "LIBGUESTFS GOTCHAS"
1382 #: ../src/guestfs.pod:657
1384 "L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: \"A feature of a "
1385 "system [...] that works in the way it is documented but is counterintuitive "
1386 "and almost invites mistakes.\""
1390 #: ../src/guestfs.pod:661
1392 "Since we developed libguestfs and the associated tools, there are several "
1393 "things we would have designed differently, but are now stuck with for "
1394 "backwards compatibility or other reasons. If there is ever a libguestfs 2.0 "
1395 "release, you can expect these to change. Beware of them."
1399 #: ../src/guestfs.pod:669
1400 msgid "Autosync / forgetting to sync."
1404 #: ../src/guestfs.pod:671
1406 "When modifying a filesystem from C or another language, you B<must> unmount "
1407 "all filesystems and call L</guestfs_sync> explicitly before you close the "
1408 "libguestfs handle. You can also call:"
1412 #: ../src/guestfs.pod:675
1415 " guestfs_set_autosync (g, 1);\n"
1420 #: ../src/guestfs.pod:677
1422 "to have the unmount/sync done automatically for you when the handle 'g' is "
1423 "closed. (This feature is called \"autosync\", L</guestfs_set_autosync> q.v.)"
1427 #: ../src/guestfs.pod:681
1429 "If you forget to do this, then it is entirely possible that your changes "
1430 "won't be written out, or will be partially written, or (very rarely) that "
1431 "you'll get disk corruption."
1435 #: ../src/guestfs.pod:685
1437 "Note that in L<guestfish(3)> autosync is the default. So quick and dirty "
1438 "guestfish scripts that forget to sync will work just fine, which can make "
1439 "this very puzzling if you are trying to debug a problem."
1443 #: ../src/guestfs.pod:689
1444 msgid "Mount option C<-o sync> should not be the default."
1448 #: ../src/guestfs.pod:691
1450 "If you use L</guestfs_mount>, then C<-o sync,noatime> are added implicitly. "
1451 "However C<-o sync> does not add any reliability benefit, but does have a "
1452 "very large performance impact."
1456 #: ../src/guestfs.pod:695
1458 "The work around is to use L</guestfs_mount_options> and set the mount "
1459 "options that you actually want to use."
1463 #: ../src/guestfs.pod:698
1464 msgid "Read-only should be the default."
1468 #: ../src/guestfs.pod:700
1470 "In L<guestfish(3)>, I<--ro> should be the default, and you should have to "
1471 "specify I<--rw> if you want to make changes to the image."
1475 #: ../src/guestfs.pod:703
1476 msgid "This would reduce the potential to corrupt live VM images."
1480 #: ../src/guestfs.pod:705
1482 "Note that many filesystems change the disk when you just mount and unmount, "
1483 "even if you didn't perform any writes. You need to use L</"
1484 "guestfs_add_drive_ro> to guarantee that the disk is not changed."
1488 #: ../src/guestfs.pod:709
1489 msgid "guestfish command line is hard to use."
1493 #: ../src/guestfs.pod:711
1495 "C<guestfish disk.img> doesn't do what people expect (open C<disk.img> for "
1496 "examination). It tries to run a guestfish command C<disk.img> which doesn't "
1497 "exist, so it fails. In earlier versions of guestfish the error message was "
1498 "also unintuitive, but we have corrected this since. Like the Bourne shell, "
1499 "we should have used C<guestfish -c command> to run commands."
1503 #: ../src/guestfs.pod:718
1504 msgid "guestfish megabyte modifiers don't work right on all commands"
1508 #: ../src/guestfs.pod:720
1510 "In recent guestfish you can use C<1M> to mean 1 megabyte (and similarly for "
1511 "other modifiers). What guestfish actually does is to multiply the number "
1512 "part by the modifier part and pass the result to the C API. However this "
1513 "doesn't work for a few APIs which aren't expecting bytes, but are already "
1514 "expecting some other unit (eg. megabytes)."
1518 #: ../src/guestfs.pod:727
1519 msgid "The most common is L</guestfs_lvcreate>. The guestfish command:"
1523 #: ../src/guestfs.pod:729
1526 " lvcreate LV VG 100M\n"
1531 #: ../src/guestfs.pod:731
1533 "does not do what you might expect. Instead because L</guestfs_lvcreate> is "
1534 "already expecting megabytes, this tries to create a 100 I<terabyte> (100 "
1535 "megabytes * megabytes) logical volume. The error message you get from this "
1536 "is also a little obscure."
1540 #: ../src/guestfs.pod:736
1542 "This could be fixed in the generator by specially marking parameters and "
1543 "return values which take bytes or other units."
1547 #: ../src/guestfs.pod:739
1548 msgid "Library should return errno with error messages."
1552 #: ../src/guestfs.pod:741
1554 "It would be a nice-to-have to be able to get the original value of 'errno' "
1555 "from inside the appliance along error paths (where set). Currently "
1556 "L<guestmount(1)> goes through hoops to try to reverse the error message "
1557 "string into an errno, see the function error() in fuse/guestmount.c."
1561 #: ../src/guestfs.pod:747
1563 "In libguestfs 1.5.4, the protocol was changed so that the Linux errno is "
1564 "sent back from the daemon."
1568 #: ../src/guestfs.pod:750
1569 msgid "Ambiguity between devices and paths"
1573 #: ../src/guestfs.pod:752
1575 "There is a subtle ambiguity in the API between a device name (eg. C</dev/"
1576 "sdb2>) and a similar pathname. A file might just happen to be called "
1577 "C<sdb2> in the directory C</dev> (consider some non-Unix VM image)."
1581 #: ../src/guestfs.pod:757
1583 "In the current API we usually resolve this ambiguity by having two separate "
1584 "calls, for example L</guestfs_checksum> and L</guestfs_checksum_device>. "
1585 "Some API calls are ambiguous and (incorrectly) resolve the problem by "
1586 "detecting if the path supplied begins with C</dev/>."
1590 #: ../src/guestfs.pod:763
1592 "To avoid both the ambiguity and the need to duplicate some calls, we could "
1593 "make paths/devices into structured names. One way to do this would be to "
1594 "use a notation like grub (C<hd(0,0)>), although nobody really likes this "
1595 "aspect of grub. Another way would be to use a structured type, equivalent "
1596 "to this OCaml type:"
1600 #: ../src/guestfs.pod:769
1603 " type path = Path of string | Device of int | Partition of int * int\n"
1608 #: ../src/guestfs.pod:771
1609 msgid "which would allow you to pass arguments like:"
1613 #: ../src/guestfs.pod:773
1616 " Path \"/foo/bar\"\n"
1617 " Device 1 (* /dev/sdb, or perhaps /dev/sda *)\n"
1618 " Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)\n"
1619 " Path \"/dev/sdb2\" (* not a device *)\n"
1624 #: ../src/guestfs.pod:778
1626 "As you can see there are still problems to resolve even with this "
1627 "representation. Also consider how it might work in guestfish."
1631 #: ../src/guestfs.pod:783
1632 msgid "PROTOCOL LIMITS"
1636 #: ../src/guestfs.pod:785
1638 "Internally libguestfs uses a message-based protocol to pass API calls and "
1639 "their responses to and from a small \"appliance\" (see L</INTERNALS> for "
1640 "plenty more detail about this). The maximum message size used by the "
1641 "protocol is slightly less than 4 MB. For some API calls you may need to be "
1642 "aware of this limit. The API calls which may be affected are individually "
1643 "documented, with a link back to this section of the documentation."
1647 #: ../src/guestfs.pod:793
1649 "A simple call such as L</guestfs_cat> returns its result (the file data) in "
1650 "a simple string. Because this string is at some point internally encoded as "
1651 "a message, the maximum size that it can return is slightly under 4 MB. If "
1652 "the requested file is larger than this then you will get an error."
1656 #: ../src/guestfs.pod:799
1658 "In order to transfer large files into and out of the guest filesystem, you "
1659 "need to use particular calls that support this. The sections L</UPLOADING> "
1660 "and L</DOWNLOADING> document how to do this."
1664 #: ../src/guestfs.pod:803
1666 "You might also consider mounting the disk image using our FUSE filesystem "
1667 "support (L<guestmount(1)>)."
1671 #: ../src/guestfs.pod:806
1672 msgid "KEYS AND PASSPHRASES"
1676 #: ../src/guestfs.pod:808
1678 "Certain libguestfs calls take a parameter that contains sensitive key "
1679 "material, passed in as a C string."
1683 #: ../src/guestfs.pod:811
1685 "In the future we would hope to change the libguestfs implementation so that "
1686 "keys are L<mlock(2)>-ed into physical RAM, and thus can never end up in "
1687 "swap. However this is I<not> done at the moment, because of the complexity "
1688 "of such an implementation."
1692 #: ../src/guestfs.pod:816
1694 "Therefore you should be aware that any key parameter you pass to libguestfs "
1695 "might end up being written out to the swap partition. If this is a concern, "
1696 "scrub the swap partition or don't use libguestfs on encrypted devices."
1700 #: ../src/guestfs.pod:821
1701 msgid "CONNECTION MANAGEMENT"
1705 #: ../src/guestfs.pod:823
1710 #: ../src/guestfs.pod:825
1712 "C<guestfs_h> is the opaque type representing a connection handle. Create a "
1713 "handle by calling L</guestfs_create>. Call L</guestfs_close> to free the "
1714 "handle and release all resources used."
1718 #: ../src/guestfs.pod:829
1720 "For information on using multiple handles and threads, see the section L</"
1721 "MULTIPLE HANDLES AND MULTIPLE THREADS> below."
1725 #: ../src/guestfs.pod:832
1726 msgid "guestfs_create"
1730 #: ../src/guestfs.pod:834
1733 " guestfs_h *guestfs_create (void);\n"
1738 #: ../src/guestfs.pod:836
1739 msgid "Create a connection handle."
1743 #: ../src/guestfs.pod:838
1744 msgid "You have to call L</guestfs_add_drive> on the handle at least once."
1748 #: ../src/guestfs.pod:840
1750 "This function returns a non-NULL pointer to a handle on success or NULL on "
1755 #: ../src/guestfs.pod:843
1756 msgid "After configuring the handle, you have to call L</guestfs_launch>."
1760 #: ../src/guestfs.pod:845
1762 "You may also want to configure error handling for the handle. See L</ERROR "
1763 "HANDLING> section below."
1767 #: ../src/guestfs.pod:848
1768 msgid "guestfs_close"
1772 #: ../src/guestfs.pod:850
1775 " void guestfs_close (guestfs_h *g);\n"
1780 #: ../src/guestfs.pod:852
1781 msgid "This closes the connection handle and frees up all resources used."
1785 #: ../src/guestfs.pod:854
1786 msgid "ERROR HANDLING"
1790 #: ../src/guestfs.pod:856
1792 "The convention in all functions that return C<int> is that they return C<-1> "
1793 "to indicate an error. You can get additional information on errors by "
1794 "calling L</guestfs_last_error> and/or by setting up an error handler with L</"
1795 "guestfs_set_error_handler>."
1799 #: ../src/guestfs.pod:861
1800 msgid "The default error handler prints the information string to C<stderr>."
1804 #: ../src/guestfs.pod:863
1806 "Out of memory errors are handled differently. The default action is to call "
1807 "L<abort(3)>. If this is undesirable, then you can set a handler using L</"
1808 "guestfs_set_out_of_memory_handler>."
1812 #: ../src/guestfs.pod:867
1813 msgid "guestfs_last_error"
1817 #: ../src/guestfs.pod:869
1820 " const char *guestfs_last_error (guestfs_h *g);\n"
1825 #: ../src/guestfs.pod:871
1827 "This returns the last error message that happened on C<g>. If there has not "
1828 "been an error since the handle was created, then this returns C<NULL>."
1832 #: ../src/guestfs.pod:875
1834 "The lifetime of the returned string is until the next error occurs, or L</"
1835 "guestfs_close> is called."
1839 #: ../src/guestfs.pod:878
1841 "The error string is not localized (ie. is always in English), because this "
1842 "makes searching for error messages in search engines give the largest number "
1847 #: ../src/guestfs.pod:882
1848 msgid "guestfs_set_error_handler"
1852 #: ../src/guestfs.pod:884
1855 " typedef void (*guestfs_error_handler_cb) (guestfs_h *g,\n"
1857 " const char *msg);\n"
1858 " void guestfs_set_error_handler (guestfs_h *g,\n"
1859 " guestfs_error_handler_cb cb,\n"
1865 #: ../src/guestfs.pod:891
1867 "The callback C<cb> will be called if there is an error. The parameters "
1868 "passed to the callback are an opaque data pointer and the error message "
1873 #: ../src/guestfs.pod:895
1875 "Note that the message string C<msg> is freed as soon as the callback "
1876 "function returns, so if you want to stash it somewhere you must make your "
1881 #: ../src/guestfs.pod:899
1882 msgid "The default handler prints messages on C<stderr>."
1886 #: ../src/guestfs.pod:901
1887 msgid "If you set C<cb> to C<NULL> then I<no> handler is called."
1891 #: ../src/guestfs.pod:903
1892 msgid "guestfs_get_error_handler"
1896 #: ../src/guestfs.pod:905
1899 " guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,\n"
1900 " void **opaque_rtn);\n"
1905 #: ../src/guestfs.pod:908
1906 msgid "Returns the current error handler callback."
1910 #: ../src/guestfs.pod:910
1911 msgid "guestfs_set_out_of_memory_handler"
1915 #: ../src/guestfs.pod:912
1918 " typedef void (*guestfs_abort_cb) (void);\n"
1919 " int guestfs_set_out_of_memory_handler (guestfs_h *g,\n"
1920 " guestfs_abort_cb);\n"
1925 #: ../src/guestfs.pod:916
1927 "The callback C<cb> will be called if there is an out of memory situation. "
1928 "I<Note this callback must not return>."
1932 #: ../src/guestfs.pod:919
1933 msgid "The default is to call L<abort(3)>."
1937 #: ../src/guestfs.pod:921
1939 "You cannot set C<cb> to C<NULL>. You can't ignore out of memory situations."
1943 #: ../src/guestfs.pod:924
1944 msgid "guestfs_get_out_of_memory_handler"
1948 #: ../src/guestfs.pod:926
1951 " guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);\n"
1956 #: ../src/guestfs.pod:928
1957 msgid "This returns the current out of memory handler."
1961 #: ../src/guestfs.pod:930
1966 #: ../src/guestfs.pod:932
1968 "Libguestfs needs a kernel and initrd.img, which it finds by looking along an "
1973 #: ../src/guestfs.pod:935
1975 "By default it looks for these in the directory C<$libdir/guestfs> (eg. C</"
1976 "usr/local/lib/guestfs> or C</usr/lib64/guestfs>)."
1980 #: ../src/guestfs.pod:938
1982 "Use L</guestfs_set_path> or set the environment variable L</LIBGUESTFS_PATH> "
1983 "to change the directories that libguestfs will search in. The value is a "
1984 "colon-separated list of paths. The current directory is I<not> searched "
1985 "unless the path contains an empty element or C<.>. For example "
1986 "C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would search the current directory and "
1987 "then C</usr/lib/guestfs>."
1991 #: ../src/guestfs.pod:945
1992 msgid "HIGH-LEVEL API ACTIONS"
1996 #: ../src/guestfs.pod:947
1997 msgid "ABI GUARANTEE"
2001 #: ../src/guestfs.pod:949
2003 "We guarantee the libguestfs ABI (binary interface), for public, high-level "
2004 "actions as outlined in this section. Although we will deprecate some "
2005 "actions, for example if they get replaced by newer calls, we will keep the "
2006 "old actions forever. This allows you the developer to program in confidence "
2007 "against the libguestfs API."
2011 #: ../src/guestfs.pod:955 ../fish/guestfish.pod:819
2016 #: ../src/guestfs.pod:957
2021 #: ../src/guestfs.pod:959
2026 #: ../src/guestfs.pod:961
2027 msgid "AVAILABILITY"
2031 #: ../src/guestfs.pod:963
2032 msgid "GROUPS OF FUNCTIONALITY IN THE APPLIANCE"
2036 #: ../src/guestfs.pod:965
2038 "Using L</guestfs_available> you can test availability of the following "
2039 "groups of functions. This test queries the appliance to see if the "
2040 "appliance you are currently using supports the functionality."
2044 #: ../src/guestfs.pod:970
2045 msgid "@AVAILABILITY@"
2049 #: ../src/guestfs.pod:972
2050 msgid "GUESTFISH supported COMMAND"
2054 #: ../src/guestfs.pod:974
2056 "In L<guestfish(3)> there is a handy interactive command C<supported> which "
2057 "prints out the available groups and whether they are supported by this build "
2058 "of libguestfs. Note however that you have to do C<run> first."
2062 #: ../src/guestfs.pod:979
2063 msgid "SINGLE CALLS AT COMPILE TIME"
2067 #: ../src/guestfs.pod:981
2069 "Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols for each C API "
2070 "function, such as:"
2074 #: ../src/guestfs.pod:984
2077 " #define LIBGUESTFS_HAVE_DD 1\n"
2082 #: ../src/guestfs.pod:986
2083 msgid "if L</guestfs_dd> is available."
2087 #: ../src/guestfs.pod:988
2089 "Before version 1.5.8, if you needed to test whether a single libguestfs "
2090 "function is available at compile time, we recommended using build tools such "
2091 "as autoconf or cmake. For example in autotools you could use:"
2095 #: ../src/guestfs.pod:993
2098 " AC_CHECK_LIB([guestfs],[guestfs_create])\n"
2099 " AC_CHECK_FUNCS([guestfs_dd])\n"
2104 #: ../src/guestfs.pod:996
2106 "which would result in C<HAVE_GUESTFS_DD> being either defined or not defined "
2111 #: ../src/guestfs.pod:999
2112 msgid "SINGLE CALLS AT RUN TIME"
2116 #: ../src/guestfs.pod:1001
2118 "Testing at compile time doesn't guarantee that a function really exists in "
2119 "the library. The reason is that you might be dynamically linked against a "
2120 "previous I<libguestfs.so> (dynamic library) which doesn't have the call. "
2121 "This situation unfortunately results in a segmentation fault, which is a "
2122 "shortcoming of the C dynamic linking system itself."
2126 #: ../src/guestfs.pod:1008
2128 "You can use L<dlopen(3)> to test if a function is available at run time, as "
2129 "in this example program (note that you still need the compile time check as "
2134 #: ../src/guestfs.pod:1012
2137 " #include <stdio.h>\n"
2138 " #include <stdlib.h>\n"
2139 " #include <unistd.h>\n"
2140 " #include <dlfcn.h>\n"
2141 " #include <guestfs.h>\n"
2146 #: ../src/guestfs.pod:1018
2151 " #ifdef LIBGUESTFS_HAVE_DD\n"
2153 " int has_function;\n"
2158 #: ../src/guestfs.pod:1024
2161 " /* Test if the function guestfs_dd is really available. */\n"
2162 " dl = dlopen (NULL, RTLD_LAZY);\n"
2164 " fprintf (stderr, \"dlopen: %s\\n\", dlerror ());\n"
2165 " exit (EXIT_FAILURE);\n"
2167 " has_function = dlsym (dl, \"guestfs_dd\") != NULL;\n"
2173 #: ../src/guestfs.pod:1033
2176 " if (!has_function)\n"
2177 " printf (\"this libguestfs.so does NOT have guestfs_dd function\\n\");\n"
2179 " printf (\"this libguestfs.so has guestfs_dd function\\n\");\n"
2180 " /* Now it's safe to call\n"
2181 " guestfs_dd (g, \"foo\", \"bar\");\n"
2185 " printf (\"guestfs_dd function was not found at compile time\\n\");\n"
2192 #: ../src/guestfs.pod:1046
2194 "You may think the above is an awful lot of hassle, and it is. There are "
2195 "other ways outside of the C linking system to ensure that this kind of "
2196 "incompatibility never arises, such as using package versioning:"
2200 #: ../src/guestfs.pod:1051
2203 " Requires: libguestfs >= 1.0.80\n"
2208 #: ../src/guestfs.pod:1053 ../src/guestfs.pod:1058
2213 #: ../src/guestfs.pod:1055
2215 "<!-- old anchor for the next section --> <a name="
2216 "\"state_machine_and_low_level_event_api\"/>"
2220 #: ../src/guestfs.pod:1060
2221 msgid "ARCHITECTURE"
2225 #: ../src/guestfs.pod:1062
2227 "Internally, libguestfs is implemented by running an appliance (a special "
2228 "type of small virtual machine) using L<qemu(1)>. Qemu runs as a child "
2229 "process of the main program."
2233 #: ../src/guestfs.pod:1066
2236 " ___________________\n"
2238 " | main program |\n"
2240 " | | child process / appliance\n"
2241 " | | __________________________\n"
2243 " +-------------------+ RPC | +-----------------+ |\n"
2244 " | libguestfs <--------------------> guestfsd | |\n"
2245 " | | | +-----------------+ |\n"
2246 " \\___________________/ | | Linux kernel | |\n"
2247 " | +--^--------------+ |\n"
2248 " \\_________|________________/\n"
2254 " \\______________/\n"
2259 #: ../src/guestfs.pod:1086
2261 "The library, linked to the main program, creates the child process and hence "
2262 "the appliance in the L</guestfs_launch> function."
2266 #: ../src/guestfs.pod:1089
2268 "Inside the appliance is a Linux kernel and a complete stack of userspace "
2269 "tools (such as LVM and ext2 programs) and a small controlling daemon called "
2270 "L</guestfsd>. The library talks to L</guestfsd> using remote procedure "
2271 "calls (RPC). There is a mostly one-to-one correspondence between libguestfs "
2272 "API calls and RPC calls to the daemon. Lastly the disk image(s) are "
2273 "attached to the qemu process which translates device access by the "
2274 "appliance's Linux kernel into accesses to the image."
2278 #: ../src/guestfs.pod:1098
2280 "A common misunderstanding is that the appliance \"is\" the virtual machine. "
2281 "Although the disk image you are attached to might also be used by some "
2282 "virtual machine, libguestfs doesn't know or care about this. (But you will "
2283 "care if both libguestfs's qemu process and your virtual machine are trying "
2284 "to update the disk image at the same time, since these usually results in "
2285 "massive disk corruption)."
2289 #: ../src/guestfs.pod:1105
2290 msgid "STATE MACHINE"
2294 #: ../src/guestfs.pod:1107
2295 msgid "libguestfs uses a state machine to model the child process:"
2299 #: ../src/guestfs.pod:1109
2311 " / | \\ \\ guestfs_launch\n"
2312 " / | _\\__V______\n"
2314 " / | | LAUNCHING |\n"
2315 " / | \\___________/\n"
2317 " / | guestfs_launch\n"
2319 " ______ / __|____V\n"
2320 " / \\ ------> / \\\n"
2321 " | BUSY | | READY |\n"
2322 " \\______/ <------ \\________/\n"
2327 #: ../src/guestfs.pod:1131
2329 "The normal transitions are (1) CONFIG (when the handle is created, but there "
2330 "is no child process), (2) LAUNCHING (when the child process is booting up), "
2331 "(3) alternating between READY and BUSY as commands are issued to, and "
2332 "carried out by, the child process."
2336 #: ../src/guestfs.pod:1136
2338 "The guest may be killed by L</guestfs_kill_subprocess>, or may die "
2339 "asynchronously at any time (eg. due to some internal error), and that causes "
2340 "the state to transition back to CONFIG."
2344 #: ../src/guestfs.pod:1140
2346 "Configuration commands for qemu such as L</guestfs_add_drive> can only be "
2347 "issued when in the CONFIG state."
2351 #: ../src/guestfs.pod:1143
2353 "The API offers one call that goes from CONFIG through LAUNCHING to READY. "
2354 "L</guestfs_launch> blocks until the child process is READY to accept "
2355 "commands (or until some failure or timeout). L</guestfs_launch> internally "
2356 "moves the state from CONFIG to LAUNCHING while it is running."
2360 #: ../src/guestfs.pod:1149
2362 "API actions such as L</guestfs_mount> can only be issued when in the READY "
2363 "state. These API calls block waiting for the command to be carried out (ie. "
2364 "the state to transition to BUSY and then back to READY). There are no non-"
2365 "blocking versions, and no way to issue more than one command per handle at "
2370 #: ../src/guestfs.pod:1155
2372 "Finally, the child process sends asynchronous messages back to the main "
2373 "program, such as kernel log messages. You can register a callback to "
2374 "receive these messages."
2378 #: ../src/guestfs.pod:1159
2379 msgid "SETTING CALLBACKS TO HANDLE EVENTS"
2383 #: ../src/guestfs.pod:1161
2385 "The child process generates events in some situations. Current events "
2386 "include: receiving a log message, the child process exits."
2390 #: ../src/guestfs.pod:1164
2392 "Use the C<guestfs_set_*_callback> functions to set a callback for different "
2397 #: ../src/guestfs.pod:1167
2399 "Only I<one callback of each type> can be registered for each handle. "
2400 "Calling C<guestfs_set_*_callback> again overwrites the previous callback of "
2401 "that type. Cancel all callbacks of this type by calling this function with "
2402 "C<cb> set to C<NULL>."
2406 #: ../src/guestfs.pod:1172
2407 msgid "guestfs_set_log_message_callback"
2411 #: ../src/guestfs.pod:1174
2414 " typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,\n"
2415 " char *buf, int len);\n"
2416 " void guestfs_set_log_message_callback (guestfs_h *g,\n"
2417 " guestfs_log_message_cb cb,\n"
2423 #: ../src/guestfs.pod:1180
2425 "The callback function C<cb> will be called whenever qemu or the guest writes "
2426 "anything to the console."
2430 #: ../src/guestfs.pod:1183
2431 msgid "Use this function to capture kernel messages and similar."
2435 #: ../src/guestfs.pod:1185
2437 "Normally there is no log message handler, and log messages are just "
2442 #: ../src/guestfs.pod:1188
2443 msgid "guestfs_set_subprocess_quit_callback"
2447 #: ../src/guestfs.pod:1190
2450 " typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);\n"
2451 " void guestfs_set_subprocess_quit_callback (guestfs_h *g,\n"
2452 " guestfs_subprocess_quit_cb cb,\n"
2458 #: ../src/guestfs.pod:1195
2460 "The callback function C<cb> will be called when the child process quits, "
2461 "either asynchronously or if killed by L</guestfs_kill_subprocess>. (This "
2462 "corresponds to a transition from any state to the CONFIG state)."
2466 #: ../src/guestfs.pod:1200
2467 msgid "guestfs_set_launch_done_callback"
2471 #: ../src/guestfs.pod:1202
2474 " typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);\n"
2475 " void guestfs_set_launch_done_callback (guestfs_h *g,\n"
2476 " guestfs_launch_done_cb cb,\n"
2482 #: ../src/guestfs.pod:1207
2484 "The callback function C<cb> will be called when the child process becomes "
2485 "ready first time after it has been launched. (This corresponds to a "
2486 "transition from LAUNCHING to the READY state)."
2490 #: ../src/guestfs.pod:1211
2491 msgid "guestfs_set_close_callback"
2495 #: ../src/guestfs.pod:1213
2498 " typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);\n"
2499 " void guestfs_set_close_callback (guestfs_h *g,\n"
2500 " guestfs_close_cb cb,\n"
2506 #: ../src/guestfs.pod:1218
2508 "The callback function C<cb> will be called while the handle is being closed "
2509 "(synchronously from L</guestfs_close>)."
2513 #: ../src/guestfs.pod:1221
2515 "Note that libguestfs installs an L<atexit(3)> handler to try to clean up "
2516 "handles that are open when the program exits. This means that this callback "
2517 "might be called indirectly from L<exit(3)>, which can cause unexpected "
2518 "problems in higher-level languages (eg. if your HLL interpreter has already "
2519 "been cleaned up by the time this is called, and if your callback then jumps "
2520 "into some HLL function)."
2524 #: ../src/guestfs.pod:1229
2525 msgid "guestfs_set_progress_callback"
2529 #: ../src/guestfs.pod:1231
2532 " typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,\n"
2533 " int proc_nr, int serial,\n"
2534 " uint64_t position, uint64_t total);\n"
2535 " void guestfs_set_progress_callback (guestfs_h *g,\n"
2536 " guestfs_progress_cb cb,\n"
2542 #: ../src/guestfs.pod:1238
2544 "Some long-running operations can generate progress messages. If this "
2545 "callback is registered, then it will be called each time a progress message "
2546 "is generated (usually two seconds after the operation started, and three "
2547 "times per second thereafter until it completes, although the frequency may "
2548 "change in future versions)."
2552 #: ../src/guestfs.pod:1244
2554 "The callback receives two numbers: C<position> and C<total>. The units of "
2555 "C<total> are not defined, although for some operations C<total> may relate "
2556 "in some way to the amount of data to be transferred (eg. in bytes or "
2557 "megabytes), and C<position> may be the portion which has been transferred."
2561 #: ../src/guestfs.pod:1250
2562 msgid "The only defined and stable parts of the API are:"
2566 #: ../src/guestfs.pod:1256
2568 "The callback can display to the user some type of progress bar or indicator "
2569 "which shows the ratio of C<position>:C<total>."
2573 #: ../src/guestfs.pod:1261
2574 msgid "0 E<lt>= C<position> E<lt>= C<total>"
2578 #: ../src/guestfs.pod:1265
2580 "If any progress notification is sent during a call, then a final progress "
2581 "notification is always sent when C<position> = C<total>."
2585 #: ../src/guestfs.pod:1268
2587 "This is to simplify caller code, so callers can easily set the progress "
2588 "indicator to \"100%\" at the end of the operation, without requiring special "
2589 "code to detect this case."
2593 #: ../src/guestfs.pod:1274
2595 "The callback also receives the procedure number and serial number of the "
2596 "call. These are only useful for debugging protocol issues, and the callback "
2597 "can normally ignore them. The callback may want to print these numbers in "
2598 "error messages or debugging messages."
2602 #: ../src/guestfs.pod:1279
2603 msgid "PRIVATE DATA AREA"
2607 #: ../src/guestfs.pod:1281
2609 "You can attach named pieces of private data to the libguestfs handle, and "
2610 "fetch them by name for the lifetime of the handle. This is called the "
2611 "private data area and is only available from the C API."
2615 #: ../src/guestfs.pod:1285
2616 msgid "To attach a named piece of data, use the following call:"
2620 #: ../src/guestfs.pod:1287
2623 " void guestfs_set_private (guestfs_h *g, const char *key, void *data);\n"
2628 #: ../src/guestfs.pod:1289
2630 "C<key> is the name to associate with this data, and C<data> is an arbitrary "
2631 "pointer (which can be C<NULL>). Any previous item with the same name is "
2636 #: ../src/guestfs.pod:1293
2638 "You can use any C<key> you want, but names beginning with an underscore "
2639 "character are reserved for internal libguestfs purposes (for implementing "
2640 "language bindings). It is recommended to prefix the name with some unique "
2641 "string to avoid collisions with other users."
2645 #: ../src/guestfs.pod:1298
2646 msgid "To retrieve the pointer, use:"
2650 #: ../src/guestfs.pod:1300
2653 " void *guestfs_get_private (guestfs_h *g, const char *key);\n"
2658 #: ../src/guestfs.pod:1302
2660 "This function returns C<NULL> if either no data is found associated with "
2661 "C<key>, or if the user previously set the C<key>'s C<data> pointer to "
2666 #: ../src/guestfs.pod:1306
2668 "Libguestfs does not try to look at or interpret the C<data> pointer in any "
2669 "way. As far as libguestfs is concerned, it need not be a valid pointer at "
2670 "all. In particular, libguestfs does I<not> try to free the data when the "
2671 "handle is closed. If the data must be freed, then the caller must either "
2672 "free it before calling L</guestfs_close> or must set up a close callback to "
2673 "do it (see L</guestfs_set_close_callback>, and note that only one callback "
2674 "can be registered for a handle)."
2678 #: ../src/guestfs.pod:1314
2680 "The private data area is implemented using a hash table, and should be "
2681 "reasonably efficient for moderate numbers of keys."
2685 #: ../src/guestfs.pod:1317
2686 msgid "BLOCK DEVICE NAMING"
2690 #: ../src/guestfs.pod:1319
2692 "In the kernel there is now quite a profusion of schemata for naming block "
2693 "devices (in this context, by I<block device> I mean a physical or virtual "
2694 "hard drive). The original Linux IDE driver used names starting with C</dev/"
2695 "hd*>. SCSI devices have historically used a different naming scheme, C</dev/"
2696 "sd*>. When the Linux kernel I<libata> driver became a popular replacement "
2697 "for the old IDE driver (particularly for SATA devices) those devices also "
2698 "used the C</dev/sd*> scheme. Additionally we now have virtual machines with "
2699 "paravirtualized drivers. This has created several different naming systems, "
2700 "such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen PV disks."
2704 #: ../src/guestfs.pod:1331
2706 "As discussed above, libguestfs uses a qemu appliance running an embedded "
2707 "Linux kernel to access block devices. We can run a variety of appliances "
2708 "based on a variety of Linux kernels."
2712 #: ../src/guestfs.pod:1335
2714 "This causes a problem for libguestfs because many API calls use device or "
2715 "partition names. Working scripts and the recipe (example) scripts that we "
2716 "make available over the internet could fail if the naming scheme changes."
2720 #: ../src/guestfs.pod:1340
2722 "Therefore libguestfs defines C</dev/sd*> as the I<standard naming scheme>. "
2723 "Internally C</dev/sd*> names are translated, if necessary, to other names as "
2724 "required. For example, under RHEL 5 which uses the C</dev/hd*> scheme, any "
2725 "device parameter C</dev/sda2> is translated to C</dev/hda2> transparently."
2729 #: ../src/guestfs.pod:1346
2731 "Note that this I<only> applies to parameters. The L</guestfs_list_devices>, "
2732 "L</guestfs_list_partitions> and similar calls return the true names of the "
2733 "devices and partitions as known to the appliance."
2737 #: ../src/guestfs.pod:1351
2738 msgid "ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION"
2742 #: ../src/guestfs.pod:1353
2744 "Usually this translation is transparent. However in some (very rare) cases "
2745 "you may need to know the exact algorithm. Such cases include where you use "
2746 "L</guestfs_config> to add a mixture of virtio and IDE devices to the qemu-"
2747 "based appliance, so have a mixture of C</dev/sd*> and C</dev/vd*> devices."
2751 #: ../src/guestfs.pod:1359
2753 "The algorithm is applied only to I<parameters> which are known to be either "
2754 "device or partition names. Return values from functions such as L</"
2755 "guestfs_list_devices> are never changed."
2759 #: ../src/guestfs.pod:1367
2760 msgid "Is the string a parameter which is a device or partition name?"
2764 #: ../src/guestfs.pod:1371
2765 msgid "Does the string begin with C</dev/sd>?"
2769 #: ../src/guestfs.pod:1375
2771 "Does the named device exist? If so, we use that device. However if I<not> "
2772 "then we continue with this algorithm."
2776 #: ../src/guestfs.pod:1380
2777 msgid "Replace initial C</dev/sd> string with C</dev/hd>."
2781 #: ../src/guestfs.pod:1382
2782 msgid "For example, change C</dev/sda2> to C</dev/hda2>."
2786 #: ../src/guestfs.pod:1384
2787 msgid "If that named device exists, use it. If not, continue."
2791 #: ../src/guestfs.pod:1388
2792 msgid "Replace initial C</dev/sd> string with C</dev/vd>."
2796 #: ../src/guestfs.pod:1390
2797 msgid "If that named device exists, use it. If not, return an error."
2801 #: ../src/guestfs.pod:1394
2802 msgid "PORTABILITY CONCERNS"
2806 #: ../src/guestfs.pod:1396
2808 "Although the standard naming scheme and automatic translation is useful for "
2809 "simple programs and guestfish scripts, for larger programs it is best not to "
2810 "rely on this mechanism."
2814 #: ../src/guestfs.pod:1400
2816 "Where possible for maximum future portability programs using libguestfs "
2817 "should use these future-proof techniques:"
2821 #: ../src/guestfs.pod:1407
2823 "Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list actual "
2824 "device names, and then use those names directly."
2828 #: ../src/guestfs.pod:1410
2830 "Since those device names exist by definition, they will never be translated."
2834 #: ../src/guestfs.pod:1415
2836 "Use higher level ways to identify filesystems, such as LVM names, UUIDs and "
2837 "filesystem labels."
2841 #: ../src/guestfs.pod:1420
2846 #: ../src/guestfs.pod:1422
2847 msgid "COMMUNICATION PROTOCOL"
2851 #: ../src/guestfs.pod:1424
2853 "Don't rely on using this protocol directly. This section documents how it "
2854 "currently works, but it may change at any time."
2858 #: ../src/guestfs.pod:1427
2860 "The protocol used to talk between the library and the daemon running inside "
2861 "the qemu virtual machine is a simple RPC mechanism built on top of XDR (RFC "
2862 "1014, RFC 1832, RFC 4506)."
2866 #: ../src/guestfs.pod:1431
2868 "The detailed format of structures is in C<src/guestfs_protocol.x> (note: "
2869 "this file is automatically generated)."
2873 #: ../src/guestfs.pod:1434
2875 "There are two broad cases, ordinary functions that don't have any C<FileIn> "
2876 "and C<FileOut> parameters, which are handled with very simple request/reply "
2877 "messages. Then there are functions that have any C<FileIn> or C<FileOut> "
2878 "parameters, which use the same request and reply messages, but they may also "
2879 "be followed by files sent using a chunked encoding."
2883 #: ../src/guestfs.pod:1441
2884 msgid "ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)"
2888 #: ../src/guestfs.pod:1443
2889 msgid "For ordinary functions, the request message is:"
2893 #: ../src/guestfs.pod:1445
2896 " total length (header + arguments,\n"
2897 " but not including the length word itself)\n"
2898 " struct guestfs_message_header (encoded as XDR)\n"
2899 " struct guestfs_<foo>_args (encoded as XDR)\n"
2904 #: ../src/guestfs.pod:1450
2906 "The total length field allows the daemon to allocate a fixed size buffer "
2907 "into which it slurps the rest of the message. As a result, the total length "
2908 "is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently 4MB), which means the "
2909 "effective size of any request is limited to somewhere under this size."
2913 #: ../src/guestfs.pod:1456
2915 "Note also that many functions don't take any arguments, in which case the "
2916 "C<guestfs_I<foo>_args> is completely omitted."
2920 #: ../src/guestfs.pod:1459
2922 "The header contains the procedure number (C<guestfs_proc>) which is how the "
2923 "receiver knows what type of args structure to expect, or none at all."
2927 #: ../src/guestfs.pod:1463
2928 msgid "The reply message for ordinary functions is:"
2932 #: ../src/guestfs.pod:1465
2935 " total length (header + ret,\n"
2936 " but not including the length word itself)\n"
2937 " struct guestfs_message_header (encoded as XDR)\n"
2938 " struct guestfs_<foo>_ret (encoded as XDR)\n"
2943 #: ../src/guestfs.pod:1470
2945 "As above the C<guestfs_I<foo>_ret> structure may be completely omitted for "
2946 "functions that return no formal return values."
2950 #: ../src/guestfs.pod:1473
2952 "As above the total length of the reply is limited to C<GUESTFS_MESSAGE_MAX>."
2956 #: ../src/guestfs.pod:1476
2958 "In the case of an error, a flag is set in the header, and the reply message "
2959 "is slightly changed:"
2963 #: ../src/guestfs.pod:1479
2966 " total length (header + error,\n"
2967 " but not including the length word itself)\n"
2968 " struct guestfs_message_header (encoded as XDR)\n"
2969 " struct guestfs_message_error (encoded as XDR)\n"
2974 #: ../src/guestfs.pod:1484
2976 "The C<guestfs_message_error> structure contains the error message as a "
2981 #: ../src/guestfs.pod:1487
2982 msgid "FUNCTIONS THAT HAVE FILEIN PARAMETERS"
2986 #: ../src/guestfs.pod:1489
2988 "A C<FileIn> parameter indicates that we transfer a file I<into> the guest. "
2989 "The normal request message is sent (see above). However this is followed by "
2990 "a sequence of file chunks."
2994 #: ../src/guestfs.pod:1493
2997 " total length (header + arguments,\n"
2998 " but not including the length word itself,\n"
2999 " and not including the chunks)\n"
3000 " struct guestfs_message_header (encoded as XDR)\n"
3001 " struct guestfs_<foo>_args (encoded as XDR)\n"
3002 " sequence of chunks for FileIn param #0\n"
3003 " sequence of chunks for FileIn param #1 etc.\n"
3008 #: ../src/guestfs.pod:1501
3009 msgid "The \"sequence of chunks\" is:"
3013 #: ../src/guestfs.pod:1503
3016 " length of chunk (not including length word itself)\n"
3017 " struct guestfs_chunk (encoded as XDR)\n"
3018 " length of chunk\n"
3019 " struct guestfs_chunk (encoded as XDR)\n"
3021 " length of chunk\n"
3022 " struct guestfs_chunk (with data.data_len == 0)\n"
3027 #: ../src/guestfs.pod:1511
3029 "The final chunk has the C<data_len> field set to zero. Additionally a flag "
3030 "is set in the final chunk to indicate either successful completion or early "
3035 #: ../src/guestfs.pod:1515
3037 "At time of writing there are no functions that have more than one FileIn "
3038 "parameter. However this is (theoretically) supported, by sending the "
3039 "sequence of chunks for each FileIn parameter one after another (from left to "
3044 #: ../src/guestfs.pod:1520
3046 "Both the library (sender) I<and> the daemon (receiver) may cancel the "
3047 "transfer. The library does this by sending a chunk with a special flag set "
3048 "to indicate cancellation. When the daemon sees this, it cancels the whole "
3049 "RPC, does I<not> send any reply, and goes back to reading the next request."
3053 #: ../src/guestfs.pod:1526
3055 "The daemon may also cancel. It does this by writing a special word "
3056 "C<GUESTFS_CANCEL_FLAG> to the socket. The library listens for this during "
3057 "the transfer, and if it gets it, it will cancel the transfer (it sends a "
3058 "cancel chunk). The special word is chosen so that even if cancellation "
3059 "happens right at the end of the transfer (after the library has finished "
3060 "writing and has started listening for the reply), the \"spurious\" cancel "
3061 "flag will not be confused with the reply message."
3065 #: ../src/guestfs.pod:1535
3067 "This protocol allows the transfer of arbitrary sized files (no 32 bit "
3068 "limit), and also files where the size is not known in advance (eg. from "
3069 "pipes or sockets). However the chunks are rather small "
3070 "(C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the daemon need "
3071 "to keep much in memory."
3075 #: ../src/guestfs.pod:1541
3076 msgid "FUNCTIONS THAT HAVE FILEOUT PARAMETERS"
3080 #: ../src/guestfs.pod:1543
3082 "The protocol for FileOut parameters is exactly the same as for FileIn "
3083 "parameters, but with the roles of daemon and library reversed."
3087 #: ../src/guestfs.pod:1546
3090 " total length (header + ret,\n"
3091 " but not including the length word itself,\n"
3092 " and not including the chunks)\n"
3093 " struct guestfs_message_header (encoded as XDR)\n"
3094 " struct guestfs_<foo>_ret (encoded as XDR)\n"
3095 " sequence of chunks for FileOut param #0\n"
3096 " sequence of chunks for FileOut param #1 etc.\n"
3101 #: ../src/guestfs.pod:1554
3102 msgid "INITIAL MESSAGE"
3106 #: ../src/guestfs.pod:1556
3108 "When the daemon launches it sends an initial word (C<GUESTFS_LAUNCH_FLAG>) "
3109 "which indicates that the guest and daemon is alive. This is what L</"
3110 "guestfs_launch> waits for."
3114 #: ../src/guestfs.pod:1560
3115 msgid "PROGRESS NOTIFICATION MESSAGES"
3119 #: ../src/guestfs.pod:1562
3121 "The daemon may send progress notification messages at any time. These are "
3122 "distinguished by the normal length word being replaced by "
3123 "C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message."
3127 #: ../src/guestfs.pod:1566
3129 "The library turns them into progress callbacks (see "
3130 "C<guestfs_set_progress_callback>) if there is a callback registered, or "
3131 "discards them if not."
3135 #: ../src/guestfs.pod:1570
3137 "The daemon self-limits the frequency of progress messages it sends (see "
3138 "C<daemon/proto.c:notify_progress>). Not all calls generate progress "
3143 #: ../src/guestfs.pod:1574
3144 msgid "MULTIPLE HANDLES AND MULTIPLE THREADS"
3148 #: ../src/guestfs.pod:1576
3150 "All high-level libguestfs actions are synchronous. If you want to use "
3151 "libguestfs asynchronously then you must create a thread."
3155 #: ../src/guestfs.pod:1579
3157 "Only use the handle from a single thread. Either use the handle exclusively "
3158 "from one thread, or provide your own mutex so that two threads cannot issue "
3159 "calls on the same handle at the same time."
3163 #: ../src/guestfs.pod:1583
3165 "See the graphical program guestfs-browser for one possible architecture for "
3166 "multithreaded programs using libvirt and libguestfs."
3170 #: ../src/guestfs.pod:1586
3171 msgid "QEMU WRAPPERS"
3175 #: ../src/guestfs.pod:1588
3177 "If you want to compile your own qemu, run qemu from a non-standard location, "
3178 "or pass extra arguments to qemu, then you can write a shell-script wrapper "
3183 #: ../src/guestfs.pod:1592
3185 "There is one important rule to remember: you I<must C<exec qemu>> as the "
3186 "last command in the shell script (so that qemu replaces the shell and "
3187 "becomes the direct child of the libguestfs-using program). If you don't do "
3188 "this, then the qemu process won't be cleaned up correctly."
3192 #: ../src/guestfs.pod:1597
3194 "Here is an example of a wrapper, where I have built my own copy of qemu from "
3199 #: ../src/guestfs.pod:1600
3203 " qemudir=/home/rjones/d/qemu\n"
3204 " exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios \"$@\"\n"
3209 #: ../src/guestfs.pod:1604
3211 "Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>, and "
3212 "then use it by setting the LIBGUESTFS_QEMU environment variable. For "
3217 #: ../src/guestfs.pod:1608
3220 " LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish\n"
3225 #: ../src/guestfs.pod:1610
3227 "Note that libguestfs also calls qemu with the -help and -version options in "
3228 "order to determine features."
3232 #: ../src/guestfs.pod:1613
3233 msgid "LIBGUESTFS VERSION NUMBERS"
3237 #: ../src/guestfs.pod:1615
3239 "Since April 2010, libguestfs has started to make separate development and "
3240 "stable releases, along with corresponding branches in our git repository. "
3241 "These separate releases can be identified by version number:"
3245 #: ../src/guestfs.pod:1620
3248 " even numbers for stable: 1.2.x, 1.4.x, ...\n"
3249 " .-------- odd numbers for development: 1.3.x, 1.5.x, ...\n"
3255 " | `-------- sub-version\n"
3257 " `------ always '1' because we don't change the ABI\n"
3262 #: ../src/guestfs.pod:1631
3263 msgid "Thus \"1.3.5\" is the 5th update to the development branch \"1.3\"."
3267 #: ../src/guestfs.pod:1633
3269 "As time passes we cherry pick fixes from the development branch and backport "
3270 "those into the stable branch, the effect being that the stable branch should "
3271 "get more stable and less buggy over time. So the stable releases are ideal "
3272 "for people who don't need new features but would just like the software to "
3277 #: ../src/guestfs.pod:1639
3278 msgid "Our criteria for backporting changes are:"
3282 #: ../src/guestfs.pod:1645
3284 "Documentation changes which don't affect any code are backported unless the "
3285 "documentation refers to a future feature which is not in stable."
3289 #: ../src/guestfs.pod:1651
3291 "Bug fixes which are not controversial, fix obvious problems, and have been "
3292 "well tested are backported."
3296 #: ../src/guestfs.pod:1656
3298 "Simple rearrangements of code which shouldn't affect how it works get "
3299 "backported. This is so that the code in the two branches doesn't get too "
3300 "far out of step, allowing us to backport future fixes more easily."
3304 #: ../src/guestfs.pod:1662
3306 "We I<don't> backport new features, new APIs, new tools etc, except in one "
3307 "exceptional case: the new feature is required in order to implement an "
3308 "important bug fix."
3312 #: ../src/guestfs.pod:1668
3314 "A new stable branch starts when we think the new features in development are "
3315 "substantial and compelling enough over the current stable branch to warrant "
3316 "it. When that happens we create new stable and development versions 1.N.0 "
3317 "and 1.(N+1).0 [N is even]. The new dot-oh release won't necessarily be so "
3318 "stable at this point, but by backporting fixes from development, that branch "
3319 "will stabilize over time."
3323 #: ../src/guestfs.pod:1676 ../fish/guestfish.pod:826
3324 #: ../test-tool/libguestfs-test-tool.pod:104 ../tools/virt-edit.pl:312
3325 #: ../tools/virt-rescue.pl:226
3326 msgid "ENVIRONMENT VARIABLES"
3330 #: ../src/guestfs.pod:1680 ../fish/guestfish.pod:852
3331 msgid "LIBGUESTFS_APPEND"
3335 #: ../src/guestfs.pod:1682 ../fish/guestfish.pod:854
3336 msgid "Pass additional options to the guest kernel."
3340 #: ../src/guestfs.pod:1684 ../fish/guestfish.pod:856
3341 msgid "LIBGUESTFS_DEBUG"
3345 #: ../src/guestfs.pod:1686
3347 "Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This has the same "
3348 "effect as calling C<guestfs_set_verbose (g, 1)>."
3352 #: ../src/guestfs.pod:1689 ../fish/guestfish.pod:861
3353 msgid "LIBGUESTFS_MEMSIZE"
3357 #: ../src/guestfs.pod:1691 ../fish/guestfish.pod:863
3359 "Set the memory allocated to the qemu process, in megabytes. For example:"
3363 #: ../src/guestfs.pod:1694 ../fish/guestfish.pod:866
3366 " LIBGUESTFS_MEMSIZE=700\n"
3371 #: ../src/guestfs.pod:1696 ../fish/guestfish.pod:868
3372 msgid "LIBGUESTFS_PATH"
3376 #: ../src/guestfs.pod:1698
3378 "Set the path that libguestfs uses to search for kernel and initrd.img. See "
3379 "the discussion of paths in section PATH above."
3383 #: ../src/guestfs.pod:1701 ../fish/guestfish.pod:873
3384 msgid "LIBGUESTFS_QEMU"
3388 #: ../src/guestfs.pod:1703 ../fish/guestfish.pod:875
3390 "Set the default qemu binary that libguestfs uses. If not set, then the qemu "
3391 "which was found at compile time by the configure script is used."
3395 #: ../src/guestfs.pod:1707
3396 msgid "See also L</QEMU WRAPPERS> above."
3400 #: ../src/guestfs.pod:1709 ../fish/guestfish.pod:879
3401 msgid "LIBGUESTFS_TRACE"
3405 #: ../src/guestfs.pod:1711
3407 "Set C<LIBGUESTFS_TRACE=1> to enable command traces. This has the same "
3408 "effect as calling C<guestfs_set_trace (g, 1)>."
3412 #: ../src/guestfs.pod:1714 ../fish/guestfish.pod:888
3417 #: ../src/guestfs.pod:1716 ../fish/guestfish.pod:890
3418 msgid "Location of temporary directory, defaults to C</tmp>."
3422 #: ../src/guestfs.pod:1718 ../fish/guestfish.pod:892
3424 "If libguestfs was compiled to use the supermin appliance then the real "
3425 "appliance is cached in this directory, shared between all handles belonging "
3426 "to the same EUID. You can use C<$TMPDIR> to configure another directory to "
3427 "use in case C</tmp> is not large enough."
3431 #: ../src/guestfs.pod:1726 ../fish/guestfish.pod:950
3432 #: ../test-tool/libguestfs-test-tool.pod:109 ../fuse/guestmount.pod:178
3433 #: ../inspector/virt-inspector.pl:846 ../tools/virt-edit.pl:325
3434 #: ../tools/virt-win-reg.pl:461 ../tools/virt-df.pl:536
3435 #: ../tools/virt-ls.pl:210 ../tools/virt-resize.pl:1390
3436 #: ../tools/virt-list-filesystems.pl:191 ../tools/virt-cat.pl:163
3437 #: ../tools/virt-tar.pl:257 ../tools/virt-rescue.pl:231
3438 #: ../tools/virt-make-fs.pl:527 ../tools/virt-list-partitions.pl:229
3443 #: ../src/guestfs.pod:1728
3445 "L<guestfish(1)>, L<guestmount(1)>, L<virt-cat(1)>, L<virt-df(1)>, L<virt-edit"
3446 "(1)>, L<virt-inspector(1)>, L<virt-list-filesystems(1)>, L<virt-list-"
3447 "partitions(1)>, L<virt-ls(1)>, L<virt-make-fs(1)>, L<virt-rescue(1)>, L<virt-"
3448 "tar(1)>, L<virt-win-reg(1)>, L<qemu(1)>, L<febootstrap(1)>, L<hivex(3)>, "
3449 "L<http://libguestfs.org/>."
3453 #: ../src/guestfs.pod:1746
3455 "Tools with a similar purpose: L<fdisk(8)>, L<parted(8)>, L<kpartx(8)>, L<lvm"
3456 "(8)>, L<disktype(1)>."
3460 #: ../src/guestfs.pod:1753 ../tools/virt-win-reg.pl:476
3461 #: ../tools/virt-make-fs.pl:541
3466 #: ../src/guestfs.pod:1755
3467 msgid "To get a list of bugs against libguestfs use this link:"
3471 #: ../src/guestfs.pod:1757
3473 "L<https://bugzilla.redhat.com/buglist.cgi?"
3474 "component=libguestfs&product=Virtualization+Tools>"
3478 #: ../src/guestfs.pod:1759
3479 msgid "To report a new bug against libguestfs use this link:"
3483 #: ../src/guestfs.pod:1761
3485 "L<https://bugzilla.redhat.com/enter_bug.cgi?"
3486 "component=libguestfs&product=Virtualization+Tools>"
3490 #: ../src/guestfs.pod:1763
3491 msgid "When reporting a bug, please check:"
3495 #: ../src/guestfs.pod:1769
3496 msgid "That the bug hasn't been reported already."
3500 #: ../src/guestfs.pod:1773
3501 msgid "That you are testing a recent version."
3505 #: ../src/guestfs.pod:1777
3506 msgid "Describe the bug accurately, and give a way to reproduce it."
3510 #: ../src/guestfs.pod:1781
3512 "Run libguestfs-test-tool and paste the B<complete, unedited> output into the "
3517 #: ../src/guestfs.pod:1786 ../fish/guestfish.pod:967
3518 #: ../test-tool/libguestfs-test-tool.pod:115 ../fuse/guestmount.pod:189
3519 #: ../inspector/virt-inspector.pl:855
3524 #: ../src/guestfs.pod:1788 ../fish/guestfish.pod:969
3525 #: ../test-tool/libguestfs-test-tool.pod:117 ../fuse/guestmount.pod:191
3526 msgid "Richard W.M. Jones (C<rjones at redhat dot com>)"
3530 #: ../src/guestfs.pod:1790 ../fish/guestfish.pod:971
3531 #: ../test-tool/libguestfs-test-tool.pod:119 ../fuse/guestmount.pod:193
3532 #: ../inspector/virt-inspector.pl:861 ../tools/virt-edit.pl:341
3533 #: ../tools/virt-win-reg.pl:491 ../tools/virt-df.pl:549
3534 #: ../tools/virt-ls.pl:225 ../tools/virt-resize.pl:1411
3535 #: ../tools/virt-list-filesystems.pl:207 ../tools/virt-cat.pl:177
3536 #: ../tools/virt-tar.pl:272 ../tools/virt-rescue.pl:245
3537 #: ../tools/virt-make-fs.pl:556 ../tools/virt-list-partitions.pl:244
3542 #: ../src/guestfs.pod:1792 ../fish/guestfish.pod:973
3543 msgid "Copyright (C) 2009-2010 Red Hat Inc. L<http://libguestfs.org/>"
3547 #: ../src/guestfs.pod:1795
3549 "This library is free software; you can redistribute it and/or modify it "
3550 "under the terms of the GNU Lesser General Public License as published by the "
3551 "Free Software Foundation; either version 2 of the License, or (at your "
3552 "option) any later version."
3556 #: ../src/guestfs.pod:1800
3558 "This library is distributed in the hope that it will be useful, but WITHOUT "
3559 "ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or "
3560 "FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License "
3565 #: ../src/guestfs.pod:1805
3567 "You should have received a copy of the GNU Lesser General Public License "
3568 "along with this library; if not, write to the Free Software Foundation, "
3569 "Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA"
3573 #: ../src/guestfs-actions.pod:1
3574 msgid "guestfs_add_cdrom"
3578 #: ../src/guestfs-actions.pod:3
3581 " int guestfs_add_cdrom (guestfs_h *g,\n"
3582 "\t\tconst char *filename);\n"
3587 #: ../src/guestfs-actions.pod:6 ../fish/guestfish-actions.pod:7
3588 msgid "This function adds a virtual CD-ROM disk image to the guest."
3592 #: ../src/guestfs-actions.pod:8 ../fish/guestfish-actions.pod:9
3593 msgid "This is equivalent to the qemu parameter C<-cdrom filename>."
3597 #: ../src/guestfs-actions.pod:10 ../src/guestfs-actions.pod:1516
3598 #: ../fish/guestfish-actions.pod:11 ../fish/guestfish-actions.pod:1211
3603 #: ../src/guestfs-actions.pod:16
3605 "This call checks for the existence of C<filename>. This stops you from "
3606 "specifying other types of drive which are supported by qemu such as C<nbd:> "
3607 "and C<http:> URLs. To specify those, use the general C<guestfs_config> call "
3612 #: ../src/guestfs-actions.pod:23
3614 "If you just want to add an ISO file (often you use this as an efficient way "
3615 "to transfer large files into the guest), then you should probably use "
3616 "C<guestfs_add_drive_ro> instead."
3620 #: ../src/guestfs-actions.pod:29 ../src/guestfs-actions.pod:63
3621 #: ../src/guestfs-actions.pod:92 ../src/guestfs-actions.pod:103
3622 #: ../src/guestfs-actions.pod:114 ../src/guestfs-actions.pod:124
3623 #: ../src/guestfs-actions.pod:135 ../src/guestfs-actions.pod:238
3624 #: ../src/guestfs-actions.pod:255 ../src/guestfs-actions.pod:266
3625 #: ../src/guestfs-actions.pod:302 ../src/guestfs-actions.pod:324
3626 #: ../src/guestfs-actions.pod:339 ../src/guestfs-actions.pod:403
3627 #: ../src/guestfs-actions.pod:430 ../src/guestfs-actions.pod:441
3628 #: ../src/guestfs-actions.pod:453 ../src/guestfs-actions.pod:534
3629 #: ../src/guestfs-actions.pod:549 ../src/guestfs-actions.pod:560
3630 #: ../src/guestfs-actions.pod:571 ../src/guestfs-actions.pod:717
3631 #: ../src/guestfs-actions.pod:734 ../src/guestfs-actions.pod:749
3632 #: ../src/guestfs-actions.pod:824 ../src/guestfs-actions.pod:839
3633 #: ../src/guestfs-actions.pod:855 ../src/guestfs-actions.pod:866
3634 #: ../src/guestfs-actions.pod:883 ../src/guestfs-actions.pod:916
3635 #: ../src/guestfs-actions.pod:974 ../src/guestfs-actions.pod:1002
3636 #: ../src/guestfs-actions.pod:1024 ../src/guestfs-actions.pod:1055
3637 #: ../src/guestfs-actions.pod:1143 ../src/guestfs-actions.pod:1174
3638 #: ../src/guestfs-actions.pod:1374 ../src/guestfs-actions.pod:1393
3639 #: ../src/guestfs-actions.pod:1474 ../src/guestfs-actions.pod:1822
3640 #: ../src/guestfs-actions.pod:1945 ../src/guestfs-actions.pod:2000
3641 #: ../src/guestfs-actions.pod:2030 ../src/guestfs-actions.pod:2439
3642 #: ../src/guestfs-actions.pod:2451 ../src/guestfs-actions.pod:2468
3643 #: ../src/guestfs-actions.pod:2576 ../src/guestfs-actions.pod:2587
3644 #: ../src/guestfs-actions.pod:2597 ../src/guestfs-actions.pod:2608
3645 #: ../src/guestfs-actions.pod:2620 ../src/guestfs-actions.pod:2650
3646 #: ../src/guestfs-actions.pod:2714 ../src/guestfs-actions.pod:2731
3647 #: ../src/guestfs-actions.pod:2745 ../src/guestfs-actions.pod:2765
3648 #: ../src/guestfs-actions.pod:2785 ../src/guestfs-actions.pod:2814
3649 #: ../src/guestfs-actions.pod:2830 ../src/guestfs-actions.pod:2846
3650 #: ../src/guestfs-actions.pod:2858 ../src/guestfs-actions.pod:2867
3651 #: ../src/guestfs-actions.pod:2900 ../src/guestfs-actions.pod:2913
3652 #: ../src/guestfs-actions.pod:2923 ../src/guestfs-actions.pod:2935
3653 #: ../src/guestfs-actions.pod:2949 ../src/guestfs-actions.pod:3029
3654 #: ../src/guestfs-actions.pod:3046 ../src/guestfs-actions.pod:3056
3655 #: ../src/guestfs-actions.pod:3101 ../src/guestfs-actions.pod:3116
3656 #: ../src/guestfs-actions.pod:3131 ../src/guestfs-actions.pod:3144
3657 #: ../src/guestfs-actions.pod:3155 ../src/guestfs-actions.pod:3166
3658 #: ../src/guestfs-actions.pod:3180 ../src/guestfs-actions.pod:3192
3659 #: ../src/guestfs-actions.pod:3209 ../src/guestfs-actions.pod:3240
3660 #: ../src/guestfs-actions.pod:3268 ../src/guestfs-actions.pod:3284
3661 #: ../src/guestfs-actions.pod:3300 ../src/guestfs-actions.pod:3309
3662 #: ../src/guestfs-actions.pod:3323 ../src/guestfs-actions.pod:3333
3663 #: ../src/guestfs-actions.pod:3345 ../src/guestfs-actions.pod:3357
3664 #: ../src/guestfs-actions.pod:3389 ../src/guestfs-actions.pod:3401
3665 #: ../src/guestfs-actions.pod:3418 ../src/guestfs-actions.pod:3429
3666 #: ../src/guestfs-actions.pod:3443 ../src/guestfs-actions.pod:3483
3667 #: ../src/guestfs-actions.pod:3514 ../src/guestfs-actions.pod:3525
3668 #: ../src/guestfs-actions.pod:3550 ../src/guestfs-actions.pod:3564
3669 #: ../src/guestfs-actions.pod:3579 ../src/guestfs-actions.pod:3701
3670 #: ../src/guestfs-actions.pod:3753 ../src/guestfs-actions.pod:3772
3671 #: ../src/guestfs-actions.pod:3787 ../src/guestfs-actions.pod:3813
3672 #: ../src/guestfs-actions.pod:3847 ../src/guestfs-actions.pod:3861
3673 #: ../src/guestfs-actions.pod:3871 ../src/guestfs-actions.pod:3882
3674 #: ../src/guestfs-actions.pod:4137 ../src/guestfs-actions.pod:4153
3675 #: ../src/guestfs-actions.pod:4164 ../src/guestfs-actions.pod:4173
3676 #: ../src/guestfs-actions.pod:4184 ../src/guestfs-actions.pod:4193
3677 #: ../src/guestfs-actions.pod:4204 ../src/guestfs-actions.pod:4217
3678 #: ../src/guestfs-actions.pod:4235 ../src/guestfs-actions.pod:4251
3679 #: ../src/guestfs-actions.pod:4267 ../src/guestfs-actions.pod:4282
3680 #: ../src/guestfs-actions.pod:4302 ../src/guestfs-actions.pod:4317
3681 #: ../src/guestfs-actions.pod:4333 ../src/guestfs-actions.pod:4351
3682 #: ../src/guestfs-actions.pod:4367 ../src/guestfs-actions.pod:4381
3683 #: ../src/guestfs-actions.pod:4406 ../src/guestfs-actions.pod:4427
3684 #: ../src/guestfs-actions.pod:4443 ../src/guestfs-actions.pod:4464
3685 #: ../src/guestfs-actions.pod:4476 ../src/guestfs-actions.pod:4488
3686 #: ../src/guestfs-actions.pod:4504 ../src/guestfs-actions.pod:4538
3687 #: ../src/guestfs-actions.pod:4558 ../src/guestfs-actions.pod:4581
3688 #: ../src/guestfs-actions.pod:4671 ../src/guestfs-actions.pod:4777
3689 #: ../src/guestfs-actions.pod:4786 ../src/guestfs-actions.pod:4796
3690 #: ../src/guestfs-actions.pod:4806 ../src/guestfs-actions.pod:4825
3691 #: ../src/guestfs-actions.pod:4835 ../src/guestfs-actions.pod:4845
3692 #: ../src/guestfs-actions.pod:4855 ../src/guestfs-actions.pod:4867
3693 #: ../src/guestfs-actions.pod:4917 ../src/guestfs-actions.pod:4931
3694 #: ../src/guestfs-actions.pod:4944 ../src/guestfs-actions.pod:4957
3695 #: ../src/guestfs-actions.pod:4971 ../src/guestfs-actions.pod:4981
3696 #: ../src/guestfs-actions.pod:4998 ../src/guestfs-actions.pod:5028
3697 #: ../src/guestfs-actions.pod:5039 ../src/guestfs-actions.pod:5074
3698 #: ../src/guestfs-actions.pod:5084 ../src/guestfs-actions.pod:5099
3699 #: ../src/guestfs-actions.pod:5125 ../src/guestfs-actions.pod:5153
3700 #: ../src/guestfs-actions.pod:5257 ../src/guestfs-actions.pod:5272
3701 #: ../src/guestfs-actions.pod:5283 ../src/guestfs-actions.pod:5329
3702 #: ../src/guestfs-actions.pod:5339 ../src/guestfs-actions.pod:5376
3703 #: ../src/guestfs-actions.pod:5403 ../src/guestfs-actions.pod:5445
3704 #: ../src/guestfs-actions.pod:5468 ../src/guestfs-actions.pod:5525
3705 #: ../src/guestfs-actions.pod:5541 ../src/guestfs-actions.pod:5567
3706 msgid "This function returns 0 on success or -1 on error."
3710 #: ../src/guestfs-actions.pod:31
3711 msgid "guestfs_add_drive"
3715 #: ../src/guestfs-actions.pod:33
3718 " int guestfs_add_drive (guestfs_h *g,\n"
3719 "\t\tconst char *filename);\n"
3724 #: ../src/guestfs-actions.pod:36 ../fish/guestfish-actions.pod:36
3726 "This function adds a virtual machine disk image C<filename> to the guest. "
3727 "The first time you call this function, the disk appears as IDE disk 0 (C</"
3728 "dev/sda>) in the guest, the second time as C</dev/sdb>, and so on."
3732 #: ../src/guestfs-actions.pod:41 ../fish/guestfish-actions.pod:41
3734 "You don't necessarily need to be root when using libguestfs. However you "
3735 "obviously do need sufficient permissions to access the filename for whatever "
3736 "operations you want to perform (ie. read access if you just want to read the "
3737 "image or write access if you want to modify the image)."
3741 #: ../src/guestfs-actions.pod:47 ../fish/guestfish-actions.pod:47
3743 "This is equivalent to the qemu parameter C<-drive file=filename,cache=off,"
3748 #: ../src/guestfs-actions.pod:50 ../fish/guestfish-actions.pod:50
3750 "C<cache=off> is omitted in cases where it is not supported by the underlying "
3755 #: ../src/guestfs-actions.pod:53 ../src/guestfs-actions.pod:82
3757 "C<if=...> is set at compile time by the configuration option C<./configure --"
3758 "with-drive-if=...>. In the rare case where you might need to change this at "
3759 "run time, use C<guestfs_add_drive_with_if> or "
3760 "C<guestfs_add_drive_ro_with_if>."
3764 #: ../src/guestfs-actions.pod:58 ../src/guestfs-actions.pod:87
3766 "Note that this call checks for the existence of C<filename>. This stops you "
3767 "from specifying other types of drive which are supported by qemu such as "
3768 "C<nbd:> and C<http:> URLs. To specify those, use the general "
3769 "C<guestfs_config> call instead."
3773 #: ../src/guestfs-actions.pod:65
3774 msgid "guestfs_add_drive_ro"
3778 #: ../src/guestfs-actions.pod:67
3781 " int guestfs_add_drive_ro (guestfs_h *g,\n"
3782 "\t\tconst char *filename);\n"
3787 #: ../src/guestfs-actions.pod:70 ../fish/guestfish-actions.pod:69
3788 msgid "This adds a drive in snapshot mode, making it effectively read-only."
3792 #: ../src/guestfs-actions.pod:73 ../fish/guestfish-actions.pod:72
3794 "Note that writes to the device are allowed, and will be seen for the "
3795 "duration of the guestfs handle, but they are written to a temporary file "
3796 "which is discarded as soon as the guestfs handle is closed. We don't "
3797 "currently have any method to enable changes to be committed, although qemu "
3802 #: ../src/guestfs-actions.pod:79 ../fish/guestfish-actions.pod:78
3804 "This is equivalent to the qemu parameter C<-drive file=filename,snapshot=on,"
3809 #: ../src/guestfs-actions.pod:94
3810 msgid "guestfs_add_drive_ro_with_if"
3814 #: ../src/guestfs-actions.pod:96
3817 " int guestfs_add_drive_ro_with_if (guestfs_h *g,\n"
3818 "\t\tconst char *filename,\n"
3819 "\t\tconst char *iface);\n"
3824 #: ../src/guestfs-actions.pod:100
3826 "This is the same as C<guestfs_add_drive_ro> but it allows you to specify the "
3827 "QEMU interface emulation to use at run time."
3831 #: ../src/guestfs-actions.pod:105
3832 msgid "guestfs_add_drive_with_if"
3836 #: ../src/guestfs-actions.pod:107
3839 " int guestfs_add_drive_with_if (guestfs_h *g,\n"
3840 "\t\tconst char *filename,\n"
3841 "\t\tconst char *iface);\n"
3846 #: ../src/guestfs-actions.pod:111
3848 "This is the same as C<guestfs_add_drive> but it allows you to specify the "
3849 "QEMU interface emulation to use at run time."
3853 #: ../src/guestfs-actions.pod:116
3854 msgid "guestfs_aug_clear"
3858 #: ../src/guestfs-actions.pod:118
3861 " int guestfs_aug_clear (guestfs_h *g,\n"
3862 "\t\tconst char *augpath);\n"
3867 #: ../src/guestfs-actions.pod:121 ../fish/guestfish-actions.pod:109
3869 "Set the value associated with C<path> to C<NULL>. This is the same as the "
3870 "L<augtool(1)> C<clear> command."
3874 #: ../src/guestfs-actions.pod:126
3875 msgid "guestfs_aug_close"
3879 #: ../src/guestfs-actions.pod:128
3882 " int guestfs_aug_close (guestfs_h *g);\n"
3887 #: ../src/guestfs-actions.pod:130
3889 "Close the current Augeas handle and free up any resources used by it. After "
3890 "calling this, you have to call C<guestfs_aug_init> again before you can use "
3891 "any other Augeas functions."
3895 #: ../src/guestfs-actions.pod:137
3896 msgid "guestfs_aug_defnode"
3900 #: ../src/guestfs-actions.pod:139
3903 " struct guestfs_int_bool *guestfs_aug_defnode (guestfs_h *g,\n"
3904 "\t\tconst char *name,\n"
3905 "\t\tconst char *expr,\n"
3906 "\t\tconst char *val);\n"
3911 #: ../src/guestfs-actions.pod:144 ../fish/guestfish-actions.pod:125
3913 "Defines a variable C<name> whose value is the result of evaluating C<expr>."
3917 #: ../src/guestfs-actions.pod:147
3919 "If C<expr> evaluates to an empty nodeset, a node is created, equivalent to "
3920 "calling C<guestfs_aug_set> C<expr>, C<value>. C<name> will be the nodeset "
3921 "containing that single node."
3925 #: ../src/guestfs-actions.pod:151 ../fish/guestfish-actions.pod:132
3927 "On success this returns a pair containing the number of nodes in the "
3928 "nodeset, and a boolean flag if a node was created."
3932 #: ../src/guestfs-actions.pod:155
3934 "This function returns a C<struct guestfs_int_bool *>, or NULL if there was "
3935 "an error. I<The caller must call C<guestfs_free_int_bool> after use>."
3939 #: ../src/guestfs-actions.pod:159
3940 msgid "guestfs_aug_defvar"
3944 #: ../src/guestfs-actions.pod:161
3947 " int guestfs_aug_defvar (guestfs_h *g,\n"
3948 "\t\tconst char *name,\n"
3949 "\t\tconst char *expr);\n"
3954 #: ../src/guestfs-actions.pod:165 ../fish/guestfish-actions.pod:140
3956 "Defines an Augeas variable C<name> whose value is the result of evaluating "
3957 "C<expr>. If C<expr> is NULL, then C<name> is undefined."
3961 #: ../src/guestfs-actions.pod:169 ../fish/guestfish-actions.pod:144
3963 "On success this returns the number of nodes in C<expr>, or C<0> if C<expr> "
3964 "evaluates to something which is not a nodeset."
3968 #: ../src/guestfs-actions.pod:172 ../src/guestfs-actions.pod:313
3969 #: ../src/guestfs-actions.pod:467 ../src/guestfs-actions.pod:492
3970 #: ../src/guestfs-actions.pod:507 ../src/guestfs-actions.pod:523
3971 #: ../src/guestfs-actions.pod:1041 ../src/guestfs-actions.pod:1356
3972 #: ../src/guestfs-actions.pod:1538 ../src/guestfs-actions.pod:1619
3973 #: ../src/guestfs-actions.pod:1650 ../src/guestfs-actions.pod:1693
3974 #: ../src/guestfs-actions.pod:1710 ../src/guestfs-actions.pod:1935
3975 #: ../src/guestfs-actions.pod:2147 ../src/guestfs-actions.pod:2165
3976 #: ../src/guestfs-actions.pod:3503 ../src/guestfs-actions.pod:3610
3977 #: ../src/guestfs-actions.pod:3941 ../src/guestfs-actions.pod:3964
3978 #: ../src/guestfs-actions.pod:5063 ../src/guestfs-actions.pod:5413
3979 #: ../src/guestfs-actions.pod:5423 ../src/guestfs-actions.pod:5433
3980 msgid "On error this function returns -1."
3984 #: ../src/guestfs-actions.pod:174
3985 msgid "guestfs_aug_get"
3989 #: ../src/guestfs-actions.pod:176
3992 " char *guestfs_aug_get (guestfs_h *g,\n"
3993 "\t\tconst char *augpath);\n"
3998 #: ../src/guestfs-actions.pod:179 ../fish/guestfish-actions.pod:151
4000 "Look up the value associated with C<path>. If C<path> matches exactly one "
4001 "node, the C<value> is returned."
4005 #: ../src/guestfs-actions.pod:182 ../src/guestfs-actions.pod:610
4006 #: ../src/guestfs-actions.pod:625 ../src/guestfs-actions.pod:682
4007 #: ../src/guestfs-actions.pod:695 ../src/guestfs-actions.pod:786
4008 #: ../src/guestfs-actions.pod:899 ../src/guestfs-actions.pod:928
4009 #: ../src/guestfs-actions.pod:942 ../src/guestfs-actions.pod:958
4010 #: ../src/guestfs-actions.pod:1069 ../src/guestfs-actions.pod:1233
4011 #: ../src/guestfs-actions.pod:1342 ../src/guestfs-actions.pod:1487
4012 #: ../src/guestfs-actions.pod:1501 ../src/guestfs-actions.pod:1577
4013 #: ../src/guestfs-actions.pod:1595 ../src/guestfs-actions.pod:1729
4014 #: ../src/guestfs-actions.pod:1868 ../src/guestfs-actions.pod:2049
4015 #: ../src/guestfs-actions.pod:2099 ../src/guestfs-actions.pod:2215
4016 #: ../src/guestfs-actions.pod:2250 ../src/guestfs-actions.pod:2565
4017 #: ../src/guestfs-actions.pod:2986 ../src/guestfs-actions.pod:3082
4018 #: ../src/guestfs-actions.pod:3625 ../src/guestfs-actions.pod:3801
4019 #: ../src/guestfs-actions.pod:3919 ../src/guestfs-actions.pod:4080
4020 #: ../src/guestfs-actions.pod:4123 ../src/guestfs-actions.pod:4599
4021 #: ../src/guestfs-actions.pod:4612 ../src/guestfs-actions.pod:4626
4022 #: ../src/guestfs-actions.pod:4647 ../src/guestfs-actions.pod:5206
4023 #: ../src/guestfs-actions.pod:5222 ../src/guestfs-actions.pod:5237
4024 #: ../src/guestfs-actions.pod:5385 ../src/guestfs-actions.pod:5615
4026 "This function returns a string, or NULL on error. I<The caller must free "
4027 "the returned string after use>."
4031 #: ../src/guestfs-actions.pod:185
4032 msgid "guestfs_aug_init"
4036 #: ../src/guestfs-actions.pod:187
4039 " int guestfs_aug_init (guestfs_h *g,\n"
4040 "\t\tconst char *root,\n"
4046 #: ../src/guestfs-actions.pod:191 ../fish/guestfish-actions.pod:158
4048 "Create a new Augeas handle for editing configuration files. If there was "
4049 "any previous Augeas handle associated with this guestfs session, then it is "
4054 #: ../src/guestfs-actions.pod:195
4055 msgid "You must call this before using any other C<guestfs_aug_*> commands."
4059 #: ../src/guestfs-actions.pod:198 ../fish/guestfish-actions.pod:165
4061 "C<root> is the filesystem root. C<root> must not be NULL, use C</> instead."
4065 #: ../src/guestfs-actions.pod:201 ../fish/guestfish-actions.pod:168
4067 "The flags are the same as the flags defined in E<lt>augeas.hE<gt>, the "
4068 "logical I<or> of the following integers:"
4072 #: ../src/guestfs-actions.pod:207 ../fish/guestfish-actions.pod:174
4073 msgid "C<AUG_SAVE_BACKUP> = 1"
4077 #: ../src/guestfs-actions.pod:209 ../fish/guestfish-actions.pod:176
4078 msgid "Keep the original file with a C<.augsave> extension."
4082 #: ../src/guestfs-actions.pod:211 ../fish/guestfish-actions.pod:178
4083 msgid "C<AUG_SAVE_NEWFILE> = 2"
4087 #: ../src/guestfs-actions.pod:213 ../fish/guestfish-actions.pod:180
4089 "Save changes into a file with extension C<.augnew>, and do not overwrite "
4090 "original. Overrides C<AUG_SAVE_BACKUP>."
4094 #: ../src/guestfs-actions.pod:216 ../fish/guestfish-actions.pod:183
4095 msgid "C<AUG_TYPE_CHECK> = 4"
4099 #: ../src/guestfs-actions.pod:218 ../fish/guestfish-actions.pod:185
4100 msgid "Typecheck lenses (can be expensive)."
4104 #: ../src/guestfs-actions.pod:220 ../fish/guestfish-actions.pod:187
4105 msgid "C<AUG_NO_STDINC> = 8"
4109 #: ../src/guestfs-actions.pod:222 ../fish/guestfish-actions.pod:189
4110 msgid "Do not use standard load path for modules."
4114 #: ../src/guestfs-actions.pod:224 ../fish/guestfish-actions.pod:191
4115 msgid "C<AUG_SAVE_NOOP> = 16"
4119 #: ../src/guestfs-actions.pod:226 ../fish/guestfish-actions.pod:193
4120 msgid "Make save a no-op, just record what would have been changed."
4124 #: ../src/guestfs-actions.pod:228 ../fish/guestfish-actions.pod:195
4125 msgid "C<AUG_NO_LOAD> = 32"
4129 #: ../src/guestfs-actions.pod:230
4130 msgid "Do not load the tree in C<guestfs_aug_init>."
4134 #: ../src/guestfs-actions.pod:234
4135 msgid "To close the handle, you can call C<guestfs_aug_close>."
4139 #: ../src/guestfs-actions.pod:236 ../fish/guestfish-actions.pod:203
4140 msgid "To find out more about Augeas, see L<http://augeas.net/>."
4144 #: ../src/guestfs-actions.pod:240
4145 msgid "guestfs_aug_insert"
4149 #: ../src/guestfs-actions.pod:242
4152 " int guestfs_aug_insert (guestfs_h *g,\n"
4153 "\t\tconst char *augpath,\n"
4154 "\t\tconst char *label,\n"
4155 "\t\tint before);\n"
4160 #: ../src/guestfs-actions.pod:247 ../fish/guestfish-actions.pod:209
4162 "Create a new sibling C<label> for C<path>, inserting it into the tree before "
4163 "or after C<path> (depending on the boolean flag C<before>)."
4167 #: ../src/guestfs-actions.pod:251 ../fish/guestfish-actions.pod:213
4169 "C<path> must match exactly one existing node in the tree, and C<label> must "
4170 "be a label, ie. not contain C</>, C<*> or end with a bracketed index C<[N]>."
4174 #: ../src/guestfs-actions.pod:257
4175 msgid "guestfs_aug_load"
4179 #: ../src/guestfs-actions.pod:259
4182 " int guestfs_aug_load (guestfs_h *g);\n"
4187 #: ../src/guestfs-actions.pod:261 ../fish/guestfish-actions.pod:221
4188 msgid "Load files into the tree."
4192 #: ../src/guestfs-actions.pod:263 ../fish/guestfish-actions.pod:223
4193 msgid "See C<aug_load> in the Augeas documentation for the full gory details."
4197 #: ../src/guestfs-actions.pod:268
4198 msgid "guestfs_aug_ls"
4202 #: ../src/guestfs-actions.pod:270
4205 " char **guestfs_aug_ls (guestfs_h *g,\n"
4206 "\t\tconst char *augpath);\n"
4211 #: ../src/guestfs-actions.pod:273
4213 "This is just a shortcut for listing C<guestfs_aug_match> C<path/*> and "
4214 "sorting the resulting nodes into alphabetical order."
4218 #: ../src/guestfs-actions.pod:276 ../src/guestfs-actions.pod:289
4219 #: ../src/guestfs-actions.pod:417 ../src/guestfs-actions.pod:802
4220 #: ../src/guestfs-actions.pod:1081 ../src/guestfs-actions.pod:1097
4221 #: ../src/guestfs-actions.pod:1185 ../src/guestfs-actions.pod:1201
4222 #: ../src/guestfs-actions.pod:1432 ../src/guestfs-actions.pod:1766
4223 #: ../src/guestfs-actions.pod:1779 ../src/guestfs-actions.pod:1795
4224 #: ../src/guestfs-actions.pod:1832 ../src/guestfs-actions.pod:1853
4225 #: ../src/guestfs-actions.pod:1915 ../src/guestfs-actions.pod:1955
4226 #: ../src/guestfs-actions.pod:2121 ../src/guestfs-actions.pod:2289
4227 #: ../src/guestfs-actions.pod:2494 ../src/guestfs-actions.pod:2550
4228 #: ../src/guestfs-actions.pod:2634 ../src/guestfs-actions.pod:2963
4229 #: ../src/guestfs-actions.pod:3470 ../src/guestfs-actions.pod:3896
4230 #: ../src/guestfs-actions.pod:4005 ../src/guestfs-actions.pod:4111
4231 #: ../src/guestfs-actions.pod:4660 ../src/guestfs-actions.pod:4709
4232 #: ../src/guestfs-actions.pod:4761 ../src/guestfs-actions.pod:4877
4233 #: ../src/guestfs-actions.pod:4898 ../src/guestfs-actions.pod:5298
4234 #: ../src/guestfs-actions.pod:5315 ../src/guestfs-actions.pod:5353
4235 #: ../src/guestfs-actions.pod:5489 ../src/guestfs-actions.pod:5505
4236 #: ../src/guestfs-actions.pod:5578 ../src/guestfs-actions.pod:5594
4237 #: ../src/guestfs-actions.pod:5634 ../src/guestfs-actions.pod:5650
4239 "This function returns a NULL-terminated array of strings (like L<environ(3)"
4240 ">), or NULL if there was an error. I<The caller must free the strings and "
4241 "the array after use>."
4245 #: ../src/guestfs-actions.pod:280
4246 msgid "guestfs_aug_match"
4250 #: ../src/guestfs-actions.pod:282
4253 " char **guestfs_aug_match (guestfs_h *g,\n"
4254 "\t\tconst char *augpath);\n"
4259 #: ../src/guestfs-actions.pod:285 ../fish/guestfish-actions.pod:237
4261 "Returns a list of paths which match the path expression C<path>. The "
4262 "returned paths are sufficiently qualified so that they match exactly one "
4263 "node in the current tree."
4267 #: ../src/guestfs-actions.pod:293
4268 msgid "guestfs_aug_mv"
4272 #: ../src/guestfs-actions.pod:295
4275 " int guestfs_aug_mv (guestfs_h *g,\n"
4276 "\t\tconst char *src,\n"
4277 "\t\tconst char *dest);\n"
4282 #: ../src/guestfs-actions.pod:299 ../fish/guestfish-actions.pod:245
4284 "Move the node C<src> to C<dest>. C<src> must match exactly one node. "
4285 "C<dest> is overwritten if it exists."
4289 #: ../src/guestfs-actions.pod:304
4290 msgid "guestfs_aug_rm"
4294 #: ../src/guestfs-actions.pod:306
4297 " int guestfs_aug_rm (guestfs_h *g,\n"
4298 "\t\tconst char *augpath);\n"
4303 #: ../src/guestfs-actions.pod:309 ../fish/guestfish-actions.pod:252
4304 msgid "Remove C<path> and all of its children."
4308 #: ../src/guestfs-actions.pod:311 ../fish/guestfish-actions.pod:254
4309 msgid "On success this returns the number of entries which were removed."
4313 #: ../src/guestfs-actions.pod:315
4314 msgid "guestfs_aug_save"
4318 #: ../src/guestfs-actions.pod:317
4321 " int guestfs_aug_save (guestfs_h *g);\n"
4326 #: ../src/guestfs-actions.pod:319 ../fish/guestfish-actions.pod:260
4327 msgid "This writes all pending changes to disk."
4331 #: ../src/guestfs-actions.pod:321
4333 "The flags which were passed to C<guestfs_aug_init> affect exactly how files "
4338 #: ../src/guestfs-actions.pod:326
4339 msgid "guestfs_aug_set"
4343 #: ../src/guestfs-actions.pod:328
4346 " int guestfs_aug_set (guestfs_h *g,\n"
4347 "\t\tconst char *augpath,\n"
4348 "\t\tconst char *val);\n"
4353 #: ../src/guestfs-actions.pod:332 ../fish/guestfish-actions.pod:269
4354 msgid "Set the value associated with C<path> to C<val>."
4358 #: ../src/guestfs-actions.pod:334
4360 "In the Augeas API, it is possible to clear a node by setting the value to "
4361 "NULL. Due to an oversight in the libguestfs API you cannot do that with "
4362 "this call. Instead you must use the C<guestfs_aug_clear> call."
4366 #: ../src/guestfs-actions.pod:341
4367 msgid "guestfs_available"
4371 #: ../src/guestfs-actions.pod:343
4374 " int guestfs_available (guestfs_h *g,\n"
4375 "\t\tchar *const *groups);\n"
4380 #: ../src/guestfs-actions.pod:346 ../fish/guestfish-actions.pod:280
4382 "This command is used to check the availability of some groups of "
4383 "functionality in the appliance, which not all builds of the libguestfs "
4384 "appliance will be able to provide."
4388 #: ../src/guestfs-actions.pod:350
4390 "The libguestfs groups, and the functions that those groups correspond to, "
4391 "are listed in L<guestfs(3)/AVAILABILITY>. You can also fetch this list at "
4392 "runtime by calling C<guestfs_available_all_groups>."
4396 #: ../src/guestfs-actions.pod:355 ../fish/guestfish-actions.pod:289
4398 "The argument C<groups> is a list of group names, eg: C<[\"inotify\", \"augeas"
4399 "\"]> would check for the availability of the Linux inotify functions and "
4400 "Augeas (configuration file editing) functions."
4404 #: ../src/guestfs-actions.pod:360 ../fish/guestfish-actions.pod:294
4405 msgid "The command returns no error if I<all> requested groups are available."
4409 #: ../src/guestfs-actions.pod:362 ../fish/guestfish-actions.pod:296
4411 "It fails with an error if one or more of the requested groups is unavailable "
4416 #: ../src/guestfs-actions.pod:365 ../fish/guestfish-actions.pod:299
4418 "If an unknown group name is included in the list of groups then an error is "
4423 #: ../src/guestfs-actions.pod:368 ../fish/guestfish-actions.pod:302
4428 #: ../src/guestfs-actions.pod:374
4429 msgid "You must call C<guestfs_launch> before calling this function."
4433 #: ../src/guestfs-actions.pod:376 ../fish/guestfish-actions.pod:310
4435 "The reason is because we don't know what groups are supported by the "
4436 "appliance/daemon until it is running and can be queried."
4440 #: ../src/guestfs-actions.pod:382 ../fish/guestfish-actions.pod:316
4442 "If a group of functions is available, this does not necessarily mean that "
4443 "they will work. You still have to check for errors when calling individual "
4444 "API functions even if they are available."
4448 #: ../src/guestfs-actions.pod:389 ../fish/guestfish-actions.pod:323
4450 "It is usually the job of distro packagers to build complete functionality "
4451 "into the libguestfs appliance. Upstream libguestfs, if built from source "
4452 "with all requirements satisfied, will support everything."
4456 #: ../src/guestfs-actions.pod:396
4458 "This call was added in version C<1.0.80>. In previous versions of "
4459 "libguestfs all you could do would be to speculatively execute a command to "
4460 "find out if the daemon implemented it. See also C<guestfs_version>."
4464 #: ../src/guestfs-actions.pod:405
4465 msgid "guestfs_available_all_groups"
4469 #: ../src/guestfs-actions.pod:407
4472 " char **guestfs_available_all_groups (guestfs_h *g);\n"
4477 #: ../src/guestfs-actions.pod:409
4479 "This command returns a list of all optional groups that this daemon knows "
4480 "about. Note this returns both supported and unsupported groups. To find "
4481 "out which ones the daemon can actually support you have to call "
4482 "C<guestfs_available> on each member of the returned list."
4486 #: ../src/guestfs-actions.pod:415
4487 msgid "See also C<guestfs_available> and L<guestfs(3)/AVAILABILITY>."
4491 #: ../src/guestfs-actions.pod:421
4492 msgid "guestfs_base64_in"
4496 #: ../src/guestfs-actions.pod:423
4499 " int guestfs_base64_in (guestfs_h *g,\n"
4500 "\t\tconst char *base64file,\n"
4501 "\t\tconst char *filename);\n"
4506 #: ../src/guestfs-actions.pod:427 ../fish/guestfish-actions.pod:353
4508 "This command uploads base64-encoded data from C<base64file> to C<filename>."
4512 #: ../src/guestfs-actions.pod:432
4513 msgid "guestfs_base64_out"
4517 #: ../src/guestfs-actions.pod:434
4520 " int guestfs_base64_out (guestfs_h *g,\n"
4521 "\t\tconst char *filename,\n"
4522 "\t\tconst char *base64file);\n"
4527 #: ../src/guestfs-actions.pod:438 ../fish/guestfish-actions.pod:362
4529 "This command downloads the contents of C<filename>, writing it out to local "
4530 "file C<base64file> encoded as base64."
4534 #: ../src/guestfs-actions.pod:443
4535 msgid "guestfs_blockdev_flushbufs"
4539 #: ../src/guestfs-actions.pod:445
4542 " int guestfs_blockdev_flushbufs (guestfs_h *g,\n"
4543 "\t\tconst char *device);\n"
4548 #: ../src/guestfs-actions.pod:448 ../fish/guestfish-actions.pod:371
4550 "This tells the kernel to flush internal buffers associated with C<device>."
4554 #: ../src/guestfs-actions.pod:451 ../src/guestfs-actions.pod:465
4555 #: ../src/guestfs-actions.pod:477 ../src/guestfs-actions.pod:490
4556 #: ../src/guestfs-actions.pod:505 ../src/guestfs-actions.pod:521
4557 #: ../src/guestfs-actions.pod:532 ../src/guestfs-actions.pod:547
4558 #: ../src/guestfs-actions.pod:558 ../src/guestfs-actions.pod:569
4559 #: ../fish/guestfish-actions.pod:374 ../fish/guestfish-actions.pod:385
4560 #: ../fish/guestfish-actions.pod:394 ../fish/guestfish-actions.pod:404
4561 #: ../fish/guestfish-actions.pod:416 ../fish/guestfish-actions.pod:429
4562 #: ../fish/guestfish-actions.pod:437 ../fish/guestfish-actions.pod:448
4563 #: ../fish/guestfish-actions.pod:456 ../fish/guestfish-actions.pod:464
4564 msgid "This uses the L<blockdev(8)> command."
4568 #: ../src/guestfs-actions.pod:455
4569 msgid "guestfs_blockdev_getbsz"
4573 #: ../src/guestfs-actions.pod:457
4576 " int guestfs_blockdev_getbsz (guestfs_h *g,\n"
4577 "\t\tconst char *device);\n"
4582 #: ../src/guestfs-actions.pod:460 ../fish/guestfish-actions.pod:380
4583 msgid "This returns the block size of a device."
4587 #: ../src/guestfs-actions.pod:462 ../src/guestfs-actions.pod:544
4588 #: ../fish/guestfish-actions.pod:382 ../fish/guestfish-actions.pod:445
4590 "(Note this is different from both I<size in blocks> and I<filesystem block "
4595 #: ../src/guestfs-actions.pod:469
4596 msgid "guestfs_blockdev_getro"
4600 #: ../src/guestfs-actions.pod:471
4603 " int guestfs_blockdev_getro (guestfs_h *g,\n"
4604 "\t\tconst char *device);\n"
4609 #: ../src/guestfs-actions.pod:474 ../fish/guestfish-actions.pod:391
4611 "Returns a boolean indicating if the block device is read-only (true if read-"
4612 "only, false if not)."
4616 #: ../src/guestfs-actions.pod:479 ../src/guestfs-actions.pod:1115
4617 #: ../src/guestfs-actions.pod:1127 ../src/guestfs-actions.pod:1559
4618 #: ../src/guestfs-actions.pod:1567 ../src/guestfs-actions.pod:1627
4619 #: ../src/guestfs-actions.pod:1670 ../src/guestfs-actions.pod:1682
4620 #: ../src/guestfs-actions.pod:1701 ../src/guestfs-actions.pod:1718
4621 #: ../src/guestfs-actions.pod:2303 ../src/guestfs-actions.pod:2314
4622 #: ../src/guestfs-actions.pod:2326 ../src/guestfs-actions.pod:2337
4623 #: ../src/guestfs-actions.pod:2350 ../src/guestfs-actions.pod:2362
4624 #: ../src/guestfs-actions.pod:2375 ../src/guestfs-actions.pod:2386
4625 #: ../src/guestfs-actions.pod:2396 ../src/guestfs-actions.pod:2407
4626 #: ../src/guestfs-actions.pod:2419 ../src/guestfs-actions.pod:2431
4627 #: ../src/guestfs-actions.pod:3595
4628 msgid "This function returns a C truth value on success or -1 on error."
4632 #: ../src/guestfs-actions.pod:481
4633 msgid "guestfs_blockdev_getsize64"
4637 #: ../src/guestfs-actions.pod:483
4640 " int64_t guestfs_blockdev_getsize64 (guestfs_h *g,\n"
4641 "\t\tconst char *device);\n"
4646 #: ../src/guestfs-actions.pod:486 ../fish/guestfish-actions.pod:400
4647 msgid "This returns the size of the device in bytes."
4651 #: ../src/guestfs-actions.pod:488
4652 msgid "See also C<guestfs_blockdev_getsz>."
4656 #: ../src/guestfs-actions.pod:494
4657 msgid "guestfs_blockdev_getss"
4661 #: ../src/guestfs-actions.pod:496
4664 " int guestfs_blockdev_getss (guestfs_h *g,\n"
4665 "\t\tconst char *device);\n"
4670 #: ../src/guestfs-actions.pod:499 ../fish/guestfish-actions.pod:410
4672 "This returns the size of sectors on a block device. Usually 512, but can be "
4673 "larger for modern devices."
4677 #: ../src/guestfs-actions.pod:502
4679 "(Note, this is not the size in sectors, use C<guestfs_blockdev_getsz> for "
4684 #: ../src/guestfs-actions.pod:509
4685 msgid "guestfs_blockdev_getsz"
4689 #: ../src/guestfs-actions.pod:511
4692 " int64_t guestfs_blockdev_getsz (guestfs_h *g,\n"
4693 "\t\tconst char *device);\n"
4698 #: ../src/guestfs-actions.pod:514 ../fish/guestfish-actions.pod:422
4700 "This returns the size of the device in units of 512-byte sectors (even if "
4701 "the sectorsize isn't 512 bytes ... weird)."
4705 #: ../src/guestfs-actions.pod:517
4707 "See also C<guestfs_blockdev_getss> for the real sector size of the device, "
4708 "and C<guestfs_blockdev_getsize64> for the more useful I<size in bytes>."
4712 #: ../src/guestfs-actions.pod:525
4713 msgid "guestfs_blockdev_rereadpt"
4717 #: ../src/guestfs-actions.pod:527
4720 " int guestfs_blockdev_rereadpt (guestfs_h *g,\n"
4721 "\t\tconst char *device);\n"
4726 #: ../src/guestfs-actions.pod:530 ../fish/guestfish-actions.pod:435
4727 msgid "Reread the partition table on C<device>."
4731 #: ../src/guestfs-actions.pod:536
4732 msgid "guestfs_blockdev_setbsz"
4736 #: ../src/guestfs-actions.pod:538
4739 " int guestfs_blockdev_setbsz (guestfs_h *g,\n"
4740 "\t\tconst char *device,\n"
4741 "\t\tint blocksize);\n"
4746 #: ../src/guestfs-actions.pod:542 ../fish/guestfish-actions.pod:443
4747 msgid "This sets the block size of a device."
4751 #: ../src/guestfs-actions.pod:551
4752 msgid "guestfs_blockdev_setro"
4756 #: ../src/guestfs-actions.pod:553
4759 " int guestfs_blockdev_setro (guestfs_h *g,\n"
4760 "\t\tconst char *device);\n"
4765 #: ../src/guestfs-actions.pod:556 ../fish/guestfish-actions.pod:454
4766 msgid "Sets the block device named C<device> to read-only."
4770 #: ../src/guestfs-actions.pod:562
4771 msgid "guestfs_blockdev_setrw"
4775 #: ../src/guestfs-actions.pod:564
4778 " int guestfs_blockdev_setrw (guestfs_h *g,\n"
4779 "\t\tconst char *device);\n"
4784 #: ../src/guestfs-actions.pod:567 ../fish/guestfish-actions.pod:462
4785 msgid "Sets the block device named C<device> to read-write."
4789 #: ../src/guestfs-actions.pod:573
4790 msgid "guestfs_case_sensitive_path"
4794 #: ../src/guestfs-actions.pod:575
4797 " char *guestfs_case_sensitive_path (guestfs_h *g,\n"
4798 "\t\tconst char *path);\n"
4803 #: ../src/guestfs-actions.pod:578 ../fish/guestfish-actions.pod:470
4805 "This can be used to resolve case insensitive paths on a filesystem which is "
4806 "case sensitive. The use case is to resolve paths which you have read from "
4807 "Windows configuration files or the Windows Registry, to the true path."
4811 #: ../src/guestfs-actions.pod:583 ../fish/guestfish-actions.pod:475
4813 "The command handles a peculiarity of the Linux ntfs-3g filesystem driver "
4814 "(and probably others), which is that although the underlying filesystem is "
4815 "case-insensitive, the driver exports the filesystem to Linux as case-"
4820 #: ../src/guestfs-actions.pod:588 ../fish/guestfish-actions.pod:480
4822 "One consequence of this is that special directories such as C<c:\\windows> "
4823 "may appear as C</WINDOWS> or C</windows> (or other things) depending on the "
4824 "precise details of how they were created. In Windows itself this would not "
4829 #: ../src/guestfs-actions.pod:594 ../fish/guestfish-actions.pod:486
4831 "Bug or feature? You decide: L<http://www.tuxera.com/community/ntfs-3g-faq/"
4836 #: ../src/guestfs-actions.pod:597 ../fish/guestfish-actions.pod:489
4838 "This function resolves the true case of each element in the path and returns "
4839 "the case-sensitive path."
4843 #: ../src/guestfs-actions.pod:600
4845 "Thus C<guestfs_case_sensitive_path> (\"/Windows/System32\") might return C<"
4846 "\"/WINDOWS/system32\"> (the exact return value would depend on details of "
4847 "how the directories were originally created under Windows)."
4851 #: ../src/guestfs-actions.pod:605 ../fish/guestfish-actions.pod:497
4852 msgid "I<Note>: This function does not handle drive names, backslashes etc."
4856 #: ../src/guestfs-actions.pod:608
4857 msgid "See also C<guestfs_realpath>."
4861 #: ../src/guestfs-actions.pod:613
4866 #: ../src/guestfs-actions.pod:615
4869 " char *guestfs_cat (guestfs_h *g,\n"
4870 "\t\tconst char *path);\n"
4875 #: ../src/guestfs-actions.pod:618 ../src/guestfs-actions.pod:3995
4876 #: ../fish/guestfish-actions.pod:506 ../fish/guestfish-actions.pod:3085
4877 msgid "Return the contents of the file named C<path>."
4881 #: ../src/guestfs-actions.pod:620
4883 "Note that this function cannot correctly handle binary files (specifically, "
4884 "files containing C<\\0> character which is treated as end of string). For "
4885 "those you need to use the C<guestfs_read_file> or C<guestfs_download> "
4886 "functions which have a more complex interface."
4890 #: ../src/guestfs-actions.pod:628 ../src/guestfs-actions.pod:789
4891 #: ../src/guestfs-actions.pod:806 ../src/guestfs-actions.pod:1085
4892 #: ../src/guestfs-actions.pod:1101 ../src/guestfs-actions.pod:1189
4893 #: ../src/guestfs-actions.pod:1205 ../src/guestfs-actions.pod:1436
4894 #: ../src/guestfs-actions.pod:1783 ../src/guestfs-actions.pod:1799
4895 #: ../src/guestfs-actions.pod:1836 ../src/guestfs-actions.pod:1857
4896 #: ../src/guestfs-actions.pod:1871 ../src/guestfs-actions.pod:1897
4897 #: ../src/guestfs-actions.pod:3835 ../src/guestfs-actions.pod:3943
4898 #: ../src/guestfs-actions.pod:3966 ../src/guestfs-actions.pod:3987
4899 #: ../src/guestfs-actions.pod:4713 ../src/guestfs-actions.pod:4765
4900 #: ../src/guestfs-actions.pod:4881 ../src/guestfs-actions.pod:4902
4901 #: ../src/guestfs-actions.pod:5447 ../src/guestfs-actions.pod:5470
4902 #: ../src/guestfs-actions.pod:5493 ../src/guestfs-actions.pod:5509
4903 #: ../src/guestfs-actions.pod:5582 ../src/guestfs-actions.pod:5598
4904 #: ../src/guestfs-actions.pod:5638 ../src/guestfs-actions.pod:5654
4905 #: ../fish/guestfish-actions.pod:513 ../fish/guestfish-actions.pod:648
4906 #: ../fish/guestfish-actions.pod:660 ../fish/guestfish-actions.pod:861
4907 #: ../fish/guestfish-actions.pod:871 ../fish/guestfish-actions.pod:938
4908 #: ../fish/guestfish-actions.pod:948 ../fish/guestfish-actions.pod:1143
4909 #: ../fish/guestfish-actions.pod:1418 ../fish/guestfish-actions.pod:1428
4910 #: ../fish/guestfish-actions.pod:1456 ../fish/guestfish-actions.pod:1471
4911 #: ../fish/guestfish-actions.pod:1481 ../fish/guestfish-actions.pod:1500
4912 #: ../fish/guestfish-actions.pod:2970 ../fish/guestfish-actions.pod:3046
4913 #: ../fish/guestfish-actions.pod:3063 ../fish/guestfish-actions.pod:3078
4914 #: ../fish/guestfish-actions.pod:3661 ../fish/guestfish-actions.pod:3707
4915 #: ../fish/guestfish-actions.pod:3792 ../fish/guestfish-actions.pod:3807
4916 #: ../fish/guestfish-actions.pod:4217 ../fish/guestfish-actions.pod:4235
4917 #: ../fish/guestfish-actions.pod:4252 ../fish/guestfish-actions.pod:4262
4918 #: ../fish/guestfish-actions.pod:4310 ../fish/guestfish-actions.pod:4320
4919 #: ../fish/guestfish-actions.pod:4349 ../fish/guestfish-actions.pod:4359
4921 "Because of the message protocol, there is a transfer limit of somewhere "
4922 "between 2MB and 4MB. See L<guestfs(3)/PROTOCOL LIMITS>."
4926 #: ../src/guestfs-actions.pod:631
4927 msgid "guestfs_checksum"
4931 #: ../src/guestfs-actions.pod:633
4934 " char *guestfs_checksum (guestfs_h *g,\n"
4935 "\t\tconst char *csumtype,\n"
4936 "\t\tconst char *path);\n"
4941 #: ../src/guestfs-actions.pod:637 ../fish/guestfish-actions.pod:520
4943 "This call computes the MD5, SHAx or CRC checksum of the file named C<path>."
4947 #: ../src/guestfs-actions.pod:640 ../fish/guestfish-actions.pod:523
4949 "The type of checksum to compute is given by the C<csumtype> parameter which "
4950 "must have one of the following values:"
4954 #: ../src/guestfs-actions.pod:645 ../fish/guestfish-actions.pod:528
4959 #: ../src/guestfs-actions.pod:647 ../fish/guestfish-actions.pod:530
4961 "Compute the cyclic redundancy check (CRC) specified by POSIX for the "
4966 #: ../src/guestfs-actions.pod:650 ../fish/guestfish-actions.pod:533
4971 #: ../src/guestfs-actions.pod:652 ../fish/guestfish-actions.pod:535
4972 msgid "Compute the MD5 hash (using the C<md5sum> program)."
4976 #: ../src/guestfs-actions.pod:654 ../fish/guestfish-actions.pod:537
4981 #: ../src/guestfs-actions.pod:656 ../fish/guestfish-actions.pod:539
4982 msgid "Compute the SHA1 hash (using the C<sha1sum> program)."
4986 #: ../src/guestfs-actions.pod:658 ../fish/guestfish-actions.pod:541
4991 #: ../src/guestfs-actions.pod:660 ../fish/guestfish-actions.pod:543
4992 msgid "Compute the SHA224 hash (using the C<sha224sum> program)."
4996 #: ../src/guestfs-actions.pod:662 ../fish/guestfish-actions.pod:545
5001 #: ../src/guestfs-actions.pod:664 ../fish/guestfish-actions.pod:547
5002 msgid "Compute the SHA256 hash (using the C<sha256sum> program)."
5006 #: ../src/guestfs-actions.pod:666 ../fish/guestfish-actions.pod:549
5011 #: ../src/guestfs-actions.pod:668 ../fish/guestfish-actions.pod:551
5012 msgid "Compute the SHA384 hash (using the C<sha384sum> program)."
5016 #: ../src/guestfs-actions.pod:670 ../fish/guestfish-actions.pod:553
5021 #: ../src/guestfs-actions.pod:672 ../fish/guestfish-actions.pod:555
5022 msgid "Compute the SHA512 hash (using the C<sha512sum> program)."
5026 #: ../src/guestfs-actions.pod:676 ../fish/guestfish-actions.pod:559
5027 msgid "The checksum is returned as a printable string."
5031 #: ../src/guestfs-actions.pod:678
5032 msgid "To get the checksum for a device, use C<guestfs_checksum_device>."
5036 #: ../src/guestfs-actions.pod:680
5037 msgid "To get the checksums for many files, use C<guestfs_checksums_out>."
5041 #: ../src/guestfs-actions.pod:685
5042 msgid "guestfs_checksum_device"
5046 #: ../src/guestfs-actions.pod:687
5049 " char *guestfs_checksum_device (guestfs_h *g,\n"
5050 "\t\tconst char *csumtype,\n"
5051 "\t\tconst char *device);\n"
5056 #: ../src/guestfs-actions.pod:691
5058 "This call computes the MD5, SHAx or CRC checksum of the contents of the "
5059 "device named C<device>. For the types of checksums supported see the "
5060 "C<guestfs_checksum> command."
5064 #: ../src/guestfs-actions.pod:698
5065 msgid "guestfs_checksums_out"
5069 #: ../src/guestfs-actions.pod:700
5072 " int guestfs_checksums_out (guestfs_h *g,\n"
5073 "\t\tconst char *csumtype,\n"
5074 "\t\tconst char *directory,\n"
5075 "\t\tconst char *sumsfile);\n"
5080 #: ../src/guestfs-actions.pod:705 ../fish/guestfish-actions.pod:577
5082 "This command computes the checksums of all regular files in C<directory> and "
5083 "then emits a list of those checksums to the local output file C<sumsfile>."
5087 #: ../src/guestfs-actions.pod:709 ../fish/guestfish-actions.pod:581
5089 "This can be used for verifying the integrity of a virtual machine. However "
5090 "to be properly secure you should pay attention to the output of the checksum "
5091 "command (it uses the ones from GNU coreutils). In particular when the "
5092 "filename is not printable, coreutils uses a special backslash syntax. For "
5093 "more information, see the GNU coreutils info file."
5097 #: ../src/guestfs-actions.pod:719
5098 msgid "guestfs_chmod"
5102 #: ../src/guestfs-actions.pod:721
5105 " int guestfs_chmod (guestfs_h *g,\n"
5107 "\t\tconst char *path);\n"
5112 #: ../src/guestfs-actions.pod:725 ../fish/guestfish-actions.pod:595
5114 "Change the mode (permissions) of C<path> to C<mode>. Only numeric modes are "
5119 #: ../src/guestfs-actions.pod:728 ../fish/guestfish-actions.pod:598
5121 "I<Note>: When using this command from guestfish, C<mode> by default would be "
5122 "decimal, unless you prefix it with C<0> to get octal, ie. use C<0700> not "
5127 #: ../src/guestfs-actions.pod:732 ../src/guestfs-actions.pod:3178
5128 #: ../src/guestfs-actions.pod:3266 ../src/guestfs-actions.pod:3282
5129 #: ../src/guestfs-actions.pod:3298 ../fish/guestfish-actions.pod:602
5130 #: ../fish/guestfish-actions.pod:2475 ../fish/guestfish-actions.pod:2545
5131 #: ../fish/guestfish-actions.pod:2555 ../fish/guestfish-actions.pod:2565
5132 msgid "The mode actually set is affected by the umask."
5136 #: ../src/guestfs-actions.pod:736
5137 msgid "guestfs_chown"
5141 #: ../src/guestfs-actions.pod:738
5144 " int guestfs_chown (guestfs_h *g,\n"
5147 "\t\tconst char *path);\n"
5152 #: ../src/guestfs-actions.pod:743 ../fish/guestfish-actions.pod:608
5153 msgid "Change the file owner to C<owner> and group to C<group>."
5157 #: ../src/guestfs-actions.pod:745 ../src/guestfs-actions.pod:2464
5158 #: ../fish/guestfish-actions.pod:610 ../fish/guestfish-actions.pod:1966
5160 "Only numeric uid and gid are supported. If you want to use names, you will "
5161 "need to locate and parse the password file yourself (Augeas support makes "
5162 "this relatively easy)."
5166 #: ../src/guestfs-actions.pod:751
5167 msgid "guestfs_command"
5171 #: ../src/guestfs-actions.pod:753
5174 " char *guestfs_command (guestfs_h *g,\n"
5175 "\t\tchar *const *arguments);\n"
5180 #: ../src/guestfs-actions.pod:756 ../fish/guestfish-actions.pod:618
5182 "This call runs a command from the guest filesystem. The filesystem must be "
5183 "mounted, and must contain a compatible operating system (ie. something "
5184 "Linux, with the same or compatible processor architecture)."
5188 #: ../src/guestfs-actions.pod:761
5190 "The single parameter is an argv-style list of arguments. The first element "
5191 "is the name of the program to run. Subsequent elements are parameters. The "
5192 "list must be non-empty (ie. must contain a program name). Note that the "
5193 "command runs directly, and is I<not> invoked via the shell (see "
5198 #: ../src/guestfs-actions.pod:768 ../fish/guestfish-actions.pod:630
5199 msgid "The return value is anything printed to I<stdout> by the command."
5203 #: ../src/guestfs-actions.pod:771 ../fish/guestfish-actions.pod:633
5205 "If the command returns a non-zero exit status, then this function returns an "
5206 "error message. The error message string is the content of I<stderr> from "
5211 #: ../src/guestfs-actions.pod:775 ../fish/guestfish-actions.pod:637
5213 "The C<$PATH> environment variable will contain at least C</usr/bin> and C</"
5214 "bin>. If you require a program from another location, you should provide "
5215 "the full path in the first parameter."
5219 #: ../src/guestfs-actions.pod:780 ../fish/guestfish-actions.pod:642
5221 "Shared libraries and data files required by the program must be available on "
5222 "filesystems which are mounted in the correct places. It is the caller's "
5223 "responsibility to ensure all filesystems that are needed are mounted at the "
5228 #: ../src/guestfs-actions.pod:792
5229 msgid "guestfs_command_lines"
5233 #: ../src/guestfs-actions.pod:794
5236 " char **guestfs_command_lines (guestfs_h *g,\n"
5237 "\t\tchar *const *arguments);\n"
5242 #: ../src/guestfs-actions.pod:797
5244 "This is the same as C<guestfs_command>, but splits the result into a list of "
5249 #: ../src/guestfs-actions.pod:800
5250 msgid "See also: C<guestfs_sh_lines>"
5254 #: ../src/guestfs-actions.pod:809
5255 msgid "guestfs_config"
5259 #: ../src/guestfs-actions.pod:811
5262 " int guestfs_config (guestfs_h *g,\n"
5263 "\t\tconst char *qemuparam,\n"
5264 "\t\tconst char *qemuvalue);\n"
5269 #: ../src/guestfs-actions.pod:815 ../fish/guestfish-actions.pod:667
5271 "This can be used to add arbitrary qemu command line parameters of the form "
5272 "C<-param value>. Actually it's not quite arbitrary - we prevent you from "
5273 "setting some parameters which would interfere with parameters that we use."
5277 #: ../src/guestfs-actions.pod:820 ../fish/guestfish-actions.pod:672
5278 msgid "The first character of C<param> string must be a C<-> (dash)."
5282 #: ../src/guestfs-actions.pod:822 ../fish/guestfish-actions.pod:674
5283 msgid "C<value> can be NULL."
5287 #: ../src/guestfs-actions.pod:826
5288 msgid "guestfs_copy_size"
5292 #: ../src/guestfs-actions.pod:828
5295 " int guestfs_copy_size (guestfs_h *g,\n"
5296 "\t\tconst char *src,\n"
5297 "\t\tconst char *dest,\n"
5298 "\t\tint64_t size);\n"
5303 #: ../src/guestfs-actions.pod:833 ../fish/guestfish-actions.pod:680
5305 "This command copies exactly C<size> bytes from one source device or file "
5306 "C<src> to another destination device or file C<dest>."
5310 #: ../src/guestfs-actions.pod:836 ../fish/guestfish-actions.pod:683
5312 "Note this will fail if the source is too short or if the destination is not "
5317 #: ../src/guestfs-actions.pod:841 ../src/guestfs-actions.pod:976
5318 #: ../src/guestfs-actions.pod:1004 ../src/guestfs-actions.pod:1376
5319 #: ../src/guestfs-actions.pod:1395 ../src/guestfs-actions.pod:5527
5320 #: ../src/guestfs-actions.pod:5543
5322 "This long-running command can generate progress notification messages so "
5323 "that the caller can display a progress bar or indicator. To receive these "
5324 "messages, the caller must register a progress callback. See L<guestfs(3)/"
5325 "guestfs_set_progress_callback>."
5329 #: ../src/guestfs-actions.pod:846
5334 #: ../src/guestfs-actions.pod:848
5337 " int guestfs_cp (guestfs_h *g,\n"
5338 "\t\tconst char *src,\n"
5339 "\t\tconst char *dest);\n"
5344 #: ../src/guestfs-actions.pod:852 ../fish/guestfish-actions.pod:690
5346 "This copies a file from C<src> to C<dest> where C<dest> is either a "
5347 "destination filename or destination directory."
5351 #: ../src/guestfs-actions.pod:857
5352 msgid "guestfs_cp_a"
5356 #: ../src/guestfs-actions.pod:859
5359 " int guestfs_cp_a (guestfs_h *g,\n"
5360 "\t\tconst char *src,\n"
5361 "\t\tconst char *dest);\n"
5366 #: ../src/guestfs-actions.pod:863 ../fish/guestfish-actions.pod:697
5368 "This copies a file or directory from C<src> to C<dest> recursively using the "
5373 #: ../src/guestfs-actions.pod:868
5378 #: ../src/guestfs-actions.pod:870
5381 " int guestfs_dd (guestfs_h *g,\n"
5382 "\t\tconst char *src,\n"
5383 "\t\tconst char *dest);\n"
5388 #: ../src/guestfs-actions.pod:874 ../fish/guestfish-actions.pod:704
5390 "This command copies from one source device or file C<src> to another "
5391 "destination device or file C<dest>. Normally you would use this to copy to "
5392 "or from a device or partition, for example to duplicate a filesystem."
5396 #: ../src/guestfs-actions.pod:879
5398 "If the destination is a device, it must be as large or larger than the "
5399 "source file or device, otherwise the copy will fail. This command cannot do "
5400 "partial copies (see C<guestfs_copy_size>)."
5404 #: ../src/guestfs-actions.pod:885
5405 msgid "guestfs_debug"
5409 #: ../src/guestfs-actions.pod:887
5412 " char *guestfs_debug (guestfs_h *g,\n"
5413 "\t\tconst char *subcmd,\n"
5414 "\t\tchar *const *extraargs);\n"
5419 #: ../src/guestfs-actions.pod:891
5421 "The C<guestfs_debug> command exposes some internals of C<guestfsd> (the "
5422 "guestfs daemon) that runs inside the qemu subprocess."
5426 #: ../src/guestfs-actions.pod:895 ../fish/guestfish-actions.pod:721
5428 "There is no comprehensive help for this command. You have to look at the "
5429 "file C<daemon/debug.c> in the libguestfs source to find out what you can do."
5433 #: ../src/guestfs-actions.pod:902
5434 msgid "guestfs_debug_upload"
5438 #: ../src/guestfs-actions.pod:904
5441 " int guestfs_debug_upload (guestfs_h *g,\n"
5442 "\t\tconst char *filename,\n"
5443 "\t\tconst char *tmpname,\n"
5449 #: ../src/guestfs-actions.pod:909
5451 "The C<guestfs_debug_upload> command uploads a file to the libguestfs "
5456 #: ../src/guestfs-actions.pod:912 ../fish/guestfish-actions.pod:732
5458 "There is no comprehensive help for this command. You have to look at the "
5459 "file C<daemon/debug.c> in the libguestfs source to find out what it is for."
5463 #: ../src/guestfs-actions.pod:918
5468 #: ../src/guestfs-actions.pod:920
5471 " char *guestfs_df (guestfs_h *g);\n"
5476 #: ../src/guestfs-actions.pod:922 ../fish/guestfish-actions.pod:742
5477 msgid "This command runs the C<df> command to report disk space used."
5481 #: ../src/guestfs-actions.pod:924 ../src/guestfs-actions.pod:938
5482 #: ../fish/guestfish-actions.pod:744 ../fish/guestfish-actions.pod:755
5484 "This command is mostly useful for interactive sessions. It is I<not> "
5485 "intended that you try to parse the output string. Use C<statvfs> from "
5490 #: ../src/guestfs-actions.pod:931
5491 msgid "guestfs_df_h"
5495 #: ../src/guestfs-actions.pod:933
5498 " char *guestfs_df_h (guestfs_h *g);\n"
5503 #: ../src/guestfs-actions.pod:935 ../fish/guestfish-actions.pod:752
5505 "This command runs the C<df -h> command to report disk space used in human-"
5510 #: ../src/guestfs-actions.pod:945
5511 msgid "guestfs_dmesg"
5515 #: ../src/guestfs-actions.pod:947
5518 " char *guestfs_dmesg (guestfs_h *g);\n"
5523 #: ../src/guestfs-actions.pod:949 ../fish/guestfish-actions.pod:763
5525 "This returns the kernel messages (C<dmesg> output) from the guest kernel. "
5526 "This is sometimes useful for extended debugging of problems."
5530 #: ../src/guestfs-actions.pod:953
5532 "Another way to get the same information is to enable verbose messages with "
5533 "C<guestfs_set_verbose> or by setting the environment variable "
5534 "C<LIBGUESTFS_DEBUG=1> before running the program."
5538 #: ../src/guestfs-actions.pod:961
5539 msgid "guestfs_download"
5543 #: ../src/guestfs-actions.pod:963
5546 " int guestfs_download (guestfs_h *g,\n"
5547 "\t\tconst char *remotefilename,\n"
5548 "\t\tconst char *filename);\n"
5553 #: ../src/guestfs-actions.pod:967 ../src/guestfs-actions.pod:989
5554 #: ../fish/guestfish-actions.pod:776 ../fish/guestfish-actions.pod:789
5556 "Download file C<remotefilename> and save it as C<filename> on the local "
5561 #: ../src/guestfs-actions.pod:970 ../src/guestfs-actions.pod:5095
5562 #: ../fish/guestfish-actions.pod:779 ../fish/guestfish-actions.pod:3965
5563 msgid "C<filename> can also be a named pipe."
5567 #: ../src/guestfs-actions.pod:972
5568 msgid "See also C<guestfs_upload>, C<guestfs_cat>."
5572 #: ../src/guestfs-actions.pod:981
5573 msgid "guestfs_download_offset"
5577 #: ../src/guestfs-actions.pod:983
5580 " int guestfs_download_offset (guestfs_h *g,\n"
5581 "\t\tconst char *remotefilename,\n"
5582 "\t\tconst char *filename,\n"
5583 "\t\tint64_t offset,\n"
5584 "\t\tint64_t size);\n"
5589 #: ../src/guestfs-actions.pod:992 ../fish/guestfish-actions.pod:792
5591 "C<remotefilename> is read for C<size> bytes starting at C<offset> (this "
5592 "region must be within the file or device)."
5596 #: ../src/guestfs-actions.pod:995
5598 "Note that there is no limit on the amount of data that can be downloaded "
5599 "with this call, unlike with C<guestfs_pread>, and this call always reads the "
5600 "full amount unless an error occurs."
5604 #: ../src/guestfs-actions.pod:1000
5605 msgid "See also C<guestfs_download>, C<guestfs_pread>."
5609 #: ../src/guestfs-actions.pod:1009
5610 msgid "guestfs_drop_caches"
5614 #: ../src/guestfs-actions.pod:1011
5617 " int guestfs_drop_caches (guestfs_h *g,\n"
5618 "\t\tint whattodrop);\n"
5623 #: ../src/guestfs-actions.pod:1014 ../fish/guestfish-actions.pod:808
5625 "This instructs the guest kernel to drop its page cache, and/or dentries and "
5626 "inode caches. The parameter C<whattodrop> tells the kernel what precisely "
5627 "to drop, see L<http://linux-mm.org/Drop_Caches>"
5631 #: ../src/guestfs-actions.pod:1019 ../fish/guestfish-actions.pod:813
5632 msgid "Setting C<whattodrop> to 3 should drop everything."
5636 #: ../src/guestfs-actions.pod:1021 ../fish/guestfish-actions.pod:815
5638 "This automatically calls L<sync(2)> before the operation, so that the "
5639 "maximum guest memory is freed."
5643 #: ../src/guestfs-actions.pod:1026
5648 #: ../src/guestfs-actions.pod:1028
5651 " int64_t guestfs_du (guestfs_h *g,\n"
5652 "\t\tconst char *path);\n"
5657 #: ../src/guestfs-actions.pod:1031 ../fish/guestfish-actions.pod:822
5659 "This command runs the C<du -s> command to estimate file space usage for "
5664 #: ../src/guestfs-actions.pod:1034 ../fish/guestfish-actions.pod:825
5666 "C<path> can be a file or a directory. If C<path> is a directory then the "
5667 "estimate includes the contents of the directory and all subdirectories "
5672 #: ../src/guestfs-actions.pod:1038 ../fish/guestfish-actions.pod:829
5674 "The result is the estimated size in I<kilobytes> (ie. units of 1024 bytes)."
5678 #: ../src/guestfs-actions.pod:1043
5679 msgid "guestfs_e2fsck_f"
5683 #: ../src/guestfs-actions.pod:1045
5686 " int guestfs_e2fsck_f (guestfs_h *g,\n"
5687 "\t\tconst char *device);\n"
5692 #: ../src/guestfs-actions.pod:1048 ../fish/guestfish-actions.pod:836
5694 "This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3 filesystem checker "
5695 "on C<device>, noninteractively (C<-p>), even if the filesystem appears to be "
5700 #: ../src/guestfs-actions.pod:1052
5702 "This command is only needed because of C<guestfs_resize2fs> (q.v.). "
5703 "Normally you should use C<guestfs_fsck>."
5707 #: ../src/guestfs-actions.pod:1057
5708 msgid "guestfs_echo_daemon"
5712 #: ../src/guestfs-actions.pod:1059
5715 " char *guestfs_echo_daemon (guestfs_h *g,\n"
5716 "\t\tchar *const *words);\n"
5721 #: ../src/guestfs-actions.pod:1062 ../fish/guestfish-actions.pod:847
5723 "This command concatenates the list of C<words> passed with single spaces "
5724 "between them and returns the resulting string."
5728 #: ../src/guestfs-actions.pod:1065 ../fish/guestfish-actions.pod:850
5729 msgid "You can use this command to test the connection through to the daemon."
5733 #: ../src/guestfs-actions.pod:1067
5734 msgid "See also C<guestfs_ping_daemon>."
5738 #: ../src/guestfs-actions.pod:1072
5739 msgid "guestfs_egrep"
5743 #: ../src/guestfs-actions.pod:1074
5746 " char **guestfs_egrep (guestfs_h *g,\n"
5747 "\t\tconst char *regex,\n"
5748 "\t\tconst char *path);\n"
5753 #: ../src/guestfs-actions.pod:1078 ../fish/guestfish-actions.pod:858
5755 "This calls the external C<egrep> program and returns the matching lines."
5759 #: ../src/guestfs-actions.pod:1088
5760 msgid "guestfs_egrepi"
5764 #: ../src/guestfs-actions.pod:1090
5767 " char **guestfs_egrepi (guestfs_h *g,\n"
5768 "\t\tconst char *regex,\n"
5769 "\t\tconst char *path);\n"
5774 #: ../src/guestfs-actions.pod:1094 ../fish/guestfish-actions.pod:868
5776 "This calls the external C<egrep -i> program and returns the matching lines."
5780 #: ../src/guestfs-actions.pod:1104
5781 msgid "guestfs_equal"
5785 #: ../src/guestfs-actions.pod:1106
5788 " int guestfs_equal (guestfs_h *g,\n"
5789 "\t\tconst char *file1,\n"
5790 "\t\tconst char *file2);\n"
5795 #: ../src/guestfs-actions.pod:1110 ../fish/guestfish-actions.pod:878
5797 "This compares the two files C<file1> and C<file2> and returns true if their "
5798 "content is exactly equal, or false otherwise."
5802 #: ../src/guestfs-actions.pod:1113 ../fish/guestfish-actions.pod:881
5803 msgid "The external L<cmp(1)> program is used for the comparison."
5807 #: ../src/guestfs-actions.pod:1117
5808 msgid "guestfs_exists"
5812 #: ../src/guestfs-actions.pod:1119
5815 " int guestfs_exists (guestfs_h *g,\n"
5816 "\t\tconst char *path);\n"
5821 #: ../src/guestfs-actions.pod:1122 ../fish/guestfish-actions.pod:887
5823 "This returns C<true> if and only if there is a file, directory (or anything) "
5824 "with the given C<path> name."
5828 #: ../src/guestfs-actions.pod:1125
5829 msgid "See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>."
5833 #: ../src/guestfs-actions.pod:1129
5834 msgid "guestfs_fallocate"
5838 #: ../src/guestfs-actions.pod:1131
5841 " int guestfs_fallocate (guestfs_h *g,\n"
5842 "\t\tconst char *path,\n"
5848 #: ../src/guestfs-actions.pod:1135 ../src/guestfs-actions.pod:1158
5849 #: ../fish/guestfish-actions.pod:896 ../fish/guestfish-actions.pod:915
5851 "This command preallocates a file (containing zero bytes) named C<path> of "
5852 "size C<len> bytes. If the file exists already, it is overwritten."
5856 #: ../src/guestfs-actions.pod:1139 ../fish/guestfish-actions.pod:900
5858 "Do not confuse this with the guestfish-specific C<alloc> command which "
5859 "allocates a file in the host and attaches it as a device."
5863 #: ../src/guestfs-actions.pod:1145 ../fish/guestfish-actions.pod:904
5865 "This function is deprecated. In new code, use the C<fallocate64> call "
5870 #: ../src/guestfs-actions.pod:1148 ../src/guestfs-actions.pod:1583
5871 #: ../src/guestfs-actions.pod:1601 ../src/guestfs-actions.pod:5476
5872 #: ../src/guestfs-actions.pod:5621 ../fish/guestfish-actions.pod:907
5873 #: ../fish/guestfish-actions.pod:1264 ../fish/guestfish-actions.pod:1278
5874 #: ../fish/guestfish-actions.pod:4241 ../fish/guestfish-actions.pod:4338
5876 "Deprecated functions will not be removed from the API, but the fact that "
5877 "they are deprecated indicates that there are problems with correct use of "
5882 #: ../src/guestfs-actions.pod:1152
5883 msgid "guestfs_fallocate64"
5887 #: ../src/guestfs-actions.pod:1154
5890 " int guestfs_fallocate64 (guestfs_h *g,\n"
5891 "\t\tconst char *path,\n"
5892 "\t\tint64_t len);\n"
5897 #: ../src/guestfs-actions.pod:1162
5899 "Note that this call allocates disk blocks for the file. To create a sparse "
5900 "file use C<guestfs_truncate_size> instead."
5904 #: ../src/guestfs-actions.pod:1165
5906 "The deprecated call C<guestfs_fallocate> does the same, but owing to an "
5907 "oversight it only allowed 30 bit lengths to be specified, effectively "
5908 "limiting the maximum size of files created through that call to 1GB."
5912 #: ../src/guestfs-actions.pod:1170 ../fish/guestfish-actions.pod:927
5914 "Do not confuse this with the guestfish-specific C<alloc> and C<sparse> "
5915 "commands which create a file in the host and attach it as a device."
5919 #: ../src/guestfs-actions.pod:1176
5920 msgid "guestfs_fgrep"
5924 #: ../src/guestfs-actions.pod:1178
5927 " char **guestfs_fgrep (guestfs_h *g,\n"
5928 "\t\tconst char *pattern,\n"
5929 "\t\tconst char *path);\n"
5934 #: ../src/guestfs-actions.pod:1182 ../fish/guestfish-actions.pod:935
5936 "This calls the external C<fgrep> program and returns the matching lines."
5940 #: ../src/guestfs-actions.pod:1192
5941 msgid "guestfs_fgrepi"
5945 #: ../src/guestfs-actions.pod:1194
5948 " char **guestfs_fgrepi (guestfs_h *g,\n"
5949 "\t\tconst char *pattern,\n"
5950 "\t\tconst char *path);\n"
5955 #: ../src/guestfs-actions.pod:1198 ../fish/guestfish-actions.pod:945
5957 "This calls the external C<fgrep -i> program and returns the matching lines."
5961 #: ../src/guestfs-actions.pod:1208
5962 msgid "guestfs_file"
5966 #: ../src/guestfs-actions.pod:1210
5969 " char *guestfs_file (guestfs_h *g,\n"
5970 "\t\tconst char *path);\n"
5975 #: ../src/guestfs-actions.pod:1213 ../fish/guestfish-actions.pod:955
5977 "This call uses the standard L<file(1)> command to determine the type or "
5978 "contents of the file."
5982 #: ../src/guestfs-actions.pod:1216 ../fish/guestfish-actions.pod:958
5984 "This call will also transparently look inside various types of compressed "
5989 #: ../src/guestfs-actions.pod:1219 ../fish/guestfish-actions.pod:961
5991 "The exact command which runs is C<file -zb path>. Note in particular that "
5992 "the filename is not prepended to the output (the C<-b> option)."
5996 #: ../src/guestfs-actions.pod:1223
5998 "This command can also be used on C</dev/> devices (and partitions, LV "
5999 "names). You can for example use this to determine if a device contains a "
6000 "filesystem, although it's usually better to use C<guestfs_vfs_type>."
6004 #: ../src/guestfs-actions.pod:1228 ../fish/guestfish-actions.pod:970
6006 "If the C<path> does not begin with C</dev/> then this command only works for "
6007 "the content of regular files. For other file types (directory, symbolic "
6008 "link etc) it will just return the string C<directory> etc."
6012 #: ../src/guestfs-actions.pod:1236
6013 msgid "guestfs_file_architecture"
6017 #: ../src/guestfs-actions.pod:1238
6020 " char *guestfs_file_architecture (guestfs_h *g,\n"
6021 "\t\tconst char *filename);\n"
6026 #: ../src/guestfs-actions.pod:1241 ../fish/guestfish-actions.pod:979
6028 "This detects the architecture of the binary C<filename>, and returns it if "
6033 #: ../src/guestfs-actions.pod:1244 ../fish/guestfish-actions.pod:982
6034 msgid "Currently defined architectures are:"
6038 #: ../src/guestfs-actions.pod:1248 ../fish/guestfish-actions.pod:986
6043 #: ../src/guestfs-actions.pod:1250 ../fish/guestfish-actions.pod:988
6045 "This string is returned for all 32 bit i386, i486, i586, i686 binaries "
6046 "irrespective of the precise processor requirements of the binary."
6050 #: ../src/guestfs-actions.pod:1253 ../fish/guestfish-actions.pod:991
6055 #: ../src/guestfs-actions.pod:1255 ../fish/guestfish-actions.pod:993
6056 msgid "64 bit x86-64."
6060 #: ../src/guestfs-actions.pod:1257 ../fish/guestfish-actions.pod:995
6065 #: ../src/guestfs-actions.pod:1259 ../fish/guestfish-actions.pod:997
6066 msgid "32 bit SPARC."
6070 #: ../src/guestfs-actions.pod:1261 ../fish/guestfish-actions.pod:999
6075 #: ../src/guestfs-actions.pod:1263 ../fish/guestfish-actions.pod:1001
6076 msgid "64 bit SPARC V9 and above."
6080 #: ../src/guestfs-actions.pod:1265 ../fish/guestfish-actions.pod:1003
6085 #: ../src/guestfs-actions.pod:1267 ../fish/guestfish-actions.pod:1005
6086 msgid "Intel Itanium."
6090 #: ../src/guestfs-actions.pod:1269 ../fish/guestfish-actions.pod:1007
6095 #: ../src/guestfs-actions.pod:1271 ../fish/guestfish-actions.pod:1009
6096 msgid "32 bit Power PC."
6100 #: ../src/guestfs-actions.pod:1273 ../fish/guestfish-actions.pod:1011
6105 #: ../src/guestfs-actions.pod:1275 ../fish/guestfish-actions.pod:1013
6106 msgid "64 bit Power PC."
6110 #: ../src/guestfs-actions.pod:1279 ../fish/guestfish-actions.pod:1017
6111 msgid "Libguestfs may return other architecture strings in future."
6115 #: ../src/guestfs-actions.pod:1281 ../fish/guestfish-actions.pod:1019
6116 msgid "The function works on at least the following types of files:"
6120 #: ../src/guestfs-actions.pod:1287 ../fish/guestfish-actions.pod:1025
6121 msgid "many types of Un*x and Linux binary"
6125 #: ../src/guestfs-actions.pod:1291 ../fish/guestfish-actions.pod:1029
6126 msgid "many types of Un*x and Linux shared library"
6130 #: ../src/guestfs-actions.pod:1295 ../fish/guestfish-actions.pod:1033
6131 msgid "Windows Win32 and Win64 binaries"
6135 #: ../src/guestfs-actions.pod:1299 ../fish/guestfish-actions.pod:1037
6136 msgid "Windows Win32 and Win64 DLLs"
6140 #: ../src/guestfs-actions.pod:1301 ../fish/guestfish-actions.pod:1039
6141 msgid "Win32 binaries and DLLs return C<i386>."
6145 #: ../src/guestfs-actions.pod:1303 ../fish/guestfish-actions.pod:1041
6146 msgid "Win64 binaries and DLLs return C<x86_64>."
6150 #: ../src/guestfs-actions.pod:1307 ../fish/guestfish-actions.pod:1045
6151 msgid "Linux kernel modules"
6155 #: ../src/guestfs-actions.pod:1311 ../fish/guestfish-actions.pod:1049
6156 msgid "Linux new-style initrd images"
6160 #: ../src/guestfs-actions.pod:1315 ../fish/guestfish-actions.pod:1053
6161 msgid "some non-x86 Linux vmlinuz kernels"
6165 #: ../src/guestfs-actions.pod:1319 ../fish/guestfish-actions.pod:1057
6166 msgid "What it can't do currently:"
6170 #: ../src/guestfs-actions.pod:1325 ../fish/guestfish-actions.pod:1063
6171 msgid "static libraries (libfoo.a)"
6175 #: ../src/guestfs-actions.pod:1329 ../fish/guestfish-actions.pod:1067
6176 msgid "Linux old-style initrd as compressed ext2 filesystem (RHEL 3)"
6180 #: ../src/guestfs-actions.pod:1333 ../fish/guestfish-actions.pod:1071
6181 msgid "x86 Linux vmlinuz kernels"
6185 #: ../src/guestfs-actions.pod:1335 ../fish/guestfish-actions.pod:1073
6187 "x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and "
6188 "compressed code, and are horribly hard to unpack. If you want to find the "
6189 "architecture of a kernel, use the architecture of the associated initrd or "
6190 "kernel module(s) instead."
6194 #: ../src/guestfs-actions.pod:1345
6195 msgid "guestfs_filesize"
6199 #: ../src/guestfs-actions.pod:1347
6202 " int64_t guestfs_filesize (guestfs_h *g,\n"
6203 "\t\tconst char *file);\n"
6208 #: ../src/guestfs-actions.pod:1350 ../fish/guestfish-actions.pod:1084
6209 msgid "This command returns the size of C<file> in bytes."
6213 #: ../src/guestfs-actions.pod:1352
6215 "To get other stats about a file, use C<guestfs_stat>, C<guestfs_lstat>, "
6216 "C<guestfs_is_dir>, C<guestfs_is_file> etc. To get the size of block "
6217 "devices, use C<guestfs_blockdev_getsize64>."
6221 #: ../src/guestfs-actions.pod:1358
6222 msgid "guestfs_fill"
6226 #: ../src/guestfs-actions.pod:1360
6229 " int guestfs_fill (guestfs_h *g,\n"
6232 "\t\tconst char *path);\n"
6237 #: ../src/guestfs-actions.pod:1365 ../fish/guestfish-actions.pod:1094
6239 "This command creates a new file called C<path>. The initial content of the "
6240 "file is C<len> octets of C<c>, where C<c> must be a number in the range C<"
6245 #: ../src/guestfs-actions.pod:1369
6247 "To fill a file with zero bytes (sparsely), it is much more efficient to use "
6248 "C<guestfs_truncate_size>. To create a file with a pattern of repeating "
6249 "bytes use C<guestfs_fill_pattern>."
6253 #: ../src/guestfs-actions.pod:1381
6254 msgid "guestfs_fill_pattern"
6258 #: ../src/guestfs-actions.pod:1383
6261 " int guestfs_fill_pattern (guestfs_h *g,\n"
6262 "\t\tconst char *pattern,\n"
6264 "\t\tconst char *path);\n"
6269 #: ../src/guestfs-actions.pod:1388
6271 "This function is like C<guestfs_fill> except that it creates a new file of "
6272 "length C<len> containing the repeating pattern of bytes in C<pattern>. The "
6273 "pattern is truncated if necessary to ensure the length of the file is "
6274 "exactly C<len> bytes."
6278 #: ../src/guestfs-actions.pod:1400
6279 msgid "guestfs_find"
6283 #: ../src/guestfs-actions.pod:1402
6286 " char **guestfs_find (guestfs_h *g,\n"
6287 "\t\tconst char *directory);\n"
6292 #: ../src/guestfs-actions.pod:1405 ../fish/guestfish-actions.pod:1116
6294 "This command lists out all files and directories, recursively, starting at "
6295 "C<directory>. It is essentially equivalent to running the shell command "
6296 "C<find directory -print> but some post-processing happens on the output, "
6301 #: ../src/guestfs-actions.pod:1410 ../fish/guestfish-actions.pod:1121
6303 "This returns a list of strings I<without any prefix>. Thus if the directory "
6308 #: ../src/guestfs-actions.pod:1413 ../fish/guestfish-actions.pod:1124
6318 #: ../src/guestfs-actions.pod:1417
6320 "then the returned list from C<guestfs_find> C</tmp> would be 4 elements:"
6324 #: ../src/guestfs-actions.pod:1420 ../fish/guestfish-actions.pod:1131
6335 #: ../src/guestfs-actions.pod:1425 ../fish/guestfish-actions.pod:1136
6336 msgid "If C<directory> is not a directory, then this command returns an error."
6340 #: ../src/guestfs-actions.pod:1428 ../fish/guestfish-actions.pod:1139
6341 msgid "The returned list is sorted."
6345 #: ../src/guestfs-actions.pod:1430
6346 msgid "See also C<guestfs_find0>."
6350 #: ../src/guestfs-actions.pod:1439
6351 msgid "guestfs_find0"
6355 #: ../src/guestfs-actions.pod:1441
6358 " int guestfs_find0 (guestfs_h *g,\n"
6359 "\t\tconst char *directory,\n"
6360 "\t\tconst char *files);\n"
6365 #: ../src/guestfs-actions.pod:1445 ../fish/guestfish-actions.pod:1150
6367 "This command lists out all files and directories, recursively, starting at "
6368 "C<directory>, placing the resulting list in the external file called "
6373 #: ../src/guestfs-actions.pod:1449
6375 "This command works the same way as C<guestfs_find> with the following "
6380 #: ../src/guestfs-actions.pod:1456 ../fish/guestfish-actions.pod:1161
6381 msgid "The resulting list is written to an external file."
6385 #: ../src/guestfs-actions.pod:1460 ../fish/guestfish-actions.pod:1165
6387 "Items (filenames) in the result are separated by C<\\0> characters. See "
6388 "L<find(1)> option I<-print0>."
6392 #: ../src/guestfs-actions.pod:1465 ../fish/guestfish-actions.pod:1170
6393 msgid "This command is not limited in the number of names that it can return."
6397 #: ../src/guestfs-actions.pod:1470 ../fish/guestfish-actions.pod:1175
6398 msgid "The result list is not sorted."
6402 #: ../src/guestfs-actions.pod:1476
6403 msgid "guestfs_findfs_label"
6407 #: ../src/guestfs-actions.pod:1478
6410 " char *guestfs_findfs_label (guestfs_h *g,\n"
6411 "\t\tconst char *label);\n"
6416 #: ../src/guestfs-actions.pod:1481 ../fish/guestfish-actions.pod:1185
6418 "This command searches the filesystems and returns the one which has the "
6419 "given label. An error is returned if no such filesystem can be found."
6423 #: ../src/guestfs-actions.pod:1485
6424 msgid "To find the label of a filesystem, use C<guestfs_vfs_label>."
6428 #: ../src/guestfs-actions.pod:1490
6429 msgid "guestfs_findfs_uuid"
6433 #: ../src/guestfs-actions.pod:1492
6436 " char *guestfs_findfs_uuid (guestfs_h *g,\n"
6437 "\t\tconst char *uuid);\n"
6442 #: ../src/guestfs-actions.pod:1495 ../fish/guestfish-actions.pod:1195
6444 "This command searches the filesystems and returns the one which has the "
6445 "given UUID. An error is returned if no such filesystem can be found."
6449 #: ../src/guestfs-actions.pod:1499
6450 msgid "To find the UUID of a filesystem, use C<guestfs_vfs_uuid>."
6454 #: ../src/guestfs-actions.pod:1504
6455 msgid "guestfs_fsck"
6459 #: ../src/guestfs-actions.pod:1506
6462 " int guestfs_fsck (guestfs_h *g,\n"
6463 "\t\tconst char *fstype,\n"
6464 "\t\tconst char *device);\n"
6469 #: ../src/guestfs-actions.pod:1510 ../fish/guestfish-actions.pod:1205
6471 "This runs the filesystem checker (fsck) on C<device> which should have "
6472 "filesystem type C<fstype>."
6476 #: ../src/guestfs-actions.pod:1513 ../fish/guestfish-actions.pod:1208
6478 "The returned integer is the status. See L<fsck(8)> for the list of status "
6479 "codes from C<fsck>."
6483 #: ../src/guestfs-actions.pod:1522 ../fish/guestfish-actions.pod:1217
6484 msgid "Multiple status codes can be summed together."
6488 #: ../src/guestfs-actions.pod:1526 ../fish/guestfish-actions.pod:1221
6490 "A non-zero return code can mean \"success\", for example if errors have been "
6491 "corrected on the filesystem."
6495 #: ../src/guestfs-actions.pod:1531 ../fish/guestfish-actions.pod:1226
6496 msgid "Checking or repairing NTFS volumes is not supported (by linux-ntfs)."
6500 #: ../src/guestfs-actions.pod:1536 ../fish/guestfish-actions.pod:1231
6502 "This command is entirely equivalent to running C<fsck -a -t fstype device>."
6506 #: ../src/guestfs-actions.pod:1540
6507 msgid "guestfs_get_append"
6511 #: ../src/guestfs-actions.pod:1542
6514 " const char *guestfs_get_append (guestfs_h *g);\n"
6519 #: ../src/guestfs-actions.pod:1544 ../fish/guestfish-actions.pod:1237
6521 "Return the additional kernel options which are added to the guest kernel "
6526 #: ../src/guestfs-actions.pod:1547 ../fish/guestfish-actions.pod:1240
6527 msgid "If C<NULL> then no options are added."
6531 #: ../src/guestfs-actions.pod:1549
6533 "This function returns a string which may be NULL. There is no way to return "
6534 "an error from this function. The string is owned by the guest handle and "
6535 "must I<not> be freed."
6539 #: ../src/guestfs-actions.pod:1553
6540 msgid "guestfs_get_autosync"
6544 #: ../src/guestfs-actions.pod:1555
6547 " int guestfs_get_autosync (guestfs_h *g);\n"
6552 #: ../src/guestfs-actions.pod:1557 ../fish/guestfish-actions.pod:1246
6553 msgid "Get the autosync flag."
6557 #: ../src/guestfs-actions.pod:1561
6558 msgid "guestfs_get_direct"
6562 #: ../src/guestfs-actions.pod:1563
6565 " int guestfs_get_direct (guestfs_h *g);\n"
6570 #: ../src/guestfs-actions.pod:1565 ../fish/guestfish-actions.pod:1252
6571 msgid "Return the direct appliance mode flag."
6575 #: ../src/guestfs-actions.pod:1569
6576 msgid "guestfs_get_e2label"
6580 #: ../src/guestfs-actions.pod:1571
6583 " char *guestfs_get_e2label (guestfs_h *g,\n"
6584 "\t\tconst char *device);\n"
6589 #: ../src/guestfs-actions.pod:1574 ../fish/guestfish-actions.pod:1258
6591 "This returns the ext2/3/4 filesystem label of the filesystem on C<device>."
6595 #: ../src/guestfs-actions.pod:1580 ../fish/guestfish-actions.pod:1261
6597 "This function is deprecated. In new code, use the C<vfs_label> call instead."
6601 #: ../src/guestfs-actions.pod:1587
6602 msgid "guestfs_get_e2uuid"
6606 #: ../src/guestfs-actions.pod:1589
6609 " char *guestfs_get_e2uuid (guestfs_h *g,\n"
6610 "\t\tconst char *device);\n"
6615 #: ../src/guestfs-actions.pod:1592 ../fish/guestfish-actions.pod:1272
6617 "This returns the ext2/3/4 filesystem UUID of the filesystem on C<device>."
6621 #: ../src/guestfs-actions.pod:1598 ../fish/guestfish-actions.pod:1275
6623 "This function is deprecated. In new code, use the C<vfs_uuid> call instead."
6627 #: ../src/guestfs-actions.pod:1605
6628 msgid "guestfs_get_memsize"
6632 #: ../src/guestfs-actions.pod:1607
6635 " int guestfs_get_memsize (guestfs_h *g);\n"
6640 #: ../src/guestfs-actions.pod:1609 ../fish/guestfish-actions.pod:1286
6642 "This gets the memory size in megabytes allocated to the qemu subprocess."
6646 #: ../src/guestfs-actions.pod:1612
6648 "If C<guestfs_set_memsize> was not called on this handle, and if "
6649 "C<LIBGUESTFS_MEMSIZE> was not set, then this returns the compiled-in default "
6650 "value for memsize."
6654 #: ../src/guestfs-actions.pod:1616 ../src/guestfs-actions.pod:1679
6655 #: ../src/guestfs-actions.pod:4348 ../src/guestfs-actions.pod:4440
6656 #: ../fish/guestfish-actions.pod:1293 ../fish/guestfish-actions.pod:1344
6657 #: ../fish/guestfish-actions.pod:3372 ../fish/guestfish-actions.pod:3459
6659 "For more information on the architecture of libguestfs, see L<guestfs(3)>."
6663 #: ../src/guestfs-actions.pod:1621
6664 msgid "guestfs_get_network"
6668 #: ../src/guestfs-actions.pod:1623
6671 " int guestfs_get_network (guestfs_h *g);\n"
6676 #: ../src/guestfs-actions.pod:1625 ../fish/guestfish-actions.pod:1300
6677 msgid "This returns the enable network flag."
6681 #: ../src/guestfs-actions.pod:1629
6682 msgid "guestfs_get_path"
6686 #: ../src/guestfs-actions.pod:1631
6689 " const char *guestfs_get_path (guestfs_h *g);\n"
6694 #: ../src/guestfs-actions.pod:1633 ../fish/guestfish-actions.pod:1306
6695 msgid "Return the current search path."
6699 #: ../src/guestfs-actions.pod:1635 ../fish/guestfish-actions.pod:1308
6701 "This is always non-NULL. If it wasn't set already, then this will return "
6706 #: ../src/guestfs-actions.pod:1638 ../src/guestfs-actions.pod:1661
6708 "This function returns a string, or NULL on error. The string is owned by "
6709 "the guest handle and must I<not> be freed."
6713 #: ../src/guestfs-actions.pod:1641
6714 msgid "guestfs_get_pid"
6718 #: ../src/guestfs-actions.pod:1643
6721 " int guestfs_get_pid (guestfs_h *g);\n"
6726 #: ../src/guestfs-actions.pod:1645 ../fish/guestfish-actions.pod:1317
6728 "Return the process ID of the qemu subprocess. If there is no qemu "
6729 "subprocess, then this will return an error."
6733 #: ../src/guestfs-actions.pod:1648 ../fish/guestfish-actions.pod:1320
6734 msgid "This is an internal call used for debugging and testing."
6738 #: ../src/guestfs-actions.pod:1652
6739 msgid "guestfs_get_qemu"
6743 #: ../src/guestfs-actions.pod:1654
6746 " const char *guestfs_get_qemu (guestfs_h *g);\n"
6751 #: ../src/guestfs-actions.pod:1656 ../fish/guestfish-actions.pod:1326
6752 msgid "Return the current qemu binary."
6756 #: ../src/guestfs-actions.pod:1658 ../fish/guestfish-actions.pod:1328
6758 "This is always non-NULL. If it wasn't set already, then this will return "
6759 "the default qemu binary name."
6763 #: ../src/guestfs-actions.pod:1664
6764 msgid "guestfs_get_recovery_proc"
6768 #: ../src/guestfs-actions.pod:1666
6771 " int guestfs_get_recovery_proc (guestfs_h *g);\n"
6776 #: ../src/guestfs-actions.pod:1668 ../fish/guestfish-actions.pod:1335
6777 msgid "Return the recovery process enabled flag."
6781 #: ../src/guestfs-actions.pod:1672
6782 msgid "guestfs_get_selinux"
6786 #: ../src/guestfs-actions.pod:1674
6789 " int guestfs_get_selinux (guestfs_h *g);\n"
6794 #: ../src/guestfs-actions.pod:1676
6796 "This returns the current setting of the selinux flag which is passed to the "
6797 "appliance at boot time. See C<guestfs_set_selinux>."
6801 #: ../src/guestfs-actions.pod:1684
6802 msgid "guestfs_get_state"
6806 #: ../src/guestfs-actions.pod:1686
6809 " int guestfs_get_state (guestfs_h *g);\n"
6814 #: ../src/guestfs-actions.pod:1688 ../fish/guestfish-actions.pod:1351
6816 "This returns the current state as an opaque integer. This is only useful "
6817 "for printing debug and internal error messages."
6821 #: ../src/guestfs-actions.pod:1691 ../src/guestfs-actions.pod:2312
6822 #: ../src/guestfs-actions.pod:2335 ../src/guestfs-actions.pod:2384
6823 #: ../src/guestfs-actions.pod:2405 ../fish/guestfish-actions.pod:1354
6824 #: ../fish/guestfish-actions.pod:1848 ../fish/guestfish-actions.pod:1866
6825 #: ../fish/guestfish-actions.pod:1904 ../fish/guestfish-actions.pod:1920
6826 msgid "For more information on states, see L<guestfs(3)>."
6830 #: ../src/guestfs-actions.pod:1695
6831 msgid "guestfs_get_trace"
6835 #: ../src/guestfs-actions.pod:1697
6838 " int guestfs_get_trace (guestfs_h *g);\n"
6843 #: ../src/guestfs-actions.pod:1699 ../fish/guestfish-actions.pod:1360
6844 msgid "Return the command trace flag."
6848 #: ../src/guestfs-actions.pod:1703
6849 msgid "guestfs_get_umask"
6853 #: ../src/guestfs-actions.pod:1705
6856 " int guestfs_get_umask (guestfs_h *g);\n"
6861 #: ../src/guestfs-actions.pod:1707
6863 "Return the current umask. By default the umask is C<022> unless it has been "
6864 "set by calling C<guestfs_umask>."
6868 #: ../src/guestfs-actions.pod:1712
6869 msgid "guestfs_get_verbose"
6873 #: ../src/guestfs-actions.pod:1714
6876 " int guestfs_get_verbose (guestfs_h *g);\n"
6881 #: ../src/guestfs-actions.pod:1716 ../fish/guestfish-actions.pod:1373
6882 msgid "This returns the verbose messages flag."
6886 #: ../src/guestfs-actions.pod:1720
6887 msgid "guestfs_getcon"
6891 #: ../src/guestfs-actions.pod:1722
6894 " char *guestfs_getcon (guestfs_h *g);\n"
6899 #: ../src/guestfs-actions.pod:1724 ../fish/guestfish-actions.pod:1379
6900 msgid "This gets the SELinux security context of the daemon."
6904 #: ../src/guestfs-actions.pod:1726
6906 "See the documentation about SELINUX in L<guestfs(3)>, and C<guestfs_setcon>"
6910 #: ../src/guestfs-actions.pod:1732
6911 msgid "guestfs_getxattrs"
6915 #: ../src/guestfs-actions.pod:1734
6918 " struct guestfs_xattr_list *guestfs_getxattrs (guestfs_h *g,\n"
6919 "\t\tconst char *path);\n"
6924 #: ../src/guestfs-actions.pod:1737 ../fish/guestfish-actions.pod:1388
6926 "This call lists the extended attributes of the file or directory C<path>."
6930 #: ../src/guestfs-actions.pod:1740 ../fish/guestfish-actions.pod:1391
6932 "At the system call level, this is a combination of the L<listxattr(2)> and "
6933 "L<getxattr(2)> calls."
6937 #: ../src/guestfs-actions.pod:1743
6938 msgid "See also: C<guestfs_lgetxattrs>, L<attr(5)>."
6942 #: ../src/guestfs-actions.pod:1745 ../src/guestfs-actions.pod:2479
6943 #: ../src/guestfs-actions.pod:3017
6945 "This function returns a C<struct guestfs_xattr_list *> (see E<lt>guestfs-"
6946 "structs.hE<gt>), or NULL if there was an error. I<The caller must call "
6947 "C<guestfs_free_xattr_list> after use>."
6951 #: ../src/guestfs-actions.pod:1750
6952 msgid "guestfs_glob_expand"
6956 #: ../src/guestfs-actions.pod:1752
6959 " char **guestfs_glob_expand (guestfs_h *g,\n"
6960 "\t\tconst char *pattern);\n"
6965 #: ../src/guestfs-actions.pod:1755 ../fish/guestfish-actions.pod:1400
6967 "This command searches for all the pathnames matching C<pattern> according to "
6968 "the wildcard expansion rules used by the shell."
6972 #: ../src/guestfs-actions.pod:1759 ../fish/guestfish-actions.pod:1404
6974 "If no paths match, then this returns an empty list (note: not an error)."
6978 #: ../src/guestfs-actions.pod:1762 ../fish/guestfish-actions.pod:1407
6980 "It is just a wrapper around the C L<glob(3)> function with flags C<GLOB_MARK|"
6981 "GLOB_BRACE>. See that manual page for more details."
6985 #: ../src/guestfs-actions.pod:1770
6986 msgid "guestfs_grep"
6990 #: ../src/guestfs-actions.pod:1772
6993 " char **guestfs_grep (guestfs_h *g,\n"
6994 "\t\tconst char *regex,\n"
6995 "\t\tconst char *path);\n"
7000 #: ../src/guestfs-actions.pod:1776 ../fish/guestfish-actions.pod:1415
7001 msgid "This calls the external C<grep> program and returns the matching lines."
7005 #: ../src/guestfs-actions.pod:1786
7006 msgid "guestfs_grepi"
7010 #: ../src/guestfs-actions.pod:1788
7013 " char **guestfs_grepi (guestfs_h *g,\n"
7014 "\t\tconst char *regex,\n"
7015 "\t\tconst char *path);\n"
7020 #: ../src/guestfs-actions.pod:1792 ../fish/guestfish-actions.pod:1425
7022 "This calls the external C<grep -i> program and returns the matching lines."
7026 #: ../src/guestfs-actions.pod:1802
7027 msgid "guestfs_grub_install"
7031 #: ../src/guestfs-actions.pod:1804
7034 " int guestfs_grub_install (guestfs_h *g,\n"
7035 "\t\tconst char *root,\n"
7036 "\t\tconst char *device);\n"
7041 #: ../src/guestfs-actions.pod:1808 ../fish/guestfish-actions.pod:1435
7043 "This command installs GRUB (the Grand Unified Bootloader) on C<device>, with "
7044 "the root directory being C<root>."
7048 #: ../src/guestfs-actions.pod:1811 ../fish/guestfish-actions.pod:1438
7050 "Note: If grub-install reports the error \"No suitable drive was found in the "
7051 "generated device map.\" it may be that you need to create a C</boot/grub/"
7052 "device.map> file first that contains the mapping between grub device names "
7053 "and Linux device names. It is usually sufficient to create a file "
7058 #: ../src/guestfs-actions.pod:1818 ../fish/guestfish-actions.pod:1445
7066 #: ../src/guestfs-actions.pod:1820 ../fish/guestfish-actions.pod:1447
7067 msgid "replacing C</dev/vda> with the name of the installation device."
7071 #: ../src/guestfs-actions.pod:1824
7072 msgid "guestfs_head"
7076 #: ../src/guestfs-actions.pod:1826
7079 " char **guestfs_head (guestfs_h *g,\n"
7080 "\t\tconst char *path);\n"
7085 #: ../src/guestfs-actions.pod:1829 ../fish/guestfish-actions.pod:1453
7087 "This command returns up to the first 10 lines of a file as a list of strings."
7091 #: ../src/guestfs-actions.pod:1839
7092 msgid "guestfs_head_n"
7096 #: ../src/guestfs-actions.pod:1841
7099 " char **guestfs_head_n (guestfs_h *g,\n"
7100 "\t\tint nrlines,\n"
7101 "\t\tconst char *path);\n"
7106 #: ../src/guestfs-actions.pod:1845 ../fish/guestfish-actions.pod:1463
7108 "If the parameter C<nrlines> is a positive number, this returns the first "
7109 "C<nrlines> lines of the file C<path>."
7113 #: ../src/guestfs-actions.pod:1848 ../fish/guestfish-actions.pod:1466
7115 "If the parameter C<nrlines> is a negative number, this returns lines from "
7116 "the file C<path>, excluding the last C<nrlines> lines."
7120 #: ../src/guestfs-actions.pod:1851 ../src/guestfs-actions.pod:4896
7121 #: ../fish/guestfish-actions.pod:1469 ../fish/guestfish-actions.pod:3805
7122 msgid "If the parameter C<nrlines> is zero, this returns an empty list."
7126 #: ../src/guestfs-actions.pod:1860
7127 msgid "guestfs_hexdump"
7131 #: ../src/guestfs-actions.pod:1862
7134 " char *guestfs_hexdump (guestfs_h *g,\n"
7135 "\t\tconst char *path);\n"
7140 #: ../src/guestfs-actions.pod:1865 ../fish/guestfish-actions.pod:1478
7142 "This runs C<hexdump -C> on the given C<path>. The result is the human-"
7143 "readable, canonical hex dump of the file."
7147 #: ../src/guestfs-actions.pod:1874
7148 msgid "guestfs_initrd_cat"
7152 #: ../src/guestfs-actions.pod:1876
7155 " char *guestfs_initrd_cat (guestfs_h *g,\n"
7156 "\t\tconst char *initrdpath,\n"
7157 "\t\tconst char *filename,\n"
7158 "\t\tsize_t *size_r);\n"
7163 #: ../src/guestfs-actions.pod:1881 ../fish/guestfish-actions.pod:1488
7165 "This command unpacks the file C<filename> from the initrd file called "
7166 "C<initrdpath>. The filename must be given I<without> the initial C</> "
7171 #: ../src/guestfs-actions.pod:1885 ../fish/guestfish-actions.pod:1492
7173 "For example, in guestfish you could use the following command to examine the "
7174 "boot script (usually called C</init>) contained in a Linux initrd or "
7179 #: ../src/guestfs-actions.pod:1889 ../fish/guestfish-actions.pod:1496
7182 " initrd-cat /boot/initrd-<version>.img init\n"
7187 #: ../src/guestfs-actions.pod:1891
7188 msgid "See also C<guestfs_initrd_list>."
7192 #: ../src/guestfs-actions.pod:1893 ../src/guestfs-actions.pod:3831
7193 #: ../src/guestfs-actions.pod:3983
7195 "This function returns a buffer, or NULL on error. The size of the returned "
7196 "buffer is written to C<*size_r>. I<The caller must free the returned buffer "
7201 #: ../src/guestfs-actions.pod:1900
7202 msgid "guestfs_initrd_list"
7206 #: ../src/guestfs-actions.pod:1902
7209 " char **guestfs_initrd_list (guestfs_h *g,\n"
7210 "\t\tconst char *path);\n"
7215 #: ../src/guestfs-actions.pod:1905 ../fish/guestfish-actions.pod:1507
7216 msgid "This command lists out files contained in an initrd."
7220 #: ../src/guestfs-actions.pod:1907 ../fish/guestfish-actions.pod:1509
7222 "The files are listed without any initial C</> character. The files are "
7223 "listed in the order they appear (not necessarily alphabetical). Directory "
7224 "names are listed as separate items."
7228 #: ../src/guestfs-actions.pod:1911 ../fish/guestfish-actions.pod:1513
7230 "Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem as "
7231 "initrd. We I<only> support the newer initramfs format (compressed cpio "
7236 #: ../src/guestfs-actions.pod:1919
7237 msgid "guestfs_inotify_add_watch"
7241 #: ../src/guestfs-actions.pod:1921
7244 " int64_t guestfs_inotify_add_watch (guestfs_h *g,\n"
7245 "\t\tconst char *path,\n"
7251 #: ../src/guestfs-actions.pod:1925 ../fish/guestfish-actions.pod:1521
7252 msgid "Watch C<path> for the events listed in C<mask>."
7256 #: ../src/guestfs-actions.pod:1927 ../fish/guestfish-actions.pod:1523
7258 "Note that if C<path> is a directory then events within that directory are "
7259 "watched, but this does I<not> happen recursively (in subdirectories)."
7263 #: ../src/guestfs-actions.pod:1931 ../fish/guestfish-actions.pod:1527
7265 "Note for non-C or non-Linux callers: the inotify events are defined by the "
7266 "Linux kernel ABI and are listed in C</usr/include/sys/inotify.h>."
7270 #: ../src/guestfs-actions.pod:1937
7271 msgid "guestfs_inotify_close"
7275 #: ../src/guestfs-actions.pod:1939
7278 " int guestfs_inotify_close (guestfs_h *g);\n"
7283 #: ../src/guestfs-actions.pod:1941 ../fish/guestfish-actions.pod:1535
7285 "This closes the inotify handle which was previously opened by inotify_init. "
7286 "It removes all watches, throws away any pending events, and deallocates all "
7291 #: ../src/guestfs-actions.pod:1947
7292 msgid "guestfs_inotify_files"
7296 #: ../src/guestfs-actions.pod:1949
7299 " char **guestfs_inotify_files (guestfs_h *g);\n"
7304 #: ../src/guestfs-actions.pod:1951
7306 "This function is a helpful wrapper around C<guestfs_inotify_read> which just "
7307 "returns a list of pathnames of objects that were touched. The returned "
7308 "pathnames are sorted and deduplicated."
7312 #: ../src/guestfs-actions.pod:1959
7313 msgid "guestfs_inotify_init"
7317 #: ../src/guestfs-actions.pod:1961
7320 " int guestfs_inotify_init (guestfs_h *g,\n"
7321 "\t\tint maxevents);\n"
7326 #: ../src/guestfs-actions.pod:1964 ../fish/guestfish-actions.pod:1551
7328 "This command creates a new inotify handle. The inotify subsystem can be "
7329 "used to notify events which happen to objects in the guest filesystem."
7333 #: ../src/guestfs-actions.pod:1968
7335 "C<maxevents> is the maximum number of events which will be queued up between "
7336 "calls to C<guestfs_inotify_read> or C<guestfs_inotify_files>. If this is "
7337 "passed as C<0>, then the kernel (or previously set) default is used. For "
7338 "Linux 2.6.29 the default was 16384 events. Beyond this limit, the kernel "
7339 "throws away events, but records the fact that it threw them away by setting "
7340 "a flag C<IN_Q_OVERFLOW> in the returned structure list (see "
7341 "C<guestfs_inotify_read>)."
7345 #: ../src/guestfs-actions.pod:1978
7347 "Before any events are generated, you have to add some watches to the "
7348 "internal watch list. See: C<guestfs_inotify_add_watch>, "
7349 "C<guestfs_inotify_rm_watch> and C<guestfs_inotify_watch_all>."
7353 #: ../src/guestfs-actions.pod:1984
7355 "Queued up events should be read periodically by calling "
7356 "C<guestfs_inotify_read> (or C<guestfs_inotify_files> which is just a helpful "
7357 "wrapper around C<guestfs_inotify_read>). If you don't read the events out "
7358 "often enough then you risk the internal queue overflowing."
7362 #: ../src/guestfs-actions.pod:1991
7364 "The handle should be closed after use by calling C<guestfs_inotify_close>. "
7365 "This also removes any watches automatically."
7369 #: ../src/guestfs-actions.pod:1995 ../fish/guestfish-actions.pod:1582
7371 "See also L<inotify(7)> for an overview of the inotify interface as exposed "
7372 "by the Linux kernel, which is roughly what we expose via libguestfs. Note "
7373 "that there is one global inotify handle per libguestfs instance."
7377 #: ../src/guestfs-actions.pod:2002
7378 msgid "guestfs_inotify_read"
7382 #: ../src/guestfs-actions.pod:2004
7385 " struct guestfs_inotify_event_list *guestfs_inotify_read (guestfs_h *g);\n"
7390 #: ../src/guestfs-actions.pod:2006 ../fish/guestfish-actions.pod:1591
7392 "Return the complete queue of events that have happened since the previous "
7397 #: ../src/guestfs-actions.pod:2009 ../fish/guestfish-actions.pod:1594
7398 msgid "If no events have happened, this returns an empty list."
7402 #: ../src/guestfs-actions.pod:2011 ../fish/guestfish-actions.pod:1596
7404 "I<Note>: In order to make sure that all events have been read, you must call "
7405 "this function repeatedly until it returns an empty list. The reason is that "
7406 "the call will read events up to the maximum appliance-to-host message size "
7407 "and leave remaining events in the queue."
7411 #: ../src/guestfs-actions.pod:2017
7413 "This function returns a C<struct guestfs_inotify_event_list *> (see "
7414 "E<lt>guestfs-structs.hE<gt>), or NULL if there was an error. I<The caller "
7415 "must call C<guestfs_free_inotify_event_list> after use>."
7419 #: ../src/guestfs-actions.pod:2022
7420 msgid "guestfs_inotify_rm_watch"
7424 #: ../src/guestfs-actions.pod:2024
7427 " int guestfs_inotify_rm_watch (guestfs_h *g,\n"
7433 #: ../src/guestfs-actions.pod:2027
7435 "Remove a previously defined inotify watch. See C<guestfs_inotify_add_watch>."
7439 #: ../src/guestfs-actions.pod:2032
7440 msgid "guestfs_inspect_get_arch"
7444 #: ../src/guestfs-actions.pod:2034
7447 " char *guestfs_inspect_get_arch (guestfs_h *g,\n"
7448 "\t\tconst char *root);\n"
7453 #: ../src/guestfs-actions.pod:2037 ../src/guestfs-actions.pod:2057
7454 #: ../src/guestfs-actions.pod:2107 ../src/guestfs-actions.pod:2130
7455 #: ../src/guestfs-actions.pod:2154 ../src/guestfs-actions.pod:2172
7456 #: ../src/guestfs-actions.pod:2202 ../src/guestfs-actions.pod:2223
7458 "This function should only be called with a root device string as returned by "
7459 "C<guestfs_inspect_os>."
7463 #: ../src/guestfs-actions.pod:2040
7465 "This returns the architecture of the inspected operating system. The "
7466 "possible return values are listed under C<guestfs_file_architecture>."
7470 #: ../src/guestfs-actions.pod:2044 ../fish/guestfish-actions.pod:1620
7472 "If the architecture could not be determined, then the string C<unknown> is "
7477 #: ../src/guestfs-actions.pod:2047 ../src/guestfs-actions.pod:2097
7478 #: ../src/guestfs-actions.pod:2145 ../src/guestfs-actions.pod:2213
7479 #: ../src/guestfs-actions.pod:2248 ../src/guestfs-actions.pod:2285
7480 #: ../fish/guestfish-actions.pod:1623 ../fish/guestfish-actions.pod:1669
7481 #: ../fish/guestfish-actions.pod:1708 ../fish/guestfish-actions.pod:1763
7482 #: ../fish/guestfish-actions.pod:1794 ../fish/guestfish-actions.pod:1828
7483 msgid "Please read L<guestfs(3)/INSPECTION> for more details."
7487 #: ../src/guestfs-actions.pod:2052
7488 msgid "guestfs_inspect_get_distro"
7492 #: ../src/guestfs-actions.pod:2054
7495 " char *guestfs_inspect_get_distro (guestfs_h *g,\n"
7496 "\t\tconst char *root);\n"
7501 #: ../src/guestfs-actions.pod:2060 ../fish/guestfish-actions.pod:1632
7503 "This returns the distro (distribution) of the inspected operating system."
7507 #: ../src/guestfs-actions.pod:2063 ../fish/guestfish-actions.pod:1635
7508 msgid "Currently defined distros are:"
7512 #: ../src/guestfs-actions.pod:2067 ../fish/guestfish-actions.pod:1639
7517 #: ../src/guestfs-actions.pod:2069 ../fish/guestfish-actions.pod:1641
7518 msgid "Debian or a Debian-derived distro such as Ubuntu."
7522 #: ../src/guestfs-actions.pod:2071 ../fish/guestfish-actions.pod:1643
7527 #: ../src/guestfs-actions.pod:2073 ../fish/guestfish-actions.pod:1645
7532 #: ../src/guestfs-actions.pod:2075 ../fish/guestfish-actions.pod:1647
7533 msgid "\"redhat-based\""
7537 #: ../src/guestfs-actions.pod:2077 ../fish/guestfish-actions.pod:1649
7538 msgid "Some Red Hat-derived distro."
7542 #: ../src/guestfs-actions.pod:2079 ../fish/guestfish-actions.pod:1651
7547 #: ../src/guestfs-actions.pod:2081 ../fish/guestfish-actions.pod:1653
7548 msgid "Red Hat Enterprise Linux and some derivatives."
7552 #: ../src/guestfs-actions.pod:2083 ../src/guestfs-actions.pod:2235
7553 #: ../fish/guestfish-actions.pod:1655 ../fish/guestfish-actions.pod:1781
7558 #: ../src/guestfs-actions.pod:2085 ../fish/guestfish-actions.pod:1657
7560 "Windows does not have distributions. This string is returned if the OS type "
7565 #: ../src/guestfs-actions.pod:2088 ../src/guestfs-actions.pod:2239
7566 #: ../fish/guestfish-actions.pod:1660 ../fish/guestfish-actions.pod:1785
7571 #: ../src/guestfs-actions.pod:2090 ../fish/guestfish-actions.pod:1662
7572 msgid "The distro could not be determined."
7576 #: ../src/guestfs-actions.pod:2094 ../src/guestfs-actions.pod:2245
7577 #: ../fish/guestfish-actions.pod:1666 ../fish/guestfish-actions.pod:1791
7579 "Future versions of libguestfs may return other strings here. The caller "
7580 "should be prepared to handle any string."
7584 #: ../src/guestfs-actions.pod:2102
7585 msgid "guestfs_inspect_get_filesystems"
7589 #: ../src/guestfs-actions.pod:2104
7592 " char **guestfs_inspect_get_filesystems (guestfs_h *g,\n"
7593 "\t\tconst char *root);\n"
7598 #: ../src/guestfs-actions.pod:2110 ../fish/guestfish-actions.pod:1678
7600 "This returns a list of all the filesystems that we think are associated with "
7601 "this operating system. This includes the root filesystem, other ordinary "
7602 "filesystems, and non-mounted devices like swap partitions."
7606 #: ../src/guestfs-actions.pod:2115 ../fish/guestfish-actions.pod:1683
7608 "In the case of a multi-boot virtual machine, it is possible for a filesystem "
7609 "to be shared between operating systems."
7613 #: ../src/guestfs-actions.pod:2118
7615 "Please read L<guestfs(3)/INSPECTION> for more details. See also "
7616 "C<guestfs_inspect_get_mountpoints>."
7620 #: ../src/guestfs-actions.pod:2125
7621 msgid "guestfs_inspect_get_major_version"
7625 #: ../src/guestfs-actions.pod:2127
7628 " int guestfs_inspect_get_major_version (guestfs_h *g,\n"
7629 "\t\tconst char *root);\n"
7634 #: ../src/guestfs-actions.pod:2133 ../fish/guestfish-actions.pod:1696
7636 "This returns the major version number of the inspected operating system."
7640 #: ../src/guestfs-actions.pod:2136 ../fish/guestfish-actions.pod:1699
7642 "Windows uses a consistent versioning scheme which is I<not> reflected in the "
7643 "popular public names used by the operating system. Notably the operating "
7644 "system known as \"Windows 7\" is really version 6.1 (ie. major = 6, minor = "
7645 "1). You can find out the real versions corresponding to releases of Windows "
7646 "by consulting Wikipedia or MSDN."
7650 #: ../src/guestfs-actions.pod:2143 ../src/guestfs-actions.pod:2160
7651 #: ../fish/guestfish-actions.pod:1706 ../fish/guestfish-actions.pod:1720
7652 msgid "If the version could not be determined, then C<0> is returned."
7656 #: ../src/guestfs-actions.pod:2149
7657 msgid "guestfs_inspect_get_minor_version"
7661 #: ../src/guestfs-actions.pod:2151
7664 " int guestfs_inspect_get_minor_version (guestfs_h *g,\n"
7665 "\t\tconst char *root);\n"
7670 #: ../src/guestfs-actions.pod:2157 ../fish/guestfish-actions.pod:1717
7672 "This returns the minor version number of the inspected operating system."
7676 #: ../src/guestfs-actions.pod:2162
7678 "Please read L<guestfs(3)/INSPECTION> for more details. See also "
7679 "C<guestfs_inspect_get_major_version>."
7683 #: ../src/guestfs-actions.pod:2167
7684 msgid "guestfs_inspect_get_mountpoints"
7688 #: ../src/guestfs-actions.pod:2169
7691 " char **guestfs_inspect_get_mountpoints (guestfs_h *g,\n"
7692 "\t\tconst char *root);\n"
7697 #: ../src/guestfs-actions.pod:2175 ../fish/guestfish-actions.pod:1732
7699 "This returns a hash of where we think the filesystems associated with this "
7700 "operating system should be mounted. Callers should note that this is at "
7701 "best an educated guess made by reading configuration files such as C</etc/"
7706 #: ../src/guestfs-actions.pod:2180 ../fish/guestfish-actions.pod:1737
7708 "Each element in the returned hashtable has a key which is the path of the "
7709 "mountpoint (eg. C</boot>) and a value which is the filesystem that would be "
7710 "mounted there (eg. C</dev/sda1>)."
7714 #: ../src/guestfs-actions.pod:2185 ../fish/guestfish-actions.pod:1742
7716 "Non-mounted devices such as swap devices are I<not> returned in this list."
7720 #: ../src/guestfs-actions.pod:2188
7722 "Please read L<guestfs(3)/INSPECTION> for more details. See also "
7723 "C<guestfs_inspect_get_filesystems>."
7727 #: ../src/guestfs-actions.pod:2191 ../src/guestfs-actions.pod:2531
7728 #: ../src/guestfs-actions.pod:3453 ../src/guestfs-actions.pod:5013
7730 "This function returns a NULL-terminated array of strings, or NULL if there "
7731 "was an error. The array of strings will always have length C<2n+1>, where "
7732 "C<n> keys and values alternate, followed by the trailing NULL entry. I<The "
7733 "caller must free the strings and the array after use>."
7737 #: ../src/guestfs-actions.pod:2197
7738 msgid "guestfs_inspect_get_product_name"
7742 #: ../src/guestfs-actions.pod:2199
7745 " char *guestfs_inspect_get_product_name (guestfs_h *g,\n"
7746 "\t\tconst char *root);\n"
7751 #: ../src/guestfs-actions.pod:2205 ../fish/guestfish-actions.pod:1755
7753 "This returns the product name of the inspected operating system. The "
7754 "product name is generally some freeform string which can be displayed to the "
7755 "user, but should not be parsed by programs."
7759 #: ../src/guestfs-actions.pod:2210 ../fish/guestfish-actions.pod:1760
7761 "If the product name could not be determined, then the string C<unknown> is "
7766 #: ../src/guestfs-actions.pod:2218
7767 msgid "guestfs_inspect_get_type"
7771 #: ../src/guestfs-actions.pod:2220
7774 " char *guestfs_inspect_get_type (guestfs_h *g,\n"
7775 "\t\tconst char *root);\n"
7780 #: ../src/guestfs-actions.pod:2226 ../fish/guestfish-actions.pod:1772
7782 "This returns the type of the inspected operating system. Currently defined "
7787 #: ../src/guestfs-actions.pod:2231 ../fish/guestfish-actions.pod:1777
7792 #: ../src/guestfs-actions.pod:2233 ../fish/guestfish-actions.pod:1779
7793 msgid "Any Linux-based operating system."
7797 #: ../src/guestfs-actions.pod:2237 ../fish/guestfish-actions.pod:1783
7798 msgid "Any Microsoft Windows operating system."
7802 #: ../src/guestfs-actions.pod:2241 ../fish/guestfish-actions.pod:1787
7803 msgid "The operating system type could not be determined."
7807 #: ../src/guestfs-actions.pod:2253
7808 msgid "guestfs_inspect_os"
7812 #: ../src/guestfs-actions.pod:2255
7815 " char **guestfs_inspect_os (guestfs_h *g);\n"
7820 #: ../src/guestfs-actions.pod:2257 ../fish/guestfish-actions.pod:1800
7822 "This function uses other libguestfs functions and certain heuristics to "
7823 "inspect the disk(s) (usually disks belonging to a virtual machine), looking "
7824 "for operating systems."
7828 #: ../src/guestfs-actions.pod:2261 ../fish/guestfish-actions.pod:1804
7829 msgid "The list returned is empty if no operating systems were found."
7833 #: ../src/guestfs-actions.pod:2263 ../fish/guestfish-actions.pod:1806
7835 "If one operating system was found, then this returns a list with a single "
7836 "element, which is the name of the root filesystem of this operating system. "
7837 "It is also possible for this function to return a list containing more than "
7838 "one element, indicating a dual-boot or multi-boot virtual machine, with each "
7839 "element being the root filesystem of one of the operating systems."
7843 #: ../src/guestfs-actions.pod:2270
7845 "You can pass the root string(s) returned to other C<guestfs_inspect_get_*> "
7846 "functions in order to query further information about each operating system, "
7847 "such as the name and version."
7851 #: ../src/guestfs-actions.pod:2275
7853 "This function uses other libguestfs features such as C<guestfs_mount_ro> and "
7854 "C<guestfs_umount_all> in order to mount and unmount filesystems and look at "
7855 "the contents. This should be called with no disks currently mounted. The "
7856 "function may also use Augeas, so any existing Augeas handle will be closed."
7860 #: ../src/guestfs-actions.pod:2281 ../fish/guestfish-actions.pod:1824
7862 "This function cannot decrypt encrypted disks. The caller must do that first "
7863 "(supplying the necessary keys) if the disk is encrypted."
7867 #: ../src/guestfs-actions.pod:2287 ../src/guestfs-actions.pod:2492
7868 #: ../src/guestfs-actions.pod:2548
7869 msgid "See also C<guestfs_list_filesystems>."
7873 #: ../src/guestfs-actions.pod:2293
7874 msgid "guestfs_is_blockdev"
7878 #: ../src/guestfs-actions.pod:2295
7881 " int guestfs_is_blockdev (guestfs_h *g,\n"
7882 "\t\tconst char *path);\n"
7887 #: ../src/guestfs-actions.pod:2298 ../fish/guestfish-actions.pod:1836
7889 "This returns C<true> if and only if there is a block device with the given "
7894 #: ../src/guestfs-actions.pod:2301 ../src/guestfs-actions.pod:2324
7895 #: ../src/guestfs-actions.pod:2348 ../src/guestfs-actions.pod:2360
7896 #: ../src/guestfs-actions.pod:2373 ../src/guestfs-actions.pod:2417
7897 #: ../src/guestfs-actions.pod:2429
7898 msgid "See also C<guestfs_stat>."
7902 #: ../src/guestfs-actions.pod:2305
7903 msgid "guestfs_is_busy"
7907 #: ../src/guestfs-actions.pod:2307
7910 " int guestfs_is_busy (guestfs_h *g);\n"
7915 #: ../src/guestfs-actions.pod:2309 ../fish/guestfish-actions.pod:1845
7917 "This returns true iff this handle is busy processing a command (in the "
7922 #: ../src/guestfs-actions.pod:2316
7923 msgid "guestfs_is_chardev"
7927 #: ../src/guestfs-actions.pod:2318
7930 " int guestfs_is_chardev (guestfs_h *g,\n"
7931 "\t\tconst char *path);\n"
7936 #: ../src/guestfs-actions.pod:2321 ../fish/guestfish-actions.pod:1854
7938 "This returns C<true> if and only if there is a character device with the "
7939 "given C<path> name."
7943 #: ../src/guestfs-actions.pod:2328
7944 msgid "guestfs_is_config"
7948 #: ../src/guestfs-actions.pod:2330
7951 " int guestfs_is_config (guestfs_h *g);\n"
7956 #: ../src/guestfs-actions.pod:2332 ../fish/guestfish-actions.pod:1863
7958 "This returns true iff this handle is being configured (in the C<CONFIG> "
7963 #: ../src/guestfs-actions.pod:2339
7964 msgid "guestfs_is_dir"
7968 #: ../src/guestfs-actions.pod:2341
7971 " int guestfs_is_dir (guestfs_h *g,\n"
7972 "\t\tconst char *path);\n"
7977 #: ../src/guestfs-actions.pod:2344 ../fish/guestfish-actions.pod:1872
7979 "This returns C<true> if and only if there is a directory with the given "
7980 "C<path> name. Note that it returns false for other objects like files."
7984 #: ../src/guestfs-actions.pod:2352
7985 msgid "guestfs_is_fifo"
7989 #: ../src/guestfs-actions.pod:2354
7992 " int guestfs_is_fifo (guestfs_h *g,\n"
7993 "\t\tconst char *path);\n"
7998 #: ../src/guestfs-actions.pod:2357 ../fish/guestfish-actions.pod:1882
8000 "This returns C<true> if and only if there is a FIFO (named pipe) with the "
8001 "given C<path> name."
8005 #: ../src/guestfs-actions.pod:2364
8006 msgid "guestfs_is_file"
8010 #: ../src/guestfs-actions.pod:2366
8013 " int guestfs_is_file (guestfs_h *g,\n"
8014 "\t\tconst char *path);\n"
8019 #: ../src/guestfs-actions.pod:2369 ../fish/guestfish-actions.pod:1891
8021 "This returns C<true> if and only if there is a regular file with the given "
8022 "C<path> name. Note that it returns false for other objects like directories."
8026 #: ../src/guestfs-actions.pod:2377
8027 msgid "guestfs_is_launching"
8031 #: ../src/guestfs-actions.pod:2379
8034 " int guestfs_is_launching (guestfs_h *g);\n"
8039 #: ../src/guestfs-actions.pod:2381 ../fish/guestfish-actions.pod:1901
8041 "This returns true iff this handle is launching the subprocess (in the "
8042 "C<LAUNCHING> state)."
8046 #: ../src/guestfs-actions.pod:2388
8047 msgid "guestfs_is_lv"
8051 #: ../src/guestfs-actions.pod:2390
8054 " int guestfs_is_lv (guestfs_h *g,\n"
8055 "\t\tconst char *device);\n"
8060 #: ../src/guestfs-actions.pod:2393 ../fish/guestfish-actions.pod:1910
8062 "This command tests whether C<device> is a logical volume, and returns true "
8063 "iff this is the case."
8067 #: ../src/guestfs-actions.pod:2398
8068 msgid "guestfs_is_ready"
8072 #: ../src/guestfs-actions.pod:2400
8075 " int guestfs_is_ready (guestfs_h *g);\n"
8080 #: ../src/guestfs-actions.pod:2402 ../fish/guestfish-actions.pod:1917
8082 "This returns true iff this handle is ready to accept commands (in the "
8087 #: ../src/guestfs-actions.pod:2409
8088 msgid "guestfs_is_socket"
8092 #: ../src/guestfs-actions.pod:2411
8095 " int guestfs_is_socket (guestfs_h *g,\n"
8096 "\t\tconst char *path);\n"
8101 #: ../src/guestfs-actions.pod:2414 ../fish/guestfish-actions.pod:1926
8103 "This returns C<true> if and only if there is a Unix domain socket with the "
8104 "given C<path> name."
8108 #: ../src/guestfs-actions.pod:2421
8109 msgid "guestfs_is_symlink"
8113 #: ../src/guestfs-actions.pod:2423
8116 " int guestfs_is_symlink (guestfs_h *g,\n"
8117 "\t\tconst char *path);\n"
8122 #: ../src/guestfs-actions.pod:2426 ../fish/guestfish-actions.pod:1935
8124 "This returns C<true> if and only if there is a symbolic link with the given "
8129 #: ../src/guestfs-actions.pod:2433
8130 msgid "guestfs_kill_subprocess"
8134 #: ../src/guestfs-actions.pod:2435
8137 " int guestfs_kill_subprocess (guestfs_h *g);\n"
8142 #: ../src/guestfs-actions.pod:2437 ../fish/guestfish-actions.pod:1944
8143 msgid "This kills the qemu subprocess. You should never need to call this."
8147 #: ../src/guestfs-actions.pod:2441
8148 msgid "guestfs_launch"
8152 #: ../src/guestfs-actions.pod:2443
8155 " int guestfs_launch (guestfs_h *g);\n"
8160 #: ../src/guestfs-actions.pod:2445 ../fish/guestfish-actions.pod:1952
8162 "Internally libguestfs is implemented by running a virtual machine using "
8167 #: ../src/guestfs-actions.pod:2448 ../fish/guestfish-actions.pod:1955
8169 "You should call this after configuring the handle (eg. adding drives) but "
8170 "before performing any actions."
8174 #: ../src/guestfs-actions.pod:2453
8175 msgid "guestfs_lchown"
8179 #: ../src/guestfs-actions.pod:2455
8182 " int guestfs_lchown (guestfs_h *g,\n"
8185 "\t\tconst char *path);\n"
8190 #: ../src/guestfs-actions.pod:2460
8192 "Change the file owner to C<owner> and group to C<group>. This is like "
8193 "C<guestfs_chown> but if C<path> is a symlink then the link itself is "
8194 "changed, not the target."
8198 #: ../src/guestfs-actions.pod:2470
8199 msgid "guestfs_lgetxattrs"
8203 #: ../src/guestfs-actions.pod:2472
8206 " struct guestfs_xattr_list *guestfs_lgetxattrs (guestfs_h *g,\n"
8207 "\t\tconst char *path);\n"
8212 #: ../src/guestfs-actions.pod:2475
8214 "This is the same as C<guestfs_getxattrs>, but if C<path> is a symbolic link, "
8215 "then it returns the extended attributes of the link itself."
8219 #: ../src/guestfs-actions.pod:2484
8220 msgid "guestfs_list_devices"
8224 #: ../src/guestfs-actions.pod:2486
8227 " char **guestfs_list_devices (guestfs_h *g);\n"
8232 #: ../src/guestfs-actions.pod:2488 ../fish/guestfish-actions.pod:1982
8233 msgid "List all the block devices."
8237 #: ../src/guestfs-actions.pod:2490 ../fish/guestfish-actions.pod:1984
8238 msgid "The full block device names are returned, eg. C</dev/sda>."
8242 #: ../src/guestfs-actions.pod:2498
8243 msgid "guestfs_list_filesystems"
8247 #: ../src/guestfs-actions.pod:2500
8250 " char **guestfs_list_filesystems (guestfs_h *g);\n"
8255 #: ../src/guestfs-actions.pod:2502 ../fish/guestfish-actions.pod:1992
8257 "This inspection command looks for filesystems on partitions, block devices "
8258 "and logical volumes, returning a list of devices containing filesystems and "
8263 #: ../src/guestfs-actions.pod:2506 ../fish/guestfish-actions.pod:1996
8265 "The return value is a hash, where the keys are the devices containing "
8266 "filesystems, and the values are the filesystem types. For example:"
8270 #: ../src/guestfs-actions.pod:2510 ../fish/guestfish-actions.pod:2000
8273 " \"/dev/sda1\" => \"ntfs\"\n"
8274 " \"/dev/sda2\" => \"ext2\"\n"
8275 " \"/dev/vg_guest/lv_root\" => \"ext4\"\n"
8276 " \"/dev/vg_guest/lv_swap\" => \"swap\"\n"
8281 #: ../src/guestfs-actions.pod:2515 ../fish/guestfish-actions.pod:2005
8283 "The value can have the special value \"unknown\", meaning the content of the "
8284 "device is undetermined or empty. \"swap\" means a Linux swap partition."
8288 #: ../src/guestfs-actions.pod:2519
8290 "This command runs other libguestfs commands, which might include "
8291 "C<guestfs_mount> and C<guestfs_umount>, and therefore you should use this "
8292 "soon after launch and only when nothing is mounted."
8296 #: ../src/guestfs-actions.pod:2523
8298 "Not all of the filesystems returned will be mountable. In particular, swap "
8299 "partitions are returned in the list. Also this command does not check that "
8300 "each filesystem found is valid and mountable, and some filesystems might be "
8301 "mountable but require special options. Filesystems may not all belong to a "
8302 "single logical operating system (use C<guestfs_inspect_os> to look for OSes)."
8306 #: ../src/guestfs-actions.pod:2537
8307 msgid "guestfs_list_partitions"
8311 #: ../src/guestfs-actions.pod:2539
8314 " char **guestfs_list_partitions (guestfs_h *g);\n"
8319 #: ../src/guestfs-actions.pod:2541 ../fish/guestfish-actions.pod:2025
8320 msgid "List all the partitions detected on all block devices."
8324 #: ../src/guestfs-actions.pod:2543 ../fish/guestfish-actions.pod:2027
8325 msgid "The full partition device names are returned, eg. C</dev/sda1>"
8329 #: ../src/guestfs-actions.pod:2545
8331 "This does not return logical volumes. For that you will need to call "
8336 #: ../src/guestfs-actions.pod:2554
8341 #: ../src/guestfs-actions.pod:2556
8344 " char *guestfs_ll (guestfs_h *g,\n"
8345 "\t\tconst char *directory);\n"
8350 #: ../src/guestfs-actions.pod:2559 ../fish/guestfish-actions.pod:2038
8352 "List the files in C<directory> (relative to the root directory, there is no "
8353 "cwd) in the format of 'ls -la'."
8357 #: ../src/guestfs-actions.pod:2562 ../fish/guestfish-actions.pod:2041
8359 "This command is mostly useful for interactive sessions. It is I<not> "
8360 "intended that you try to parse the output string."
8364 #: ../src/guestfs-actions.pod:2568
8369 #: ../src/guestfs-actions.pod:2570
8372 " int guestfs_ln (guestfs_h *g,\n"
8373 "\t\tconst char *target,\n"
8374 "\t\tconst char *linkname);\n"
8379 #: ../src/guestfs-actions.pod:2574 ../fish/guestfish-actions.pod:2048
8380 msgid "This command creates a hard link using the C<ln> command."
8384 #: ../src/guestfs-actions.pod:2578
8385 msgid "guestfs_ln_f"
8389 #: ../src/guestfs-actions.pod:2580
8392 " int guestfs_ln_f (guestfs_h *g,\n"
8393 "\t\tconst char *target,\n"
8394 "\t\tconst char *linkname);\n"
8399 #: ../src/guestfs-actions.pod:2584 ../fish/guestfish-actions.pod:2054
8401 "This command creates a hard link using the C<ln -f> command. The C<-f> "
8402 "option removes the link (C<linkname>) if it exists already."
8406 #: ../src/guestfs-actions.pod:2589
8407 msgid "guestfs_ln_s"
8411 #: ../src/guestfs-actions.pod:2591
8414 " int guestfs_ln_s (guestfs_h *g,\n"
8415 "\t\tconst char *target,\n"
8416 "\t\tconst char *linkname);\n"
8421 #: ../src/guestfs-actions.pod:2595 ../fish/guestfish-actions.pod:2061
8422 msgid "This command creates a symbolic link using the C<ln -s> command."
8426 #: ../src/guestfs-actions.pod:2599
8427 msgid "guestfs_ln_sf"
8431 #: ../src/guestfs-actions.pod:2601
8434 " int guestfs_ln_sf (guestfs_h *g,\n"
8435 "\t\tconst char *target,\n"
8436 "\t\tconst char *linkname);\n"
8441 #: ../src/guestfs-actions.pod:2605 ../fish/guestfish-actions.pod:2067
8443 "This command creates a symbolic link using the C<ln -sf> command, The C<-f> "
8444 "option removes the link (C<linkname>) if it exists already."
8448 #: ../src/guestfs-actions.pod:2610
8449 msgid "guestfs_lremovexattr"
8453 #: ../src/guestfs-actions.pod:2612
8456 " int guestfs_lremovexattr (guestfs_h *g,\n"
8457 "\t\tconst char *xattr,\n"
8458 "\t\tconst char *path);\n"
8463 #: ../src/guestfs-actions.pod:2616
8465 "This is the same as C<guestfs_removexattr>, but if C<path> is a symbolic "
8466 "link, then it removes an extended attribute of the link itself."
8470 #: ../src/guestfs-actions.pod:2622
8475 #: ../src/guestfs-actions.pod:2624
8478 " char **guestfs_ls (guestfs_h *g,\n"
8479 "\t\tconst char *directory);\n"
8484 #: ../src/guestfs-actions.pod:2627 ../fish/guestfish-actions.pod:2082
8486 "List the files in C<directory> (relative to the root directory, there is no "
8487 "cwd). The '.' and '..' entries are not returned, but hidden files are shown."
8491 #: ../src/guestfs-actions.pod:2631
8493 "This command is mostly useful for interactive sessions. Programs should "
8494 "probably use C<guestfs_readdir> instead."
8498 #: ../src/guestfs-actions.pod:2638
8499 msgid "guestfs_lsetxattr"
8503 #: ../src/guestfs-actions.pod:2640
8506 " int guestfs_lsetxattr (guestfs_h *g,\n"
8507 "\t\tconst char *xattr,\n"
8508 "\t\tconst char *val,\n"
8510 "\t\tconst char *path);\n"
8515 #: ../src/guestfs-actions.pod:2646
8517 "This is the same as C<guestfs_setxattr>, but if C<path> is a symbolic link, "
8518 "then it sets an extended attribute of the link itself."
8522 #: ../src/guestfs-actions.pod:2652
8523 msgid "guestfs_lstat"
8527 #: ../src/guestfs-actions.pod:2654
8530 " struct guestfs_stat *guestfs_lstat (guestfs_h *g,\n"
8531 "\t\tconst char *path);\n"
8536 #: ../src/guestfs-actions.pod:2657 ../src/guestfs-actions.pod:4678
8537 #: ../fish/guestfish-actions.pod:2101 ../fish/guestfish-actions.pod:3640
8538 msgid "Returns file information for the given C<path>."
8542 #: ../src/guestfs-actions.pod:2659
8544 "This is the same as C<guestfs_stat> except that if C<path> is a symbolic "
8545 "link, then the link is stat-ed, not the file it refers to."
8549 #: ../src/guestfs-actions.pod:2663 ../fish/guestfish-actions.pod:2107
8550 msgid "This is the same as the C<lstat(2)> system call."
8554 #: ../src/guestfs-actions.pod:2665 ../src/guestfs-actions.pod:4682
8556 "This function returns a C<struct guestfs_stat *>, or NULL if there was an "
8557 "error. I<The caller must call C<guestfs_free_stat> after use>."
8561 #: ../src/guestfs-actions.pod:2669
8562 msgid "guestfs_lstatlist"
8566 #: ../src/guestfs-actions.pod:2671
8569 " struct guestfs_stat_list *guestfs_lstatlist (guestfs_h *g,\n"
8570 "\t\tconst char *path,\n"
8571 "\t\tchar *const *names);\n"
8576 #: ../src/guestfs-actions.pod:2675
8578 "This call allows you to perform the C<guestfs_lstat> operation on multiple "
8579 "files, where all files are in the directory C<path>. C<names> is the list "
8580 "of files from this directory."
8584 #: ../src/guestfs-actions.pod:2679 ../fish/guestfish-actions.pod:2117
8586 "On return you get a list of stat structs, with a one-to-one correspondence "
8587 "to the C<names> list. If any name did not exist or could not be lstat'd, "
8588 "then the C<ino> field of that structure is set to C<-1>."
8592 #: ../src/guestfs-actions.pod:2684
8594 "This call is intended for programs that want to efficiently list a directory "
8595 "contents without making many round-trips. See also C<guestfs_lxattrlist> "
8596 "for a similarly efficient call for getting extended attributes. Very long "
8597 "directory listings might cause the protocol message size to be exceeded, "
8598 "causing this call to fail. The caller must split up such requests into "
8599 "smaller groups of names."
8603 #: ../src/guestfs-actions.pod:2692
8605 "This function returns a C<struct guestfs_stat_list *> (see E<lt>guestfs-"
8606 "structs.hE<gt>), or NULL if there was an error. I<The caller must call "
8607 "C<guestfs_free_stat_list> after use>."
8611 #: ../src/guestfs-actions.pod:2697
8612 msgid "guestfs_luks_add_key"
8616 #: ../src/guestfs-actions.pod:2699
8619 " int guestfs_luks_add_key (guestfs_h *g,\n"
8620 "\t\tconst char *device,\n"
8621 "\t\tconst char *key,\n"
8622 "\t\tconst char *newkey,\n"
8623 "\t\tint keyslot);\n"
8628 #: ../src/guestfs-actions.pod:2705 ../fish/guestfish-actions.pod:2134
8630 "This command adds a new key on LUKS device C<device>. C<key> is any "
8631 "existing key, and is used to access the device. C<newkey> is the new key to "
8632 "add. C<keyslot> is the key slot that will be replaced."
8636 #: ../src/guestfs-actions.pod:2710
8638 "Note that if C<keyslot> already contains a key, then this command will "
8639 "fail. You have to use C<guestfs_luks_kill_slot> first to remove that key."
8643 #: ../src/guestfs-actions.pod:2716 ../src/guestfs-actions.pod:2750
8644 #: ../src/guestfs-actions.pod:2770 ../src/guestfs-actions.pod:2787
8645 #: ../src/guestfs-actions.pod:2816 ../src/guestfs-actions.pod:2832
8647 "This function takes a key or passphrase parameter which could contain "
8648 "sensitive material. Read the section L</KEYS AND PASSPHRASES> for more "
8653 #: ../src/guestfs-actions.pod:2720
8654 msgid "guestfs_luks_close"
8658 #: ../src/guestfs-actions.pod:2722
8661 " int guestfs_luks_close (guestfs_h *g,\n"
8662 "\t\tconst char *device);\n"
8667 #: ../src/guestfs-actions.pod:2725
8669 "This closes a LUKS device that was created earlier by C<guestfs_luks_open> "
8670 "or C<guestfs_luks_open_ro>. The C<device> parameter must be the name of the "
8671 "LUKS mapping device (ie. C</dev/mapper/mapname>) and I<not> the name of the "
8672 "underlying block device."
8676 #: ../src/guestfs-actions.pod:2733
8677 msgid "guestfs_luks_format"
8681 #: ../src/guestfs-actions.pod:2735
8684 " int guestfs_luks_format (guestfs_h *g,\n"
8685 "\t\tconst char *device,\n"
8686 "\t\tconst char *key,\n"
8687 "\t\tint keyslot);\n"
8692 #: ../src/guestfs-actions.pod:2740 ../fish/guestfish-actions.pod:2160
8694 "This command erases existing data on C<device> and formats the device as a "
8695 "LUKS encrypted device. C<key> is the initial key, which is added to key "
8696 "slot C<slot>. (LUKS supports 8 key slots, numbered 0-7)."
8700 #: ../src/guestfs-actions.pod:2747 ../src/guestfs-actions.pod:2767
8701 #: ../src/guestfs-actions.pod:2869 ../src/guestfs-actions.pod:3581
8702 #: ../src/guestfs-actions.pod:4219 ../src/guestfs-actions.pod:4540
8703 #: ../src/guestfs-actions.pod:4560 ../src/guestfs-actions.pod:4583
8704 #: ../src/guestfs-actions.pod:5548 ../fish/guestfish-actions.pod:2168
8705 #: ../fish/guestfish-actions.pod:2181 ../fish/guestfish-actions.pod:2252
8706 #: ../fish/guestfish-actions.pod:2767 ../fish/guestfish-actions.pod:3259
8707 #: ../fish/guestfish-actions.pod:3539 ../fish/guestfish-actions.pod:3555
8708 #: ../fish/guestfish-actions.pod:3570 ../fish/guestfish-actions.pod:4285
8710 "B<This command is dangerous. Without careful use you can easily destroy all "
8715 #: ../src/guestfs-actions.pod:2754
8716 msgid "guestfs_luks_format_cipher"
8720 #: ../src/guestfs-actions.pod:2756
8723 " int guestfs_luks_format_cipher (guestfs_h *g,\n"
8724 "\t\tconst char *device,\n"
8725 "\t\tconst char *key,\n"
8726 "\t\tint keyslot,\n"
8727 "\t\tconst char *cipher);\n"
8732 #: ../src/guestfs-actions.pod:2762
8734 "This command is the same as C<guestfs_luks_format> but it also allows you to "
8735 "set the C<cipher> used."
8739 #: ../src/guestfs-actions.pod:2774
8740 msgid "guestfs_luks_kill_slot"
8744 #: ../src/guestfs-actions.pod:2776
8747 " int guestfs_luks_kill_slot (guestfs_h *g,\n"
8748 "\t\tconst char *device,\n"
8749 "\t\tconst char *key,\n"
8750 "\t\tint keyslot);\n"
8755 #: ../src/guestfs-actions.pod:2781 ../fish/guestfish-actions.pod:2188
8757 "This command deletes the key in key slot C<keyslot> from the encrypted LUKS "
8758 "device C<device>. C<key> must be one of the I<other> keys."
8762 #: ../src/guestfs-actions.pod:2791
8763 msgid "guestfs_luks_open"
8767 #: ../src/guestfs-actions.pod:2793
8770 " int guestfs_luks_open (guestfs_h *g,\n"
8771 "\t\tconst char *device,\n"
8772 "\t\tconst char *key,\n"
8773 "\t\tconst char *mapname);\n"
8778 #: ../src/guestfs-actions.pod:2798 ../fish/guestfish-actions.pod:2199
8780 "This command opens a block device which has been encrypted according to the "
8781 "Linux Unified Key Setup (LUKS) standard."
8785 #: ../src/guestfs-actions.pod:2801 ../fish/guestfish-actions.pod:2202
8786 msgid "C<device> is the encrypted block device or partition."
8790 #: ../src/guestfs-actions.pod:2803 ../fish/guestfish-actions.pod:2204
8792 "The caller must supply one of the keys associated with the LUKS block "
8793 "device, in the C<key> parameter."
8797 #: ../src/guestfs-actions.pod:2806 ../fish/guestfish-actions.pod:2207
8799 "This creates a new block device called C</dev/mapper/mapname>. Reads and "
8800 "writes to this block device are decrypted from and encrypted to the "
8801 "underlying C<device> respectively."
8805 #: ../src/guestfs-actions.pod:2810
8807 "If this block device contains LVM volume groups, then calling "
8808 "C<guestfs_vgscan> followed by C<guestfs_vg_activate_all> will make them "
8813 #: ../src/guestfs-actions.pod:2820
8814 msgid "guestfs_luks_open_ro"
8818 #: ../src/guestfs-actions.pod:2822
8821 " int guestfs_luks_open_ro (guestfs_h *g,\n"
8822 "\t\tconst char *device,\n"
8823 "\t\tconst char *key,\n"
8824 "\t\tconst char *mapname);\n"
8829 #: ../src/guestfs-actions.pod:2827
8831 "This is the same as C<guestfs_luks_open> except that a read-only mapping is "
8836 #: ../src/guestfs-actions.pod:2836
8837 msgid "guestfs_lvcreate"
8841 #: ../src/guestfs-actions.pod:2838
8844 " int guestfs_lvcreate (guestfs_h *g,\n"
8845 "\t\tconst char *logvol,\n"
8846 "\t\tconst char *volgroup,\n"
8847 "\t\tint mbytes);\n"
8852 #: ../src/guestfs-actions.pod:2843 ../fish/guestfish-actions.pod:2232
8854 "This creates an LVM logical volume called C<logvol> on the volume group "
8855 "C<volgroup>, with C<size> megabytes."
8859 #: ../src/guestfs-actions.pod:2848
8860 msgid "guestfs_lvm_clear_filter"
8864 #: ../src/guestfs-actions.pod:2850
8867 " int guestfs_lvm_clear_filter (guestfs_h *g);\n"
8872 #: ../src/guestfs-actions.pod:2852
8874 "This undoes the effect of C<guestfs_lvm_set_filter>. LVM will be able to "
8875 "see every block device."
8879 #: ../src/guestfs-actions.pod:2855 ../src/guestfs-actions.pod:2891
8880 #: ../fish/guestfish-actions.pod:2242 ../fish/guestfish-actions.pod:2273
8882 "This command also clears the LVM cache and performs a volume group scan."
8886 #: ../src/guestfs-actions.pod:2860
8887 msgid "guestfs_lvm_remove_all"
8891 #: ../src/guestfs-actions.pod:2862
8894 " int guestfs_lvm_remove_all (guestfs_h *g);\n"
8899 #: ../src/guestfs-actions.pod:2864 ../fish/guestfish-actions.pod:2249
8901 "This command removes all LVM logical volumes, volume groups and physical "
8906 #: ../src/guestfs-actions.pod:2872
8907 msgid "guestfs_lvm_set_filter"
8911 #: ../src/guestfs-actions.pod:2874
8914 " int guestfs_lvm_set_filter (guestfs_h *g,\n"
8915 "\t\tchar *const *devices);\n"
8920 #: ../src/guestfs-actions.pod:2877 ../fish/guestfish-actions.pod:2259
8922 "This sets the LVM device filter so that LVM will only be able to \"see\" the "
8923 "block devices in the list C<devices>, and will ignore all other attached "
8928 #: ../src/guestfs-actions.pod:2881 ../fish/guestfish-actions.pod:2263
8930 "Where disk image(s) contain duplicate PVs or VGs, this command is useful to "
8931 "get LVM to ignore the duplicates, otherwise LVM can get confused. Note also "
8932 "there are two types of duplication possible: either cloned PVs/VGs which "
8933 "have identical UUIDs; or VGs that are not cloned but just happen to have the "
8934 "same name. In normal operation you cannot create this situation, but you "
8935 "can do it outside LVM, eg. by cloning disk images or by bit twiddling "
8936 "inside the LVM metadata."
8940 #: ../src/guestfs-actions.pod:2894 ../fish/guestfish-actions.pod:2276
8941 msgid "You can filter whole block devices or individual partitions."
8945 #: ../src/guestfs-actions.pod:2896 ../fish/guestfish-actions.pod:2278
8947 "You cannot use this if any VG is currently in use (eg. contains a mounted "
8948 "filesystem), even if you are not filtering out that VG."
8952 #: ../src/guestfs-actions.pod:2902
8953 msgid "guestfs_lvremove"
8957 #: ../src/guestfs-actions.pod:2904
8960 " int guestfs_lvremove (guestfs_h *g,\n"
8961 "\t\tconst char *device);\n"
8966 #: ../src/guestfs-actions.pod:2907 ../fish/guestfish-actions.pod:2286
8968 "Remove an LVM logical volume C<device>, where C<device> is the path to the "
8969 "LV, such as C</dev/VG/LV>."
8973 #: ../src/guestfs-actions.pod:2910 ../fish/guestfish-actions.pod:2289
8975 "You can also remove all LVs in a volume group by specifying the VG name, C</"
8980 #: ../src/guestfs-actions.pod:2915
8981 msgid "guestfs_lvrename"
8985 #: ../src/guestfs-actions.pod:2917
8988 " int guestfs_lvrename (guestfs_h *g,\n"
8989 "\t\tconst char *logvol,\n"
8990 "\t\tconst char *newlogvol);\n"
8995 #: ../src/guestfs-actions.pod:2921 ../fish/guestfish-actions.pod:2296
8996 msgid "Rename a logical volume C<logvol> with the new name C<newlogvol>."
9000 #: ../src/guestfs-actions.pod:2925
9001 msgid "guestfs_lvresize"
9005 #: ../src/guestfs-actions.pod:2927
9008 " int guestfs_lvresize (guestfs_h *g,\n"
9009 "\t\tconst char *device,\n"
9010 "\t\tint mbytes);\n"
9015 #: ../src/guestfs-actions.pod:2931 ../fish/guestfish-actions.pod:2302
9017 "This resizes (expands or shrinks) an existing LVM logical volume to "
9018 "C<mbytes>. When reducing, data in the reduced part is lost."
9022 #: ../src/guestfs-actions.pod:2937
9023 msgid "guestfs_lvresize_free"
9027 #: ../src/guestfs-actions.pod:2939
9030 " int guestfs_lvresize_free (guestfs_h *g,\n"
9031 "\t\tconst char *lv,\n"
9032 "\t\tint percent);\n"
9037 #: ../src/guestfs-actions.pod:2943 ../fish/guestfish-actions.pod:2310
9039 "This expands an existing logical volume C<lv> so that it fills C<pc>% of the "
9040 "remaining free space in the volume group. Commonly you would call this with "
9041 "pc = 100 which expands the logical volume as much as possible, using all "
9042 "remaining free space in the volume group."
9046 #: ../src/guestfs-actions.pod:2951
9051 #: ../src/guestfs-actions.pod:2953
9054 " char **guestfs_lvs (guestfs_h *g);\n"
9059 #: ../src/guestfs-actions.pod:2955 ../fish/guestfish-actions.pod:2320
9061 "List all the logical volumes detected. This is the equivalent of the L<lvs"
9066 #: ../src/guestfs-actions.pod:2958 ../fish/guestfish-actions.pod:2323
9068 "This returns a list of the logical volume device names (eg. C</dev/"
9069 "VolGroup00/LogVol00>)."
9073 #: ../src/guestfs-actions.pod:2961
9074 msgid "See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>."
9078 #: ../src/guestfs-actions.pod:2967
9079 msgid "guestfs_lvs_full"
9083 #: ../src/guestfs-actions.pod:2969
9086 " struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *g);\n"
9091 #: ../src/guestfs-actions.pod:2971 ../fish/guestfish-actions.pod:2332
9093 "List all the logical volumes detected. This is the equivalent of the L<lvs"
9094 "(8)> command. The \"full\" version includes all fields."
9098 #: ../src/guestfs-actions.pod:2974
9100 "This function returns a C<struct guestfs_lvm_lv_list *> (see E<lt>guestfs-"
9101 "structs.hE<gt>), or NULL if there was an error. I<The caller must call "
9102 "C<guestfs_free_lvm_lv_list> after use>."
9106 #: ../src/guestfs-actions.pod:2979
9107 msgid "guestfs_lvuuid"
9111 #: ../src/guestfs-actions.pod:2981
9114 " char *guestfs_lvuuid (guestfs_h *g,\n"
9115 "\t\tconst char *device);\n"
9120 #: ../src/guestfs-actions.pod:2984 ../fish/guestfish-actions.pod:2339
9121 msgid "This command returns the UUID of the LVM LV C<device>."
9125 #: ../src/guestfs-actions.pod:2989
9126 msgid "guestfs_lxattrlist"
9130 #: ../src/guestfs-actions.pod:2991
9133 " struct guestfs_xattr_list *guestfs_lxattrlist (guestfs_h *g,\n"
9134 "\t\tconst char *path,\n"
9135 "\t\tchar *const *names);\n"
9140 #: ../src/guestfs-actions.pod:2995 ../fish/guestfish-actions.pod:2345
9142 "This call allows you to get the extended attributes of multiple files, where "
9143 "all files are in the directory C<path>. C<names> is the list of files from "
9148 #: ../src/guestfs-actions.pod:2999 ../fish/guestfish-actions.pod:2349
9150 "On return you get a flat list of xattr structs which must be interpreted "
9151 "sequentially. The first xattr struct always has a zero-length C<attrname>. "
9152 "C<attrval> in this struct is zero-length to indicate there was an error "
9153 "doing C<lgetxattr> for this file, I<or> is a C string which is a decimal "
9154 "number (the number of following attributes for this file, which could be C<"
9155 "\"0\">). Then after the first xattr struct are the zero or more attributes "
9156 "for the first named file. This repeats for the second and subsequent files."
9160 #: ../src/guestfs-actions.pod:3009
9162 "This call is intended for programs that want to efficiently list a directory "
9163 "contents without making many round-trips. See also C<guestfs_lstatlist> for "
9164 "a similarly efficient call for getting standard stats. Very long directory "
9165 "listings might cause the protocol message size to be exceeded, causing this "
9166 "call to fail. The caller must split up such requests into smaller groups of "
9171 #: ../src/guestfs-actions.pod:3022
9172 msgid "guestfs_mkdir"
9176 #: ../src/guestfs-actions.pod:3024
9179 " int guestfs_mkdir (guestfs_h *g,\n"
9180 "\t\tconst char *path);\n"
9185 #: ../src/guestfs-actions.pod:3027 ../fish/guestfish-actions.pod:2371
9186 msgid "Create a directory named C<path>."
9190 #: ../src/guestfs-actions.pod:3031
9191 msgid "guestfs_mkdir_mode"
9195 #: ../src/guestfs-actions.pod:3033
9198 " int guestfs_mkdir_mode (guestfs_h *g,\n"
9199 "\t\tconst char *path,\n"
9205 #: ../src/guestfs-actions.pod:3037 ../fish/guestfish-actions.pod:2377
9207 "This command creates a directory, setting the initial permissions of the "
9208 "directory to C<mode>."
9212 #: ../src/guestfs-actions.pod:3040 ../fish/guestfish-actions.pod:2380
9214 "For common Linux filesystems, the actual mode which is set will be C<mode & "
9215 "~umask & 01777>. Non-native-Linux filesystems may interpret the mode in "
9220 #: ../src/guestfs-actions.pod:3044
9221 msgid "See also C<guestfs_mkdir>, C<guestfs_umask>"
9225 #: ../src/guestfs-actions.pod:3048
9226 msgid "guestfs_mkdir_p"
9230 #: ../src/guestfs-actions.pod:3050
9233 " int guestfs_mkdir_p (guestfs_h *g,\n"
9234 "\t\tconst char *path);\n"
9239 #: ../src/guestfs-actions.pod:3053 ../fish/guestfish-actions.pod:2390
9241 "Create a directory named C<path>, creating any parent directories as "
9242 "necessary. This is like the C<mkdir -p> shell command."
9246 #: ../src/guestfs-actions.pod:3058
9247 msgid "guestfs_mkdtemp"
9251 #: ../src/guestfs-actions.pod:3060
9254 " char *guestfs_mkdtemp (guestfs_h *g,\n"
9255 "\t\tconst char *template);\n"
9260 #: ../src/guestfs-actions.pod:3063 ../fish/guestfish-actions.pod:2397
9262 "This command creates a temporary directory. The C<template> parameter "
9263 "should be a full pathname for the temporary directory name with the final "
9264 "six characters being \"XXXXXX\"."
9268 #: ../src/guestfs-actions.pod:3068 ../fish/guestfish-actions.pod:2402
9270 "For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\", the second one "
9271 "being suitable for Windows filesystems."
9275 #: ../src/guestfs-actions.pod:3071 ../fish/guestfish-actions.pod:2405
9276 msgid "The name of the temporary directory that was created is returned."
9280 #: ../src/guestfs-actions.pod:3074 ../fish/guestfish-actions.pod:2408
9281 msgid "The temporary directory is created with mode 0700 and is owned by root."
9285 #: ../src/guestfs-actions.pod:3077 ../fish/guestfish-actions.pod:2411
9287 "The caller is responsible for deleting the temporary directory and its "
9288 "contents after use."
9292 #: ../src/guestfs-actions.pod:3080 ../fish/guestfish-actions.pod:2414
9293 msgid "See also: L<mkdtemp(3)>"
9297 #: ../src/guestfs-actions.pod:3085
9298 msgid "guestfs_mke2fs_J"
9302 #: ../src/guestfs-actions.pod:3087
9305 " int guestfs_mke2fs_J (guestfs_h *g,\n"
9306 "\t\tconst char *fstype,\n"
9307 "\t\tint blocksize,\n"
9308 "\t\tconst char *device,\n"
9309 "\t\tconst char *journal);\n"
9314 #: ../src/guestfs-actions.pod:3093 ../fish/guestfish-actions.pod:2420
9316 "This creates an ext2/3/4 filesystem on C<device> with an external journal on "
9317 "C<journal>. It is equivalent to the command:"
9321 #: ../src/guestfs-actions.pod:3097 ../fish/guestfish-actions.pod:2424
9324 " mke2fs -t fstype -b blocksize -J device=<journal> <device>\n"
9329 #: ../src/guestfs-actions.pod:3099
9330 msgid "See also C<guestfs_mke2journal>."
9334 #: ../src/guestfs-actions.pod:3103
9335 msgid "guestfs_mke2fs_JL"
9339 #: ../src/guestfs-actions.pod:3105
9342 " int guestfs_mke2fs_JL (guestfs_h *g,\n"
9343 "\t\tconst char *fstype,\n"
9344 "\t\tint blocksize,\n"
9345 "\t\tconst char *device,\n"
9346 "\t\tconst char *label);\n"
9351 #: ../src/guestfs-actions.pod:3111 ../fish/guestfish-actions.pod:2432
9353 "This creates an ext2/3/4 filesystem on C<device> with an external journal on "
9354 "the journal labeled C<label>."
9358 #: ../src/guestfs-actions.pod:3114
9359 msgid "See also C<guestfs_mke2journal_L>."
9363 #: ../src/guestfs-actions.pod:3118
9364 msgid "guestfs_mke2fs_JU"
9368 #: ../src/guestfs-actions.pod:3120
9371 " int guestfs_mke2fs_JU (guestfs_h *g,\n"
9372 "\t\tconst char *fstype,\n"
9373 "\t\tint blocksize,\n"
9374 "\t\tconst char *device,\n"
9375 "\t\tconst char *uuid);\n"
9380 #: ../src/guestfs-actions.pod:3126 ../fish/guestfish-actions.pod:2441
9382 "This creates an ext2/3/4 filesystem on C<device> with an external journal on "
9383 "the journal with UUID C<uuid>."
9387 #: ../src/guestfs-actions.pod:3129
9388 msgid "See also C<guestfs_mke2journal_U>."
9392 #: ../src/guestfs-actions.pod:3133
9393 msgid "guestfs_mke2journal"
9397 #: ../src/guestfs-actions.pod:3135
9400 " int guestfs_mke2journal (guestfs_h *g,\n"
9401 "\t\tint blocksize,\n"
9402 "\t\tconst char *device);\n"
9407 #: ../src/guestfs-actions.pod:3139 ../fish/guestfish-actions.pod:2450
9409 "This creates an ext2 external journal on C<device>. It is equivalent to the "
9414 #: ../src/guestfs-actions.pod:3142 ../fish/guestfish-actions.pod:2453
9417 " mke2fs -O journal_dev -b blocksize device\n"
9422 #: ../src/guestfs-actions.pod:3146
9423 msgid "guestfs_mke2journal_L"
9427 #: ../src/guestfs-actions.pod:3148
9430 " int guestfs_mke2journal_L (guestfs_h *g,\n"
9431 "\t\tint blocksize,\n"
9432 "\t\tconst char *label,\n"
9433 "\t\tconst char *device);\n"
9438 #: ../src/guestfs-actions.pod:3153 ../fish/guestfish-actions.pod:2459
9439 msgid "This creates an ext2 external journal on C<device> with label C<label>."
9443 #: ../src/guestfs-actions.pod:3157
9444 msgid "guestfs_mke2journal_U"
9448 #: ../src/guestfs-actions.pod:3159
9451 " int guestfs_mke2journal_U (guestfs_h *g,\n"
9452 "\t\tint blocksize,\n"
9453 "\t\tconst char *uuid,\n"
9454 "\t\tconst char *device);\n"
9459 #: ../src/guestfs-actions.pod:3164 ../fish/guestfish-actions.pod:2465
9460 msgid "This creates an ext2 external journal on C<device> with UUID C<uuid>."
9464 #: ../src/guestfs-actions.pod:3168
9465 msgid "guestfs_mkfifo"
9469 #: ../src/guestfs-actions.pod:3170
9472 " int guestfs_mkfifo (guestfs_h *g,\n"
9474 "\t\tconst char *path);\n"
9479 #: ../src/guestfs-actions.pod:3174
9481 "This call creates a FIFO (named pipe) called C<path> with mode C<mode>. It "
9482 "is just a convenient wrapper around C<guestfs_mknod>."
9486 #: ../src/guestfs-actions.pod:3182
9487 msgid "guestfs_mkfs"
9491 #: ../src/guestfs-actions.pod:3184
9494 " int guestfs_mkfs (guestfs_h *g,\n"
9495 "\t\tconst char *fstype,\n"
9496 "\t\tconst char *device);\n"
9501 #: ../src/guestfs-actions.pod:3188 ../fish/guestfish-actions.pod:2481
9503 "This creates a filesystem on C<device> (usually a partition or LVM logical "
9504 "volume). The filesystem type is C<fstype>, for example C<ext3>."
9508 #: ../src/guestfs-actions.pod:3194
9509 msgid "guestfs_mkfs_b"
9513 #: ../src/guestfs-actions.pod:3196
9516 " int guestfs_mkfs_b (guestfs_h *g,\n"
9517 "\t\tconst char *fstype,\n"
9518 "\t\tint blocksize,\n"
9519 "\t\tconst char *device);\n"
9524 #: ../src/guestfs-actions.pod:3201
9526 "This call is similar to C<guestfs_mkfs>, but it allows you to control the "
9527 "block size of the resulting filesystem. Supported block sizes depend on the "
9528 "filesystem type, but typically they are C<1024>, C<2048> or C<4096> only."
9532 #: ../src/guestfs-actions.pod:3206 ../fish/guestfish-actions.pod:2494
9534 "For VFAT and NTFS the C<blocksize> parameter is treated as the requested "
9539 #: ../src/guestfs-actions.pod:3211
9540 msgid "guestfs_mkmountpoint"
9544 #: ../src/guestfs-actions.pod:3213
9547 " int guestfs_mkmountpoint (guestfs_h *g,\n"
9548 "\t\tconst char *exemptpath);\n"
9553 #: ../src/guestfs-actions.pod:3216
9555 "C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are specialized calls "
9556 "that can be used to create extra mountpoints before mounting the first "
9561 #: ../src/guestfs-actions.pod:3220 ../fish/guestfish-actions.pod:2505
9563 "These calls are I<only> necessary in some very limited circumstances, mainly "
9564 "the case where you want to mount a mix of unrelated and/or read-only "
9565 "filesystems together."
9569 #: ../src/guestfs-actions.pod:3224 ../fish/guestfish-actions.pod:2509
9571 "For example, live CDs often contain a \"Russian doll\" nest of filesystems, "
9572 "an ISO outer layer, with a squashfs image inside, with an ext2/3 image "
9573 "inside that. You can unpack this as follows in guestfish:"
9577 #: ../src/guestfs-actions.pod:3229 ../fish/guestfish-actions.pod:2514
9580 " add-ro Fedora-11-i686-Live.iso\n"
9582 " mkmountpoint /cd\n"
9583 " mkmountpoint /squash\n"
9584 " mkmountpoint /ext3\n"
9585 " mount /dev/sda /cd\n"
9586 " mount-loop /cd/LiveOS/squashfs.img /squash\n"
9587 " mount-loop /squash/LiveOS/ext3fs.img /ext3\n"
9592 #: ../src/guestfs-actions.pod:3238 ../fish/guestfish-actions.pod:2523
9593 msgid "The inner filesystem is now unpacked under the /ext3 mountpoint."
9597 #: ../src/guestfs-actions.pod:3242
9598 msgid "guestfs_mknod"
9602 #: ../src/guestfs-actions.pod:3244
9605 " int guestfs_mknod (guestfs_h *g,\n"
9607 "\t\tint devmajor,\n"
9608 "\t\tint devminor,\n"
9609 "\t\tconst char *path);\n"
9614 #: ../src/guestfs-actions.pod:3250 ../fish/guestfish-actions.pod:2529
9616 "This call creates block or character special devices, or named pipes (FIFOs)."
9620 #: ../src/guestfs-actions.pod:3253 ../fish/guestfish-actions.pod:2532
9622 "The C<mode> parameter should be the mode, using the standard constants. "
9623 "C<devmajor> and C<devminor> are the device major and minor numbers, only "
9624 "used when creating block and character special devices."
9628 #: ../src/guestfs-actions.pod:3258
9630 "Note that, just like L<mknod(2)>, the mode must be bitwise OR'd with "
9631 "S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates a "
9632 "regular file). These constants are available in the standard Linux header "
9633 "files, or you can use C<guestfs_mknod_b>, C<guestfs_mknod_c> or "
9634 "C<guestfs_mkfifo> which are wrappers around this command which bitwise OR in "
9635 "the appropriate constant for you."
9639 #: ../src/guestfs-actions.pod:3270
9640 msgid "guestfs_mknod_b"
9644 #: ../src/guestfs-actions.pod:3272
9647 " int guestfs_mknod_b (guestfs_h *g,\n"
9649 "\t\tint devmajor,\n"
9650 "\t\tint devminor,\n"
9651 "\t\tconst char *path);\n"
9656 #: ../src/guestfs-actions.pod:3278
9658 "This call creates a block device node called C<path> with mode C<mode> and "
9659 "device major/minor C<devmajor> and C<devminor>. It is just a convenient "
9660 "wrapper around C<guestfs_mknod>."
9664 #: ../src/guestfs-actions.pod:3286
9665 msgid "guestfs_mknod_c"
9669 #: ../src/guestfs-actions.pod:3288
9672 " int guestfs_mknod_c (guestfs_h *g,\n"
9674 "\t\tint devmajor,\n"
9675 "\t\tint devminor,\n"
9676 "\t\tconst char *path);\n"
9681 #: ../src/guestfs-actions.pod:3294
9683 "This call creates a char device node called C<path> with mode C<mode> and "
9684 "device major/minor C<devmajor> and C<devminor>. It is just a convenient "
9685 "wrapper around C<guestfs_mknod>."
9689 #: ../src/guestfs-actions.pod:3302
9690 msgid "guestfs_mkswap"
9694 #: ../src/guestfs-actions.pod:3304
9697 " int guestfs_mkswap (guestfs_h *g,\n"
9698 "\t\tconst char *device);\n"
9703 #: ../src/guestfs-actions.pod:3307 ../fish/guestfish-actions.pod:2571
9704 msgid "Create a swap partition on C<device>."
9708 #: ../src/guestfs-actions.pod:3311
9709 msgid "guestfs_mkswap_L"
9713 #: ../src/guestfs-actions.pod:3313
9716 " int guestfs_mkswap_L (guestfs_h *g,\n"
9717 "\t\tconst char *label,\n"
9718 "\t\tconst char *device);\n"
9723 #: ../src/guestfs-actions.pod:3317 ../fish/guestfish-actions.pod:2577
9724 msgid "Create a swap partition on C<device> with label C<label>."
9728 #: ../src/guestfs-actions.pod:3319 ../fish/guestfish-actions.pod:2579
9730 "Note that you cannot attach a swap label to a block device (eg. C</dev/"
9731 "sda>), just to a partition. This appears to be a limitation of the kernel "
9736 #: ../src/guestfs-actions.pod:3325
9737 msgid "guestfs_mkswap_U"
9741 #: ../src/guestfs-actions.pod:3327
9744 " int guestfs_mkswap_U (guestfs_h *g,\n"
9745 "\t\tconst char *uuid,\n"
9746 "\t\tconst char *device);\n"
9751 #: ../src/guestfs-actions.pod:3331 ../fish/guestfish-actions.pod:2587
9752 msgid "Create a swap partition on C<device> with UUID C<uuid>."
9756 #: ../src/guestfs-actions.pod:3335
9757 msgid "guestfs_mkswap_file"
9761 #: ../src/guestfs-actions.pod:3337
9764 " int guestfs_mkswap_file (guestfs_h *g,\n"
9765 "\t\tconst char *path);\n"
9770 #: ../src/guestfs-actions.pod:3340 ../fish/guestfish-actions.pod:2593
9771 msgid "Create a swap file."
9775 #: ../src/guestfs-actions.pod:3342
9777 "This command just writes a swap file signature to an existing file. To "
9778 "create the file itself, use something like C<guestfs_fallocate>."
9782 #: ../src/guestfs-actions.pod:3347
9783 msgid "guestfs_modprobe"
9787 #: ../src/guestfs-actions.pod:3349
9790 " int guestfs_modprobe (guestfs_h *g,\n"
9791 "\t\tconst char *modulename);\n"
9796 #: ../src/guestfs-actions.pod:3352 ../fish/guestfish-actions.pod:2602
9797 msgid "This loads a kernel module in the appliance."
9801 #: ../src/guestfs-actions.pod:3354 ../fish/guestfish-actions.pod:2604
9803 "The kernel module must have been whitelisted when libguestfs was built (see "
9804 "C<appliance/kmod.whitelist.in> in the source)."
9808 #: ../src/guestfs-actions.pod:3359
9809 msgid "guestfs_mount"
9813 #: ../src/guestfs-actions.pod:3361
9816 " int guestfs_mount (guestfs_h *g,\n"
9817 "\t\tconst char *device,\n"
9818 "\t\tconst char *mountpoint);\n"
9823 #: ../src/guestfs-actions.pod:3365 ../fish/guestfish-actions.pod:2611
9825 "Mount a guest disk at a position in the filesystem. Block devices are named "
9826 "C</dev/sda>, C</dev/sdb> and so on, as they were added to the guest. If "
9827 "those block devices contain partitions, they will have the usual names (eg. "
9828 "C</dev/sda1>). Also LVM C</dev/VG/LV>-style names can be used."
9832 #: ../src/guestfs-actions.pod:3371 ../fish/guestfish-actions.pod:2617
9834 "The rules are the same as for L<mount(2)>: A filesystem must first be "
9835 "mounted on C</> before others can be mounted. Other filesystems can only be "
9836 "mounted on directories which already exist."
9840 #: ../src/guestfs-actions.pod:3376 ../fish/guestfish-actions.pod:2622
9842 "The mounted filesystem is writable, if we have sufficient permissions on the "
9843 "underlying device."
9847 #: ../src/guestfs-actions.pod:3379
9849 "B<Important note:> When you use this call, the filesystem options C<sync> "
9850 "and C<noatime> are set implicitly. This was originally done because we "
9851 "thought it would improve reliability, but it turns out that I<-o sync> has a "
9852 "very large negative performance impact and negligible effect on "
9853 "reliability. Therefore we recommend that you avoid using C<guestfs_mount> "
9854 "in any code that needs performance, and instead use C<guestfs_mount_options> "
9855 "(use an empty string for the first parameter if you don't want any options)."
9859 #: ../src/guestfs-actions.pod:3391
9860 msgid "guestfs_mount_loop"
9864 #: ../src/guestfs-actions.pod:3393
9867 " int guestfs_mount_loop (guestfs_h *g,\n"
9868 "\t\tconst char *file,\n"
9869 "\t\tconst char *mountpoint);\n"
9874 #: ../src/guestfs-actions.pod:3397 ../fish/guestfish-actions.pod:2639
9876 "This command lets you mount C<file> (a filesystem image in a file) on a "
9877 "mount point. It is entirely equivalent to the command C<mount -o loop file "
9882 #: ../src/guestfs-actions.pod:3403
9883 msgid "guestfs_mount_options"
9887 #: ../src/guestfs-actions.pod:3405
9890 " int guestfs_mount_options (guestfs_h *g,\n"
9891 "\t\tconst char *options,\n"
9892 "\t\tconst char *device,\n"
9893 "\t\tconst char *mountpoint);\n"
9898 #: ../src/guestfs-actions.pod:3410
9900 "This is the same as the C<guestfs_mount> command, but it allows you to set "
9901 "the mount options as for the L<mount(8)> I<-o> flag."
9905 #: ../src/guestfs-actions.pod:3414 ../fish/guestfish-actions.pod:2651
9907 "If the C<options> parameter is an empty string, then no options are passed "
9908 "(all options default to whatever the filesystem uses)."
9912 #: ../src/guestfs-actions.pod:3420
9913 msgid "guestfs_mount_ro"
9917 #: ../src/guestfs-actions.pod:3422
9920 " int guestfs_mount_ro (guestfs_h *g,\n"
9921 "\t\tconst char *device,\n"
9922 "\t\tconst char *mountpoint);\n"
9927 #: ../src/guestfs-actions.pod:3426
9929 "This is the same as the C<guestfs_mount> command, but it mounts the "
9930 "filesystem with the read-only (I<-o ro>) flag."
9934 #: ../src/guestfs-actions.pod:3431
9935 msgid "guestfs_mount_vfs"
9939 #: ../src/guestfs-actions.pod:3433
9942 " int guestfs_mount_vfs (guestfs_h *g,\n"
9943 "\t\tconst char *options,\n"
9944 "\t\tconst char *vfstype,\n"
9945 "\t\tconst char *device,\n"
9946 "\t\tconst char *mountpoint);\n"
9951 #: ../src/guestfs-actions.pod:3439
9953 "This is the same as the C<guestfs_mount> command, but it allows you to set "
9954 "both the mount options and the vfstype as for the L<mount(8)> I<-o> and I<-"
9959 #: ../src/guestfs-actions.pod:3445
9960 msgid "guestfs_mountpoints"
9964 #: ../src/guestfs-actions.pod:3447
9967 " char **guestfs_mountpoints (guestfs_h *g);\n"
9972 #: ../src/guestfs-actions.pod:3449
9974 "This call is similar to C<guestfs_mounts>. That call returns a list of "
9975 "devices. This one returns a hash table (map) of device name to directory "
9976 "where the device is mounted."
9980 #: ../src/guestfs-actions.pod:3459
9981 msgid "guestfs_mounts"
9985 #: ../src/guestfs-actions.pod:3461
9988 " char **guestfs_mounts (guestfs_h *g);\n"
9993 #: ../src/guestfs-actions.pod:3463 ../fish/guestfish-actions.pod:2682
9995 "This returns the list of currently mounted filesystems. It returns the list "
9996 "of devices (eg. C</dev/sda1>, C</dev/VG/LV>)."
10000 #: ../src/guestfs-actions.pod:3466 ../fish/guestfish-actions.pod:2685
10001 msgid "Some internal mounts are not shown."
10005 #: ../src/guestfs-actions.pod:3468
10006 msgid "See also: C<guestfs_mountpoints>"
10010 #: ../src/guestfs-actions.pod:3474
10015 #: ../src/guestfs-actions.pod:3476
10018 " int guestfs_mv (guestfs_h *g,\n"
10019 "\t\tconst char *src,\n"
10020 "\t\tconst char *dest);\n"
10025 #: ../src/guestfs-actions.pod:3480 ../fish/guestfish-actions.pod:2693
10027 "This moves a file from C<src> to C<dest> where C<dest> is either a "
10028 "destination filename or destination directory."
10032 #: ../src/guestfs-actions.pod:3485
10033 msgid "guestfs_ntfs_3g_probe"
10037 #: ../src/guestfs-actions.pod:3487
10040 " int guestfs_ntfs_3g_probe (guestfs_h *g,\n"
10042 "\t\tconst char *device);\n"
10047 #: ../src/guestfs-actions.pod:3491 ../fish/guestfish-actions.pod:2700
10049 "This command runs the L<ntfs-3g.probe(8)> command which probes an NTFS "
10050 "C<device> for mountability. (Not all NTFS volumes can be mounted read-"
10051 "write, and some cannot be mounted at all)."
10055 #: ../src/guestfs-actions.pod:3495 ../fish/guestfish-actions.pod:2704
10057 "C<rw> is a boolean flag. Set it to true if you want to test if the volume "
10058 "can be mounted read-write. Set it to false if you want to test if the "
10059 "volume can be mounted read-only."
10063 #: ../src/guestfs-actions.pod:3499 ../fish/guestfish-actions.pod:2708
10065 "The return value is an integer which C<0> if the operation would succeed, or "
10066 "some non-zero value documented in the L<ntfs-3g.probe(8)> manual page."
10070 #: ../src/guestfs-actions.pod:3505
10071 msgid "guestfs_ntfsresize"
10075 #: ../src/guestfs-actions.pod:3507
10078 " int guestfs_ntfsresize (guestfs_h *g,\n"
10079 "\t\tconst char *device);\n"
10084 #: ../src/guestfs-actions.pod:3510 ../fish/guestfish-actions.pod:2716
10086 "This command resizes an NTFS filesystem, expanding or shrinking it to the "
10087 "size of the underlying device. See also L<ntfsresize(8)>."
10091 #: ../src/guestfs-actions.pod:3516
10092 msgid "guestfs_ntfsresize_size"
10096 #: ../src/guestfs-actions.pod:3518
10099 " int guestfs_ntfsresize_size (guestfs_h *g,\n"
10100 "\t\tconst char *device,\n"
10101 "\t\tint64_t size);\n"
10106 #: ../src/guestfs-actions.pod:3522
10108 "This command is the same as C<guestfs_ntfsresize> except that it allows you "
10109 "to specify the new size (in bytes) explicitly."
10113 #: ../src/guestfs-actions.pod:3527
10114 msgid "guestfs_part_add"
10118 #: ../src/guestfs-actions.pod:3529
10121 " int guestfs_part_add (guestfs_h *g,\n"
10122 "\t\tconst char *device,\n"
10123 "\t\tconst char *prlogex,\n"
10124 "\t\tint64_t startsect,\n"
10125 "\t\tint64_t endsect);\n"
10130 #: ../src/guestfs-actions.pod:3535
10132 "This command adds a partition to C<device>. If there is no partition table "
10133 "on the device, call C<guestfs_part_init> first."
10137 #: ../src/guestfs-actions.pod:3538 ../fish/guestfish-actions.pod:2734
10139 "The C<prlogex> parameter is the type of partition. Normally you should pass "
10140 "C<p> or C<primary> here, but MBR partition tables also support C<l> (or "
10141 "C<logical>) and C<e> (or C<extended>) partition types."
10145 #: ../src/guestfs-actions.pod:3543 ../fish/guestfish-actions.pod:2739
10147 "C<startsect> and C<endsect> are the start and end of the partition in "
10148 "I<sectors>. C<endsect> may be negative, which means it counts backwards "
10149 "from the end of the disk (C<-1> is the last sector)."
10153 #: ../src/guestfs-actions.pod:3547
10155 "Creating a partition which covers the whole disk is not so easy. Use "
10156 "C<guestfs_part_disk> to do that."
10160 #: ../src/guestfs-actions.pod:3552
10161 msgid "guestfs_part_del"
10165 #: ../src/guestfs-actions.pod:3554
10168 " int guestfs_part_del (guestfs_h *g,\n"
10169 "\t\tconst char *device,\n"
10170 "\t\tint partnum);\n"
10175 #: ../src/guestfs-actions.pod:3558 ../fish/guestfish-actions.pod:2750
10176 msgid "This command deletes the partition numbered C<partnum> on C<device>."
10180 #: ../src/guestfs-actions.pod:3560 ../fish/guestfish-actions.pod:2752
10182 "Note that in the case of MBR partitioning, deleting an extended partition "
10183 "also deletes any logical partitions it contains."
10187 #: ../src/guestfs-actions.pod:3566
10188 msgid "guestfs_part_disk"
10192 #: ../src/guestfs-actions.pod:3568
10195 " int guestfs_part_disk (guestfs_h *g,\n"
10196 "\t\tconst char *device,\n"
10197 "\t\tconst char *parttype);\n"
10202 #: ../src/guestfs-actions.pod:3572
10204 "This command is simply a combination of C<guestfs_part_init> followed by "
10205 "C<guestfs_part_add> to create a single primary partition covering the whole "
10210 #: ../src/guestfs-actions.pod:3576
10212 "C<parttype> is the partition table type, usually C<mbr> or C<gpt>, but other "
10213 "possible values are described in C<guestfs_part_init>."
10217 #: ../src/guestfs-actions.pod:3584
10218 msgid "guestfs_part_get_bootable"
10222 #: ../src/guestfs-actions.pod:3586
10225 " int guestfs_part_get_bootable (guestfs_h *g,\n"
10226 "\t\tconst char *device,\n"
10227 "\t\tint partnum);\n"
10232 #: ../src/guestfs-actions.pod:3590 ../fish/guestfish-actions.pod:2774
10234 "This command returns true if the partition C<partnum> on C<device> has the "
10235 "bootable flag set."
10239 #: ../src/guestfs-actions.pod:3593
10240 msgid "See also C<guestfs_part_set_bootable>."
10244 #: ../src/guestfs-actions.pod:3597
10245 msgid "guestfs_part_get_mbr_id"
10249 #: ../src/guestfs-actions.pod:3599
10252 " int guestfs_part_get_mbr_id (guestfs_h *g,\n"
10253 "\t\tconst char *device,\n"
10254 "\t\tint partnum);\n"
10259 #: ../src/guestfs-actions.pod:3603 ../fish/guestfish-actions.pod:2783
10261 "Returns the MBR type byte (also known as the ID byte) from the numbered "
10262 "partition C<partnum>."
10266 #: ../src/guestfs-actions.pod:3606 ../src/guestfs-actions.pod:3768
10268 "Note that only MBR (old DOS-style) partitions have type bytes. You will get "
10269 "undefined results for other partition table types (see "
10270 "C<guestfs_part_get_parttype>)."
10274 #: ../src/guestfs-actions.pod:3612
10275 msgid "guestfs_part_get_parttype"
10279 #: ../src/guestfs-actions.pod:3614
10282 " char *guestfs_part_get_parttype (guestfs_h *g,\n"
10283 "\t\tconst char *device);\n"
10288 #: ../src/guestfs-actions.pod:3617 ../fish/guestfish-actions.pod:2794
10290 "This command examines the partition table on C<device> and returns the "
10291 "partition table type (format) being used."
10295 #: ../src/guestfs-actions.pod:3620
10297 "Common return values include: C<msdos> (a DOS/Windows style MBR partition "
10298 "table), C<gpt> (a GPT/EFI-style partition table). Other values are "
10299 "possible, although unusual. See C<guestfs_part_init> for a full list."
10303 #: ../src/guestfs-actions.pod:3628
10304 msgid "guestfs_part_init"
10308 #: ../src/guestfs-actions.pod:3630
10311 " int guestfs_part_init (guestfs_h *g,\n"
10312 "\t\tconst char *device,\n"
10313 "\t\tconst char *parttype);\n"
10318 #: ../src/guestfs-actions.pod:3634 ../fish/guestfish-actions.pod:2806
10320 "This creates an empty partition table on C<device> of one of the partition "
10321 "types listed below. Usually C<parttype> should be either C<msdos> or C<gpt> "
10322 "(for large disks)."
10326 #: ../src/guestfs-actions.pod:3638
10328 "Initially there are no partitions. Following this, you should call "
10329 "C<guestfs_part_add> for each partition required."
10333 #: ../src/guestfs-actions.pod:3641 ../fish/guestfish-actions.pod:2813
10334 msgid "Possible values for C<parttype> are:"
10338 #: ../src/guestfs-actions.pod:3645 ../fish/guestfish-actions.pod:2817
10339 msgid "B<efi> | B<gpt>"
10343 #: ../src/guestfs-actions.pod:3647 ../fish/guestfish-actions.pod:2819
10344 msgid "Intel EFI / GPT partition table."
10348 #: ../src/guestfs-actions.pod:3649 ../fish/guestfish-actions.pod:2821
10350 "This is recommended for >= 2 TB partitions that will be accessed from Linux "
10351 "and Intel-based Mac OS X. It also has limited backwards compatibility with "
10352 "the C<mbr> format."
10356 #: ../src/guestfs-actions.pod:3653 ../fish/guestfish-actions.pod:2825
10357 msgid "B<mbr> | B<msdos>"
10361 #: ../src/guestfs-actions.pod:3655 ../fish/guestfish-actions.pod:2827
10363 "The standard PC \"Master Boot Record\" (MBR) format used by MS-DOS and "
10364 "Windows. This partition type will B<only> work for device sizes up to 2 "
10365 "TB. For large disks we recommend using C<gpt>."
10369 #: ../src/guestfs-actions.pod:3662 ../fish/guestfish-actions.pod:2834
10371 "Other partition table types that may work but are not supported include:"
10375 #: ../src/guestfs-actions.pod:3667 ../fish/guestfish-actions.pod:2839
10380 #: ../src/guestfs-actions.pod:3669 ../fish/guestfish-actions.pod:2841
10381 msgid "AIX disk labels."
10385 #: ../src/guestfs-actions.pod:3671 ../fish/guestfish-actions.pod:2843
10386 msgid "B<amiga> | B<rdb>"
10390 #: ../src/guestfs-actions.pod:3673 ../fish/guestfish-actions.pod:2845
10391 msgid "Amiga \"Rigid Disk Block\" format."
10395 #: ../src/guestfs-actions.pod:3675 ../fish/guestfish-actions.pod:2847
10400 #: ../src/guestfs-actions.pod:3677 ../fish/guestfish-actions.pod:2849
10401 msgid "BSD disk labels."
10405 #: ../src/guestfs-actions.pod:3679 ../fish/guestfish-actions.pod:2851
10410 #: ../src/guestfs-actions.pod:3681 ../fish/guestfish-actions.pod:2853
10411 msgid "DASD, used on IBM mainframes."
10415 #: ../src/guestfs-actions.pod:3683 ../fish/guestfish-actions.pod:2855
10420 #: ../src/guestfs-actions.pod:3685 ../fish/guestfish-actions.pod:2857
10421 msgid "MIPS/SGI volumes."
10425 #: ../src/guestfs-actions.pod:3687 ../fish/guestfish-actions.pod:2859
10430 #: ../src/guestfs-actions.pod:3689 ../fish/guestfish-actions.pod:2861
10431 msgid "Old Mac partition format. Modern Macs use C<gpt>."
10435 #: ../src/guestfs-actions.pod:3691 ../fish/guestfish-actions.pod:2863
10440 #: ../src/guestfs-actions.pod:3693 ../fish/guestfish-actions.pod:2865
10441 msgid "NEC PC-98 format, common in Japan apparently."
10445 #: ../src/guestfs-actions.pod:3695 ../fish/guestfish-actions.pod:2867
10450 #: ../src/guestfs-actions.pod:3697 ../fish/guestfish-actions.pod:2869
10451 msgid "Sun disk labels."
10455 #: ../src/guestfs-actions.pod:3703
10456 msgid "guestfs_part_list"
10460 #: ../src/guestfs-actions.pod:3705
10463 " struct guestfs_partition_list *guestfs_part_list (guestfs_h *g,\n"
10464 "\t\tconst char *device);\n"
10469 #: ../src/guestfs-actions.pod:3708 ../fish/guestfish-actions.pod:2877
10471 "This command parses the partition table on C<device> and returns the list of "
10472 "partitions found."
10476 #: ../src/guestfs-actions.pod:3711 ../fish/guestfish-actions.pod:2880
10477 msgid "The fields in the returned structure are:"
10481 #: ../src/guestfs-actions.pod:3715 ../fish/guestfish-actions.pod:2884
10482 msgid "B<part_num>"
10486 #: ../src/guestfs-actions.pod:3717 ../fish/guestfish-actions.pod:2886
10487 msgid "Partition number, counting from 1."
10491 #: ../src/guestfs-actions.pod:3719 ../fish/guestfish-actions.pod:2888
10492 msgid "B<part_start>"
10496 #: ../src/guestfs-actions.pod:3721
10498 "Start of the partition I<in bytes>. To get sectors you have to divide by "
10499 "the device's sector size, see C<guestfs_blockdev_getss>."
10503 #: ../src/guestfs-actions.pod:3724 ../fish/guestfish-actions.pod:2893
10504 msgid "B<part_end>"
10508 #: ../src/guestfs-actions.pod:3726 ../fish/guestfish-actions.pod:2895
10509 msgid "End of the partition in bytes."
10513 #: ../src/guestfs-actions.pod:3728 ../fish/guestfish-actions.pod:2897
10514 msgid "B<part_size>"
10518 #: ../src/guestfs-actions.pod:3730 ../fish/guestfish-actions.pod:2899
10519 msgid "Size of the partition in bytes."
10523 #: ../src/guestfs-actions.pod:3734
10525 "This function returns a C<struct guestfs_partition_list *> (see E<lt>guestfs-"
10526 "structs.hE<gt>), or NULL if there was an error. I<The caller must call "
10527 "C<guestfs_free_partition_list> after use>."
10531 #: ../src/guestfs-actions.pod:3739
10532 msgid "guestfs_part_set_bootable"
10536 #: ../src/guestfs-actions.pod:3741
10539 " int guestfs_part_set_bootable (guestfs_h *g,\n"
10540 "\t\tconst char *device,\n"
10541 "\t\tint partnum,\n"
10542 "\t\tint bootable);\n"
10547 #: ../src/guestfs-actions.pod:3746 ../fish/guestfish-actions.pod:2907
10549 "This sets the bootable flag on partition numbered C<partnum> on device "
10550 "C<device>. Note that partitions are numbered from 1."
10554 #: ../src/guestfs-actions.pod:3749 ../fish/guestfish-actions.pod:2910
10556 "The bootable flag is used by some operating systems (notably Windows) to "
10557 "determine which partition to boot from. It is by no means universally "
10562 #: ../src/guestfs-actions.pod:3755
10563 msgid "guestfs_part_set_mbr_id"
10567 #: ../src/guestfs-actions.pod:3757
10570 " int guestfs_part_set_mbr_id (guestfs_h *g,\n"
10571 "\t\tconst char *device,\n"
10572 "\t\tint partnum,\n"
10573 "\t\tint idbyte);\n"
10578 #: ../src/guestfs-actions.pod:3762 ../fish/guestfish-actions.pod:2918
10580 "Sets the MBR type byte (also known as the ID byte) of the numbered partition "
10581 "C<partnum> to C<idbyte>. Note that the type bytes quoted in most "
10582 "documentation are in fact hexadecimal numbers, but usually documented "
10583 "without any leading \"0x\" which might be confusing."
10587 #: ../src/guestfs-actions.pod:3774
10588 msgid "guestfs_part_set_name"
10592 #: ../src/guestfs-actions.pod:3776
10595 " int guestfs_part_set_name (guestfs_h *g,\n"
10596 "\t\tconst char *device,\n"
10597 "\t\tint partnum,\n"
10598 "\t\tconst char *name);\n"
10603 #: ../src/guestfs-actions.pod:3781 ../fish/guestfish-actions.pod:2932
10605 "This sets the partition name on partition numbered C<partnum> on device "
10606 "C<device>. Note that partitions are numbered from 1."
10610 #: ../src/guestfs-actions.pod:3784 ../fish/guestfish-actions.pod:2935
10612 "The partition name can only be set on certain types of partition table. "
10613 "This works on C<gpt> but not on C<mbr> partitions."
10617 #: ../src/guestfs-actions.pod:3789
10618 msgid "guestfs_part_to_dev"
10622 #: ../src/guestfs-actions.pod:3791
10625 " char *guestfs_part_to_dev (guestfs_h *g,\n"
10626 "\t\tconst char *partition);\n"
10631 #: ../src/guestfs-actions.pod:3794 ../fish/guestfish-actions.pod:2942
10633 "This function takes a partition name (eg. \"/dev/sdb1\") and removes the "
10634 "partition number, returning the device name (eg. \"/dev/sdb\")."
10638 #: ../src/guestfs-actions.pod:3798
10640 "The named partition must exist, for example as a string returned from "
10641 "C<guestfs_list_partitions>."
10645 #: ../src/guestfs-actions.pod:3804
10646 msgid "guestfs_ping_daemon"
10650 #: ../src/guestfs-actions.pod:3806
10653 " int guestfs_ping_daemon (guestfs_h *g);\n"
10658 #: ../src/guestfs-actions.pod:3808 ../fish/guestfish-actions.pod:2953
10660 "This is a test probe into the guestfs daemon running inside the qemu "
10661 "subprocess. Calling this function checks that the daemon responds to the "
10662 "ping message, without affecting the daemon or attached block device(s) in "
10667 #: ../src/guestfs-actions.pod:3815
10668 msgid "guestfs_pread"
10672 #: ../src/guestfs-actions.pod:3817
10675 " char *guestfs_pread (guestfs_h *g,\n"
10676 "\t\tconst char *path,\n"
10678 "\t\tint64_t offset,\n"
10679 "\t\tsize_t *size_r);\n"
10684 #: ../src/guestfs-actions.pod:3823 ../fish/guestfish-actions.pod:2962
10686 "This command lets you read part of a file. It reads C<count> bytes of the "
10687 "file, starting at C<offset>, from file C<path>."
10691 #: ../src/guestfs-actions.pod:3826 ../fish/guestfish-actions.pod:2965
10693 "This may read fewer bytes than requested. For further details see the "
10694 "L<pread(2)> system call."
10698 #: ../src/guestfs-actions.pod:3829 ../src/guestfs-actions.pod:3962
10699 msgid "See also C<guestfs_pwrite>."
10703 #: ../src/guestfs-actions.pod:3838
10704 msgid "guestfs_pvcreate"
10708 #: ../src/guestfs-actions.pod:3840
10711 " int guestfs_pvcreate (guestfs_h *g,\n"
10712 "\t\tconst char *device);\n"
10717 #: ../src/guestfs-actions.pod:3843 ../fish/guestfish-actions.pod:2977
10719 "This creates an LVM physical volume on the named C<device>, where C<device> "
10720 "should usually be a partition name such as C</dev/sda1>."
10724 #: ../src/guestfs-actions.pod:3849
10725 msgid "guestfs_pvremove"
10729 #: ../src/guestfs-actions.pod:3851
10732 " int guestfs_pvremove (guestfs_h *g,\n"
10733 "\t\tconst char *device);\n"
10738 #: ../src/guestfs-actions.pod:3854 ../fish/guestfish-actions.pod:2985
10740 "This wipes a physical volume C<device> so that LVM will no longer recognise "
10745 #: ../src/guestfs-actions.pod:3857 ../fish/guestfish-actions.pod:2988
10747 "The implementation uses the C<pvremove> command which refuses to wipe "
10748 "physical volumes that contain any volume groups, so you have to remove those "
10753 #: ../src/guestfs-actions.pod:3863
10754 msgid "guestfs_pvresize"
10758 #: ../src/guestfs-actions.pod:3865
10761 " int guestfs_pvresize (guestfs_h *g,\n"
10762 "\t\tconst char *device);\n"
10767 #: ../src/guestfs-actions.pod:3868 ../fish/guestfish-actions.pod:2996
10769 "This resizes (expands or shrinks) an existing LVM physical volume to match "
10770 "the new size of the underlying device."
10774 #: ../src/guestfs-actions.pod:3873
10775 msgid "guestfs_pvresize_size"
10779 #: ../src/guestfs-actions.pod:3875
10782 " int guestfs_pvresize_size (guestfs_h *g,\n"
10783 "\t\tconst char *device,\n"
10784 "\t\tint64_t size);\n"
10789 #: ../src/guestfs-actions.pod:3879
10791 "This command is the same as C<guestfs_pvresize> except that it allows you to "
10792 "specify the new size (in bytes) explicitly."
10796 #: ../src/guestfs-actions.pod:3884
10797 msgid "guestfs_pvs"
10801 #: ../src/guestfs-actions.pod:3886
10804 " char **guestfs_pvs (guestfs_h *g);\n"
10809 #: ../src/guestfs-actions.pod:3888 ../fish/guestfish-actions.pod:3010
10811 "List all the physical volumes detected. This is the equivalent of the L<pvs"
10816 #: ../src/guestfs-actions.pod:3891 ../fish/guestfish-actions.pod:3013
10818 "This returns a list of just the device names that contain PVs (eg. C</dev/"
10823 #: ../src/guestfs-actions.pod:3894
10824 msgid "See also C<guestfs_pvs_full>."
10828 #: ../src/guestfs-actions.pod:3900
10829 msgid "guestfs_pvs_full"
10833 #: ../src/guestfs-actions.pod:3902
10836 " struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *g);\n"
10841 #: ../src/guestfs-actions.pod:3904 ../fish/guestfish-actions.pod:3022
10843 "List all the physical volumes detected. This is the equivalent of the L<pvs"
10844 "(8)> command. The \"full\" version includes all fields."
10848 #: ../src/guestfs-actions.pod:3907
10850 "This function returns a C<struct guestfs_lvm_pv_list *> (see E<lt>guestfs-"
10851 "structs.hE<gt>), or NULL if there was an error. I<The caller must call "
10852 "C<guestfs_free_lvm_pv_list> after use>."
10856 #: ../src/guestfs-actions.pod:3912
10857 msgid "guestfs_pvuuid"
10861 #: ../src/guestfs-actions.pod:3914
10864 " char *guestfs_pvuuid (guestfs_h *g,\n"
10865 "\t\tconst char *device);\n"
10870 #: ../src/guestfs-actions.pod:3917 ../fish/guestfish-actions.pod:3029
10871 msgid "This command returns the UUID of the LVM PV C<device>."
10875 #: ../src/guestfs-actions.pod:3922
10876 msgid "guestfs_pwrite"
10880 #: ../src/guestfs-actions.pod:3924
10883 " int guestfs_pwrite (guestfs_h *g,\n"
10884 "\t\tconst char *path,\n"
10885 "\t\tconst char *content,\n"
10886 "\t\tsize_t content_size,\n"
10887 "\t\tint64_t offset);\n"
10892 #: ../src/guestfs-actions.pod:3930 ../fish/guestfish-actions.pod:3035
10894 "This command writes to part of a file. It writes the data buffer C<content> "
10895 "to the file C<path> starting at offset C<offset>."
10899 #: ../src/guestfs-actions.pod:3933 ../fish/guestfish-actions.pod:3038
10901 "This command implements the L<pwrite(2)> system call, and like that system "
10902 "call it may not write the full data requested. The return value is the "
10903 "number of bytes that were actually written to the file. This could even be "
10904 "0, although short writes are unlikely for regular files in ordinary "
10909 #: ../src/guestfs-actions.pod:3939
10910 msgid "See also C<guestfs_pread>, C<guestfs_pwrite_device>."
10914 #: ../src/guestfs-actions.pod:3946
10915 msgid "guestfs_pwrite_device"
10919 #: ../src/guestfs-actions.pod:3948
10922 " int guestfs_pwrite_device (guestfs_h *g,\n"
10923 "\t\tconst char *device,\n"
10924 "\t\tconst char *content,\n"
10925 "\t\tsize_t content_size,\n"
10926 "\t\tint64_t offset);\n"
10931 #: ../src/guestfs-actions.pod:3954 ../fish/guestfish-actions.pod:3053
10933 "This command writes to part of a device. It writes the data buffer "
10934 "C<content> to C<device> starting at offset C<offset>."
10938 #: ../src/guestfs-actions.pod:3957 ../fish/guestfish-actions.pod:3056
10940 "This command implements the L<pwrite(2)> system call, and like that system "
10941 "call it may not write the full data requested (although short writes to disk "
10942 "devices and partitions are probably impossible with standard Linux kernels)."
10946 #: ../src/guestfs-actions.pod:3969
10947 msgid "guestfs_read_file"
10951 #: ../src/guestfs-actions.pod:3971
10954 " char *guestfs_read_file (guestfs_h *g,\n"
10955 "\t\tconst char *path,\n"
10956 "\t\tsize_t *size_r);\n"
10961 #: ../src/guestfs-actions.pod:3975 ../fish/guestfish-actions.pod:3070
10962 msgid "This calls returns the contents of the file C<path> as a buffer."
10966 #: ../src/guestfs-actions.pod:3978
10968 "Unlike C<guestfs_cat>, this function can correctly handle files that contain "
10969 "embedded ASCII NUL characters. However unlike C<guestfs_download>, this "
10970 "function is limited in the total size of file that can be handled."
10974 #: ../src/guestfs-actions.pod:3990
10975 msgid "guestfs_read_lines"
10979 #: ../src/guestfs-actions.pod:3992
10982 " char **guestfs_read_lines (guestfs_h *g,\n"
10983 "\t\tconst char *path);\n"
10988 #: ../src/guestfs-actions.pod:3997 ../fish/guestfish-actions.pod:3087
10990 "The file contents are returned as a list of lines. Trailing C<LF> and "
10991 "C<CRLF> character sequences are I<not> returned."
10995 #: ../src/guestfs-actions.pod:4000
10997 "Note that this function cannot correctly handle binary files (specifically, "
10998 "files containing C<\\0> character which is treated as end of line). For "
10999 "those you need to use the C<guestfs_read_file> function which has a more "
11000 "complex interface."
11004 #: ../src/guestfs-actions.pod:4009
11005 msgid "guestfs_readdir"
11009 #: ../src/guestfs-actions.pod:4011
11012 " struct guestfs_dirent_list *guestfs_readdir (guestfs_h *g,\n"
11013 "\t\tconst char *dir);\n"
11018 #: ../src/guestfs-actions.pod:4014 ../fish/guestfish-actions.pod:3099
11019 msgid "This returns the list of directory entries in directory C<dir>."
11023 #: ../src/guestfs-actions.pod:4016 ../fish/guestfish-actions.pod:3101
11025 "All entries in the directory are returned, including C<.> and C<..>. The "
11026 "entries are I<not> sorted, but returned in the same order as the underlying "
11031 #: ../src/guestfs-actions.pod:4020 ../fish/guestfish-actions.pod:3105
11033 "Also this call returns basic file type information about each file. The "
11034 "C<ftyp> field will contain one of the following characters:"
11038 #: ../src/guestfs-actions.pod:4025 ../fish/guestfish-actions.pod:3110
11043 #: ../src/guestfs-actions.pod:4027 ../fish/guestfish-actions.pod:3112
11044 msgid "Block special"
11048 #: ../src/guestfs-actions.pod:4029 ../fish/guestfish-actions.pod:3114
11053 #: ../src/guestfs-actions.pod:4031 ../fish/guestfish-actions.pod:3116
11054 msgid "Char special"
11058 #: ../src/guestfs-actions.pod:4033 ../fish/guestfish-actions.pod:3118
11063 #: ../src/guestfs-actions.pod:4035 ../fish/guestfish-actions.pod:3120
11068 #: ../src/guestfs-actions.pod:4037 ../fish/guestfish-actions.pod:3122
11073 #: ../src/guestfs-actions.pod:4039 ../fish/guestfish-actions.pod:3124
11074 msgid "FIFO (named pipe)"
11078 #: ../src/guestfs-actions.pod:4041 ../fish/guestfish-actions.pod:3126
11083 #: ../src/guestfs-actions.pod:4043 ../fish/guestfish-actions.pod:3128
11084 msgid "Symbolic link"
11088 #: ../src/guestfs-actions.pod:4045 ../fish/guestfish-actions.pod:3130
11093 #: ../src/guestfs-actions.pod:4047 ../fish/guestfish-actions.pod:3132
11094 msgid "Regular file"
11098 #: ../src/guestfs-actions.pod:4049 ../fish/guestfish-actions.pod:3134
11103 #: ../src/guestfs-actions.pod:4051 ../fish/guestfish-actions.pod:3136
11108 #: ../src/guestfs-actions.pod:4053 ../fish/guestfish-actions.pod:3138
11113 #: ../src/guestfs-actions.pod:4055 ../fish/guestfish-actions.pod:3140
11114 msgid "Unknown file type"
11118 #: ../src/guestfs-actions.pod:4057 ../fish/guestfish-actions.pod:3142
11123 #: ../src/guestfs-actions.pod:4059 ../fish/guestfish-actions.pod:3144
11125 "The L<readdir(3)> call returned a C<d_type> field with an unexpected value"
11129 #: ../src/guestfs-actions.pod:4064
11131 "This function is primarily intended for use by programs. To get a simple "
11132 "list of names, use C<guestfs_ls>. To get a printable directory for human "
11133 "consumption, use C<guestfs_ll>."
11137 #: ../src/guestfs-actions.pod:4068
11139 "This function returns a C<struct guestfs_dirent_list *> (see E<lt>guestfs-"
11140 "structs.hE<gt>), or NULL if there was an error. I<The caller must call "
11141 "C<guestfs_free_dirent_list> after use>."
11145 #: ../src/guestfs-actions.pod:4073
11146 msgid "guestfs_readlink"
11150 #: ../src/guestfs-actions.pod:4075
11153 " char *guestfs_readlink (guestfs_h *g,\n"
11154 "\t\tconst char *path);\n"
11159 #: ../src/guestfs-actions.pod:4078 ../fish/guestfish-actions.pod:3157
11160 msgid "This command reads the target of a symbolic link."
11164 #: ../src/guestfs-actions.pod:4083
11165 msgid "guestfs_readlinklist"
11169 #: ../src/guestfs-actions.pod:4085
11172 " char **guestfs_readlinklist (guestfs_h *g,\n"
11173 "\t\tconst char *path,\n"
11174 "\t\tchar *const *names);\n"
11179 #: ../src/guestfs-actions.pod:4089 ../fish/guestfish-actions.pod:3163
11181 "This call allows you to do a C<readlink> operation on multiple files, where "
11182 "all files are in the directory C<path>. C<names> is the list of files from "
11187 #: ../src/guestfs-actions.pod:4093 ../fish/guestfish-actions.pod:3167
11189 "On return you get a list of strings, with a one-to-one correspondence to the "
11190 "C<names> list. Each string is the value of the symbolic link."
11194 #: ../src/guestfs-actions.pod:4097 ../fish/guestfish-actions.pod:3171
11196 "If the C<readlink(2)> operation fails on any name, then the corresponding "
11197 "result string is the empty string C<\"\">. However the whole operation is "
11198 "completed even if there were C<readlink(2)> errors, and so you can call this "
11199 "function with names where you don't know if they are symbolic links already "
11200 "(albeit slightly less efficient)."
11204 #: ../src/guestfs-actions.pod:4104 ../fish/guestfish-actions.pod:3178
11206 "This call is intended for programs that want to efficiently list a directory "
11207 "contents without making many round-trips. Very long directory listings "
11208 "might cause the protocol message size to be exceeded, causing this call to "
11209 "fail. The caller must split up such requests into smaller groups of names."
11213 #: ../src/guestfs-actions.pod:4115
11214 msgid "guestfs_realpath"
11218 #: ../src/guestfs-actions.pod:4117
11221 " char *guestfs_realpath (guestfs_h *g,\n"
11222 "\t\tconst char *path);\n"
11227 #: ../src/guestfs-actions.pod:4120 ../fish/guestfish-actions.pod:3189
11229 "Return the canonicalized absolute pathname of C<path>. The returned path "
11230 "has no C<.>, C<..> or symbolic link path elements."
11234 #: ../src/guestfs-actions.pod:4126
11235 msgid "guestfs_removexattr"
11239 #: ../src/guestfs-actions.pod:4128
11242 " int guestfs_removexattr (guestfs_h *g,\n"
11243 "\t\tconst char *xattr,\n"
11244 "\t\tconst char *path);\n"
11249 #: ../src/guestfs-actions.pod:4132 ../fish/guestfish-actions.pod:3196
11251 "This call removes the extended attribute named C<xattr> of the file C<path>."
11255 #: ../src/guestfs-actions.pod:4135
11256 msgid "See also: C<guestfs_lremovexattr>, L<attr(5)>."
11260 #: ../src/guestfs-actions.pod:4139
11261 msgid "guestfs_resize2fs"
11265 #: ../src/guestfs-actions.pod:4141
11268 " int guestfs_resize2fs (guestfs_h *g,\n"
11269 "\t\tconst char *device);\n"
11274 #: ../src/guestfs-actions.pod:4144 ../fish/guestfish-actions.pod:3205
11276 "This resizes an ext2, ext3 or ext4 filesystem to match the size of the "
11277 "underlying device."
11281 #: ../src/guestfs-actions.pod:4147
11283 "I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f> on the "
11284 "C<device> before calling this command. For unknown reasons C<resize2fs> "
11285 "sometimes gives an error about this and sometimes not. In any case, it is "
11286 "always safe to call C<guestfs_e2fsck_f> before calling this function."
11290 #: ../src/guestfs-actions.pod:4155
11291 msgid "guestfs_resize2fs_size"
11295 #: ../src/guestfs-actions.pod:4157
11298 " int guestfs_resize2fs_size (guestfs_h *g,\n"
11299 "\t\tconst char *device,\n"
11300 "\t\tint64_t size);\n"
11305 #: ../src/guestfs-actions.pod:4161
11307 "This command is the same as C<guestfs_resize2fs> except that it allows you "
11308 "to specify the new size (in bytes) explicitly."
11312 #: ../src/guestfs-actions.pod:4166
11317 #: ../src/guestfs-actions.pod:4168
11320 " int guestfs_rm (guestfs_h *g,\n"
11321 "\t\tconst char *path);\n"
11326 #: ../src/guestfs-actions.pod:4171 ../fish/guestfish-actions.pod:3225
11327 msgid "Remove the single file C<path>."
11331 #: ../src/guestfs-actions.pod:4175
11332 msgid "guestfs_rm_rf"
11336 #: ../src/guestfs-actions.pod:4177
11339 " int guestfs_rm_rf (guestfs_h *g,\n"
11340 "\t\tconst char *path);\n"
11345 #: ../src/guestfs-actions.pod:4180 ../fish/guestfish-actions.pod:3231
11347 "Remove the file or directory C<path>, recursively removing the contents if "
11348 "its a directory. This is like the C<rm -rf> shell command."
11352 #: ../src/guestfs-actions.pod:4186
11353 msgid "guestfs_rmdir"
11357 #: ../src/guestfs-actions.pod:4188
11360 " int guestfs_rmdir (guestfs_h *g,\n"
11361 "\t\tconst char *path);\n"
11366 #: ../src/guestfs-actions.pod:4191 ../fish/guestfish-actions.pod:3239
11367 msgid "Remove the single directory C<path>."
11371 #: ../src/guestfs-actions.pod:4195
11372 msgid "guestfs_rmmountpoint"
11376 #: ../src/guestfs-actions.pod:4197
11379 " int guestfs_rmmountpoint (guestfs_h *g,\n"
11380 "\t\tconst char *exemptpath);\n"
11385 #: ../src/guestfs-actions.pod:4200
11387 "This calls removes a mountpoint that was previously created with "
11388 "C<guestfs_mkmountpoint>. See C<guestfs_mkmountpoint> for full details."
11392 #: ../src/guestfs-actions.pod:4206
11393 msgid "guestfs_scrub_device"
11397 #: ../src/guestfs-actions.pod:4208
11400 " int guestfs_scrub_device (guestfs_h *g,\n"
11401 "\t\tconst char *device);\n"
11406 #: ../src/guestfs-actions.pod:4211 ../fish/guestfish-actions.pod:3253
11408 "This command writes patterns over C<device> to make data retrieval more "
11413 #: ../src/guestfs-actions.pod:4214 ../src/guestfs-actions.pod:4232
11414 #: ../src/guestfs-actions.pod:4248 ../fish/guestfish-actions.pod:3256
11415 #: ../fish/guestfish-actions.pod:3271 ../fish/guestfish-actions.pod:3284
11417 "It is an interface to the L<scrub(1)> program. See that manual page for "
11422 #: ../src/guestfs-actions.pod:4222
11423 msgid "guestfs_scrub_file"
11427 #: ../src/guestfs-actions.pod:4224
11430 " int guestfs_scrub_file (guestfs_h *g,\n"
11431 "\t\tconst char *file);\n"
11436 #: ../src/guestfs-actions.pod:4227 ../fish/guestfish-actions.pod:3266
11438 "This command writes patterns over a file to make data retrieval more "
11443 #: ../src/guestfs-actions.pod:4230 ../fish/guestfish-actions.pod:3269
11444 msgid "The file is I<removed> after scrubbing."
11448 #: ../src/guestfs-actions.pod:4237
11449 msgid "guestfs_scrub_freespace"
11453 #: ../src/guestfs-actions.pod:4239
11456 " int guestfs_scrub_freespace (guestfs_h *g,\n"
11457 "\t\tconst char *dir);\n"
11462 #: ../src/guestfs-actions.pod:4242
11464 "This command creates the directory C<dir> and then fills it with files until "
11465 "the filesystem is full, and scrubs the files as for C<guestfs_scrub_file>, "
11466 "and deletes them. The intention is to scrub any free space on the partition "
11467 "containing C<dir>."
11471 #: ../src/guestfs-actions.pod:4253
11472 msgid "guestfs_set_append"
11476 #: ../src/guestfs-actions.pod:4255
11479 " int guestfs_set_append (guestfs_h *g,\n"
11480 "\t\tconst char *append);\n"
11485 #: ../src/guestfs-actions.pod:4258 ../fish/guestfish-actions.pod:3293
11487 "This function is used to add additional options to the guest kernel command "
11492 #: ../src/guestfs-actions.pod:4261 ../fish/guestfish-actions.pod:3296
11494 "The default is C<NULL> unless overridden by setting C<LIBGUESTFS_APPEND> "
11495 "environment variable."
11499 #: ../src/guestfs-actions.pod:4264 ../fish/guestfish-actions.pod:3299
11501 "Setting C<append> to C<NULL> means I<no> additional options are passed "
11502 "(libguestfs always adds a few of its own)."
11506 #: ../src/guestfs-actions.pod:4269
11507 msgid "guestfs_set_autosync"
11511 #: ../src/guestfs-actions.pod:4271
11514 " int guestfs_set_autosync (guestfs_h *g,\n"
11515 "\t\tint autosync);\n"
11520 #: ../src/guestfs-actions.pod:4274
11522 "If C<autosync> is true, this enables autosync. Libguestfs will make a best "
11523 "effort attempt to run C<guestfs_umount_all> followed by C<guestfs_sync> when "
11524 "the handle is closed (also if the program exits without closing handles)."
11528 #: ../src/guestfs-actions.pod:4279 ../fish/guestfish-actions.pod:3313
11530 "This is disabled by default (except in guestfish where it is enabled by "
11535 #: ../src/guestfs-actions.pod:4284
11536 msgid "guestfs_set_direct"
11540 #: ../src/guestfs-actions.pod:4286
11543 " int guestfs_set_direct (guestfs_h *g,\n"
11544 "\t\tint direct);\n"
11549 #: ../src/guestfs-actions.pod:4289 ../fish/guestfish-actions.pod:3322
11551 "If the direct appliance mode flag is enabled, then stdin and stdout are "
11552 "passed directly through to the appliance once it is launched."
11556 #: ../src/guestfs-actions.pod:4293
11558 "One consequence of this is that log messages aren't caught by the library "
11559 "and handled by C<guestfs_set_log_message_callback>, but go straight to "
11564 #: ../src/guestfs-actions.pod:4297 ../fish/guestfish-actions.pod:3330
11565 msgid "You probably don't want to use this unless you know what you are doing."
11569 #: ../src/guestfs-actions.pod:4300 ../fish/guestfish-actions.pod:3333
11570 msgid "The default is disabled."
11574 #: ../src/guestfs-actions.pod:4304
11575 msgid "guestfs_set_e2label"
11579 #: ../src/guestfs-actions.pod:4306
11582 " int guestfs_set_e2label (guestfs_h *g,\n"
11583 "\t\tconst char *device,\n"
11584 "\t\tconst char *label);\n"
11589 #: ../src/guestfs-actions.pod:4310 ../fish/guestfish-actions.pod:3339
11591 "This sets the ext2/3/4 filesystem label of the filesystem on C<device> to "
11592 "C<label>. Filesystem labels are limited to 16 characters."
11596 #: ../src/guestfs-actions.pod:4314
11598 "You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label> to return "
11599 "the existing label on a filesystem."
11603 #: ../src/guestfs-actions.pod:4319
11604 msgid "guestfs_set_e2uuid"
11608 #: ../src/guestfs-actions.pod:4321
11611 " int guestfs_set_e2uuid (guestfs_h *g,\n"
11612 "\t\tconst char *device,\n"
11613 "\t\tconst char *uuid);\n"
11618 #: ../src/guestfs-actions.pod:4325 ../fish/guestfish-actions.pod:3350
11620 "This sets the ext2/3/4 filesystem UUID of the filesystem on C<device> to "
11621 "C<uuid>. The format of the UUID and alternatives such as C<clear>, "
11622 "C<random> and C<time> are described in the L<tune2fs(8)> manpage."
11626 #: ../src/guestfs-actions.pod:4330
11628 "You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid> to return "
11629 "the existing UUID of a filesystem."
11633 #: ../src/guestfs-actions.pod:4335
11634 msgid "guestfs_set_memsize"
11638 #: ../src/guestfs-actions.pod:4337
11641 " int guestfs_set_memsize (guestfs_h *g,\n"
11642 "\t\tint memsize);\n"
11647 #: ../src/guestfs-actions.pod:4340
11649 "This sets the memory size in megabytes allocated to the qemu subprocess. "
11650 "This only has any effect if called before C<guestfs_launch>."
11654 #: ../src/guestfs-actions.pod:4344 ../fish/guestfish-actions.pod:3368
11656 "You can also change this by setting the environment variable "
11657 "C<LIBGUESTFS_MEMSIZE> before the handle is created."
11661 #: ../src/guestfs-actions.pod:4353
11662 msgid "guestfs_set_network"
11666 #: ../src/guestfs-actions.pod:4355
11669 " int guestfs_set_network (guestfs_h *g,\n"
11670 "\t\tint network);\n"
11675 #: ../src/guestfs-actions.pod:4358 ../fish/guestfish-actions.pod:3381
11677 "If C<network> is true, then the network is enabled in the libguestfs "
11678 "appliance. The default is false."
11682 #: ../src/guestfs-actions.pod:4361 ../fish/guestfish-actions.pod:3384
11684 "This affects whether commands are able to access the network (see L<guestfs"
11685 "(3)/RUNNING COMMANDS>)."
11689 #: ../src/guestfs-actions.pod:4364
11691 "You must call this before calling C<guestfs_launch>, otherwise it has no "
11696 #: ../src/guestfs-actions.pod:4369
11697 msgid "guestfs_set_path"
11701 #: ../src/guestfs-actions.pod:4371
11704 " int guestfs_set_path (guestfs_h *g,\n"
11705 "\t\tconst char *searchpath);\n"
11710 #: ../src/guestfs-actions.pod:4374 ../fish/guestfish-actions.pod:3396
11711 msgid "Set the path that libguestfs searches for kernel and initrd.img."
11715 #: ../src/guestfs-actions.pod:4376 ../fish/guestfish-actions.pod:3398
11717 "The default is C<$libdir/guestfs> unless overridden by setting "
11718 "C<LIBGUESTFS_PATH> environment variable."
11722 #: ../src/guestfs-actions.pod:4379 ../fish/guestfish-actions.pod:3401
11723 msgid "Setting C<path> to C<NULL> restores the default path."
11727 #: ../src/guestfs-actions.pod:4383
11728 msgid "guestfs_set_qemu"
11732 #: ../src/guestfs-actions.pod:4385
11735 " int guestfs_set_qemu (guestfs_h *g,\n"
11736 "\t\tconst char *qemu);\n"
11741 #: ../src/guestfs-actions.pod:4388 ../fish/guestfish-actions.pod:3409
11742 msgid "Set the qemu binary that we will use."
11746 #: ../src/guestfs-actions.pod:4390 ../fish/guestfish-actions.pod:3411
11748 "The default is chosen when the library was compiled by the configure script."
11752 #: ../src/guestfs-actions.pod:4393 ../fish/guestfish-actions.pod:3414
11754 "You can also override this by setting the C<LIBGUESTFS_QEMU> environment "
11759 #: ../src/guestfs-actions.pod:4396 ../fish/guestfish-actions.pod:3417
11760 msgid "Setting C<qemu> to C<NULL> restores the default qemu binary."
11764 #: ../src/guestfs-actions.pod:4398 ../fish/guestfish-actions.pod:3419
11766 "Note that you should call this function as early as possible after creating "
11767 "the handle. This is because some pre-launch operations depend on testing "
11768 "qemu features (by running C<qemu -help>). If the qemu binary changes, we "
11769 "don't retest features, and so you might see inconsistent results. Using the "
11770 "environment variable C<LIBGUESTFS_QEMU> is safest of all since that picks "
11771 "the qemu binary at the same time as the handle is created."
11775 #: ../src/guestfs-actions.pod:4408
11776 msgid "guestfs_set_recovery_proc"
11780 #: ../src/guestfs-actions.pod:4410
11783 " int guestfs_set_recovery_proc (guestfs_h *g,\n"
11784 "\t\tint recoveryproc);\n"
11789 #: ../src/guestfs-actions.pod:4413
11791 "If this is called with the parameter C<false> then C<guestfs_launch> does "
11792 "not create a recovery process. The purpose of the recovery process is to "
11793 "stop runaway qemu processes in the case where the main program aborts "
11798 #: ../src/guestfs-actions.pod:4418
11800 "This only has any effect if called before C<guestfs_launch>, and the default "
11805 #: ../src/guestfs-actions.pod:4421 ../fish/guestfish-actions.pod:3441
11807 "About the only time when you would want to disable this is if the main "
11808 "process will fork itself into the background (\"daemonize\" itself). In "
11809 "this case the recovery process thinks that the main program has disappeared "
11810 "and so kills qemu, which is not very helpful."
11814 #: ../src/guestfs-actions.pod:4429
11815 msgid "guestfs_set_selinux"
11819 #: ../src/guestfs-actions.pod:4431
11822 " int guestfs_set_selinux (guestfs_h *g,\n"
11823 "\t\tint selinux);\n"
11828 #: ../src/guestfs-actions.pod:4434 ../fish/guestfish-actions.pod:3453
11830 "This sets the selinux flag that is passed to the appliance at boot time. "
11831 "The default is C<selinux=0> (disabled)."
11835 #: ../src/guestfs-actions.pod:4437 ../fish/guestfish-actions.pod:3456
11837 "Note that if SELinux is enabled, it is always in Permissive mode "
11838 "(C<enforcing=0>)."
11842 #: ../src/guestfs-actions.pod:4445
11843 msgid "guestfs_set_trace"
11847 #: ../src/guestfs-actions.pod:4447
11850 " int guestfs_set_trace (guestfs_h *g,\n"
11851 "\t\tint trace);\n"
11856 #: ../src/guestfs-actions.pod:4450 ../fish/guestfish-actions.pod:3468
11858 "If the command trace flag is set to 1, then commands are printed on stderr "
11859 "before they are executed in a format which is very similar to the one used "
11860 "by guestfish. In other words, you can run a program with this enabled, and "
11861 "you will get out a script which you can feed to guestfish to perform the "
11862 "same set of actions."
11866 #: ../src/guestfs-actions.pod:4457 ../fish/guestfish-actions.pod:3475
11868 "If you want to trace C API calls into libguestfs (and other libraries) then "
11869 "possibly a better way is to use the external ltrace(1) command."
11873 #: ../src/guestfs-actions.pod:4461 ../fish/guestfish-actions.pod:3479
11875 "Command traces are disabled unless the environment variable "
11876 "C<LIBGUESTFS_TRACE> is defined and set to C<1>."
11880 #: ../src/guestfs-actions.pod:4466
11881 msgid "guestfs_set_verbose"
11885 #: ../src/guestfs-actions.pod:4468
11888 " int guestfs_set_verbose (guestfs_h *g,\n"
11889 "\t\tint verbose);\n"
11894 #: ../src/guestfs-actions.pod:4471 ../fish/guestfish-actions.pod:3488
11895 msgid "If C<verbose> is true, this turns on verbose messages (to C<stderr>)."
11899 #: ../src/guestfs-actions.pod:4473 ../fish/guestfish-actions.pod:3490
11901 "Verbose messages are disabled unless the environment variable "
11902 "C<LIBGUESTFS_DEBUG> is defined and set to C<1>."
11906 #: ../src/guestfs-actions.pod:4478
11907 msgid "guestfs_setcon"
11911 #: ../src/guestfs-actions.pod:4480
11914 " int guestfs_setcon (guestfs_h *g,\n"
11915 "\t\tconst char *context);\n"
11920 #: ../src/guestfs-actions.pod:4483 ../fish/guestfish-actions.pod:3497
11922 "This sets the SELinux security context of the daemon to the string "
11927 #: ../src/guestfs-actions.pod:4486 ../fish/guestfish-actions.pod:3500
11928 msgid "See the documentation about SELINUX in L<guestfs(3)>."
11932 #: ../src/guestfs-actions.pod:4490
11933 msgid "guestfs_setxattr"
11937 #: ../src/guestfs-actions.pod:4492
11940 " int guestfs_setxattr (guestfs_h *g,\n"
11941 "\t\tconst char *xattr,\n"
11942 "\t\tconst char *val,\n"
11943 "\t\tint vallen,\n"
11944 "\t\tconst char *path);\n"
11949 #: ../src/guestfs-actions.pod:4498 ../fish/guestfish-actions.pod:3506
11951 "This call sets the extended attribute named C<xattr> of the file C<path> to "
11952 "the value C<val> (of length C<vallen>). The value is arbitrary 8 bit data."
11956 #: ../src/guestfs-actions.pod:4502
11957 msgid "See also: C<guestfs_lsetxattr>, L<attr(5)>."
11961 #: ../src/guestfs-actions.pod:4506
11962 msgid "guestfs_sfdisk"
11966 #: ../src/guestfs-actions.pod:4508
11969 " int guestfs_sfdisk (guestfs_h *g,\n"
11970 "\t\tconst char *device,\n"
11973 "\t\tint sectors,\n"
11974 "\t\tchar *const *lines);\n"
11979 #: ../src/guestfs-actions.pod:4515 ../fish/guestfish-actions.pod:3516
11981 "This is a direct interface to the L<sfdisk(8)> program for creating "
11982 "partitions on block devices."
11986 #: ../src/guestfs-actions.pod:4518 ../fish/guestfish-actions.pod:3519
11987 msgid "C<device> should be a block device, for example C</dev/sda>."
11991 #: ../src/guestfs-actions.pod:4520 ../fish/guestfish-actions.pod:3521
11993 "C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads and "
11994 "sectors on the device, which are passed directly to sfdisk as the I<-C>, I<-"
11995 "H> and I<-S> parameters. If you pass C<0> for any of these, then the "
11996 "corresponding parameter is omitted. Usually for 'large' disks, you can just "
11997 "pass C<0> for these, but for small (floppy-sized) disks, sfdisk (or rather, "
11998 "the kernel) cannot work out the right geometry and you will need to tell it."
12002 #: ../src/guestfs-actions.pod:4528 ../fish/guestfish-actions.pod:3529
12004 "C<lines> is a list of lines that we feed to C<sfdisk>. For more information "
12005 "refer to the L<sfdisk(8)> manpage."
12009 #: ../src/guestfs-actions.pod:4531 ../fish/guestfish-actions.pod:3532
12011 "To create a single partition occupying the whole disk, you would pass "
12012 "C<lines> as a single element list, when the single element being the string "
12017 #: ../src/guestfs-actions.pod:4535
12019 "See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>, C<guestfs_part_init>"
12023 #: ../src/guestfs-actions.pod:4543
12024 msgid "guestfs_sfdiskM"
12028 #: ../src/guestfs-actions.pod:4545
12031 " int guestfs_sfdiskM (guestfs_h *g,\n"
12032 "\t\tconst char *device,\n"
12033 "\t\tchar *const *lines);\n"
12038 #: ../src/guestfs-actions.pod:4549
12040 "This is a simplified interface to the C<guestfs_sfdisk> command, where "
12041 "partition sizes are specified in megabytes only (rounded to the nearest "
12042 "cylinder) and you don't need to specify the cyls, heads and sectors "
12043 "parameters which were rarely if ever used anyway."
12047 #: ../src/guestfs-actions.pod:4555
12049 "See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage and "
12050 "C<guestfs_part_disk>"
12054 #: ../src/guestfs-actions.pod:4563
12055 msgid "guestfs_sfdisk_N"
12059 #: ../src/guestfs-actions.pod:4565
12062 " int guestfs_sfdisk_N (guestfs_h *g,\n"
12063 "\t\tconst char *device,\n"
12064 "\t\tint partnum,\n"
12067 "\t\tint sectors,\n"
12068 "\t\tconst char *line);\n"
12073 #: ../src/guestfs-actions.pod:4573 ../fish/guestfish-actions.pod:3562
12075 "This runs L<sfdisk(8)> option to modify just the single partition C<n> "
12076 "(note: C<n> counts from 1)."
12080 #: ../src/guestfs-actions.pod:4576
12082 "For other parameters, see C<guestfs_sfdisk>. You should usually pass C<0> "
12083 "for the cyls/heads/sectors parameters."
12087 #: ../src/guestfs-actions.pod:4579
12088 msgid "See also: C<guestfs_part_add>"
12092 #: ../src/guestfs-actions.pod:4586
12093 msgid "guestfs_sfdisk_disk_geometry"
12097 #: ../src/guestfs-actions.pod:4588
12100 " char *guestfs_sfdisk_disk_geometry (guestfs_h *g,\n"
12101 "\t\tconst char *device);\n"
12106 #: ../src/guestfs-actions.pod:4591
12108 "This displays the disk geometry of C<device> read from the partition table. "
12109 "Especially in the case where the underlying block device has been resized, "
12110 "this can be different from the kernel's idea of the geometry (see "
12111 "C<guestfs_sfdisk_kernel_geometry>)."
12115 #: ../src/guestfs-actions.pod:4596 ../src/guestfs-actions.pod:4609
12116 #: ../fish/guestfish-actions.pod:3582 ../fish/guestfish-actions.pod:3591
12117 msgid "The result is in human-readable format, and not designed to be parsed."
12121 #: ../src/guestfs-actions.pod:4602
12122 msgid "guestfs_sfdisk_kernel_geometry"
12126 #: ../src/guestfs-actions.pod:4604
12129 " char *guestfs_sfdisk_kernel_geometry (guestfs_h *g,\n"
12130 "\t\tconst char *device);\n"
12135 #: ../src/guestfs-actions.pod:4607 ../fish/guestfish-actions.pod:3589
12136 msgid "This displays the kernel's idea of the geometry of C<device>."
12140 #: ../src/guestfs-actions.pod:4615
12141 msgid "guestfs_sfdisk_l"
12145 #: ../src/guestfs-actions.pod:4617
12148 " char *guestfs_sfdisk_l (guestfs_h *g,\n"
12149 "\t\tconst char *device);\n"
12154 #: ../src/guestfs-actions.pod:4620 ../fish/guestfish-actions.pod:3598
12156 "This displays the partition table on C<device>, in the human-readable output "
12157 "of the L<sfdisk(8)> command. It is not intended to be parsed."
12161 #: ../src/guestfs-actions.pod:4624
12162 msgid "See also: C<guestfs_part_list>"
12166 #: ../src/guestfs-actions.pod:4629
12171 #: ../src/guestfs-actions.pod:4631
12174 " char *guestfs_sh (guestfs_h *g,\n"
12175 "\t\tconst char *command);\n"
12180 #: ../src/guestfs-actions.pod:4634 ../fish/guestfish-actions.pod:3608
12182 "This call runs a command from the guest filesystem via the guest's C</bin/"
12187 #: ../src/guestfs-actions.pod:4637
12188 msgid "This is like C<guestfs_command>, but passes the command to:"
12192 #: ../src/guestfs-actions.pod:4639 ../fish/guestfish-actions.pod:3613
12195 " /bin/sh -c \"command\"\n"
12200 #: ../src/guestfs-actions.pod:4641 ../fish/guestfish-actions.pod:3615
12202 "Depending on the guest's shell, this usually results in wildcards being "
12203 "expanded, shell expressions being interpolated and so on."
12207 #: ../src/guestfs-actions.pod:4645
12208 msgid "All the provisos about C<guestfs_command> apply to this call."
12212 #: ../src/guestfs-actions.pod:4650
12213 msgid "guestfs_sh_lines"
12217 #: ../src/guestfs-actions.pod:4652
12220 " char **guestfs_sh_lines (guestfs_h *g,\n"
12221 "\t\tconst char *command);\n"
12226 #: ../src/guestfs-actions.pod:4655
12228 "This is the same as C<guestfs_sh>, but splits the result into a list of "
12233 #: ../src/guestfs-actions.pod:4658
12234 msgid "See also: C<guestfs_command_lines>"
12238 #: ../src/guestfs-actions.pod:4664
12239 msgid "guestfs_sleep"
12243 #: ../src/guestfs-actions.pod:4666
12246 " int guestfs_sleep (guestfs_h *g,\n"
12252 #: ../src/guestfs-actions.pod:4669 ../fish/guestfish-actions.pod:3634
12253 msgid "Sleep for C<secs> seconds."
12257 #: ../src/guestfs-actions.pod:4673 ../src/guestfs-structs.pod:109
12258 msgid "guestfs_stat"
12262 #: ../src/guestfs-actions.pod:4675
12265 " struct guestfs_stat *guestfs_stat (guestfs_h *g,\n"
12266 "\t\tconst char *path);\n"
12271 #: ../src/guestfs-actions.pod:4680 ../fish/guestfish-actions.pod:3642
12272 msgid "This is the same as the C<stat(2)> system call."
12276 #: ../src/guestfs-actions.pod:4686 ../src/guestfs-structs.pod:135
12277 msgid "guestfs_statvfs"
12281 #: ../src/guestfs-actions.pod:4688
12284 " struct guestfs_statvfs *guestfs_statvfs (guestfs_h *g,\n"
12285 "\t\tconst char *path);\n"
12290 #: ../src/guestfs-actions.pod:4691 ../fish/guestfish-actions.pod:3648
12292 "Returns file system statistics for any mounted file system. C<path> should "
12293 "be a file or directory in the mounted file system (typically it is the mount "
12294 "point itself, but it doesn't need to be)."
12298 #: ../src/guestfs-actions.pod:4695 ../fish/guestfish-actions.pod:3652
12299 msgid "This is the same as the C<statvfs(2)> system call."
12303 #: ../src/guestfs-actions.pod:4697
12305 "This function returns a C<struct guestfs_statvfs *>, or NULL if there was an "
12306 "error. I<The caller must call C<guestfs_free_statvfs> after use>."
12310 #: ../src/guestfs-actions.pod:4701
12311 msgid "guestfs_strings"
12315 #: ../src/guestfs-actions.pod:4703
12318 " char **guestfs_strings (guestfs_h *g,\n"
12319 "\t\tconst char *path);\n"
12324 #: ../src/guestfs-actions.pod:4706 ../fish/guestfish-actions.pod:3658
12326 "This runs the L<strings(1)> command on a file and returns the list of "
12327 "printable strings found."
12331 #: ../src/guestfs-actions.pod:4716
12332 msgid "guestfs_strings_e"
12336 #: ../src/guestfs-actions.pod:4718
12339 " char **guestfs_strings_e (guestfs_h *g,\n"
12340 "\t\tconst char *encoding,\n"
12341 "\t\tconst char *path);\n"
12346 #: ../src/guestfs-actions.pod:4722
12348 "This is like the C<guestfs_strings> command, but allows you to specify the "
12349 "encoding of strings that are looked for in the source file C<path>."
12353 #: ../src/guestfs-actions.pod:4726 ../fish/guestfish-actions.pod:3672
12354 msgid "Allowed encodings are:"
12358 #: ../src/guestfs-actions.pod:4730 ../fish/guestfish-actions.pod:3676
12363 #: ../src/guestfs-actions.pod:4732
12365 "Single 7-bit-byte characters like ASCII and the ASCII-compatible parts of "
12366 "ISO-8859-X (this is what C<guestfs_strings> uses)."
12370 #: ../src/guestfs-actions.pod:4735 ../fish/guestfish-actions.pod:3681
12375 #: ../src/guestfs-actions.pod:4737 ../fish/guestfish-actions.pod:3683
12376 msgid "Single 8-bit-byte characters."
12380 #: ../src/guestfs-actions.pod:4739 ../fish/guestfish-actions.pod:3685
12385 #: ../src/guestfs-actions.pod:4741 ../fish/guestfish-actions.pod:3687
12386 msgid "16-bit big endian strings such as those encoded in UTF-16BE or UCS-2BE."
12390 #: ../src/guestfs-actions.pod:4744 ../fish/guestfish-actions.pod:3690
12391 msgid "l (lower case letter L)"
12395 #: ../src/guestfs-actions.pod:4746 ../fish/guestfish-actions.pod:3692
12397 "16-bit little endian such as UTF-16LE and UCS-2LE. This is useful for "
12398 "examining binaries in Windows guests."
12402 #: ../src/guestfs-actions.pod:4749 ../fish/guestfish-actions.pod:3695
12407 #: ../src/guestfs-actions.pod:4751 ../fish/guestfish-actions.pod:3697
12408 msgid "32-bit big endian such as UCS-4BE."
12412 #: ../src/guestfs-actions.pod:4753 ../fish/guestfish-actions.pod:3699
12417 #: ../src/guestfs-actions.pod:4755 ../fish/guestfish-actions.pod:3701
12418 msgid "32-bit little endian such as UCS-4LE."
12422 #: ../src/guestfs-actions.pod:4759 ../fish/guestfish-actions.pod:3705
12423 msgid "The returned strings are transcoded to UTF-8."
12427 #: ../src/guestfs-actions.pod:4768
12428 msgid "guestfs_swapoff_device"
12432 #: ../src/guestfs-actions.pod:4770
12435 " int guestfs_swapoff_device (guestfs_h *g,\n"
12436 "\t\tconst char *device);\n"
12441 #: ../src/guestfs-actions.pod:4773
12443 "This command disables the libguestfs appliance swap device or partition "
12444 "named C<device>. See C<guestfs_swapon_device>."
12448 #: ../src/guestfs-actions.pod:4779
12449 msgid "guestfs_swapoff_file"
12453 #: ../src/guestfs-actions.pod:4781
12456 " int guestfs_swapoff_file (guestfs_h *g,\n"
12457 "\t\tconst char *file);\n"
12462 #: ../src/guestfs-actions.pod:4784 ../fish/guestfish-actions.pod:3722
12463 msgid "This command disables the libguestfs appliance swap on file."
12467 #: ../src/guestfs-actions.pod:4788
12468 msgid "guestfs_swapoff_label"
12472 #: ../src/guestfs-actions.pod:4790
12475 " int guestfs_swapoff_label (guestfs_h *g,\n"
12476 "\t\tconst char *label);\n"
12481 #: ../src/guestfs-actions.pod:4793 ../fish/guestfish-actions.pod:3728
12483 "This command disables the libguestfs appliance swap on labeled swap "
12488 #: ../src/guestfs-actions.pod:4798
12489 msgid "guestfs_swapoff_uuid"
12493 #: ../src/guestfs-actions.pod:4800
12496 " int guestfs_swapoff_uuid (guestfs_h *g,\n"
12497 "\t\tconst char *uuid);\n"
12502 #: ../src/guestfs-actions.pod:4803 ../fish/guestfish-actions.pod:3735
12504 "This command disables the libguestfs appliance swap partition with the given "
12509 #: ../src/guestfs-actions.pod:4808
12510 msgid "guestfs_swapon_device"
12514 #: ../src/guestfs-actions.pod:4810
12517 " int guestfs_swapon_device (guestfs_h *g,\n"
12518 "\t\tconst char *device);\n"
12523 #: ../src/guestfs-actions.pod:4813
12525 "This command enables the libguestfs appliance to use the swap device or "
12526 "partition named C<device>. The increased memory is made available for all "
12527 "commands, for example those run using C<guestfs_command> or C<guestfs_sh>."
12531 #: ../src/guestfs-actions.pod:4818 ../fish/guestfish-actions.pod:3747
12533 "Note that you should not swap to existing guest swap partitions unless you "
12534 "know what you are doing. They may contain hibernation information, or other "
12535 "information that the guest doesn't want you to trash. You also risk leaking "
12536 "information about the host to the guest this way. Instead, attach a new "
12537 "host device to the guest and swap on that."
12541 #: ../src/guestfs-actions.pod:4827
12542 msgid "guestfs_swapon_file"
12546 #: ../src/guestfs-actions.pod:4829
12549 " int guestfs_swapon_file (guestfs_h *g,\n"
12550 "\t\tconst char *file);\n"
12555 #: ../src/guestfs-actions.pod:4832
12557 "This command enables swap to a file. See C<guestfs_swapon_device> for other "
12562 #: ../src/guestfs-actions.pod:4837
12563 msgid "guestfs_swapon_label"
12567 #: ../src/guestfs-actions.pod:4839
12570 " int guestfs_swapon_label (guestfs_h *g,\n"
12571 "\t\tconst char *label);\n"
12576 #: ../src/guestfs-actions.pod:4842
12578 "This command enables swap to a labeled swap partition. See "
12579 "C<guestfs_swapon_device> for other notes."
12583 #: ../src/guestfs-actions.pod:4847
12584 msgid "guestfs_swapon_uuid"
12588 #: ../src/guestfs-actions.pod:4849
12591 " int guestfs_swapon_uuid (guestfs_h *g,\n"
12592 "\t\tconst char *uuid);\n"
12597 #: ../src/guestfs-actions.pod:4852
12599 "This command enables swap to a swap partition with the given UUID. See "
12600 "C<guestfs_swapon_device> for other notes."
12604 #: ../src/guestfs-actions.pod:4857
12605 msgid "guestfs_sync"
12609 #: ../src/guestfs-actions.pod:4859
12612 " int guestfs_sync (guestfs_h *g);\n"
12617 #: ../src/guestfs-actions.pod:4861 ../fish/guestfish-actions.pod:3779
12619 "This syncs the disk, so that any writes are flushed through to the "
12620 "underlying disk image."
12624 #: ../src/guestfs-actions.pod:4864 ../fish/guestfish-actions.pod:3782
12626 "You should always call this if you have modified a disk image, before "
12627 "closing the handle."
12631 #: ../src/guestfs-actions.pod:4869
12632 msgid "guestfs_tail"
12636 #: ../src/guestfs-actions.pod:4871
12639 " char **guestfs_tail (guestfs_h *g,\n"
12640 "\t\tconst char *path);\n"
12645 #: ../src/guestfs-actions.pod:4874 ../fish/guestfish-actions.pod:3789
12647 "This command returns up to the last 10 lines of a file as a list of strings."
12651 #: ../src/guestfs-actions.pod:4884
12652 msgid "guestfs_tail_n"
12656 #: ../src/guestfs-actions.pod:4886
12659 " char **guestfs_tail_n (guestfs_h *g,\n"
12660 "\t\tint nrlines,\n"
12661 "\t\tconst char *path);\n"
12666 #: ../src/guestfs-actions.pod:4890 ../fish/guestfish-actions.pod:3799
12668 "If the parameter C<nrlines> is a positive number, this returns the last "
12669 "C<nrlines> lines of the file C<path>."
12673 #: ../src/guestfs-actions.pod:4893 ../fish/guestfish-actions.pod:3802
12675 "If the parameter C<nrlines> is a negative number, this returns lines from "
12676 "the file C<path>, starting with the C<-nrlines>th line."
12680 #: ../src/guestfs-actions.pod:4905
12681 msgid "guestfs_tar_in"
12685 #: ../src/guestfs-actions.pod:4907
12688 " int guestfs_tar_in (guestfs_h *g,\n"
12689 "\t\tconst char *tarfile,\n"
12690 "\t\tconst char *directory);\n"
12695 #: ../src/guestfs-actions.pod:4911 ../fish/guestfish-actions.pod:3814
12697 "This command uploads and unpacks local file C<tarfile> (an I<uncompressed> "
12698 "tar file) into C<directory>."
12702 #: ../src/guestfs-actions.pod:4914
12704 "To upload a compressed tarball, use C<guestfs_tgz_in> or C<guestfs_txz_in>."
12708 #: ../src/guestfs-actions.pod:4919
12709 msgid "guestfs_tar_out"
12713 #: ../src/guestfs-actions.pod:4921
12716 " int guestfs_tar_out (guestfs_h *g,\n"
12717 "\t\tconst char *directory,\n"
12718 "\t\tconst char *tarfile);\n"
12723 #: ../src/guestfs-actions.pod:4925 ../fish/guestfish-actions.pod:3826
12725 "This command packs the contents of C<directory> and downloads it to local "
12730 #: ../src/guestfs-actions.pod:4928
12732 "To download a compressed tarball, use C<guestfs_tgz_out> or "
12733 "C<guestfs_txz_out>."
12737 #: ../src/guestfs-actions.pod:4933
12738 msgid "guestfs_tgz_in"
12742 #: ../src/guestfs-actions.pod:4935
12745 " int guestfs_tgz_in (guestfs_h *g,\n"
12746 "\t\tconst char *tarball,\n"
12747 "\t\tconst char *directory);\n"
12752 #: ../src/guestfs-actions.pod:4939 ../fish/guestfish-actions.pod:3838
12754 "This command uploads and unpacks local file C<tarball> (a I<gzip compressed> "
12755 "tar file) into C<directory>."
12759 #: ../src/guestfs-actions.pod:4942
12760 msgid "To upload an uncompressed tarball, use C<guestfs_tar_in>."
12764 #: ../src/guestfs-actions.pod:4946
12765 msgid "guestfs_tgz_out"
12769 #: ../src/guestfs-actions.pod:4948
12772 " int guestfs_tgz_out (guestfs_h *g,\n"
12773 "\t\tconst char *directory,\n"
12774 "\t\tconst char *tarball);\n"
12779 #: ../src/guestfs-actions.pod:4952 ../fish/guestfish-actions.pod:3849
12781 "This command packs the contents of C<directory> and downloads it to local "
12786 #: ../src/guestfs-actions.pod:4955
12787 msgid "To download an uncompressed tarball, use C<guestfs_tar_out>."
12791 #: ../src/guestfs-actions.pod:4959
12792 msgid "guestfs_touch"
12796 #: ../src/guestfs-actions.pod:4961
12799 " int guestfs_touch (guestfs_h *g,\n"
12800 "\t\tconst char *path);\n"
12805 #: ../src/guestfs-actions.pod:4964 ../fish/guestfish-actions.pod:3860
12807 "Touch acts like the L<touch(1)> command. It can be used to update the "
12808 "timestamps on a file, or, if the file does not exist, to create a new zero-"
12813 #: ../src/guestfs-actions.pod:4968 ../fish/guestfish-actions.pod:3864
12815 "This command only works on regular files, and will fail on other file types "
12816 "such as directories, symbolic links, block special etc."
12820 #: ../src/guestfs-actions.pod:4973
12821 msgid "guestfs_truncate"
12825 #: ../src/guestfs-actions.pod:4975
12828 " int guestfs_truncate (guestfs_h *g,\n"
12829 "\t\tconst char *path);\n"
12834 #: ../src/guestfs-actions.pod:4978 ../fish/guestfish-actions.pod:3871
12836 "This command truncates C<path> to a zero-length file. The file must exist "
12841 #: ../src/guestfs-actions.pod:4983
12842 msgid "guestfs_truncate_size"
12846 #: ../src/guestfs-actions.pod:4985
12849 " int guestfs_truncate_size (guestfs_h *g,\n"
12850 "\t\tconst char *path,\n"
12851 "\t\tint64_t size);\n"
12856 #: ../src/guestfs-actions.pod:4989 ../fish/guestfish-actions.pod:3878
12858 "This command truncates C<path> to size C<size> bytes. The file must exist "
12863 #: ../src/guestfs-actions.pod:4992
12865 "If the current file size is less than C<size> then the file is extended to "
12866 "the required size with zero bytes. This creates a sparse file (ie. disk "
12867 "blocks are not allocated for the file until you write to it). To create a "
12868 "non-sparse file of zeroes, use C<guestfs_fallocate64> instead."
12872 #: ../src/guestfs-actions.pod:5000
12873 msgid "guestfs_tune2fs_l"
12877 #: ../src/guestfs-actions.pod:5002
12880 " char **guestfs_tune2fs_l (guestfs_h *g,\n"
12881 "\t\tconst char *device);\n"
12886 #: ../src/guestfs-actions.pod:5005 ../fish/guestfish-actions.pod:3891
12888 "This returns the contents of the ext2, ext3 or ext4 filesystem superblock on "
12893 #: ../src/guestfs-actions.pod:5008 ../fish/guestfish-actions.pod:3894
12895 "It is the same as running C<tune2fs -l device>. See L<tune2fs(8)> manpage "
12896 "for more details. The list of fields returned isn't clearly defined, and "
12897 "depends on both the version of C<tune2fs> that libguestfs was built against, "
12898 "and the filesystem itself."
12902 #: ../src/guestfs-actions.pod:5019
12903 msgid "guestfs_txz_in"
12907 #: ../src/guestfs-actions.pod:5021
12910 " int guestfs_txz_in (guestfs_h *g,\n"
12911 "\t\tconst char *tarball,\n"
12912 "\t\tconst char *directory);\n"
12917 #: ../src/guestfs-actions.pod:5025 ../fish/guestfish-actions.pod:3903
12919 "This command uploads and unpacks local file C<tarball> (an I<xz compressed> "
12920 "tar file) into C<directory>."
12924 #: ../src/guestfs-actions.pod:5030
12925 msgid "guestfs_txz_out"
12929 #: ../src/guestfs-actions.pod:5032
12932 " int guestfs_txz_out (guestfs_h *g,\n"
12933 "\t\tconst char *directory,\n"
12934 "\t\tconst char *tarball);\n"
12939 #: ../src/guestfs-actions.pod:5036 ../fish/guestfish-actions.pod:3912
12941 "This command packs the contents of C<directory> and downloads it to local "
12942 "file C<tarball> (as an xz compressed tar archive)."
12946 #: ../src/guestfs-actions.pod:5041
12947 msgid "guestfs_umask"
12951 #: ../src/guestfs-actions.pod:5043
12954 " int guestfs_umask (guestfs_h *g,\n"
12960 #: ../src/guestfs-actions.pod:5046 ../fish/guestfish-actions.pod:3921
12962 "This function sets the mask used for creating new files and device nodes to "
12967 #: ../src/guestfs-actions.pod:5049 ../fish/guestfish-actions.pod:3924
12969 "Typical umask values would be C<022> which creates new files with "
12970 "permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and C<002> which creates "
12971 "new files with permissions like \"-rw-rw-r--\" or \"-rwxrwxr-x\"."
12975 #: ../src/guestfs-actions.pod:5054 ../fish/guestfish-actions.pod:3929
12977 "The default umask is C<022>. This is important because it means that "
12978 "directories and device nodes will be created with C<0644> or C<0755> mode "
12979 "even if you specify C<0777>."
12983 #: ../src/guestfs-actions.pod:5058
12985 "See also C<guestfs_get_umask>, L<umask(2)>, C<guestfs_mknod>, "
12986 "C<guestfs_mkdir>."
12990 #: ../src/guestfs-actions.pod:5061 ../fish/guestfish-actions.pod:3936
12991 msgid "This call returns the previous umask."
12995 #: ../src/guestfs-actions.pod:5065
12996 msgid "guestfs_umount"
13000 #: ../src/guestfs-actions.pod:5067
13003 " int guestfs_umount (guestfs_h *g,\n"
13004 "\t\tconst char *pathordevice);\n"
13009 #: ../src/guestfs-actions.pod:5070 ../fish/guestfish-actions.pod:3944
13011 "This unmounts the given filesystem. The filesystem may be specified either "
13012 "by its mountpoint (path) or the device which contains the filesystem."
13016 #: ../src/guestfs-actions.pod:5076
13017 msgid "guestfs_umount_all"
13021 #: ../src/guestfs-actions.pod:5078
13024 " int guestfs_umount_all (guestfs_h *g);\n"
13029 #: ../src/guestfs-actions.pod:5080 ../fish/guestfish-actions.pod:3954
13030 msgid "This unmounts all mounted filesystems."
13034 #: ../src/guestfs-actions.pod:5082 ../fish/guestfish-actions.pod:3956
13035 msgid "Some internal mounts are not unmounted by this call."
13039 #: ../src/guestfs-actions.pod:5086
13040 msgid "guestfs_upload"
13044 #: ../src/guestfs-actions.pod:5088
13047 " int guestfs_upload (guestfs_h *g,\n"
13048 "\t\tconst char *filename,\n"
13049 "\t\tconst char *remotefilename);\n"
13054 #: ../src/guestfs-actions.pod:5092 ../src/guestfs-actions.pod:5108
13055 #: ../fish/guestfish-actions.pod:3962 ../fish/guestfish-actions.pod:3975
13056 msgid "Upload local file C<filename> to C<remotefilename> on the filesystem."
13060 #: ../src/guestfs-actions.pod:5097
13061 msgid "See also C<guestfs_download>."
13065 #: ../src/guestfs-actions.pod:5101
13066 msgid "guestfs_upload_offset"
13070 #: ../src/guestfs-actions.pod:5103
13073 " int guestfs_upload_offset (guestfs_h *g,\n"
13074 "\t\tconst char *filename,\n"
13075 "\t\tconst char *remotefilename,\n"
13076 "\t\tint64_t offset);\n"
13081 #: ../src/guestfs-actions.pod:5111 ../fish/guestfish-actions.pod:3978
13083 "C<remotefilename> is overwritten starting at the byte C<offset> specified. "
13084 "The intention is to overwrite parts of existing files or devices, although "
13085 "if a non-existant file is specified then it is created with a \"hole\" "
13086 "before C<offset>. The size of the data written is implicit in the size of "
13087 "the source C<filename>."
13091 #: ../src/guestfs-actions.pod:5118
13093 "Note that there is no limit on the amount of data that can be uploaded with "
13094 "this call, unlike with C<guestfs_pwrite>, and this call always writes the "
13095 "full amount unless an error occurs."
13099 #: ../src/guestfs-actions.pod:5123
13100 msgid "See also C<guestfs_upload>, C<guestfs_pwrite>."
13104 #: ../src/guestfs-actions.pod:5127
13105 msgid "guestfs_utimens"
13109 #: ../src/guestfs-actions.pod:5129
13112 " int guestfs_utimens (guestfs_h *g,\n"
13113 "\t\tconst char *path,\n"
13114 "\t\tint64_t atsecs,\n"
13115 "\t\tint64_t atnsecs,\n"
13116 "\t\tint64_t mtsecs,\n"
13117 "\t\tint64_t mtnsecs);\n"
13122 #: ../src/guestfs-actions.pod:5136 ../fish/guestfish-actions.pod:3998
13123 msgid "This command sets the timestamps of a file with nanosecond precision."
13127 #: ../src/guestfs-actions.pod:5139 ../fish/guestfish-actions.pod:4001
13129 "C<atsecs, atnsecs> are the last access time (atime) in secs and nanoseconds "
13134 #: ../src/guestfs-actions.pod:5142 ../fish/guestfish-actions.pod:4004
13136 "C<mtsecs, mtnsecs> are the last modification time (mtime) in secs and "
13137 "nanoseconds from the epoch."
13141 #: ../src/guestfs-actions.pod:5145 ../fish/guestfish-actions.pod:4007
13143 "If the C<*nsecs> field contains the special value C<-1> then the "
13144 "corresponding timestamp is set to the current time. (The C<*secs> field is "
13145 "ignored in this case)."
13149 #: ../src/guestfs-actions.pod:5149 ../fish/guestfish-actions.pod:4011
13151 "If the C<*nsecs> field contains the special value C<-2> then the "
13152 "corresponding timestamp is left unchanged. (The C<*secs> field is ignored "
13157 #: ../src/guestfs-actions.pod:5155 ../src/guestfs-structs.pod:175
13158 msgid "guestfs_version"
13162 #: ../src/guestfs-actions.pod:5157
13165 " struct guestfs_version *guestfs_version (guestfs_h *g);\n"
13170 #: ../src/guestfs-actions.pod:5159 ../fish/guestfish-actions.pod:4019
13172 "Return the libguestfs version number that the program is linked against."
13176 #: ../src/guestfs-actions.pod:5162 ../fish/guestfish-actions.pod:4022
13178 "Note that because of dynamic linking this is not necessarily the version of "
13179 "libguestfs that you compiled against. You can compile the program, and then "
13180 "at runtime dynamically link against a completely different C<libguestfs.so> "
13185 #: ../src/guestfs-actions.pod:5167 ../fish/guestfish-actions.pod:4027
13187 "This call was added in version C<1.0.58>. In previous versions of "
13188 "libguestfs there was no way to get the version number. From C code you can "
13189 "use dynamic linker functions to find out if this symbol exists (if it "
13190 "doesn't, then it's an earlier version)."
13194 #: ../src/guestfs-actions.pod:5173 ../fish/guestfish-actions.pod:4033
13196 "The call returns a structure with four elements. The first three (C<major>, "
13197 "C<minor> and C<release>) are numbers and correspond to the usual version "
13198 "triplet. The fourth element (C<extra>) is a string and is normally empty, "
13199 "but may be used for distro-specific information."
13203 #: ../src/guestfs-actions.pod:5179 ../fish/guestfish-actions.pod:4039
13205 "To construct the original version string: C<$major.$minor.$release$extra>"
13209 #: ../src/guestfs-actions.pod:5182 ../fish/guestfish-actions.pod:4042
13210 msgid "See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>."
13214 #: ../src/guestfs-actions.pod:5184
13216 "I<Note:> Don't use this call to test for availability of features. In "
13217 "enterprise distributions we backport features from later versions into "
13218 "earlier versions, making this an unreliable way to test for features. Use "
13219 "C<guestfs_available> instead."
13223 #: ../src/guestfs-actions.pod:5190
13225 "This function returns a C<struct guestfs_version *>, or NULL if there was an "
13226 "error. I<The caller must call C<guestfs_free_version> after use>."
13230 #: ../src/guestfs-actions.pod:5194
13231 msgid "guestfs_vfs_label"
13235 #: ../src/guestfs-actions.pod:5196
13238 " char *guestfs_vfs_label (guestfs_h *g,\n"
13239 "\t\tconst char *device);\n"
13244 #: ../src/guestfs-actions.pod:5199 ../fish/guestfish-actions.pod:4054
13245 msgid "This returns the filesystem label of the filesystem on C<device>."
13249 #: ../src/guestfs-actions.pod:5202 ../fish/guestfish-actions.pod:4057
13250 msgid "If the filesystem is unlabeled, this returns the empty string."
13254 #: ../src/guestfs-actions.pod:5204
13255 msgid "To find a filesystem from the label, use C<guestfs_findfs_label>."
13259 #: ../src/guestfs-actions.pod:5209
13260 msgid "guestfs_vfs_type"
13264 #: ../src/guestfs-actions.pod:5211
13267 " char *guestfs_vfs_type (guestfs_h *g,\n"
13268 "\t\tconst char *device);\n"
13273 #: ../src/guestfs-actions.pod:5214 ../fish/guestfish-actions.pod:4065
13275 "This command gets the filesystem type corresponding to the filesystem on "
13280 #: ../src/guestfs-actions.pod:5217 ../fish/guestfish-actions.pod:4068
13282 "For most filesystems, the result is the name of the Linux VFS module which "
13283 "would be used to mount this filesystem if you mounted it without specifying "
13284 "the filesystem type. For example a string such as C<ext3> or C<ntfs>."
13288 #: ../src/guestfs-actions.pod:5225
13289 msgid "guestfs_vfs_uuid"
13293 #: ../src/guestfs-actions.pod:5227
13296 " char *guestfs_vfs_uuid (guestfs_h *g,\n"
13297 "\t\tconst char *device);\n"
13302 #: ../src/guestfs-actions.pod:5230 ../fish/guestfish-actions.pod:4077
13303 msgid "This returns the filesystem UUID of the filesystem on C<device>."
13307 #: ../src/guestfs-actions.pod:5233 ../fish/guestfish-actions.pod:4080
13308 msgid "If the filesystem does not have a UUID, this returns the empty string."
13312 #: ../src/guestfs-actions.pod:5235
13313 msgid "To find a filesystem from the UUID, use C<guestfs_findfs_uuid>."
13317 #: ../src/guestfs-actions.pod:5240
13318 msgid "guestfs_vg_activate"
13322 #: ../src/guestfs-actions.pod:5242
13325 " int guestfs_vg_activate (guestfs_h *g,\n"
13326 "\t\tint activate,\n"
13327 "\t\tchar *const *volgroups);\n"
13332 #: ../src/guestfs-actions.pod:5246 ../fish/guestfish-actions.pod:4088
13334 "This command activates or (if C<activate> is false) deactivates all logical "
13335 "volumes in the listed volume groups C<volgroups>. If activated, then they "
13336 "are made known to the kernel, ie. they appear as C</dev/mapper> devices. If "
13337 "deactivated, then those devices disappear."
13341 #: ../src/guestfs-actions.pod:5252 ../fish/guestfish-actions.pod:4094
13342 msgid "This command is the same as running C<vgchange -a y|n volgroups...>"
13346 #: ../src/guestfs-actions.pod:5254 ../fish/guestfish-actions.pod:4096
13348 "Note that if C<volgroups> is an empty list then B<all> volume groups are "
13349 "activated or deactivated."
13353 #: ../src/guestfs-actions.pod:5259
13354 msgid "guestfs_vg_activate_all"
13358 #: ../src/guestfs-actions.pod:5261
13361 " int guestfs_vg_activate_all (guestfs_h *g,\n"
13362 "\t\tint activate);\n"
13367 #: ../src/guestfs-actions.pod:5264 ../fish/guestfish-actions.pod:4103
13369 "This command activates or (if C<activate> is false) deactivates all logical "
13370 "volumes in all volume groups. If activated, then they are made known to the "
13371 "kernel, ie. they appear as C</dev/mapper> devices. If deactivated, then "
13372 "those devices disappear."
13376 #: ../src/guestfs-actions.pod:5270 ../fish/guestfish-actions.pod:4109
13377 msgid "This command is the same as running C<vgchange -a y|n>"
13381 #: ../src/guestfs-actions.pod:5274
13382 msgid "guestfs_vgcreate"
13386 #: ../src/guestfs-actions.pod:5276
13389 " int guestfs_vgcreate (guestfs_h *g,\n"
13390 "\t\tconst char *volgroup,\n"
13391 "\t\tchar *const *physvols);\n"
13396 #: ../src/guestfs-actions.pod:5280 ../fish/guestfish-actions.pod:4115
13398 "This creates an LVM volume group called C<volgroup> from the non-empty list "
13399 "of physical volumes C<physvols>."
13403 #: ../src/guestfs-actions.pod:5285
13404 msgid "guestfs_vglvuuids"
13408 #: ../src/guestfs-actions.pod:5287
13411 " char **guestfs_vglvuuids (guestfs_h *g,\n"
13412 "\t\tconst char *vgname);\n"
13417 #: ../src/guestfs-actions.pod:5290 ../fish/guestfish-actions.pod:4122
13419 "Given a VG called C<vgname>, this returns the UUIDs of all the logical "
13420 "volumes created in this volume group."
13424 #: ../src/guestfs-actions.pod:5293
13426 "You can use this along with C<guestfs_lvs> and C<guestfs_lvuuid> calls to "
13427 "associate logical volumes and volume groups."
13431 #: ../src/guestfs-actions.pod:5296
13432 msgid "See also C<guestfs_vgpvuuids>."
13436 #: ../src/guestfs-actions.pod:5302
13437 msgid "guestfs_vgpvuuids"
13441 #: ../src/guestfs-actions.pod:5304
13444 " char **guestfs_vgpvuuids (guestfs_h *g,\n"
13445 "\t\tconst char *vgname);\n"
13450 #: ../src/guestfs-actions.pod:5307 ../fish/guestfish-actions.pod:4134
13452 "Given a VG called C<vgname>, this returns the UUIDs of all the physical "
13453 "volumes that this volume group resides on."
13457 #: ../src/guestfs-actions.pod:5310
13459 "You can use this along with C<guestfs_pvs> and C<guestfs_pvuuid> calls to "
13460 "associate physical volumes and volume groups."
13464 #: ../src/guestfs-actions.pod:5313
13465 msgid "See also C<guestfs_vglvuuids>."
13469 #: ../src/guestfs-actions.pod:5319
13470 msgid "guestfs_vgremove"
13474 #: ../src/guestfs-actions.pod:5321
13477 " int guestfs_vgremove (guestfs_h *g,\n"
13478 "\t\tconst char *vgname);\n"
13483 #: ../src/guestfs-actions.pod:5324 ../fish/guestfish-actions.pod:4146
13484 msgid "Remove an LVM volume group C<vgname>, (for example C<VG>)."
13488 #: ../src/guestfs-actions.pod:5326 ../fish/guestfish-actions.pod:4148
13490 "This also forcibly removes all logical volumes in the volume group (if any)."
13494 #: ../src/guestfs-actions.pod:5331
13495 msgid "guestfs_vgrename"
13499 #: ../src/guestfs-actions.pod:5333
13502 " int guestfs_vgrename (guestfs_h *g,\n"
13503 "\t\tconst char *volgroup,\n"
13504 "\t\tconst char *newvolgroup);\n"
13509 #: ../src/guestfs-actions.pod:5337 ../fish/guestfish-actions.pod:4155
13510 msgid "Rename a volume group C<volgroup> with the new name C<newvolgroup>."
13514 #: ../src/guestfs-actions.pod:5341
13515 msgid "guestfs_vgs"
13519 #: ../src/guestfs-actions.pod:5343
13522 " char **guestfs_vgs (guestfs_h *g);\n"
13527 #: ../src/guestfs-actions.pod:5345 ../fish/guestfish-actions.pod:4161
13529 "List all the volumes groups detected. This is the equivalent of the L<vgs(8)"
13534 #: ../src/guestfs-actions.pod:5348 ../fish/guestfish-actions.pod:4164
13536 "This returns a list of just the volume group names that were detected (eg. "
13541 #: ../src/guestfs-actions.pod:5351
13542 msgid "See also C<guestfs_vgs_full>."
13546 #: ../src/guestfs-actions.pod:5357
13547 msgid "guestfs_vgs_full"
13551 #: ../src/guestfs-actions.pod:5359
13554 " struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *g);\n"
13559 #: ../src/guestfs-actions.pod:5361 ../fish/guestfish-actions.pod:4173
13561 "List all the volumes groups detected. This is the equivalent of the L<vgs(8)"
13562 "> command. The \"full\" version includes all fields."
13566 #: ../src/guestfs-actions.pod:5364
13568 "This function returns a C<struct guestfs_lvm_vg_list *> (see E<lt>guestfs-"
13569 "structs.hE<gt>), or NULL if there was an error. I<The caller must call "
13570 "C<guestfs_free_lvm_vg_list> after use>."
13574 #: ../src/guestfs-actions.pod:5369
13575 msgid "guestfs_vgscan"
13579 #: ../src/guestfs-actions.pod:5371
13582 " int guestfs_vgscan (guestfs_h *g);\n"
13587 #: ../src/guestfs-actions.pod:5373 ../fish/guestfish-actions.pod:4180
13589 "This rescans all block devices and rebuilds the list of LVM physical "
13590 "volumes, volume groups and logical volumes."
13594 #: ../src/guestfs-actions.pod:5378
13595 msgid "guestfs_vguuid"
13599 #: ../src/guestfs-actions.pod:5380
13602 " char *guestfs_vguuid (guestfs_h *g,\n"
13603 "\t\tconst char *vgname);\n"
13608 #: ../src/guestfs-actions.pod:5383 ../fish/guestfish-actions.pod:4187
13609 msgid "This command returns the UUID of the LVM VG named C<vgname>."
13613 #: ../src/guestfs-actions.pod:5388
13614 msgid "guestfs_wait_ready"
13618 #: ../src/guestfs-actions.pod:5390
13621 " int guestfs_wait_ready (guestfs_h *g);\n"
13626 #: ../src/guestfs-actions.pod:5392
13627 msgid "This function is a no op."
13631 #: ../src/guestfs-actions.pod:5394
13633 "In versions of the API E<lt> 1.0.71 you had to call this function just after "
13634 "calling C<guestfs_launch> to wait for the launch to complete. However this "
13635 "is no longer necessary because C<guestfs_launch> now does the waiting."
13639 #: ../src/guestfs-actions.pod:5399
13641 "If you see any calls to this function in code then you can just remove them, "
13642 "unless you want to retain compatibility with older versions of the API."
13646 #: ../src/guestfs-actions.pod:5405
13647 msgid "guestfs_wc_c"
13651 #: ../src/guestfs-actions.pod:5407
13654 " int guestfs_wc_c (guestfs_h *g,\n"
13655 "\t\tconst char *path);\n"
13660 #: ../src/guestfs-actions.pod:5410 ../fish/guestfish-actions.pod:4193
13662 "This command counts the characters in a file, using the C<wc -c> external "
13667 #: ../src/guestfs-actions.pod:5415
13668 msgid "guestfs_wc_l"
13672 #: ../src/guestfs-actions.pod:5417
13675 " int guestfs_wc_l (guestfs_h *g,\n"
13676 "\t\tconst char *path);\n"
13681 #: ../src/guestfs-actions.pod:5420 ../fish/guestfish-actions.pod:4200
13683 "This command counts the lines in a file, using the C<wc -l> external command."
13687 #: ../src/guestfs-actions.pod:5425
13688 msgid "guestfs_wc_w"
13692 #: ../src/guestfs-actions.pod:5427
13695 " int guestfs_wc_w (guestfs_h *g,\n"
13696 "\t\tconst char *path);\n"
13701 #: ../src/guestfs-actions.pod:5430 ../fish/guestfish-actions.pod:4207
13703 "This command counts the words in a file, using the C<wc -w> external command."
13707 #: ../src/guestfs-actions.pod:5435
13708 msgid "guestfs_write"
13712 #: ../src/guestfs-actions.pod:5437
13715 " int guestfs_write (guestfs_h *g,\n"
13716 "\t\tconst char *path,\n"
13717 "\t\tconst char *content,\n"
13718 "\t\tsize_t content_size);\n"
13723 #: ../src/guestfs-actions.pod:5442 ../fish/guestfish-actions.pod:4214
13725 "This call creates a file called C<path>. The content of the file is the "
13726 "string C<content> (which can contain any 8 bit data)."
13730 #: ../src/guestfs-actions.pod:5450
13731 msgid "guestfs_write_file"
13735 #: ../src/guestfs-actions.pod:5452
13738 " int guestfs_write_file (guestfs_h *g,\n"
13739 "\t\tconst char *path,\n"
13740 "\t\tconst char *content,\n"
13746 #: ../src/guestfs-actions.pod:5457 ../fish/guestfish-actions.pod:4224
13748 "This call creates a file called C<path>. The contents of the file is the "
13749 "string C<content> (which can contain any 8 bit data), with length C<size>."
13753 #: ../src/guestfs-actions.pod:5461 ../fish/guestfish-actions.pod:4228
13755 "As a special case, if C<size> is C<0> then the length is calculated using "
13756 "C<strlen> (so in this case the content cannot contain embedded ASCII NULs)."
13760 #: ../src/guestfs-actions.pod:5465 ../fish/guestfish-actions.pod:4232
13762 "I<NB.> Owing to a bug, writing content containing ASCII NUL characters does "
13763 "I<not> work, even if the length is specified."
13767 #: ../src/guestfs-actions.pod:5473 ../fish/guestfish-actions.pod:4238
13769 "This function is deprecated. In new code, use the C<write> call instead."
13773 #: ../src/guestfs-actions.pod:5480
13774 msgid "guestfs_zegrep"
13778 #: ../src/guestfs-actions.pod:5482
13781 " char **guestfs_zegrep (guestfs_h *g,\n"
13782 "\t\tconst char *regex,\n"
13783 "\t\tconst char *path);\n"
13788 #: ../src/guestfs-actions.pod:5486 ../fish/guestfish-actions.pod:4249
13790 "This calls the external C<zegrep> program and returns the matching lines."
13794 #: ../src/guestfs-actions.pod:5496
13795 msgid "guestfs_zegrepi"
13799 #: ../src/guestfs-actions.pod:5498
13802 " char **guestfs_zegrepi (guestfs_h *g,\n"
13803 "\t\tconst char *regex,\n"
13804 "\t\tconst char *path);\n"
13809 #: ../src/guestfs-actions.pod:5502 ../fish/guestfish-actions.pod:4259
13811 "This calls the external C<zegrep -i> program and returns the matching lines."
13815 #: ../src/guestfs-actions.pod:5512
13816 msgid "guestfs_zero"
13820 #: ../src/guestfs-actions.pod:5514
13823 " int guestfs_zero (guestfs_h *g,\n"
13824 "\t\tconst char *device);\n"
13829 #: ../src/guestfs-actions.pod:5517 ../fish/guestfish-actions.pod:4269
13830 msgid "This command writes zeroes over the first few blocks of C<device>."
13834 #: ../src/guestfs-actions.pod:5519 ../fish/guestfish-actions.pod:4271
13836 "How many blocks are zeroed isn't specified (but it's I<not> enough to "
13837 "securely wipe the device). It should be sufficient to remove any partition "
13838 "tables, filesystem superblocks and so on."
13842 #: ../src/guestfs-actions.pod:5523
13843 msgid "See also: C<guestfs_zero_device>, C<guestfs_scrub_device>."
13847 #: ../src/guestfs-actions.pod:5532
13848 msgid "guestfs_zero_device"
13852 #: ../src/guestfs-actions.pod:5534
13855 " int guestfs_zero_device (guestfs_h *g,\n"
13856 "\t\tconst char *device);\n"
13861 #: ../src/guestfs-actions.pod:5537
13863 "This command writes zeroes over the entire C<device>. Compare with "
13864 "C<guestfs_zero> which just zeroes the first few blocks of a device."
13868 #: ../src/guestfs-actions.pod:5551
13869 msgid "guestfs_zerofree"
13873 #: ../src/guestfs-actions.pod:5553
13876 " int guestfs_zerofree (guestfs_h *g,\n"
13877 "\t\tconst char *device);\n"
13882 #: ../src/guestfs-actions.pod:5556 ../fish/guestfish-actions.pod:4292
13884 "This runs the I<zerofree> program on C<device>. This program claims to zero "
13885 "unused inodes and disk blocks on an ext2/3 filesystem, thus making it "
13886 "possible to compress the filesystem more effectively."
13890 #: ../src/guestfs-actions.pod:5561 ../fish/guestfish-actions.pod:4297
13891 msgid "You should B<not> run this program if the filesystem is mounted."
13895 #: ../src/guestfs-actions.pod:5564 ../fish/guestfish-actions.pod:4300
13897 "It is possible that using this program can damage the filesystem or data on "
13902 #: ../src/guestfs-actions.pod:5569
13903 msgid "guestfs_zfgrep"
13907 #: ../src/guestfs-actions.pod:5571
13910 " char **guestfs_zfgrep (guestfs_h *g,\n"
13911 "\t\tconst char *pattern,\n"
13912 "\t\tconst char *path);\n"
13917 #: ../src/guestfs-actions.pod:5575 ../fish/guestfish-actions.pod:4307
13919 "This calls the external C<zfgrep> program and returns the matching lines."
13923 #: ../src/guestfs-actions.pod:5585
13924 msgid "guestfs_zfgrepi"
13928 #: ../src/guestfs-actions.pod:5587
13931 " char **guestfs_zfgrepi (guestfs_h *g,\n"
13932 "\t\tconst char *pattern,\n"
13933 "\t\tconst char *path);\n"
13938 #: ../src/guestfs-actions.pod:5591 ../fish/guestfish-actions.pod:4317
13940 "This calls the external C<zfgrep -i> program and returns the matching lines."
13944 #: ../src/guestfs-actions.pod:5601
13945 msgid "guestfs_zfile"
13949 #: ../src/guestfs-actions.pod:5603
13952 " char *guestfs_zfile (guestfs_h *g,\n"
13953 "\t\tconst char *meth,\n"
13954 "\t\tconst char *path);\n"
13959 #: ../src/guestfs-actions.pod:5607 ../fish/guestfish-actions.pod:4327
13961 "This command runs C<file> after first decompressing C<path> using C<method>."
13965 #: ../src/guestfs-actions.pod:5610 ../fish/guestfish-actions.pod:4330
13966 msgid "C<method> must be one of C<gzip>, C<compress> or C<bzip2>."
13970 #: ../src/guestfs-actions.pod:5612
13972 "Since 1.0.63, use C<guestfs_file> instead which can now process compressed "
13977 #: ../src/guestfs-actions.pod:5618 ../fish/guestfish-actions.pod:4335
13979 "This function is deprecated. In new code, use the C<file> call instead."
13983 #: ../src/guestfs-actions.pod:5625
13984 msgid "guestfs_zgrep"
13988 #: ../src/guestfs-actions.pod:5627
13991 " char **guestfs_zgrep (guestfs_h *g,\n"
13992 "\t\tconst char *regex,\n"
13993 "\t\tconst char *path);\n"
13998 #: ../src/guestfs-actions.pod:5631 ../fish/guestfish-actions.pod:4346
14000 "This calls the external C<zgrep> program and returns the matching lines."
14004 #: ../src/guestfs-actions.pod:5641
14005 msgid "guestfs_zgrepi"
14009 #: ../src/guestfs-actions.pod:5643
14012 " char **guestfs_zgrepi (guestfs_h *g,\n"
14013 "\t\tconst char *regex,\n"
14014 "\t\tconst char *path);\n"
14019 #: ../src/guestfs-actions.pod:5647 ../fish/guestfish-actions.pod:4356
14021 "This calls the external C<zgrep -i> program and returns the matching lines."
14025 #: ../src/guestfs-availability.pod:3
14030 #: ../src/guestfs-availability.pod:5
14032 "The following functions: L</guestfs_aug_clear> L</guestfs_aug_close> L</"
14033 "guestfs_aug_defnode> L</guestfs_aug_defvar> L</guestfs_aug_get> L</"
14034 "guestfs_aug_init> L</guestfs_aug_insert> L</guestfs_aug_load> L</"
14035 "guestfs_aug_ls> L</guestfs_aug_match> L</guestfs_aug_mv> L</guestfs_aug_rm> "
14036 "L</guestfs_aug_save> L</guestfs_aug_set>"
14040 #: ../src/guestfs-availability.pod:21
14045 #: ../src/guestfs-availability.pod:23
14047 "The following functions: L</guestfs_inotify_add_watch> L</"
14048 "guestfs_inotify_close> L</guestfs_inotify_files> L</guestfs_inotify_init> L</"
14049 "guestfs_inotify_read> L</guestfs_inotify_rm_watch>"
14053 #: ../src/guestfs-availability.pod:31
14054 msgid "B<linuxfsuuid>"
14058 #: ../src/guestfs-availability.pod:33
14060 "The following functions: L</guestfs_mke2fs_JU> L</guestfs_mke2journal_U> L</"
14061 "guestfs_mkswap_U> L</guestfs_swapoff_uuid> L</guestfs_swapon_uuid>"
14065 #: ../src/guestfs-availability.pod:40
14066 msgid "B<linuxmodules>"
14070 #: ../src/guestfs-availability.pod:42
14071 msgid "The following functions: L</guestfs_modprobe>"
14075 #: ../src/guestfs-availability.pod:45
14076 msgid "B<linuxxattrs>"
14080 #: ../src/guestfs-availability.pod:47
14082 "The following functions: L</guestfs_getxattrs> L</guestfs_lgetxattrs> L</"
14083 "guestfs_lremovexattr> L</guestfs_lsetxattr> L</guestfs_lxattrlist> L</"
14084 "guestfs_removexattr> L</guestfs_setxattr>"
14088 #: ../src/guestfs-availability.pod:56
14093 #: ../src/guestfs-availability.pod:58
14095 "The following functions: L</guestfs_luks_add_key> L</guestfs_luks_close> L</"
14096 "guestfs_luks_format> L</guestfs_luks_format_cipher> L</"
14097 "guestfs_luks_kill_slot> L</guestfs_luks_open> L</guestfs_luks_open_ro>"
14101 #: ../src/guestfs-availability.pod:67
14106 #: ../src/guestfs-availability.pod:69
14108 "The following functions: L</guestfs_is_lv> L</guestfs_lvcreate> L</"
14109 "guestfs_lvm_remove_all> L</guestfs_lvm_set_filter> L</guestfs_lvremove> L</"
14110 "guestfs_lvresize> L</guestfs_lvresize_free> L</guestfs_lvs> L</"
14111 "guestfs_lvs_full> L</guestfs_pvcreate> L</guestfs_pvremove> L</"
14112 "guestfs_pvresize> L</guestfs_pvresize_size> L</guestfs_pvs> L</"
14113 "guestfs_pvs_full> L</guestfs_vg_activate> L</guestfs_vg_activate_all> L</"
14114 "guestfs_vgcreate> L</guestfs_vgremove> L</guestfs_vgs> L</guestfs_vgs_full>"
14118 #: ../src/guestfs-availability.pod:92
14123 #: ../src/guestfs-availability.pod:94
14125 "The following functions: L</guestfs_mkfifo> L</guestfs_mknod> L</"
14126 "guestfs_mknod_b> L</guestfs_mknod_c>"
14130 #: ../src/guestfs-availability.pod:100
14135 #: ../src/guestfs-availability.pod:102
14136 msgid "The following functions: L</guestfs_ntfs_3g_probe>"
14140 #: ../src/guestfs-availability.pod:105
14141 msgid "B<ntfsprogs>"
14145 #: ../src/guestfs-availability.pod:107
14147 "The following functions: L</guestfs_ntfsresize> L</guestfs_ntfsresize_size>"
14151 #: ../src/guestfs-availability.pod:111
14152 msgid "B<realpath>"
14156 #: ../src/guestfs-availability.pod:113
14157 msgid "The following functions: L</guestfs_realpath>"
14161 #: ../src/guestfs-availability.pod:116
14166 #: ../src/guestfs-availability.pod:118
14168 "The following functions: L</guestfs_scrub_device> L</guestfs_scrub_file> L</"
14169 "guestfs_scrub_freespace>"
14173 #: ../src/guestfs-availability.pod:123
14178 #: ../src/guestfs-availability.pod:125
14179 msgid "The following functions: L</guestfs_getcon> L</guestfs_setcon>"
14183 #: ../src/guestfs-availability.pod:129
14188 #: ../src/guestfs-availability.pod:131
14189 msgid "The following functions: L</guestfs_txz_in> L</guestfs_txz_out>"
14193 #: ../src/guestfs-availability.pod:135
14194 msgid "B<zerofree>"
14198 #: ../src/guestfs-availability.pod:137
14199 msgid "The following functions: L</guestfs_zerofree>"
14203 #: ../src/guestfs-structs.pod:1
14204 msgid "guestfs_int_bool"
14208 #: ../src/guestfs-structs.pod:3
14211 " struct guestfs_int_bool {\n"
14219 #: ../src/guestfs-structs.pod:8
14222 " struct guestfs_int_bool_list {\n"
14223 " uint32_t len; /* Number of elements in list. */\n"
14224 " struct guestfs_int_bool *val; /* Elements. */\n"
14230 #: ../src/guestfs-structs.pod:13
14233 " void guestfs_free_int_bool (struct guestfs_free_int_bool *);\n"
14234 " void guestfs_free_int_bool_list (struct guestfs_free_int_bool_list *);\n"
14239 #: ../src/guestfs-structs.pod:16
14240 msgid "guestfs_lvm_pv"
14244 #: ../src/guestfs-structs.pod:18
14247 " struct guestfs_lvm_pv {\n"
14248 " char *pv_name;\n"
14249 " /* The next field is NOT nul-terminated, be careful when printing it: */\n"
14250 " char pv_uuid[32];\n"
14252 " uint64_t pv_size;\n"
14253 " uint64_t dev_size;\n"
14254 " uint64_t pv_free;\n"
14255 " uint64_t pv_used;\n"
14256 " char *pv_attr;\n"
14257 " int64_t pv_pe_count;\n"
14258 " int64_t pv_pe_alloc_count;\n"
14259 " char *pv_tags;\n"
14260 " uint64_t pe_start;\n"
14261 " int64_t pv_mda_count;\n"
14262 " uint64_t pv_mda_free;\n"
14268 #: ../src/guestfs-structs.pod:36
14271 " struct guestfs_lvm_pv_list {\n"
14272 " uint32_t len; /* Number of elements in list. */\n"
14273 " struct guestfs_lvm_pv *val; /* Elements. */\n"
14279 #: ../src/guestfs-structs.pod:41
14282 " void guestfs_free_lvm_pv (struct guestfs_free_lvm_pv *);\n"
14283 " void guestfs_free_lvm_pv_list (struct guestfs_free_lvm_pv_list *);\n"
14288 #: ../src/guestfs-structs.pod:44
14289 msgid "guestfs_lvm_vg"
14293 #: ../src/guestfs-structs.pod:46
14296 " struct guestfs_lvm_vg {\n"
14297 " char *vg_name;\n"
14298 " /* The next field is NOT nul-terminated, be careful when printing it: */\n"
14299 " char vg_uuid[32];\n"
14301 " char *vg_attr;\n"
14302 " uint64_t vg_size;\n"
14303 " uint64_t vg_free;\n"
14304 " char *vg_sysid;\n"
14305 " uint64_t vg_extent_size;\n"
14306 " int64_t vg_extent_count;\n"
14307 " int64_t vg_free_count;\n"
14308 " int64_t max_lv;\n"
14309 " int64_t max_pv;\n"
14310 " int64_t pv_count;\n"
14311 " int64_t lv_count;\n"
14312 " int64_t snap_count;\n"
14313 " int64_t vg_seqno;\n"
14314 " char *vg_tags;\n"
14315 " int64_t vg_mda_count;\n"
14316 " uint64_t vg_mda_free;\n"
14322 #: ../src/guestfs-structs.pod:69
14325 " struct guestfs_lvm_vg_list {\n"
14326 " uint32_t len; /* Number of elements in list. */\n"
14327 " struct guestfs_lvm_vg *val; /* Elements. */\n"
14333 #: ../src/guestfs-structs.pod:74
14336 " void guestfs_free_lvm_vg (struct guestfs_free_lvm_vg *);\n"
14337 " void guestfs_free_lvm_vg_list (struct guestfs_free_lvm_vg_list *);\n"
14342 #: ../src/guestfs-structs.pod:77
14343 msgid "guestfs_lvm_lv"
14347 #: ../src/guestfs-structs.pod:79
14350 " struct guestfs_lvm_lv {\n"
14351 " char *lv_name;\n"
14352 " /* The next field is NOT nul-terminated, be careful when printing it: */\n"
14353 " char lv_uuid[32];\n"
14354 " char *lv_attr;\n"
14355 " int64_t lv_major;\n"
14356 " int64_t lv_minor;\n"
14357 " int64_t lv_kernel_major;\n"
14358 " int64_t lv_kernel_minor;\n"
14359 " uint64_t lv_size;\n"
14360 " int64_t seg_count;\n"
14362 " /* The next field is [0..100] or -1 meaning 'not present': */\n"
14363 " float snap_percent;\n"
14364 " /* The next field is [0..100] or -1 meaning 'not present': */\n"
14365 " float copy_percent;\n"
14366 " char *move_pv;\n"
14367 " char *lv_tags;\n"
14368 " char *mirror_log;\n"
14369 " char *modules;\n"
14375 #: ../src/guestfs-structs.pod:101
14378 " struct guestfs_lvm_lv_list {\n"
14379 " uint32_t len; /* Number of elements in list. */\n"
14380 " struct guestfs_lvm_lv *val; /* Elements. */\n"
14386 #: ../src/guestfs-structs.pod:106
14389 " void guestfs_free_lvm_lv (struct guestfs_free_lvm_lv *);\n"
14390 " void guestfs_free_lvm_lv_list (struct guestfs_free_lvm_lv_list *);\n"
14395 #: ../src/guestfs-structs.pod:111
14398 " struct guestfs_stat {\n"
14402 " int64_t nlink;\n"
14407 " int64_t blksize;\n"
14408 " int64_t blocks;\n"
14409 " int64_t atime;\n"
14410 " int64_t mtime;\n"
14411 " int64_t ctime;\n"
14417 #: ../src/guestfs-structs.pod:127
14420 " struct guestfs_stat_list {\n"
14421 " uint32_t len; /* Number of elements in list. */\n"
14422 " struct guestfs_stat *val; /* Elements. */\n"
14428 #: ../src/guestfs-structs.pod:132
14431 " void guestfs_free_stat (struct guestfs_free_stat *);\n"
14432 " void guestfs_free_stat_list (struct guestfs_free_stat_list *);\n"
14437 #: ../src/guestfs-structs.pod:137
14440 " struct guestfs_statvfs {\n"
14441 " int64_t bsize;\n"
14442 " int64_t frsize;\n"
14443 " int64_t blocks;\n"
14444 " int64_t bfree;\n"
14445 " int64_t bavail;\n"
14446 " int64_t files;\n"
14447 " int64_t ffree;\n"
14448 " int64_t favail;\n"
14451 " int64_t namemax;\n"
14457 #: ../src/guestfs-structs.pod:151
14460 " struct guestfs_statvfs_list {\n"
14461 " uint32_t len; /* Number of elements in list. */\n"
14462 " struct guestfs_statvfs *val; /* Elements. */\n"
14468 #: ../src/guestfs-structs.pod:156
14471 " void guestfs_free_statvfs (struct guestfs_free_statvfs *);\n"
14472 " void guestfs_free_statvfs_list (struct guestfs_free_statvfs_list *);\n"
14477 #: ../src/guestfs-structs.pod:159
14478 msgid "guestfs_dirent"
14482 #: ../src/guestfs-structs.pod:161
14485 " struct guestfs_dirent {\n"
14494 #: ../src/guestfs-structs.pod:167
14497 " struct guestfs_dirent_list {\n"
14498 " uint32_t len; /* Number of elements in list. */\n"
14499 " struct guestfs_dirent *val; /* Elements. */\n"
14505 #: ../src/guestfs-structs.pod:172
14508 " void guestfs_free_dirent (struct guestfs_free_dirent *);\n"
14509 " void guestfs_free_dirent_list (struct guestfs_free_dirent_list *);\n"
14514 #: ../src/guestfs-structs.pod:177
14517 " struct guestfs_version {\n"
14518 " int64_t major;\n"
14519 " int64_t minor;\n"
14520 " int64_t release;\n"
14527 #: ../src/guestfs-structs.pod:184
14530 " struct guestfs_version_list {\n"
14531 " uint32_t len; /* Number of elements in list. */\n"
14532 " struct guestfs_version *val; /* Elements. */\n"
14538 #: ../src/guestfs-structs.pod:189
14541 " void guestfs_free_version (struct guestfs_free_version *);\n"
14542 " void guestfs_free_version_list (struct guestfs_free_version_list *);\n"
14547 #: ../src/guestfs-structs.pod:192
14548 msgid "guestfs_xattr"
14552 #: ../src/guestfs-structs.pod:194
14555 " struct guestfs_xattr {\n"
14556 " char *attrname;\n"
14557 " /* The next two fields describe a byte array. */\n"
14558 " uint32_t attrval_len;\n"
14559 " char *attrval;\n"
14565 #: ../src/guestfs-structs.pod:201
14568 " struct guestfs_xattr_list {\n"
14569 " uint32_t len; /* Number of elements in list. */\n"
14570 " struct guestfs_xattr *val; /* Elements. */\n"
14576 #: ../src/guestfs-structs.pod:206
14579 " void guestfs_free_xattr (struct guestfs_free_xattr *);\n"
14580 " void guestfs_free_xattr_list (struct guestfs_free_xattr_list *);\n"
14585 #: ../src/guestfs-structs.pod:209
14586 msgid "guestfs_inotify_event"
14590 #: ../src/guestfs-structs.pod:211
14593 " struct guestfs_inotify_event {\n"
14594 " int64_t in_wd;\n"
14595 " uint32_t in_mask;\n"
14596 " uint32_t in_cookie;\n"
14597 " char *in_name;\n"
14603 #: ../src/guestfs-structs.pod:218
14606 " struct guestfs_inotify_event_list {\n"
14607 " uint32_t len; /* Number of elements in list. */\n"
14608 " struct guestfs_inotify_event *val; /* Elements. */\n"
14614 #: ../src/guestfs-structs.pod:223
14617 " void guestfs_free_inotify_event (struct guestfs_free_inotify_event *);\n"
14618 " void guestfs_free_inotify_event_list (struct guestfs_free_inotify_event_list *);\n"
14623 #: ../src/guestfs-structs.pod:226
14624 msgid "guestfs_partition"
14628 #: ../src/guestfs-structs.pod:228
14631 " struct guestfs_partition {\n"
14632 " int32_t part_num;\n"
14633 " uint64_t part_start;\n"
14634 " uint64_t part_end;\n"
14635 " uint64_t part_size;\n"
14641 #: ../src/guestfs-structs.pod:235
14644 " struct guestfs_partition_list {\n"
14645 " uint32_t len; /* Number of elements in list. */\n"
14646 " struct guestfs_partition *val; /* Elements. */\n"
14652 #: ../src/guestfs-structs.pod:240
14655 " void guestfs_free_partition (struct guestfs_free_partition *);\n"
14656 " void guestfs_free_partition_list (struct guestfs_free_partition_list *);\n"
14661 #: ../fish/guestfish.pod:5
14662 msgid "guestfish - the libguestfs Filesystem Interactive SHell"
14666 #: ../fish/guestfish.pod:9
14669 " guestfish [--options] [commands]\n"
14674 #: ../fish/guestfish.pod:11
14682 #: ../fish/guestfish.pod:13
14685 " guestfish -a disk.img\n"
14690 #: ../fish/guestfish.pod:15
14693 " guestfish -a disk.img -m dev[:mountpoint]\n"
14698 #: ../fish/guestfish.pod:17
14701 " guestfish -d libvirt-domain\n"
14706 #: ../fish/guestfish.pod:19
14709 " guestfish -a disk.img -i\n"
14714 #: ../fish/guestfish.pod:21
14717 " guestfish -d libvirt-domain -i\n"
14722 #: ../fish/guestfish.pod:23 ../fuse/guestmount.pod:11 ../tools/virt-edit.pl:45
14723 #: ../tools/virt-win-reg.pl:52 ../tools/virt-tar.pl:60
14724 #: ../tools/virt-rescue.pl:41
14729 #: ../fish/guestfish.pod:25
14731 "Using guestfish in read/write mode on live virtual machines can be "
14732 "dangerous, potentially causing disk corruption. Use the I<--ro> (read-only) "
14733 "option to use guestfish safely if the disk image or virtual machine might be "
14738 #: ../fish/guestfish.pod:32
14740 "Guestfish is a shell and command-line tool for examining and modifying "
14741 "virtual machine filesystems. It uses libguestfs and exposes all of the "
14742 "functionality of the guestfs API, see L<guestfs(3)>."
14746 #: ../fish/guestfish.pod:36
14748 "Guestfish gives you structured access to the libguestfs API, from shell "
14749 "scripts or the command line or interactively. If you want to rescue a "
14750 "broken virtual machine image, you should look at the L<virt-rescue(1)> "
14755 #: ../fish/guestfish.pod:41 ../fish/guestfish.pod:759
14756 #: ../fuse/guestmount.pod:35 ../tools/virt-edit.pl:59
14757 #: ../tools/virt-resize.pl:66 ../tools/virt-cat.pl:51 ../tools/virt-tar.pl:46
14762 #: ../fish/guestfish.pod:43
14763 msgid "As an interactive shell"
14767 #: ../fish/guestfish.pod:45
14775 #: ../fish/guestfish.pod:47
14778 " Welcome to guestfish, the libguestfs filesystem interactive shell for\n"
14779 " editing virtual machine filesystems.\n"
14784 #: ../fish/guestfish.pod:50
14787 " Type: 'help' for a list of commands\n"
14788 " 'man' to read the manual\n"
14789 " 'quit' to quit the shell\n"
14794 #: ../fish/guestfish.pod:54
14797 " ><fs> add-ro disk.img\n"
14799 " ><fs> list-filesystems\n"
14800 " /dev/sda1: ext4\n"
14801 " /dev/vg_guest/lv_root: ext4\n"
14802 " /dev/vg_guest/lv_swap: swap\n"
14803 " ><fs> mount /dev/vg_guest/lv_root /\n"
14804 " ><fs> cat /etc/fstab\n"
14806 " # Created by anaconda\n"
14813 #: ../fish/guestfish.pod:67
14814 msgid "From shell scripts"
14818 #: ../fish/guestfish.pod:69
14819 msgid "Create a new C</etc/motd> file in a guest or disk image:"
14823 #: ../fish/guestfish.pod:71
14826 " guestfish <<_EOF_\n"
14829 " mount /dev/vg_guest/lv_root /\n"
14830 " write /etc/motd \"Welcome, new users\"\n"
14836 #: ../fish/guestfish.pod:78
14837 msgid "List the LVM logical volumes in a disk image:"
14841 #: ../fish/guestfish.pod:80
14844 " guestfish -a disk.img --ro <<_EOF_\n"
14852 #: ../fish/guestfish.pod:85
14853 msgid "List all the filesystems in a disk image:"
14857 #: ../fish/guestfish.pod:87
14860 " guestfish -a disk.img --ro <<_EOF_\n"
14862 " list-filesystems\n"
14868 #: ../fish/guestfish.pod:92
14869 msgid "On one command line"
14873 #: ../fish/guestfish.pod:94
14874 msgid "Update C</etc/resolv.conf> in a guest:"
14878 #: ../fish/guestfish.pod:96
14882 " add disk.img : run : mount /dev/vg_guest/lv_root / : \\\n"
14883 " write /etc/resolv.conf \"nameserver 1.2.3.4\"\n"
14888 #: ../fish/guestfish.pod:100
14889 msgid "Edit C</boot/grub/grub.conf> interactively:"
14893 #: ../fish/guestfish.pod:102
14896 " guestfish --add disk.img \\\n"
14897 " --mount /dev/vg_guest/lv_root \\\n"
14898 " --mount /dev/sda1:/boot \\\n"
14899 " edit /boot/grub/grub.conf\n"
14904 #: ../fish/guestfish.pod:107
14905 msgid "Mount disks automatically"
14909 #: ../fish/guestfish.pod:109
14911 "Use the I<-i> option to automatically mount the disks from a virtual machine:"
14915 #: ../fish/guestfish.pod:112
14918 " guestfish --ro -a disk.img -i cat /etc/group\n"
14923 #: ../fish/guestfish.pod:114
14926 " guestfish --ro -d libvirt-domain -i cat /etc/group\n"
14931 #: ../fish/guestfish.pod:116
14932 msgid "Another way to edit C</boot/grub/grub.conf> interactively is:"
14936 #: ../fish/guestfish.pod:118
14939 " guestfish -a disk.img -i edit /boot/grub/grub.conf\n"
14944 #: ../fish/guestfish.pod:120
14945 msgid "As a script interpreter"
14949 #: ../fish/guestfish.pod:122
14950 msgid "Create a 100MB disk containing an ext2-formatted partition:"
14954 #: ../fish/guestfish.pod:124
14957 " #!/usr/bin/guestfish -f\n"
14958 " sparse test1.img 100M\n"
14960 " part-disk /dev/sda mbr\n"
14961 " mkfs ext2 /dev/sda1\n"
14966 #: ../fish/guestfish.pod:130
14967 msgid "Start with a prepared disk"
14971 #: ../fish/guestfish.pod:132
14973 "An alternate way to create a 100MB disk called C<test1.img> containing a "
14974 "single ext2-formatted partition:"
14978 #: ../fish/guestfish.pod:135
14981 " guestfish -N fs\n"
14986 #: ../fish/guestfish.pod:137
14987 msgid "To list what is available do:"
14991 #: ../fish/guestfish.pod:139 ../fish/guestfish.pod:750
14994 " guestfish -N help | less\n"
14999 #: ../fish/guestfish.pod:141
15000 msgid "Remote control"
15004 #: ../fish/guestfish.pod:143
15007 " eval `guestfish --listen`\n"
15008 " guestfish --remote add-ro disk.img\n"
15009 " guestfish --remote run\n"
15010 " guestfish --remote lvs\n"
15015 #: ../fish/guestfish.pod:148 ../test-tool/libguestfs-test-tool.pod:37
15016 #: ../fuse/guestmount.pod:70 ../inspector/virt-inspector.pl:75
15017 #: ../tools/virt-edit.pl:73 ../tools/virt-win-reg.pl:172
15018 #: ../tools/virt-df.pl:71 ../tools/virt-ls.pl:79 ../tools/virt-resize.pl:233
15019 #: ../tools/virt-list-filesystems.pl:50 ../tools/virt-cat.pl:80
15020 #: ../tools/virt-tar.pl:99 ../tools/virt-rescue.pl:103
15021 #: ../tools/virt-make-fs.pl:153 ../tools/virt-list-partitions.pl:51
15026 #: ../fish/guestfish.pod:152 ../fuse/guestmount.pod:94
15027 #: ../inspector/virt-inspector.pl:83 ../tools/virt-edit.pl:81
15028 #: ../tools/virt-win-reg.pl:180 ../tools/virt-df.pl:79 ../tools/virt-ls.pl:87
15029 #: ../tools/virt-resize.pl:241 ../tools/virt-list-filesystems.pl:58
15030 #: ../tools/virt-cat.pl:88 ../tools/virt-tar.pl:107
15031 #: ../tools/virt-rescue.pl:111 ../tools/virt-make-fs.pl:161
15032 #: ../tools/virt-list-partitions.pl:59
15037 #: ../fish/guestfish.pod:154
15038 msgid "Displays general help on options."
15042 #: ../fish/guestfish.pod:156
15043 msgid "B<-h> | B<--cmd-help>"
15047 #: ../fish/guestfish.pod:158
15048 msgid "Lists all available guestfish commands."
15052 #: ../fish/guestfish.pod:160
15053 msgid "B<-h cmd> | B<--cmd-help cmd>"
15057 #: ../fish/guestfish.pod:162
15058 msgid "Displays detailed help on a single command C<cmd>."
15062 #: ../fish/guestfish.pod:164 ../fuse/guestmount.pod:74
15063 msgid "B<-a image> | B<--add image>"
15067 #: ../fish/guestfish.pod:166
15068 msgid "Add a block device or virtual machine image to the shell."
15072 #: ../fish/guestfish.pod:168
15073 msgid "B<-c URI> | B<--connect URI>"
15077 #: ../fish/guestfish.pod:170
15079 "When used in conjunction with the I<-d> option, this specifies the libvirt "
15080 "URI to use. The default is to use the default libvirt connection."
15084 #: ../fish/guestfish.pod:174
15085 msgid "B<-d libvirt-domain> | B<--domain libvirt-domain>"
15089 #: ../fish/guestfish.pod:176
15091 "Add disks from the named libvirt domain. If the I<--ro> option is also "
15092 "used, then any libvirt domain can be used. However in write mode, only "
15093 "libvirt domains which are shut down can be named here."
15097 #: ../fish/guestfish.pod:180
15098 msgid "B<-D> | B<--no-dest-paths>"
15102 #: ../fish/guestfish.pod:182
15104 "Don't tab-complete paths on the guest filesystem. It is useful to be able "
15105 "to hit the tab key to complete paths on the guest filesystem, but this "
15106 "causes extra \"hidden\" guestfs calls to be made, so this option is here to "
15107 "allow this feature to be disabled."
15111 #: ../fish/guestfish.pod:187
15112 msgid "B<--echo-keys>"
15116 #: ../fish/guestfish.pod:189
15118 "When prompting for keys and passphrases, guestfish normally turns echoing "
15119 "off so you cannot see what you are typing. If you are not worried about "
15120 "Tempest attacks and there is no one else in the room you can specify this "
15121 "flag to see what you are typing."
15125 #: ../fish/guestfish.pod:194
15126 msgid "B<-f file> | B<--file file>"
15130 #: ../fish/guestfish.pod:196
15131 msgid "Read commands from C<file>. To write pure guestfish scripts, use:"
15135 #: ../fish/guestfish.pod:199
15138 " #!/usr/bin/guestfish -f\n"
15143 #: ../fish/guestfish.pod:201
15144 msgid "B<-i> | B<--inspector>"
15148 #: ../fish/guestfish.pod:203
15150 "Using L<virt-inspector(1)> code, inspect the disks looking for an operating "
15151 "system and mount filesystems as they would be mounted on the real virtual "
15156 #: ../fish/guestfish.pod:207
15157 msgid "Typical usage is either:"
15161 #: ../fish/guestfish.pod:209
15164 " guestfish -d myguest -i\n"
15169 #: ../fish/guestfish.pod:211
15170 msgid "(for an inactive libvirt domain called I<myguest>), or:"
15174 #: ../fish/guestfish.pod:213
15177 " guestfish --ro -d myguest -i\n"
15182 #: ../fish/guestfish.pod:215
15183 msgid "(for active domains, readonly), or specify the block device directly:"
15187 #: ../fish/guestfish.pod:217
15190 " guestfish -a /dev/Guests/MyGuest -i\n"
15195 #: ../fish/guestfish.pod:219
15197 "Note that the command line syntax changed slightly over older versions of "
15198 "guestfish. You can still use the old syntax:"
15202 #: ../fish/guestfish.pod:222
15205 " guestfish [--ro] -i disk.img\n"
15210 #: ../fish/guestfish.pod:224
15213 " guestfish [--ro] -i libvirt-domain\n"
15218 #: ../fish/guestfish.pod:226
15219 msgid "B<--keys-from-stdin>"
15223 #: ../fish/guestfish.pod:228
15225 "Read key or passphrase parameters from stdin. The default is to try to read "
15226 "passphrases from the user by opening C</dev/tty>."
15230 #: ../fish/guestfish.pod:231
15231 msgid "B<--listen>"
15235 #: ../fish/guestfish.pod:233
15237 "Fork into the background and listen for remote commands. See section L</"
15238 "REMOTE CONTROL GUESTFISH OVER A SOCKET> below."
15242 #: ../fish/guestfish.pod:236
15243 msgid "B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>"
15247 #: ../fish/guestfish.pod:238
15248 msgid "Mount the named partition or logical volume on the given mountpoint."
15252 #: ../fish/guestfish.pod:240
15253 msgid "If the mountpoint is omitted, it defaults to C</>."
15257 #: ../fish/guestfish.pod:242
15258 msgid "You have to mount something on C</> before most commands will work."
15262 #: ../fish/guestfish.pod:244
15264 "If any I<-m> or I<--mount> options are given, the guest is automatically "
15269 #: ../fish/guestfish.pod:247
15271 "If you don't know what filesystems a disk image contains, you can either run "
15272 "guestfish without this option, then list the partitions and LVs available "
15273 "(see L</list-partitions> and L</lvs> commands), or you can use the L<virt-"
15274 "list-filesystems(1)> program."
15278 #: ../fish/guestfish.pod:252 ../fuse/guestmount.pod:106
15279 msgid "B<-n> | B<--no-sync>"
15283 #: ../fish/guestfish.pod:254
15285 "Disable autosync. This is enabled by default. See the discussion of "
15286 "autosync in the L<guestfs(3)> manpage."
15290 #: ../fish/guestfish.pod:257
15291 msgid "B<-N type> | B<--new type> | B<-N help>"
15295 #: ../fish/guestfish.pod:259
15297 "Prepare a fresh disk image formatted as \"type\". This is an alternative to "
15298 "the I<-a> option: whereas I<-a> adds an existing disk, I<-N> creates a "
15299 "preformatted disk with a filesystem and adds it. See L</PREPARED DISK "
15304 #: ../fish/guestfish.pod:264
15305 msgid "B<--progress-bars>"
15309 #: ../fish/guestfish.pod:266
15310 msgid "Enable progress bars, even when guestfish is used non-interactively."
15314 #: ../fish/guestfish.pod:268
15316 "Progress bars are enabled by default when guestfish is used as an "
15317 "interactive shell."
15321 #: ../fish/guestfish.pod:271
15322 msgid "B<--no-progress-bars>"
15326 #: ../fish/guestfish.pod:273
15327 msgid "Disable progress bars."
15331 #: ../fish/guestfish.pod:275
15332 msgid "B<--remote[=pid]>"
15336 #: ../fish/guestfish.pod:277
15338 "Send remote commands to C<$GUESTFISH_PID> or C<pid>. See section L</REMOTE "
15339 "CONTROL GUESTFISH OVER A SOCKET> below."
15343 #: ../fish/guestfish.pod:280 ../fuse/guestmount.pod:148
15344 msgid "B<-r> | B<--ro>"
15348 #: ../fish/guestfish.pod:282
15350 "This changes the I<-a> and I<-m> options so that disks are added and mounts "
15351 "are done read-only (see L<guestfs(3)/guestfs_mount_ro>)."
15355 #: ../fish/guestfish.pod:285 ../tools/virt-rescue.pl:162
15357 "The option must always be used if the disk image or virtual machine might be "
15358 "running, and is generally recommended in cases where you don't need write "
15359 "access to the disk."
15363 #: ../fish/guestfish.pod:289
15365 "Note that prepared disk images created with I<-N> are not affected by the "
15370 #: ../fish/guestfish.pod:292 ../fuse/guestmount.pod:158
15371 #: ../tools/virt-rescue.pl:170
15372 msgid "B<--selinux>"
15376 #: ../fish/guestfish.pod:294
15377 msgid "Enable SELinux support for the guest. See L<guestfs(3)/SELINUX>."
15381 #: ../fish/guestfish.pod:296 ../fuse/guestmount.pod:168
15382 msgid "B<-v> | B<--verbose>"
15386 #: ../fish/guestfish.pod:298
15388 "Enable very verbose messages. This is particularly useful if you find a bug."
15392 #: ../fish/guestfish.pod:301 ../fuse/guestmount.pod:172
15393 msgid "B<-V> | B<--version>"
15397 #: ../fish/guestfish.pod:303
15398 msgid "Display the guestfish / libguestfs version number and exit."
15402 #: ../fish/guestfish.pod:305
15407 #: ../fish/guestfish.pod:307
15408 msgid "Echo each command before executing it."
15412 #: ../fish/guestfish.pod:311
15413 msgid "COMMANDS ON COMMAND LINE"
15417 #: ../fish/guestfish.pod:313
15419 "Any additional (non-option) arguments are treated as commands to execute."
15423 #: ../fish/guestfish.pod:316
15425 "Commands to execute should be separated by a colon (C<:>), where the colon "
15426 "is a separate parameter. Thus:"
15430 #: ../fish/guestfish.pod:319
15433 " guestfish cmd [args...] : cmd [args...] : cmd [args...] ...\n"
15438 #: ../fish/guestfish.pod:321
15440 "If there are no additional arguments, then we enter a shell, either an "
15441 "interactive shell with a prompt (if the input is a terminal) or a non-"
15442 "interactive shell."
15446 #: ../fish/guestfish.pod:325
15448 "In either command line mode or non-interactive shell, the first command that "
15449 "gives an error causes the whole shell to exit. In interactive mode (with a "
15450 "prompt) if a command fails, you can continue to enter commands."
15454 #: ../fish/guestfish.pod:330
15455 msgid "USING launch (OR run)"
15459 #: ../fish/guestfish.pod:332
15461 "As with L<guestfs(3)>, you must first configure your guest by adding disks, "
15462 "then launch it, then mount any disks you need, and finally issue actions/"
15463 "commands. So the general order of the day is:"
15467 #: ../fish/guestfish.pod:340
15468 msgid "add or -a/--add"
15472 #: ../fish/guestfish.pod:344
15473 msgid "launch (aka run)"
15477 #: ../fish/guestfish.pod:348
15478 msgid "mount or -m/--mount"
15482 #: ../fish/guestfish.pod:352
15483 msgid "any other commands"
15487 #: ../fish/guestfish.pod:356
15489 "C<run> is a synonym for C<launch>. You must C<launch> (or C<run>) your "
15490 "guest before mounting or performing any other commands."
15494 #: ../fish/guestfish.pod:359
15496 "The only exception is that if any of the I<-i>, I<-m>, I<--mount>, I<-N> or "
15497 "I<--new> options were given then C<run> is done automatically, simply "
15498 "because guestfish can't perform the action you asked for without doing this."
15502 #: ../fish/guestfish.pod:364
15507 #: ../fish/guestfish.pod:366
15509 "You can quote ordinary parameters using either single or double quotes. For "
15514 #: ../fish/guestfish.pod:369
15517 " add \"file with a space.img\"\n"
15522 #: ../fish/guestfish.pod:371
15525 " rm '/file name'\n"
15530 #: ../fish/guestfish.pod:373
15538 #: ../fish/guestfish.pod:375
15540 "A few commands require a list of strings to be passed. For these, use a "
15541 "whitespace-separated list, enclosed in quotes. Strings containing "
15542 "whitespace to be passed through must be enclosed in single quotes. A "
15543 "literal single quote must be escaped with a backslash."
15547 #: ../fish/guestfish.pod:380
15550 " vgcreate VG \"/dev/sda1 /dev/sdb1\"\n"
15551 " command \"/bin/echo 'foo bar'\"\n"
15552 " command \"/bin/echo \\'foo\\'\"\n"
15557 #: ../fish/guestfish.pod:384
15562 #: ../fish/guestfish.pod:386
15564 "This section applies to all commands which can take integers as parameters."
15568 #: ../fish/guestfish.pod:389
15569 msgid "SIZE SUFFIX"
15573 #: ../fish/guestfish.pod:391
15575 "When the command takes a parameter measured in bytes, you can use one of the "
15576 "following suffixes to specify kilobytes, megabytes and larger sizes:"
15580 #: ../fish/guestfish.pod:397
15581 msgid "B<k> or B<K> or B<KiB>"
15585 #: ../fish/guestfish.pod:399
15586 msgid "The size in kilobytes (multiplied by 1024)."
15590 #: ../fish/guestfish.pod:401
15595 #: ../fish/guestfish.pod:403
15596 msgid "The size in SI 1000 byte units."
15600 #: ../fish/guestfish.pod:405
15601 msgid "B<M> or B<MiB>"
15605 #: ../fish/guestfish.pod:407
15606 msgid "The size in megabytes (multiplied by 1048576)."
15610 #: ../fish/guestfish.pod:409
15615 #: ../fish/guestfish.pod:411
15616 msgid "The size in SI 1000000 byte units."
15620 #: ../fish/guestfish.pod:413
15621 msgid "B<G> or B<GiB>"
15625 #: ../fish/guestfish.pod:415
15626 msgid "The size in gigabytes (multiplied by 2**30)."
15630 #: ../fish/guestfish.pod:417
15635 #: ../fish/guestfish.pod:419
15636 msgid "The size in SI 10**9 byte units."
15640 #: ../fish/guestfish.pod:421
15641 msgid "B<T> or B<TiB>"
15645 #: ../fish/guestfish.pod:423
15646 msgid "The size in terabytes (multiplied by 2**40)."
15650 #: ../fish/guestfish.pod:425
15655 #: ../fish/guestfish.pod:427
15656 msgid "The size in SI 10**12 byte units."
15660 #: ../fish/guestfish.pod:429
15661 msgid "B<P> or B<PiB>"
15665 #: ../fish/guestfish.pod:431
15666 msgid "The size in petabytes (multiplied by 2**50)."
15670 #: ../fish/guestfish.pod:433
15675 #: ../fish/guestfish.pod:435
15676 msgid "The size in SI 10**15 byte units."
15680 #: ../fish/guestfish.pod:437
15681 msgid "B<E> or B<EiB>"
15685 #: ../fish/guestfish.pod:439
15686 msgid "The size in exabytes (multiplied by 2**60)."
15690 #: ../fish/guestfish.pod:441
15695 #: ../fish/guestfish.pod:443
15696 msgid "The size in SI 10**18 byte units."
15700 #: ../fish/guestfish.pod:445
15701 msgid "B<Z> or B<ZiB>"
15705 #: ../fish/guestfish.pod:447
15706 msgid "The size in zettabytes (multiplied by 2**70)."
15710 #: ../fish/guestfish.pod:449
15715 #: ../fish/guestfish.pod:451
15716 msgid "The size in SI 10**21 byte units."
15720 #: ../fish/guestfish.pod:453
15721 msgid "B<Y> or B<YiB>"
15725 #: ../fish/guestfish.pod:455
15726 msgid "The size in yottabytes (multiplied by 2**80)."
15730 #: ../fish/guestfish.pod:457
15735 #: ../fish/guestfish.pod:459
15736 msgid "The size in SI 10**24 byte units."
15740 #: ../fish/guestfish.pod:463
15741 msgid "For example:"
15745 #: ../fish/guestfish.pod:465
15748 " truncate-size /file 1G\n"
15753 #: ../fish/guestfish.pod:467
15754 msgid "would truncate the file to 1 gigabyte."
15758 #: ../fish/guestfish.pod:469
15760 "Be careful because a few commands take sizes in kilobytes or megabytes (eg. "
15761 "the parameter to L</memsize> is specified in megabytes already). Adding a "
15762 "suffix will probably not do what you expect."
15766 #: ../fish/guestfish.pod:473
15767 msgid "OCTAL AND HEXADECIMAL NUMBERS"
15771 #: ../fish/guestfish.pod:475
15773 "For specifying the radix (base) use the C convention: C<0> to prefix an "
15774 "octal number or C<0x> to prefix a hexadecimal number. For example:"
15778 #: ../fish/guestfish.pod:478
15781 " 1234 decimal number 1234\n"
15782 " 02322 octal number, equivalent to decimal 1234\n"
15783 " 0x4d2 hexadecimal number, equivalent to decimal 1234\n"
15788 #: ../fish/guestfish.pod:482
15790 "When using the C<chmod> command, you almost always want to specify an octal "
15791 "number for the mode, and you must prefix it with C<0> (unlike the Unix "
15792 "L<chmod(1)> program):"
15796 #: ../fish/guestfish.pod:486
15799 " chmod 0777 /public # OK\n"
15800 " chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.\n"
15805 #: ../fish/guestfish.pod:489
15807 "Commands that return numbers usually print them in decimal, but some "
15808 "commands print numbers in other radices (eg. C<umask> prints the mode in "
15809 "octal, preceeded by C<0>)."
15813 #: ../fish/guestfish.pod:493
15814 msgid "WILDCARDS AND GLOBBING"
15818 #: ../fish/guestfish.pod:495
15820 "Neither guestfish nor the underlying guestfs API performs wildcard expansion "
15821 "(globbing) by default. So for example the following will not do what you "
15826 #: ../fish/guestfish.pod:499
15834 #: ../fish/guestfish.pod:501
15836 "Assuming you don't have a directory called literally C</home/*> then the "
15837 "above command will return an error."
15841 #: ../fish/guestfish.pod:504
15842 msgid "To perform wildcard expansion, use the C<glob> command."
15846 #: ../fish/guestfish.pod:506
15849 " glob rm-rf /home/*\n"
15854 #: ../fish/guestfish.pod:508
15856 "runs C<rm-rf> on each path that matches (ie. potentially running the command "
15857 "many times), equivalent to:"
15861 #: ../fish/guestfish.pod:511
15864 " rm-rf /home/jim\n"
15865 " rm-rf /home/joe\n"
15866 " rm-rf /home/mary\n"
15871 #: ../fish/guestfish.pod:515
15872 msgid "C<glob> only works on simple guest paths and not on device names."
15876 #: ../fish/guestfish.pod:517
15878 "If you have several parameters, each containing a wildcard, then glob will "
15879 "perform a Cartesian product."
15883 #: ../fish/guestfish.pod:520
15888 #: ../fish/guestfish.pod:522
15890 "Any line which starts with a I<#> character is treated as a comment and "
15891 "ignored. The I<#> can optionally be preceeded by whitespace, but B<not> by "
15892 "a command. For example:"
15896 #: ../fish/guestfish.pod:526
15899 " # this is a comment\n"
15900 " # this is a comment\n"
15901 " foo # NOT a comment\n"
15906 #: ../fish/guestfish.pod:530
15907 msgid "Blank lines are also ignored."
15911 #: ../fish/guestfish.pod:532
15912 msgid "RUNNING COMMANDS LOCALLY"
15916 #: ../fish/guestfish.pod:534
15918 "Any line which starts with a I<!> character is treated as a command sent to "
15919 "the local shell (C</bin/sh> or whatever L<system(3)> uses). For example:"
15923 #: ../fish/guestfish.pod:538
15927 " tgz-out /remote local/remote-data.tar.gz\n"
15932 #: ../fish/guestfish.pod:541
15934 "will create a directory C<local> on the host, and then export the contents "
15935 "of C</remote> on the mounted filesystem to C<local/remote-data.tar.gz>. "
15936 "(See C<tgz-out>)."
15940 #: ../fish/guestfish.pod:545
15942 "To change the local directory, use the C<lcd> command. C<!cd> will have no "
15943 "effect, due to the way that subprocesses work in Unix."
15947 #: ../fish/guestfish.pod:548
15952 #: ../fish/guestfish.pod:550
15954 "Use C<command E<lt>spaceE<gt> | command> to pipe the output of the first "
15955 "command (a guestfish command) to the second command (any host command). For "
15960 #: ../fish/guestfish.pod:554
15963 " cat /etc/passwd | awk -F: '$3 == 0 { print }'\n"
15968 #: ../fish/guestfish.pod:556
15970 "(where C<cat> is the guestfish cat command, but C<awk> is the host awk "
15971 "program). The above command would list all accounts in the guest filesystem "
15972 "which have UID 0, ie. root accounts including backdoors. Other examples:"
15976 #: ../fish/guestfish.pod:561
15979 " hexdump /bin/ls | head\n"
15980 " list-devices | tail -1\n"
15981 " tgz-out / - | tar ztf -\n"
15986 #: ../fish/guestfish.pod:565
15988 "The space before the pipe symbol is required, any space after the pipe "
15989 "symbol is optional. Everything after the pipe symbol is just passed "
15990 "straight to the host shell, so it can contain redirections, globs and "
15991 "anything else that makes sense on the host side."
15995 #: ../fish/guestfish.pod:570
15997 "To use a literal argument which begins with a pipe symbol, you have to quote "
16002 #: ../fish/guestfish.pod:573
16010 #: ../fish/guestfish.pod:575
16011 msgid "HOME DIRECTORIES"
16015 #: ../fish/guestfish.pod:577
16017 "If a parameter starts with the character C<~> then the tilde may be expanded "
16018 "as a home directory path (either C<~> for the current user's home directory, "
16019 "or C<~user> for another user)."
16023 #: ../fish/guestfish.pod:581
16025 "Note that home directory expansion happens for users known I<on the host>, "
16026 "not in the guest filesystem."
16030 #: ../fish/guestfish.pod:584
16032 "To use a literal argument which begins with a tilde, you have to quote it, "
16037 #: ../fish/guestfish.pod:587
16045 #: ../fish/guestfish.pod:591
16047 "Libguestfs has some support for Linux guests encrypted according to the "
16048 "Linux Unified Key Setup (LUKS) standard, which includes nearly all whole "
16049 "disk encryption systems used by modern Linux guests. Currently only LVM-on-"
16050 "LUKS is supported."
16054 #: ../fish/guestfish.pod:596
16055 msgid "Identify encrypted block devices and partitions using L</vfs-type>:"
16059 #: ../fish/guestfish.pod:598
16062 " ><fs> vfs-type /dev/sda2\n"
16068 #: ../fish/guestfish.pod:601
16070 "Then open those devices using L</luks-open>. This creates a device-mapper "
16071 "device called C</dev/mapper/luksdev>."
16075 #: ../fish/guestfish.pod:604
16078 " ><fs> luks-open /dev/sda2 luksdev\n"
16079 " Enter key or passphrase (\"key\"): <enter the passphrase>\n"
16084 #: ../fish/guestfish.pod:607
16086 "Finally you have to tell LVM to scan for volume groups on the newly created "
16091 #: ../fish/guestfish.pod:610
16095 " vg-activate-all true\n"
16100 #: ../fish/guestfish.pod:613
16101 msgid "The logical volume(s) can now be mounted in the usual way."
16105 #: ../fish/guestfish.pod:615
16107 "Before closing a LUKS device you must unmount any logical volumes on it and "
16108 "deactivate the volume groups by calling C<vg-activate false VG> on each "
16109 "one. Then you can close the mapper device:"
16113 #: ../fish/guestfish.pod:619
16116 " vg-activate false /dev/VG\n"
16117 " luks-close /dev/mapper/luksdev\n"
16122 #: ../fish/guestfish.pod:622
16123 msgid "WINDOWS PATHS"
16127 #: ../fish/guestfish.pod:624
16129 "If a path is prefixed with C<win:> then you can use Windows-style paths "
16130 "(with some limitations). The following commands are equivalent:"
16134 #: ../fish/guestfish.pod:627
16137 " file /WINDOWS/system32/config/system.LOG\n"
16142 #: ../fish/guestfish.pod:629
16145 " file win:/windows/system32/config/system.log\n"
16150 #: ../fish/guestfish.pod:631
16153 " file win:\\windows\\system32\\config\\system.log\n"
16158 #: ../fish/guestfish.pod:633
16161 " file WIN:C:\\Windows\\SYSTEM32\\conFIG\\SYSTEM.LOG\n"
16166 #: ../fish/guestfish.pod:635
16168 "This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also "
16169 "handles case insensitivity like Windows would. This only works in argument "
16170 "positions that expect a path."
16174 #: ../fish/guestfish.pod:639
16175 msgid "UPLOADING AND DOWNLOADING FILES"
16179 #: ../fish/guestfish.pod:641
16181 "For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and "
16182 "others which upload from or download to a local file, you can use the "
16183 "special filename C<-> to mean \"from stdin\" or \"to stdout\". For example:"
16187 #: ../fish/guestfish.pod:645
16195 #: ../fish/guestfish.pod:647
16197 "reads stdin and creates from that a file C</foo> in the disk image, and:"
16201 #: ../fish/guestfish.pod:650
16204 " tar-out /etc - | tar tf -\n"
16209 #: ../fish/guestfish.pod:652
16211 "writes the tarball to stdout and then pipes that into the external \"tar\" "
16212 "command (see L</PIPES>)."
16216 #: ../fish/guestfish.pod:655
16218 "When using C<-> to read from stdin, the input is read up to the end of "
16219 "stdin. You can also use a special \"heredoc\"-like syntax to read up to "
16220 "some arbitrary end marker:"
16224 #: ../fish/guestfish.pod:659
16227 " upload -<<END /foo\n"
16236 #: ../fish/guestfish.pod:665
16238 "Any string of characters can be used instead of C<END>. The end marker must "
16239 "appear on a line of its own, without any preceeding or following characters "
16240 "(not even spaces)."
16244 #: ../fish/guestfish.pod:669
16246 "Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to "
16247 "upload local files (so-called \"FileIn\" parameters in the generator)."
16251 #: ../fish/guestfish.pod:672
16252 msgid "EXIT ON ERROR BEHAVIOUR"
16256 #: ../fish/guestfish.pod:674
16258 "By default, guestfish will ignore any errors when in interactive mode (ie. "
16259 "taking commands from a human over a tty), and will exit on the first error "
16260 "in non-interactive mode (scripts, commands given on the command line)."
16264 #: ../fish/guestfish.pod:679
16266 "If you prefix a command with a I<-> character, then that command will not "
16267 "cause guestfish to exit, even if that (one) command returns an error."
16271 #: ../fish/guestfish.pod:683
16272 msgid "REMOTE CONTROL GUESTFISH OVER A SOCKET"
16276 #: ../fish/guestfish.pod:685
16278 "Guestfish can be remote-controlled over a socket. This is useful "
16279 "particularly in shell scripts where you want to make several different "
16280 "changes to a filesystem, but you don't want the overhead of starting up a "
16281 "guestfish process each time."
16285 #: ../fish/guestfish.pod:690
16286 msgid "Start a guestfish server process using:"
16290 #: ../fish/guestfish.pod:692
16293 " eval `guestfish --listen`\n"
16298 #: ../fish/guestfish.pod:694
16299 msgid "and then send it commands by doing:"
16303 #: ../fish/guestfish.pod:696
16306 " guestfish --remote cmd [...]\n"
16311 #: ../fish/guestfish.pod:698
16312 msgid "To cause the server to exit, send it the exit command:"
16316 #: ../fish/guestfish.pod:700
16319 " guestfish --remote exit\n"
16324 #: ../fish/guestfish.pod:702
16326 "Note that the server will normally exit if there is an error in a command. "
16327 "You can change this in the usual way. See section L</EXIT ON ERROR "
16332 #: ../fish/guestfish.pod:706
16333 msgid "CONTROLLING MULTIPLE GUESTFISH PROCESSES"
16337 #: ../fish/guestfish.pod:708
16339 "The C<eval> statement sets the environment variable C<$GUESTFISH_PID>, which "
16340 "is how the I<--remote> option knows where to send the commands. You can "
16341 "have several guestfish listener processes running using:"
16345 #: ../fish/guestfish.pod:712
16348 " eval `guestfish --listen`\n"
16349 " pid1=$GUESTFISH_PID\n"
16350 " eval `guestfish --listen`\n"
16351 " pid2=$GUESTFISH_PID\n"
16353 " guestfish --remote=$pid1 cmd\n"
16354 " guestfish --remote=$pid2 cmd\n"
16359 #: ../fish/guestfish.pod:720
16360 msgid "REMOTE CONTROL DETAILS"
16364 #: ../fish/guestfish.pod:722
16366 "Remote control happens over a Unix domain socket called C</tmp/.guestfish-"
16367 "$UID/socket-$PID>, where C<$UID> is the effective user ID of the process, "
16368 "and C<$PID> is the process ID of the server."
16372 #: ../fish/guestfish.pod:726
16373 msgid "Guestfish client and server versions must match exactly."
16377 #: ../fish/guestfish.pod:728
16378 msgid "PREPARED DISK IMAGES"
16382 #: ../fish/guestfish.pod:730
16384 "Use the I<-N type> or I<--new type> parameter to select one of a set of "
16385 "preformatted disk images that guestfish can make for you to save typing. "
16386 "This is particularly useful for testing purposes. This option is used "
16387 "instead of the I<-a> option, and like I<-a> can appear multiple times (and "
16388 "can be mixed with I<-a>)."
16392 #: ../fish/guestfish.pod:736
16394 "The new disk is called C<test1.img> for the first I<-N>, C<test2.img> for "
16395 "the second and so on. Existing files in the current directory are "
16400 #: ../fish/guestfish.pod:740
16402 "The type briefly describes how the disk should be sized, partitioned, how "
16403 "filesystem(s) should be created, and how content should be added. "
16404 "Optionally the type can be followed by extra parameters, separated by C<:> "
16405 "(colon) characters. For example, I<-N fs> creates a default 100MB, sparsely-"
16406 "allocated disk, containing a single partition, with the partition formatted "
16407 "as ext2. I<-N fs:ext4:1G> is the same, but for an ext4 filesystem on a 1GB "
16412 #: ../fish/guestfish.pod:748
16413 msgid "To list the available types and any extra parameters they take, run:"
16417 #: ../fish/guestfish.pod:752
16419 "Note that the prepared filesystem is not mounted. You would usually have to "
16420 "use the C<mount /dev/sda1 /> command or add the I<-m /dev/sda1> option."
16424 #: ../fish/guestfish.pod:756
16426 "If any I<-N> or I<--new> options are given, the guest is automatically "
16431 #: ../fish/guestfish.pod:761
16432 msgid "Create a 100MB disk with an ext4-formatted partition:"
16436 #: ../fish/guestfish.pod:763
16439 " guestfish -N fs:ext4\n"
16444 #: ../fish/guestfish.pod:765
16445 msgid "Create a 32MB disk with a VFAT-formatted partition, and mount it:"
16449 #: ../fish/guestfish.pod:767
16452 " guestfish -N fs:vfat:32M -m /dev/sda1\n"
16457 #: ../fish/guestfish.pod:769
16458 msgid "Create a blank 200MB disk:"
16462 #: ../fish/guestfish.pod:771
16465 " guestfish -N disk:200M\n"
16470 #: ../fish/guestfish.pod:773
16471 msgid "PROGRESS BARS"
16475 #: ../fish/guestfish.pod:775
16477 "Some (not all) long-running commands send progress notification messages as "
16478 "they are running. Guestfish turns these messages into progress bars."
16482 #: ../fish/guestfish.pod:779
16484 "When a command that supports progress bars takes longer than two seconds to "
16485 "run, and if progress bars are enabled, then you will see one appearing below "
16490 #: ../fish/guestfish.pod:783
16493 " ><fs> copy-size /large-file /another-file 2048M\n"
16494 " / 10% [#####-----------------------------------------] 00:30\n"
16499 #: ../fish/guestfish.pod:786
16501 "The spinner on the left hand side moves round once for every progress "
16502 "notification received from the backend. This is a (reasonably) golden "
16503 "assurance that the command is \"doing something\" even if the progress bar "
16504 "is not moving, because the command is able to send the progress "
16505 "notifications. When the bar reaches 100% and the command finishes, the "
16506 "spinner disappears."
16510 #: ../fish/guestfish.pod:793
16512 "Progress bars are enabled by default when guestfish is used interactively. "
16513 "You can enable them even for non-interactive modes using I<--progress-bars>, "
16514 "and you can disable them completely using I<--no-progress-bars>."
16518 #: ../fish/guestfish.pod:798
16519 msgid "GUESTFISH COMMANDS"
16523 #: ../fish/guestfish.pod:800
16525 "The commands in this section are guestfish convenience commands, in other "
16526 "words, they are not part of the L<guestfs(3)> API."
16530 #: ../fish/guestfish.pod:803
16535 #: ../fish/guestfish.pod:805
16544 #: ../fish/guestfish.pod:808
16546 "Without any parameter, this lists all commands. With a C<cmd> parameter, "
16547 "this displays detailed help for a command."
16551 #: ../fish/guestfish.pod:811
16552 msgid "quit | exit"
16556 #: ../fish/guestfish.pod:813
16557 msgid "This exits guestfish. You can also use C<^D> key."
16561 #: ../fish/guestfish.pod:815
16562 msgid "@FISH_COMMANDS@"
16566 #: ../fish/guestfish.pod:817
16571 #: ../fish/guestfish.pod:821 ../test-tool/libguestfs-test-tool.pod:83
16576 #: ../fish/guestfish.pod:823
16578 "guestfish returns 0 if the commands completed without error, or 1 if there "
16583 #: ../fish/guestfish.pod:830
16588 #: ../fish/guestfish.pod:832
16590 "The C<edit> command uses C<$EDITOR> as the editor. If not set, it uses "
16595 #: ../fish/guestfish.pod:835
16596 msgid "GUESTFISH_PID"
16600 #: ../fish/guestfish.pod:837
16602 "Used with the I<--remote> option to specify the remote guestfish process to "
16603 "control. See section L</REMOTE CONTROL GUESTFISH OVER A SOCKET>."
16607 #: ../fish/guestfish.pod:841
16612 #: ../fish/guestfish.pod:843
16614 "The L</hexedit> command uses C<$HEXEDITOR> as the external hex editor. If "
16615 "not specified, the external L<hexedit(1)> program is used."
16619 #: ../fish/guestfish.pod:847
16624 #: ../fish/guestfish.pod:849
16626 "If compiled with GNU readline support, various files in the home directory "
16627 "can be used. See L</FILES>."
16631 #: ../fish/guestfish.pod:858
16633 "Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This has the same "
16634 "effect as using the B<-v> option."
16638 #: ../fish/guestfish.pod:870
16640 "Set the path that guestfish uses to search for kernel and initrd.img. See "
16641 "the discussion of paths in L<guestfs(3)>."
16645 #: ../fish/guestfish.pod:881
16646 msgid "Set C<LIBGUESTFS_TRACE=1> to enable command traces."
16650 #: ../fish/guestfish.pod:883
16655 #: ../fish/guestfish.pod:885
16657 "The C<more> command uses C<$PAGER> as the pager. If not set, it uses "
16662 #: ../fish/guestfish.pod:900 ../test-tool/libguestfs-test-tool.pod:88
16667 #: ../fish/guestfish.pod:904
16668 msgid "$HOME/.guestfish"
16672 #: ../fish/guestfish.pod:906
16674 "If compiled with GNU readline support, then the command history is saved in "
16679 #: ../fish/guestfish.pod:909
16680 msgid "$HOME/.inputrc"
16684 #: ../fish/guestfish.pod:911
16685 msgid "/etc/inputrc"
16689 #: ../fish/guestfish.pod:913
16691 "If compiled with GNU readline support, then these files can be used to "
16692 "configure readline. For further information, please see L<readline(3)/"
16693 "INITIALIZATION FILE>."
16697 #: ../fish/guestfish.pod:917
16698 msgid "To write rules which only apply to guestfish, use:"
16702 #: ../fish/guestfish.pod:919
16712 #: ../fish/guestfish.pod:923
16714 "Variables that you can set in inputrc that change the behaviour of guestfish "
16715 "in useful ways include:"
16719 #: ../fish/guestfish.pod:928
16720 msgid "completion-ignore-case (default: on)"
16724 #: ../fish/guestfish.pod:930
16726 "By default, guestfish will ignore case when tab-completing paths on the "
16731 #: ../fish/guestfish.pod:933
16734 " set completion-ignore-case off\n"
16739 #: ../fish/guestfish.pod:935
16740 msgid "to make guestfish case sensitive."
16744 #: ../fish/guestfish.pod:939
16749 #: ../fish/guestfish.pod:941
16750 msgid "test2.img (etc)"
16754 #: ../fish/guestfish.pod:943
16756 "When using the C<-N> or C<--new> option, the prepared disk or filesystem "
16757 "will be created in the file C<test1.img> in the current directory. The "
16758 "second use of C<-N> will use C<test2.img> and so on. Any existing file with "
16759 "the same name will be overwritten."
16763 #: ../fish/guestfish.pod:952
16765 "L<guestfs(3)>, L<http://libguestfs.org/>, L<virt-cat(1)>, L<virt-df(1)>, "
16766 "L<virt-edit(1)>, L<virt-list-filesystems(1)>, L<virt-list-partitions(1)>, "
16767 "L<virt-ls(1)>, L<virt-make-fs(1)>, L<virt-rescue(1)>, L<virt-resize(1)>, "
16768 "L<virt-tar(1)>, L<virt-win-reg(1)>, L<hexedit(1)>."
16772 #: ../fish/guestfish.pod:976 ../test-tool/libguestfs-test-tool.pod:124
16773 #: ../fuse/guestmount.pod:198 ../inspector/virt-inspector.pl:865
16774 #: ../tools/virt-edit.pl:345 ../tools/virt-win-reg.pl:495
16775 #: ../tools/virt-df.pl:553 ../tools/virt-ls.pl:229
16776 #: ../tools/virt-resize.pl:1415 ../tools/virt-list-filesystems.pl:211
16777 #: ../tools/virt-cat.pl:181 ../tools/virt-tar.pl:276
16778 #: ../tools/virt-rescue.pl:249 ../tools/virt-make-fs.pl:560
16779 #: ../tools/virt-list-partitions.pl:248
16781 "This program is free software; you can redistribute it and/or modify it "
16782 "under the terms of the GNU General Public License as published by the Free "
16783 "Software Foundation; either version 2 of the License, or (at your option) "
16784 "any later version."
16788 #: ../fish/guestfish.pod:981 ../test-tool/libguestfs-test-tool.pod:129
16789 #: ../fuse/guestmount.pod:203 ../inspector/virt-inspector.pl:870
16790 #: ../tools/virt-edit.pl:350 ../tools/virt-win-reg.pl:500
16791 #: ../tools/virt-df.pl:558 ../tools/virt-ls.pl:234
16792 #: ../tools/virt-resize.pl:1420 ../tools/virt-list-filesystems.pl:216
16793 #: ../tools/virt-cat.pl:186 ../tools/virt-tar.pl:281
16794 #: ../tools/virt-rescue.pl:254 ../tools/virt-make-fs.pl:565
16795 #: ../tools/virt-list-partitions.pl:253
16797 "This program is distributed in the hope that it will be useful, but WITHOUT "
16798 "ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or "
16799 "FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for "
16804 #: ../fish/guestfish.pod:986 ../test-tool/libguestfs-test-tool.pod:134
16805 #: ../fuse/guestmount.pod:208 ../inspector/virt-inspector.pl:875
16806 #: ../tools/virt-edit.pl:355 ../tools/virt-win-reg.pl:505
16807 #: ../tools/virt-df.pl:563 ../tools/virt-ls.pl:239
16808 #: ../tools/virt-resize.pl:1425 ../tools/virt-list-filesystems.pl:221
16809 #: ../tools/virt-cat.pl:191 ../tools/virt-tar.pl:286
16810 #: ../tools/virt-rescue.pl:259 ../tools/virt-make-fs.pl:570
16811 #: ../tools/virt-list-partitions.pl:258
16813 "You should have received a copy of the GNU General Public License along with "
16814 "this program; if not, write to the Free Software Foundation, Inc., 675 Mass "
16815 "Ave, Cambridge, MA 02139, USA."
16819 #: ../fish/guestfish-actions.pod:1
16824 #: ../fish/guestfish-actions.pod:3
16829 #: ../fish/guestfish-actions.pod:5
16832 " add-cdrom filename\n"
16837 #: ../fish/guestfish-actions.pod:17
16839 "This call checks for the existence of C<filename>. This stops you from "
16840 "specifying other types of drive which are supported by qemu such as C<nbd:> "
16841 "and C<http:> URLs. To specify those, use the general L</config> call "
16846 #: ../fish/guestfish-actions.pod:24
16848 "If you just want to add an ISO file (often you use this as an efficient way "
16849 "to transfer large files into the guest), then you should probably use L</add-"
16850 "drive-ro> instead."
16854 #: ../fish/guestfish-actions.pod:30
16859 #: ../fish/guestfish-actions.pod:32
16864 #: ../fish/guestfish-actions.pod:34
16867 " add-drive filename\n"
16872 #: ../fish/guestfish-actions.pod:53 ../fish/guestfish-actions.pod:81
16874 "C<if=...> is set at compile time by the configuration option C<./configure --"
16875 "with-drive-if=...>. In the rare case where you might need to change this at "
16876 "run time, use L</add-drive-with-if> or L</add-drive-ro-with-if>."
16880 #: ../fish/guestfish-actions.pod:58 ../fish/guestfish-actions.pod:86
16882 "Note that this call checks for the existence of C<filename>. This stops you "
16883 "from specifying other types of drive which are supported by qemu such as "
16884 "C<nbd:> and C<http:> URLs. To specify those, use the general L</config> "
16889 #: ../fish/guestfish-actions.pod:63
16890 msgid "add-drive-ro"
16894 #: ../fish/guestfish-actions.pod:65
16899 #: ../fish/guestfish-actions.pod:67
16902 " add-drive-ro filename\n"
16907 #: ../fish/guestfish-actions.pod:91
16908 msgid "add-drive-ro-with-if"
16912 #: ../fish/guestfish-actions.pod:93
16915 " add-drive-ro-with-if filename iface\n"
16920 #: ../fish/guestfish-actions.pod:95
16922 "This is the same as L</add-drive-ro> but it allows you to specify the QEMU "
16923 "interface emulation to use at run time."
16927 #: ../fish/guestfish-actions.pod:98
16928 msgid "add-drive-with-if"
16932 #: ../fish/guestfish-actions.pod:100
16935 " add-drive-with-if filename iface\n"
16940 #: ../fish/guestfish-actions.pod:102
16942 "This is the same as L</add-drive> but it allows you to specify the QEMU "
16943 "interface emulation to use at run time."
16947 #: ../fish/guestfish-actions.pod:105
16952 #: ../fish/guestfish-actions.pod:107
16955 " aug-clear augpath\n"
16960 #: ../fish/guestfish-actions.pod:112
16965 #: ../fish/guestfish-actions.pod:114
16973 #: ../fish/guestfish-actions.pod:116
16975 "Close the current Augeas handle and free up any resources used by it. After "
16976 "calling this, you have to call L</aug-init> again before you can use any "
16977 "other Augeas functions."
16981 #: ../fish/guestfish-actions.pod:121
16982 msgid "aug-defnode"
16986 #: ../fish/guestfish-actions.pod:123
16989 " aug-defnode name expr val\n"
16994 #: ../fish/guestfish-actions.pod:128
16996 "If C<expr> evaluates to an empty nodeset, a node is created, equivalent to "
16997 "calling L</aug-set> C<expr>, C<value>. C<name> will be the nodeset "
16998 "containing that single node."
17002 #: ../fish/guestfish-actions.pod:136
17007 #: ../fish/guestfish-actions.pod:138
17010 " aug-defvar name expr\n"
17015 #: ../fish/guestfish-actions.pod:147
17020 #: ../fish/guestfish-actions.pod:149
17023 " aug-get augpath\n"
17028 #: ../fish/guestfish-actions.pod:154
17033 #: ../fish/guestfish-actions.pod:156
17036 " aug-init root flags\n"
17041 #: ../fish/guestfish-actions.pod:162
17042 msgid "You must call this before using any other L</aug-*> commands."
17046 #: ../fish/guestfish-actions.pod:197
17047 msgid "Do not load the tree in L</aug-init>."
17051 #: ../fish/guestfish-actions.pod:201
17052 msgid "To close the handle, you can call L</aug-close>."
17056 #: ../fish/guestfish-actions.pod:205
17061 #: ../fish/guestfish-actions.pod:207
17064 " aug-insert augpath label true|false\n"
17069 #: ../fish/guestfish-actions.pod:217
17074 #: ../fish/guestfish-actions.pod:219
17082 #: ../fish/guestfish-actions.pod:226
17087 #: ../fish/guestfish-actions.pod:228
17090 " aug-ls augpath\n"
17095 #: ../fish/guestfish-actions.pod:230
17097 "This is just a shortcut for listing L</aug-match> C<path/*> and sorting the "
17098 "resulting nodes into alphabetical order."
17102 #: ../fish/guestfish-actions.pod:233
17107 #: ../fish/guestfish-actions.pod:235
17110 " aug-match augpath\n"
17115 #: ../fish/guestfish-actions.pod:241
17120 #: ../fish/guestfish-actions.pod:243
17123 " aug-mv src dest\n"
17128 #: ../fish/guestfish-actions.pod:248
17133 #: ../fish/guestfish-actions.pod:250
17136 " aug-rm augpath\n"
17141 #: ../fish/guestfish-actions.pod:256
17146 #: ../fish/guestfish-actions.pod:258
17154 #: ../fish/guestfish-actions.pod:262
17156 "The flags which were passed to L</aug-init> affect exactly how files are "
17161 #: ../fish/guestfish-actions.pod:265
17166 #: ../fish/guestfish-actions.pod:267
17169 " aug-set augpath val\n"
17174 #: ../fish/guestfish-actions.pod:271
17176 "In the Augeas API, it is possible to clear a node by setting the value to "
17177 "NULL. Due to an oversight in the libguestfs API you cannot do that with "
17178 "this call. Instead you must use the L</aug-clear> call."
17182 #: ../fish/guestfish-actions.pod:276
17187 #: ../fish/guestfish-actions.pod:278
17190 " available 'groups ...'\n"
17195 #: ../fish/guestfish-actions.pod:284
17197 "The libguestfs groups, and the functions that those groups correspond to, "
17198 "are listed in L<guestfs(3)/AVAILABILITY>. You can also fetch this list at "
17199 "runtime by calling L</available-all-groups>."
17203 #: ../fish/guestfish-actions.pod:308
17204 msgid "You must call L</launch> before calling this function."
17208 #: ../fish/guestfish-actions.pod:330
17210 "This call was added in version C<1.0.80>. In previous versions of "
17211 "libguestfs all you could do would be to speculatively execute a command to "
17212 "find out if the daemon implemented it. See also L</version>."
17216 #: ../fish/guestfish-actions.pod:337
17217 msgid "available-all-groups"
17221 #: ../fish/guestfish-actions.pod:339
17224 " available-all-groups\n"
17229 #: ../fish/guestfish-actions.pod:341
17231 "This command returns a list of all optional groups that this daemon knows "
17232 "about. Note this returns both supported and unsupported groups. To find "
17233 "out which ones the daemon can actually support you have to call L</"
17234 "available> on each member of the returned list."
17238 #: ../fish/guestfish-actions.pod:347
17239 msgid "See also L</available> and L<guestfs(3)/AVAILABILITY>."
17243 #: ../fish/guestfish-actions.pod:349
17248 #: ../fish/guestfish-actions.pod:351
17251 " base64-in (base64file|-) filename\n"
17256 #: ../fish/guestfish-actions.pod:356 ../fish/guestfish-actions.pod:365
17257 #: ../fish/guestfish-actions.pod:589 ../fish/guestfish-actions.pod:736
17258 #: ../fish/guestfish-actions.pod:783 ../fish/guestfish-actions.pod:802
17259 #: ../fish/guestfish-actions.pod:1179 ../fish/guestfish-actions.pod:3820
17260 #: ../fish/guestfish-actions.pod:3832 ../fish/guestfish-actions.pod:3843
17261 #: ../fish/guestfish-actions.pod:3854 ../fish/guestfish-actions.pod:3906
17262 #: ../fish/guestfish-actions.pod:3915 ../fish/guestfish-actions.pod:3969
17263 #: ../fish/guestfish-actions.pod:3992
17264 msgid "Use C<-> instead of a filename to read/write from stdin/stdout."
17268 #: ../fish/guestfish-actions.pod:358
17273 #: ../fish/guestfish-actions.pod:360
17276 " base64-out filename (base64file|-)\n"
17281 #: ../fish/guestfish-actions.pod:367
17282 msgid "blockdev-flushbufs"
17286 #: ../fish/guestfish-actions.pod:369
17289 " blockdev-flushbufs device\n"
17294 #: ../fish/guestfish-actions.pod:376
17295 msgid "blockdev-getbsz"
17299 #: ../fish/guestfish-actions.pod:378
17302 " blockdev-getbsz device\n"
17307 #: ../fish/guestfish-actions.pod:387
17308 msgid "blockdev-getro"
17312 #: ../fish/guestfish-actions.pod:389
17315 " blockdev-getro device\n"
17320 #: ../fish/guestfish-actions.pod:396
17321 msgid "blockdev-getsize64"
17325 #: ../fish/guestfish-actions.pod:398
17328 " blockdev-getsize64 device\n"
17333 #: ../fish/guestfish-actions.pod:402
17334 msgid "See also L</blockdev-getsz>."
17338 #: ../fish/guestfish-actions.pod:406
17339 msgid "blockdev-getss"
17343 #: ../fish/guestfish-actions.pod:408
17346 " blockdev-getss device\n"
17351 #: ../fish/guestfish-actions.pod:413
17353 "(Note, this is not the size in sectors, use L</blockdev-getsz> for that)."
17357 #: ../fish/guestfish-actions.pod:418
17358 msgid "blockdev-getsz"
17362 #: ../fish/guestfish-actions.pod:420
17365 " blockdev-getsz device\n"
17370 #: ../fish/guestfish-actions.pod:425
17372 "See also L</blockdev-getss> for the real sector size of the device, and L</"
17373 "blockdev-getsize64> for the more useful I<size in bytes>."
17377 #: ../fish/guestfish-actions.pod:431
17378 msgid "blockdev-rereadpt"
17382 #: ../fish/guestfish-actions.pod:433
17385 " blockdev-rereadpt device\n"
17390 #: ../fish/guestfish-actions.pod:439
17391 msgid "blockdev-setbsz"
17395 #: ../fish/guestfish-actions.pod:441
17398 " blockdev-setbsz device blocksize\n"
17403 #: ../fish/guestfish-actions.pod:450
17404 msgid "blockdev-setro"
17408 #: ../fish/guestfish-actions.pod:452
17411 " blockdev-setro device\n"
17416 #: ../fish/guestfish-actions.pod:458
17417 msgid "blockdev-setrw"
17421 #: ../fish/guestfish-actions.pod:460
17424 " blockdev-setrw device\n"
17429 #: ../fish/guestfish-actions.pod:466
17430 msgid "case-sensitive-path"
17434 #: ../fish/guestfish-actions.pod:468
17437 " case-sensitive-path path\n"
17442 #: ../fish/guestfish-actions.pod:492
17444 "Thus L</case-sensitive-path> (\"/Windows/System32\") might return C<\"/"
17445 "WINDOWS/system32\"> (the exact return value would depend on details of how "
17446 "the directories were originally created under Windows)."
17450 #: ../fish/guestfish-actions.pod:500
17451 msgid "See also L</realpath>."
17455 #: ../fish/guestfish-actions.pod:502
17460 #: ../fish/guestfish-actions.pod:504
17468 #: ../fish/guestfish-actions.pod:508
17470 "Note that this function cannot correctly handle binary files (specifically, "
17471 "files containing C<\\0> character which is treated as end of string). For "
17472 "those you need to use the L</read-file> or L</download> functions which have "
17473 "a more complex interface."
17477 #: ../fish/guestfish-actions.pod:516
17482 #: ../fish/guestfish-actions.pod:518
17485 " checksum csumtype path\n"
17490 #: ../fish/guestfish-actions.pod:561
17491 msgid "To get the checksum for a device, use L</checksum-device>."
17495 #: ../fish/guestfish-actions.pod:563
17496 msgid "To get the checksums for many files, use L</checksums-out>."
17500 #: ../fish/guestfish-actions.pod:565
17501 msgid "checksum-device"
17505 #: ../fish/guestfish-actions.pod:567
17508 " checksum-device csumtype device\n"
17513 #: ../fish/guestfish-actions.pod:569
17515 "This call computes the MD5, SHAx or CRC checksum of the contents of the "
17516 "device named C<device>. For the types of checksums supported see the L</"
17517 "checksum> command."
17521 #: ../fish/guestfish-actions.pod:573
17522 msgid "checksums-out"
17526 #: ../fish/guestfish-actions.pod:575
17529 " checksums-out csumtype directory (sumsfile|-)\n"
17534 #: ../fish/guestfish-actions.pod:591
17539 #: ../fish/guestfish-actions.pod:593
17542 " chmod mode path\n"
17547 #: ../fish/guestfish-actions.pod:604
17552 #: ../fish/guestfish-actions.pod:606
17555 " chown owner group path\n"
17560 #: ../fish/guestfish-actions.pod:614
17565 #: ../fish/guestfish-actions.pod:616
17568 " command 'arguments ...'\n"
17573 #: ../fish/guestfish-actions.pod:623
17575 "The single parameter is an argv-style list of arguments. The first element "
17576 "is the name of the program to run. Subsequent elements are parameters. The "
17577 "list must be non-empty (ie. must contain a program name). Note that the "
17578 "command runs directly, and is I<not> invoked via the shell (see L</sh>)."
17582 #: ../fish/guestfish-actions.pod:651
17583 msgid "command-lines"
17587 #: ../fish/guestfish-actions.pod:653
17590 " command-lines 'arguments ...'\n"
17595 #: ../fish/guestfish-actions.pod:655
17597 "This is the same as L</command>, but splits the result into a list of lines."
17601 #: ../fish/guestfish-actions.pod:658
17602 msgid "See also: L</sh-lines>"
17606 #: ../fish/guestfish-actions.pod:663
17611 #: ../fish/guestfish-actions.pod:665
17614 " config qemuparam qemuvalue\n"
17619 #: ../fish/guestfish-actions.pod:676
17624 #: ../fish/guestfish-actions.pod:678
17627 " copy-size src dest size\n"
17632 #: ../fish/guestfish-actions.pod:686
17637 #: ../fish/guestfish-actions.pod:688
17645 #: ../fish/guestfish-actions.pod:693
17650 #: ../fish/guestfish-actions.pod:695
17658 #: ../fish/guestfish-actions.pod:700
17663 #: ../fish/guestfish-actions.pod:702
17671 #: ../fish/guestfish-actions.pod:709
17673 "If the destination is a device, it must be as large or larger than the "
17674 "source file or device, otherwise the copy will fail. This command cannot do "
17675 "partial copies (see L</copy-size>)."
17679 #: ../fish/guestfish-actions.pod:713
17684 #: ../fish/guestfish-actions.pod:715
17687 " debug subcmd 'extraargs ...'\n"
17692 #: ../fish/guestfish-actions.pod:717
17694 "The L</debug> command exposes some internals of C<guestfsd> (the guestfs "
17695 "daemon) that runs inside the qemu subprocess."
17699 #: ../fish/guestfish-actions.pod:725
17700 msgid "debug-upload"
17704 #: ../fish/guestfish-actions.pod:727
17707 " debug-upload (filename|-) tmpname mode\n"
17712 #: ../fish/guestfish-actions.pod:729
17714 "The L</debug-upload> command uploads a file to the libguestfs appliance."
17718 #: ../fish/guestfish-actions.pod:738
17723 #: ../fish/guestfish-actions.pod:740
17731 #: ../fish/guestfish-actions.pod:748
17736 #: ../fish/guestfish-actions.pod:750
17744 #: ../fish/guestfish-actions.pod:759
17749 #: ../fish/guestfish-actions.pod:761
17757 #: ../fish/guestfish-actions.pod:767
17759 "Another way to get the same information is to enable verbose messages with "
17760 "L</set-verbose> or by setting the environment variable C<LIBGUESTFS_DEBUG=1> "
17761 "before running the program."
17765 #: ../fish/guestfish-actions.pod:772
17770 #: ../fish/guestfish-actions.pod:774
17773 " download remotefilename (filename|-)\n"
17778 #: ../fish/guestfish-actions.pod:781
17779 msgid "See also L</upload>, L</cat>."
17783 #: ../fish/guestfish-actions.pod:785
17784 msgid "download-offset"
17788 #: ../fish/guestfish-actions.pod:787
17791 " download-offset remotefilename (filename|-) offset size\n"
17796 #: ../fish/guestfish-actions.pod:795
17798 "Note that there is no limit on the amount of data that can be downloaded "
17799 "with this call, unlike with L</pread>, and this call always reads the full "
17800 "amount unless an error occurs."
17804 #: ../fish/guestfish-actions.pod:800
17805 msgid "See also L</download>, L</pread>."
17809 #: ../fish/guestfish-actions.pod:804
17810 msgid "drop-caches"
17814 #: ../fish/guestfish-actions.pod:806
17817 " drop-caches whattodrop\n"
17822 #: ../fish/guestfish-actions.pod:818
17827 #: ../fish/guestfish-actions.pod:820
17835 #: ../fish/guestfish-actions.pod:832
17840 #: ../fish/guestfish-actions.pod:834
17843 " e2fsck-f device\n"
17848 #: ../fish/guestfish-actions.pod:840
17850 "This command is only needed because of L</resize2fs> (q.v.). Normally you "
17851 "should use L</fsck>."
17855 #: ../fish/guestfish-actions.pod:843
17856 msgid "echo-daemon"
17860 #: ../fish/guestfish-actions.pod:845
17863 " echo-daemon 'words ...'\n"
17868 #: ../fish/guestfish-actions.pod:852
17869 msgid "See also L</ping-daemon>."
17873 #: ../fish/guestfish-actions.pod:854
17878 #: ../fish/guestfish-actions.pod:856
17881 " egrep regex path\n"
17886 #: ../fish/guestfish-actions.pod:864
17891 #: ../fish/guestfish-actions.pod:866
17894 " egrepi regex path\n"
17899 #: ../fish/guestfish-actions.pod:874
17904 #: ../fish/guestfish-actions.pod:876
17907 " equal file1 file2\n"
17912 #: ../fish/guestfish-actions.pod:883
17917 #: ../fish/guestfish-actions.pod:885
17925 #: ../fish/guestfish-actions.pod:890
17926 msgid "See also L</is-file>, L</is-dir>, L</stat>."
17930 #: ../fish/guestfish-actions.pod:892
17935 #: ../fish/guestfish-actions.pod:894
17938 " fallocate path len\n"
17943 #: ../fish/guestfish-actions.pod:911
17944 msgid "fallocate64"
17948 #: ../fish/guestfish-actions.pod:913
17951 " fallocate64 path len\n"
17956 #: ../fish/guestfish-actions.pod:919
17958 "Note that this call allocates disk blocks for the file. To create a sparse "
17959 "file use L</truncate-size> instead."
17963 #: ../fish/guestfish-actions.pod:922
17965 "The deprecated call L</fallocate> does the same, but owing to an oversight "
17966 "it only allowed 30 bit lengths to be specified, effectively limiting the "
17967 "maximum size of files created through that call to 1GB."
17971 #: ../fish/guestfish-actions.pod:931
17976 #: ../fish/guestfish-actions.pod:933
17979 " fgrep pattern path\n"
17984 #: ../fish/guestfish-actions.pod:941
17989 #: ../fish/guestfish-actions.pod:943
17992 " fgrepi pattern path\n"
17997 #: ../fish/guestfish-actions.pod:951
18002 #: ../fish/guestfish-actions.pod:953
18010 #: ../fish/guestfish-actions.pod:965
18012 "This command can also be used on C</dev/> devices (and partitions, LV "
18013 "names). You can for example use this to determine if a device contains a "
18014 "filesystem, although it's usually better to use L</vfs-type>."
18018 #: ../fish/guestfish-actions.pod:975
18019 msgid "file-architecture"
18023 #: ../fish/guestfish-actions.pod:977
18026 " file-architecture filename\n"
18031 #: ../fish/guestfish-actions.pod:1080
18036 #: ../fish/guestfish-actions.pod:1082
18044 #: ../fish/guestfish-actions.pod:1086
18046 "To get other stats about a file, use L</stat>, L</lstat>, L</is-dir>, L</is-"
18047 "file> etc. To get the size of block devices, use L</blockdev-getsize64>."
18051 #: ../fish/guestfish-actions.pod:1090
18056 #: ../fish/guestfish-actions.pod:1092
18059 " fill c len path\n"
18064 #: ../fish/guestfish-actions.pod:1098
18066 "To fill a file with zero bytes (sparsely), it is much more efficient to use "
18067 "L</truncate-size>. To create a file with a pattern of repeating bytes use "
18068 "L</fill-pattern>."
18072 #: ../fish/guestfish-actions.pod:1103
18073 msgid "fill-pattern"
18077 #: ../fish/guestfish-actions.pod:1105
18080 " fill-pattern pattern len path\n"
18085 #: ../fish/guestfish-actions.pod:1107
18087 "This function is like L</fill> except that it creates a new file of length "
18088 "C<len> containing the repeating pattern of bytes in C<pattern>. The pattern "
18089 "is truncated if necessary to ensure the length of the file is exactly C<len> "
18094 #: ../fish/guestfish-actions.pod:1112
18099 #: ../fish/guestfish-actions.pod:1114
18102 " find directory\n"
18107 #: ../fish/guestfish-actions.pod:1128
18108 msgid "then the returned list from L</find> C</tmp> would be 4 elements:"
18112 #: ../fish/guestfish-actions.pod:1141
18113 msgid "See also L</find0>."
18117 #: ../fish/guestfish-actions.pod:1146
18122 #: ../fish/guestfish-actions.pod:1148
18125 " find0 directory (files|-)\n"
18130 #: ../fish/guestfish-actions.pod:1154
18132 "This command works the same way as L</find> with the following exceptions:"
18136 #: ../fish/guestfish-actions.pod:1181
18137 msgid "findfs-label"
18141 #: ../fish/guestfish-actions.pod:1183
18144 " findfs-label label\n"
18149 #: ../fish/guestfish-actions.pod:1189
18150 msgid "To find the label of a filesystem, use L</vfs-label>."
18154 #: ../fish/guestfish-actions.pod:1191
18155 msgid "findfs-uuid"
18159 #: ../fish/guestfish-actions.pod:1193
18162 " findfs-uuid uuid\n"
18167 #: ../fish/guestfish-actions.pod:1199
18168 msgid "To find the UUID of a filesystem, use L</vfs-uuid>."
18172 #: ../fish/guestfish-actions.pod:1201
18177 #: ../fish/guestfish-actions.pod:1203
18180 " fsck fstype device\n"
18185 #: ../fish/guestfish-actions.pod:1233
18190 #: ../fish/guestfish-actions.pod:1235
18198 #: ../fish/guestfish-actions.pod:1242
18199 msgid "get-autosync"
18203 #: ../fish/guestfish-actions.pod:1244
18211 #: ../fish/guestfish-actions.pod:1248
18216 #: ../fish/guestfish-actions.pod:1250
18224 #: ../fish/guestfish-actions.pod:1254
18225 msgid "get-e2label"
18229 #: ../fish/guestfish-actions.pod:1256
18232 " get-e2label device\n"
18237 #: ../fish/guestfish-actions.pod:1268
18242 #: ../fish/guestfish-actions.pod:1270
18245 " get-e2uuid device\n"
18250 #: ../fish/guestfish-actions.pod:1282
18251 msgid "get-memsize"
18255 #: ../fish/guestfish-actions.pod:1284
18263 #: ../fish/guestfish-actions.pod:1289
18265 "If L</set-memsize> was not called on this handle, and if "
18266 "C<LIBGUESTFS_MEMSIZE> was not set, then this returns the compiled-in default "
18267 "value for memsize."
18271 #: ../fish/guestfish-actions.pod:1296
18272 msgid "get-network"
18276 #: ../fish/guestfish-actions.pod:1298
18284 #: ../fish/guestfish-actions.pod:1302
18289 #: ../fish/guestfish-actions.pod:1304
18297 #: ../fish/guestfish-actions.pod:1311
18302 #: ../fish/guestfish-actions.pod:1313
18307 #: ../fish/guestfish-actions.pod:1315
18315 #: ../fish/guestfish-actions.pod:1322
18320 #: ../fish/guestfish-actions.pod:1324
18328 #: ../fish/guestfish-actions.pod:1331
18329 msgid "get-recovery-proc"
18333 #: ../fish/guestfish-actions.pod:1333
18336 " get-recovery-proc\n"
18341 #: ../fish/guestfish-actions.pod:1337
18342 msgid "get-selinux"
18346 #: ../fish/guestfish-actions.pod:1339
18354 #: ../fish/guestfish-actions.pod:1341
18356 "This returns the current setting of the selinux flag which is passed to the "
18357 "appliance at boot time. See L</set-selinux>."
18361 #: ../fish/guestfish-actions.pod:1347
18366 #: ../fish/guestfish-actions.pod:1349
18374 #: ../fish/guestfish-actions.pod:1356
18379 #: ../fish/guestfish-actions.pod:1358
18387 #: ../fish/guestfish-actions.pod:1362
18392 #: ../fish/guestfish-actions.pod:1364
18400 #: ../fish/guestfish-actions.pod:1366
18402 "Return the current umask. By default the umask is C<022> unless it has been "
18403 "set by calling L</umask>."
18407 #: ../fish/guestfish-actions.pod:1369
18408 msgid "get-verbose"
18412 #: ../fish/guestfish-actions.pod:1371
18420 #: ../fish/guestfish-actions.pod:1375
18425 #: ../fish/guestfish-actions.pod:1377
18433 #: ../fish/guestfish-actions.pod:1381
18434 msgid "See the documentation about SELINUX in L<guestfs(3)>, and L</setcon>"
18438 #: ../fish/guestfish-actions.pod:1384
18443 #: ../fish/guestfish-actions.pod:1386
18446 " getxattrs path\n"
18451 #: ../fish/guestfish-actions.pod:1394
18452 msgid "See also: L</lgetxattrs>, L<attr(5)>."
18456 #: ../fish/guestfish-actions.pod:1396
18457 msgid "glob-expand"
18461 #: ../fish/guestfish-actions.pod:1398
18464 " glob-expand pattern\n"
18469 #: ../fish/guestfish-actions.pod:1411
18474 #: ../fish/guestfish-actions.pod:1413
18477 " grep regex path\n"
18482 #: ../fish/guestfish-actions.pod:1421
18487 #: ../fish/guestfish-actions.pod:1423
18490 " grepi regex path\n"
18495 #: ../fish/guestfish-actions.pod:1431
18496 msgid "grub-install"
18500 #: ../fish/guestfish-actions.pod:1433
18503 " grub-install root device\n"
18508 #: ../fish/guestfish-actions.pod:1449
18513 #: ../fish/guestfish-actions.pod:1451
18521 #: ../fish/guestfish-actions.pod:1459
18526 #: ../fish/guestfish-actions.pod:1461
18529 " head-n nrlines path\n"
18534 #: ../fish/guestfish-actions.pod:1474
18539 #: ../fish/guestfish-actions.pod:1476
18547 #: ../fish/guestfish-actions.pod:1484
18552 #: ../fish/guestfish-actions.pod:1486
18555 " initrd-cat initrdpath filename\n"
18560 #: ../fish/guestfish-actions.pod:1498
18561 msgid "See also L</initrd-list>."
18565 #: ../fish/guestfish-actions.pod:1503
18566 msgid "initrd-list"
18570 #: ../fish/guestfish-actions.pod:1505
18573 " initrd-list path\n"
18578 #: ../fish/guestfish-actions.pod:1517
18579 msgid "inotify-add-watch"
18583 #: ../fish/guestfish-actions.pod:1519
18586 " inotify-add-watch path mask\n"
18591 #: ../fish/guestfish-actions.pod:1531
18592 msgid "inotify-close"
18596 #: ../fish/guestfish-actions.pod:1533
18604 #: ../fish/guestfish-actions.pod:1539
18605 msgid "inotify-files"
18609 #: ../fish/guestfish-actions.pod:1541
18617 #: ../fish/guestfish-actions.pod:1543
18619 "This function is a helpful wrapper around L</inotify-read> which just "
18620 "returns a list of pathnames of objects that were touched. The returned "
18621 "pathnames are sorted and deduplicated."
18625 #: ../fish/guestfish-actions.pod:1547
18626 msgid "inotify-init"
18630 #: ../fish/guestfish-actions.pod:1549
18633 " inotify-init maxevents\n"
18638 #: ../fish/guestfish-actions.pod:1555
18640 "C<maxevents> is the maximum number of events which will be queued up between "
18641 "calls to L</inotify-read> or L</inotify-files>. If this is passed as C<0>, "
18642 "then the kernel (or previously set) default is used. For Linux 2.6.29 the "
18643 "default was 16384 events. Beyond this limit, the kernel throws away events, "
18644 "but records the fact that it threw them away by setting a flag "
18645 "C<IN_Q_OVERFLOW> in the returned structure list (see L</inotify-read>)."
18649 #: ../fish/guestfish-actions.pod:1565
18651 "Before any events are generated, you have to add some watches to the "
18652 "internal watch list. See: L</inotify-add-watch>, L</inotify-rm-watch> and "
18653 "L</inotify-watch-all>."
18657 #: ../fish/guestfish-actions.pod:1571
18659 "Queued up events should be read periodically by calling L</inotify-read> (or "
18660 "L</inotify-files> which is just a helpful wrapper around L</inotify-read>). "
18661 "If you don't read the events out often enough then you risk the internal "
18662 "queue overflowing."
18666 #: ../fish/guestfish-actions.pod:1578
18668 "The handle should be closed after use by calling L</inotify-close>. This "
18669 "also removes any watches automatically."
18673 #: ../fish/guestfish-actions.pod:1587
18674 msgid "inotify-read"
18678 #: ../fish/guestfish-actions.pod:1589
18686 #: ../fish/guestfish-actions.pod:1602
18687 msgid "inotify-rm-watch"
18691 #: ../fish/guestfish-actions.pod:1604
18694 " inotify-rm-watch wd\n"
18699 #: ../fish/guestfish-actions.pod:1606
18700 msgid "Remove a previously defined inotify watch. See L</inotify-add-watch>."
18704 #: ../fish/guestfish-actions.pod:1609
18705 msgid "inspect-get-arch"
18709 #: ../fish/guestfish-actions.pod:1611
18712 " inspect-get-arch root\n"
18717 #: ../fish/guestfish-actions.pod:1613 ../fish/guestfish-actions.pod:1629
18718 #: ../fish/guestfish-actions.pod:1675 ../fish/guestfish-actions.pod:1693
18719 #: ../fish/guestfish-actions.pod:1714 ../fish/guestfish-actions.pod:1729
18720 #: ../fish/guestfish-actions.pod:1752 ../fish/guestfish-actions.pod:1769
18722 "This function should only be called with a root device string as returned by "
18727 #: ../fish/guestfish-actions.pod:1616
18729 "This returns the architecture of the inspected operating system. The "
18730 "possible return values are listed under L</file-architecture>."
18734 #: ../fish/guestfish-actions.pod:1625
18735 msgid "inspect-get-distro"
18739 #: ../fish/guestfish-actions.pod:1627
18742 " inspect-get-distro root\n"
18747 #: ../fish/guestfish-actions.pod:1671
18748 msgid "inspect-get-filesystems"
18752 #: ../fish/guestfish-actions.pod:1673
18755 " inspect-get-filesystems root\n"
18760 #: ../fish/guestfish-actions.pod:1686
18762 "Please read L<guestfs(3)/INSPECTION> for more details. See also L</inspect-"
18763 "get-mountpoints>."
18767 #: ../fish/guestfish-actions.pod:1689
18768 msgid "inspect-get-major-version"
18772 #: ../fish/guestfish-actions.pod:1691
18775 " inspect-get-major-version root\n"
18780 #: ../fish/guestfish-actions.pod:1710
18781 msgid "inspect-get-minor-version"
18785 #: ../fish/guestfish-actions.pod:1712
18788 " inspect-get-minor-version root\n"
18793 #: ../fish/guestfish-actions.pod:1722
18795 "Please read L<guestfs(3)/INSPECTION> for more details. See also L</inspect-"
18796 "get-major-version>."
18800 #: ../fish/guestfish-actions.pod:1725
18801 msgid "inspect-get-mountpoints"
18805 #: ../fish/guestfish-actions.pod:1727
18808 " inspect-get-mountpoints root\n"
18813 #: ../fish/guestfish-actions.pod:1745
18815 "Please read L<guestfs(3)/INSPECTION> for more details. See also L</inspect-"
18816 "get-filesystems>."
18820 #: ../fish/guestfish-actions.pod:1748
18821 msgid "inspect-get-product-name"
18825 #: ../fish/guestfish-actions.pod:1750
18828 " inspect-get-product-name root\n"
18833 #: ../fish/guestfish-actions.pod:1765
18834 msgid "inspect-get-type"
18838 #: ../fish/guestfish-actions.pod:1767
18841 " inspect-get-type root\n"
18846 #: ../fish/guestfish-actions.pod:1796
18851 #: ../fish/guestfish-actions.pod:1798
18859 #: ../fish/guestfish-actions.pod:1813
18861 "You can pass the root string(s) returned to other L</inspect-get-*> "
18862 "functions in order to query further information about each operating system, "
18863 "such as the name and version."
18867 #: ../fish/guestfish-actions.pod:1818
18869 "This function uses other libguestfs features such as L</mount-ro> and L</"
18870 "umount-all> in order to mount and unmount filesystems and look at the "
18871 "contents. This should be called with no disks currently mounted. The "
18872 "function may also use Augeas, so any existing Augeas handle will be closed."
18876 #: ../fish/guestfish-actions.pod:1830 ../fish/guestfish-actions.pod:1986
18877 #: ../fish/guestfish-actions.pod:2032
18878 msgid "See also L</list-filesystems>."
18882 #: ../fish/guestfish-actions.pod:1832
18883 msgid "is-blockdev"
18887 #: ../fish/guestfish-actions.pod:1834
18890 " is-blockdev path\n"
18895 #: ../fish/guestfish-actions.pod:1839 ../fish/guestfish-actions.pod:1857
18896 #: ../fish/guestfish-actions.pod:1876 ../fish/guestfish-actions.pod:1885
18897 #: ../fish/guestfish-actions.pod:1895 ../fish/guestfish-actions.pod:1929
18898 #: ../fish/guestfish-actions.pod:1938
18899 msgid "See also L</stat>."
18903 #: ../fish/guestfish-actions.pod:1841
18908 #: ../fish/guestfish-actions.pod:1843
18916 #: ../fish/guestfish-actions.pod:1850
18921 #: ../fish/guestfish-actions.pod:1852
18924 " is-chardev path\n"
18929 #: ../fish/guestfish-actions.pod:1859
18934 #: ../fish/guestfish-actions.pod:1861
18942 #: ../fish/guestfish-actions.pod:1868
18947 #: ../fish/guestfish-actions.pod:1870
18955 #: ../fish/guestfish-actions.pod:1878
18960 #: ../fish/guestfish-actions.pod:1880
18968 #: ../fish/guestfish-actions.pod:1887
18973 #: ../fish/guestfish-actions.pod:1889
18981 #: ../fish/guestfish-actions.pod:1897
18982 msgid "is-launching"
18986 #: ../fish/guestfish-actions.pod:1899
18994 #: ../fish/guestfish-actions.pod:1906
18999 #: ../fish/guestfish-actions.pod:1908
19007 #: ../fish/guestfish-actions.pod:1913
19012 #: ../fish/guestfish-actions.pod:1915
19020 #: ../fish/guestfish-actions.pod:1922
19025 #: ../fish/guestfish-actions.pod:1924
19028 " is-socket path\n"
19033 #: ../fish/guestfish-actions.pod:1931
19038 #: ../fish/guestfish-actions.pod:1933
19041 " is-symlink path\n"
19046 #: ../fish/guestfish-actions.pod:1940
19047 msgid "kill-subprocess"
19051 #: ../fish/guestfish-actions.pod:1942
19054 " kill-subprocess\n"
19059 #: ../fish/guestfish-actions.pod:1946
19064 #: ../fish/guestfish-actions.pod:1948
19069 #: ../fish/guestfish-actions.pod:1950
19077 #: ../fish/guestfish-actions.pod:1958
19082 #: ../fish/guestfish-actions.pod:1960
19085 " lchown owner group path\n"
19090 #: ../fish/guestfish-actions.pod:1962
19092 "Change the file owner to C<owner> and group to C<group>. This is like L</"
19093 "chown> but if C<path> is a symlink then the link itself is changed, not the "
19098 #: ../fish/guestfish-actions.pod:1970
19103 #: ../fish/guestfish-actions.pod:1972
19106 " lgetxattrs path\n"
19111 #: ../fish/guestfish-actions.pod:1974
19113 "This is the same as L</getxattrs>, but if C<path> is a symbolic link, then "
19114 "it returns the extended attributes of the link itself."
19118 #: ../fish/guestfish-actions.pod:1978
19119 msgid "list-devices"
19123 #: ../fish/guestfish-actions.pod:1980
19131 #: ../fish/guestfish-actions.pod:1988
19132 msgid "list-filesystems"
19136 #: ../fish/guestfish-actions.pod:1990
19139 " list-filesystems\n"
19144 #: ../fish/guestfish-actions.pod:2009
19146 "This command runs other libguestfs commands, which might include L</mount> "
19147 "and L</umount>, and therefore you should use this soon after launch and only "
19148 "when nothing is mounted."
19152 #: ../fish/guestfish-actions.pod:2013
19154 "Not all of the filesystems returned will be mountable. In particular, swap "
19155 "partitions are returned in the list. Also this command does not check that "
19156 "each filesystem found is valid and mountable, and some filesystems might be "
19157 "mountable but require special options. Filesystems may not all belong to a "
19158 "single logical operating system (use L</inspect-os> to look for OSes)."
19162 #: ../fish/guestfish-actions.pod:2021
19163 msgid "list-partitions"
19167 #: ../fish/guestfish-actions.pod:2023
19170 " list-partitions\n"
19175 #: ../fish/guestfish-actions.pod:2029
19177 "This does not return logical volumes. For that you will need to call L</"
19182 #: ../fish/guestfish-actions.pod:2034
19187 #: ../fish/guestfish-actions.pod:2036
19195 #: ../fish/guestfish-actions.pod:2044
19200 #: ../fish/guestfish-actions.pod:2046
19203 " ln target linkname\n"
19208 #: ../fish/guestfish-actions.pod:2050
19213 #: ../fish/guestfish-actions.pod:2052
19216 " ln-f target linkname\n"
19221 #: ../fish/guestfish-actions.pod:2057
19226 #: ../fish/guestfish-actions.pod:2059
19229 " ln-s target linkname\n"
19234 #: ../fish/guestfish-actions.pod:2063
19239 #: ../fish/guestfish-actions.pod:2065
19242 " ln-sf target linkname\n"
19247 #: ../fish/guestfish-actions.pod:2070
19248 msgid "lremovexattr"
19252 #: ../fish/guestfish-actions.pod:2072
19255 " lremovexattr xattr path\n"
19260 #: ../fish/guestfish-actions.pod:2074
19262 "This is the same as L</removexattr>, but if C<path> is a symbolic link, then "
19263 "it removes an extended attribute of the link itself."
19267 #: ../fish/guestfish-actions.pod:2078
19272 #: ../fish/guestfish-actions.pod:2080
19280 #: ../fish/guestfish-actions.pod:2086
19282 "This command is mostly useful for interactive sessions. Programs should "
19283 "probably use L</readdir> instead."
19287 #: ../fish/guestfish-actions.pod:2089
19292 #: ../fish/guestfish-actions.pod:2091
19295 " lsetxattr xattr val vallen path\n"
19300 #: ../fish/guestfish-actions.pod:2093
19302 "This is the same as L</setxattr>, but if C<path> is a symbolic link, then it "
19303 "sets an extended attribute of the link itself."
19307 #: ../fish/guestfish-actions.pod:2097
19312 #: ../fish/guestfish-actions.pod:2099
19320 #: ../fish/guestfish-actions.pod:2103
19322 "This is the same as L</stat> except that if C<path> is a symbolic link, then "
19323 "the link is stat-ed, not the file it refers to."
19327 #: ../fish/guestfish-actions.pod:2109
19332 #: ../fish/guestfish-actions.pod:2111
19335 " lstatlist path 'names ...'\n"
19340 #: ../fish/guestfish-actions.pod:2113
19342 "This call allows you to perform the L</lstat> operation on multiple files, "
19343 "where all files are in the directory C<path>. C<names> is the list of files "
19344 "from this directory."
19348 #: ../fish/guestfish-actions.pod:2122
19350 "This call is intended for programs that want to efficiently list a directory "
19351 "contents without making many round-trips. See also L</lxattrlist> for a "
19352 "similarly efficient call for getting extended attributes. Very long "
19353 "directory listings might cause the protocol message size to be exceeded, "
19354 "causing this call to fail. The caller must split up such requests into "
19355 "smaller groups of names."
19359 #: ../fish/guestfish-actions.pod:2130
19360 msgid "luks-add-key"
19364 #: ../fish/guestfish-actions.pod:2132
19367 " luks-add-key device keyslot\n"
19372 #: ../fish/guestfish-actions.pod:2139
19374 "Note that if C<keyslot> already contains a key, then this command will "
19375 "fail. You have to use L</luks-kill-slot> first to remove that key."
19379 #: ../fish/guestfish-actions.pod:2143 ../fish/guestfish-actions.pod:2165
19380 #: ../fish/guestfish-actions.pod:2178 ../fish/guestfish-actions.pod:2192
19381 #: ../fish/guestfish-actions.pod:2215 ../fish/guestfish-actions.pod:2225
19383 "This command has one or more key or passphrase parameters. Guestfish will "
19384 "prompt for these separately."
19388 #: ../fish/guestfish-actions.pod:2146
19393 #: ../fish/guestfish-actions.pod:2148
19396 " luks-close device\n"
19401 #: ../fish/guestfish-actions.pod:2150
19403 "This closes a LUKS device that was created earlier by L</luks-open> or L</"
19404 "luks-open-ro>. The C<device> parameter must be the name of the LUKS mapping "
19405 "device (ie. C</dev/mapper/mapname>) and I<not> the name of the underlying "
19410 #: ../fish/guestfish-actions.pod:2156
19411 msgid "luks-format"
19415 #: ../fish/guestfish-actions.pod:2158
19418 " luks-format device keyslot\n"
19423 #: ../fish/guestfish-actions.pod:2171
19424 msgid "luks-format-cipher"
19428 #: ../fish/guestfish-actions.pod:2173
19431 " luks-format-cipher device keyslot cipher\n"
19436 #: ../fish/guestfish-actions.pod:2175
19438 "This command is the same as L</luks-format> but it also allows you to set "
19439 "the C<cipher> used."
19443 #: ../fish/guestfish-actions.pod:2184
19444 msgid "luks-kill-slot"
19448 #: ../fish/guestfish-actions.pod:2186
19451 " luks-kill-slot device keyslot\n"
19456 #: ../fish/guestfish-actions.pod:2195
19461 #: ../fish/guestfish-actions.pod:2197
19464 " luks-open device mapname\n"
19469 #: ../fish/guestfish-actions.pod:2211
19471 "If this block device contains LVM volume groups, then calling L</vgscan> "
19472 "followed by L</vg-activate-all> will make them visible."
19476 #: ../fish/guestfish-actions.pod:2218
19477 msgid "luks-open-ro"
19481 #: ../fish/guestfish-actions.pod:2220
19484 " luks-open-ro device mapname\n"
19489 #: ../fish/guestfish-actions.pod:2222
19491 "This is the same as L</luks-open> except that a read-only mapping is created."
19495 #: ../fish/guestfish-actions.pod:2228
19500 #: ../fish/guestfish-actions.pod:2230
19503 " lvcreate logvol volgroup mbytes\n"
19508 #: ../fish/guestfish-actions.pod:2235
19509 msgid "lvm-clear-filter"
19513 #: ../fish/guestfish-actions.pod:2237
19516 " lvm-clear-filter\n"
19521 #: ../fish/guestfish-actions.pod:2239
19523 "This undoes the effect of L</lvm-set-filter>. LVM will be able to see every "
19528 #: ../fish/guestfish-actions.pod:2245
19529 msgid "lvm-remove-all"
19533 #: ../fish/guestfish-actions.pod:2247
19536 " lvm-remove-all\n"
19541 #: ../fish/guestfish-actions.pod:2255
19542 msgid "lvm-set-filter"
19546 #: ../fish/guestfish-actions.pod:2257
19549 " lvm-set-filter 'devices ...'\n"
19554 #: ../fish/guestfish-actions.pod:2282
19559 #: ../fish/guestfish-actions.pod:2284
19562 " lvremove device\n"
19567 #: ../fish/guestfish-actions.pod:2292
19572 #: ../fish/guestfish-actions.pod:2294
19575 " lvrename logvol newlogvol\n"
19580 #: ../fish/guestfish-actions.pod:2298
19585 #: ../fish/guestfish-actions.pod:2300
19588 " lvresize device mbytes\n"
19593 #: ../fish/guestfish-actions.pod:2306
19594 msgid "lvresize-free"
19598 #: ../fish/guestfish-actions.pod:2308
19601 " lvresize-free lv percent\n"
19606 #: ../fish/guestfish-actions.pod:2316
19611 #: ../fish/guestfish-actions.pod:2318
19619 #: ../fish/guestfish-actions.pod:2326
19620 msgid "See also L</lvs-full>, L</list-filesystems>."
19624 #: ../fish/guestfish-actions.pod:2328
19629 #: ../fish/guestfish-actions.pod:2330
19637 #: ../fish/guestfish-actions.pod:2335
19642 #: ../fish/guestfish-actions.pod:2337
19650 #: ../fish/guestfish-actions.pod:2341
19655 #: ../fish/guestfish-actions.pod:2343
19658 " lxattrlist path 'names ...'\n"
19663 #: ../fish/guestfish-actions.pod:2359
19665 "This call is intended for programs that want to efficiently list a directory "
19666 "contents without making many round-trips. See also L</lstatlist> for a "
19667 "similarly efficient call for getting standard stats. Very long directory "
19668 "listings might cause the protocol message size to be exceeded, causing this "
19669 "call to fail. The caller must split up such requests into smaller groups of "
19674 #: ../fish/guestfish-actions.pod:2367
19679 #: ../fish/guestfish-actions.pod:2369
19687 #: ../fish/guestfish-actions.pod:2373
19692 #: ../fish/guestfish-actions.pod:2375
19695 " mkdir-mode path mode\n"
19700 #: ../fish/guestfish-actions.pod:2384
19701 msgid "See also L</mkdir>, L</umask>"
19705 #: ../fish/guestfish-actions.pod:2386
19710 #: ../fish/guestfish-actions.pod:2388
19718 #: ../fish/guestfish-actions.pod:2393
19723 #: ../fish/guestfish-actions.pod:2395
19726 " mkdtemp template\n"
19731 #: ../fish/guestfish-actions.pod:2416
19736 #: ../fish/guestfish-actions.pod:2418
19739 " mke2fs-J fstype blocksize device journal\n"
19744 #: ../fish/guestfish-actions.pod:2426
19745 msgid "See also L</mke2journal>."
19749 #: ../fish/guestfish-actions.pod:2428
19754 #: ../fish/guestfish-actions.pod:2430
19757 " mke2fs-JL fstype blocksize device label\n"
19762 #: ../fish/guestfish-actions.pod:2435
19763 msgid "See also L</mke2journal-L>."
19767 #: ../fish/guestfish-actions.pod:2437
19772 #: ../fish/guestfish-actions.pod:2439
19775 " mke2fs-JU fstype blocksize device uuid\n"
19780 #: ../fish/guestfish-actions.pod:2444
19781 msgid "See also L</mke2journal-U>."
19785 #: ../fish/guestfish-actions.pod:2446
19786 msgid "mke2journal"
19790 #: ../fish/guestfish-actions.pod:2448
19793 " mke2journal blocksize device\n"
19798 #: ../fish/guestfish-actions.pod:2455
19799 msgid "mke2journal-L"
19803 #: ../fish/guestfish-actions.pod:2457
19806 " mke2journal-L blocksize label device\n"
19811 #: ../fish/guestfish-actions.pod:2461
19812 msgid "mke2journal-U"
19816 #: ../fish/guestfish-actions.pod:2463
19819 " mke2journal-U blocksize uuid device\n"
19824 #: ../fish/guestfish-actions.pod:2467
19829 #: ../fish/guestfish-actions.pod:2469
19832 " mkfifo mode path\n"
19837 #: ../fish/guestfish-actions.pod:2471
19839 "This call creates a FIFO (named pipe) called C<path> with mode C<mode>. It "
19840 "is just a convenient wrapper around L</mknod>."
19844 #: ../fish/guestfish-actions.pod:2477
19849 #: ../fish/guestfish-actions.pod:2479
19852 " mkfs fstype device\n"
19857 #: ../fish/guestfish-actions.pod:2485
19862 #: ../fish/guestfish-actions.pod:2487
19865 " mkfs-b fstype blocksize device\n"
19870 #: ../fish/guestfish-actions.pod:2489
19872 "This call is similar to L</mkfs>, but it allows you to control the block "
19873 "size of the resulting filesystem. Supported block sizes depend on the "
19874 "filesystem type, but typically they are C<1024>, C<2048> or C<4096> only."
19878 #: ../fish/guestfish-actions.pod:2497
19879 msgid "mkmountpoint"
19883 #: ../fish/guestfish-actions.pod:2499
19886 " mkmountpoint exemptpath\n"
19891 #: ../fish/guestfish-actions.pod:2501
19893 "L</mkmountpoint> and L</rmmountpoint> are specialized calls that can be used "
19894 "to create extra mountpoints before mounting the first filesystem."
19898 #: ../fish/guestfish-actions.pod:2525
19903 #: ../fish/guestfish-actions.pod:2527
19906 " mknod mode devmajor devminor path\n"
19911 #: ../fish/guestfish-actions.pod:2537
19913 "Note that, just like L<mknod(2)>, the mode must be bitwise OR'd with "
19914 "S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates a "
19915 "regular file). These constants are available in the standard Linux header "
19916 "files, or you can use L</mknod-b>, L</mknod-c> or L</mkfifo> which are "
19917 "wrappers around this command which bitwise OR in the appropriate constant "
19922 #: ../fish/guestfish-actions.pod:2547
19927 #: ../fish/guestfish-actions.pod:2549
19930 " mknod-b mode devmajor devminor path\n"
19935 #: ../fish/guestfish-actions.pod:2551
19937 "This call creates a block device node called C<path> with mode C<mode> and "
19938 "device major/minor C<devmajor> and C<devminor>. It is just a convenient "
19939 "wrapper around L</mknod>."
19943 #: ../fish/guestfish-actions.pod:2557
19948 #: ../fish/guestfish-actions.pod:2559
19951 " mknod-c mode devmajor devminor path\n"
19956 #: ../fish/guestfish-actions.pod:2561
19958 "This call creates a char device node called C<path> with mode C<mode> and "
19959 "device major/minor C<devmajor> and C<devminor>. It is just a convenient "
19960 "wrapper around L</mknod>."
19964 #: ../fish/guestfish-actions.pod:2567
19969 #: ../fish/guestfish-actions.pod:2569
19977 #: ../fish/guestfish-actions.pod:2573
19982 #: ../fish/guestfish-actions.pod:2575
19985 " mkswap-L label device\n"
19990 #: ../fish/guestfish-actions.pod:2583
19995 #: ../fish/guestfish-actions.pod:2585
19998 " mkswap-U uuid device\n"
20003 #: ../fish/guestfish-actions.pod:2589
20004 msgid "mkswap-file"
20008 #: ../fish/guestfish-actions.pod:2591
20011 " mkswap-file path\n"
20016 #: ../fish/guestfish-actions.pod:2595
20018 "This command just writes a swap file signature to an existing file. To "
20019 "create the file itself, use something like L</fallocate>."
20023 #: ../fish/guestfish-actions.pod:2598
20028 #: ../fish/guestfish-actions.pod:2600
20031 " modprobe modulename\n"
20036 #: ../fish/guestfish-actions.pod:2607
20041 #: ../fish/guestfish-actions.pod:2609
20044 " mount device mountpoint\n"
20049 #: ../fish/guestfish-actions.pod:2625
20051 "B<Important note:> When you use this call, the filesystem options C<sync> "
20052 "and C<noatime> are set implicitly. This was originally done because we "
20053 "thought it would improve reliability, but it turns out that I<-o sync> has a "
20054 "very large negative performance impact and negligible effect on "
20055 "reliability. Therefore we recommend that you avoid using L</mount> in any "
20056 "code that needs performance, and instead use L</mount-options> (use an empty "
20057 "string for the first parameter if you don't want any options)."
20061 #: ../fish/guestfish-actions.pod:2635
20066 #: ../fish/guestfish-actions.pod:2637
20069 " mount-loop file mountpoint\n"
20074 #: ../fish/guestfish-actions.pod:2643
20075 msgid "mount-options"
20079 #: ../fish/guestfish-actions.pod:2645
20082 " mount-options options device mountpoint\n"
20087 #: ../fish/guestfish-actions.pod:2647
20089 "This is the same as the L</mount> command, but it allows you to set the "
20090 "mount options as for the L<mount(8)> I<-o> flag."
20094 #: ../fish/guestfish-actions.pod:2655
20099 #: ../fish/guestfish-actions.pod:2657
20102 " mount-ro device mountpoint\n"
20107 #: ../fish/guestfish-actions.pod:2659
20109 "This is the same as the L</mount> command, but it mounts the filesystem with "
20110 "the read-only (I<-o ro>) flag."
20114 #: ../fish/guestfish-actions.pod:2662
20119 #: ../fish/guestfish-actions.pod:2664
20122 " mount-vfs options vfstype device mountpoint\n"
20127 #: ../fish/guestfish-actions.pod:2666
20129 "This is the same as the L</mount> command, but it allows you to set both the "
20130 "mount options and the vfstype as for the L<mount(8)> I<-o> and I<-t> flags."
20134 #: ../fish/guestfish-actions.pod:2670
20135 msgid "mountpoints"
20139 #: ../fish/guestfish-actions.pod:2672
20147 #: ../fish/guestfish-actions.pod:2674
20149 "This call is similar to L</mounts>. That call returns a list of devices. "
20150 "This one returns a hash table (map) of device name to directory where the "
20151 "device is mounted."
20155 #: ../fish/guestfish-actions.pod:2678
20160 #: ../fish/guestfish-actions.pod:2680
20168 #: ../fish/guestfish-actions.pod:2687
20169 msgid "See also: L</mountpoints>"
20173 #: ../fish/guestfish-actions.pod:2689
20178 #: ../fish/guestfish-actions.pod:2691
20186 #: ../fish/guestfish-actions.pod:2696
20187 msgid "ntfs-3g-probe"
20191 #: ../fish/guestfish-actions.pod:2698
20194 " ntfs-3g-probe true|false device\n"
20199 #: ../fish/guestfish-actions.pod:2712
20204 #: ../fish/guestfish-actions.pod:2714
20207 " ntfsresize device\n"
20212 #: ../fish/guestfish-actions.pod:2720
20213 msgid "ntfsresize-size"
20217 #: ../fish/guestfish-actions.pod:2722
20220 " ntfsresize-size device size\n"
20225 #: ../fish/guestfish-actions.pod:2724
20227 "This command is the same as L</ntfsresize> except that it allows you to "
20228 "specify the new size (in bytes) explicitly."
20232 #: ../fish/guestfish-actions.pod:2727
20237 #: ../fish/guestfish-actions.pod:2729
20240 " part-add device prlogex startsect endsect\n"
20245 #: ../fish/guestfish-actions.pod:2731
20247 "This command adds a partition to C<device>. If there is no partition table "
20248 "on the device, call L</part-init> first."
20252 #: ../fish/guestfish-actions.pod:2743
20254 "Creating a partition which covers the whole disk is not so easy. Use L</"
20255 "part-disk> to do that."
20259 #: ../fish/guestfish-actions.pod:2746
20264 #: ../fish/guestfish-actions.pod:2748
20267 " part-del device partnum\n"
20272 #: ../fish/guestfish-actions.pod:2756
20277 #: ../fish/guestfish-actions.pod:2758
20280 " part-disk device parttype\n"
20285 #: ../fish/guestfish-actions.pod:2760
20287 "This command is simply a combination of L</part-init> followed by L</part-"
20288 "add> to create a single primary partition covering the whole disk."
20292 #: ../fish/guestfish-actions.pod:2764
20294 "C<parttype> is the partition table type, usually C<mbr> or C<gpt>, but other "
20295 "possible values are described in L</part-init>."
20299 #: ../fish/guestfish-actions.pod:2770
20300 msgid "part-get-bootable"
20304 #: ../fish/guestfish-actions.pod:2772
20307 " part-get-bootable device partnum\n"
20312 #: ../fish/guestfish-actions.pod:2777
20313 msgid "See also L</part-set-bootable>."
20317 #: ../fish/guestfish-actions.pod:2779
20318 msgid "part-get-mbr-id"
20322 #: ../fish/guestfish-actions.pod:2781
20325 " part-get-mbr-id device partnum\n"
20330 #: ../fish/guestfish-actions.pod:2786 ../fish/guestfish-actions.pod:2924
20332 "Note that only MBR (old DOS-style) partitions have type bytes. You will get "
20333 "undefined results for other partition table types (see L</part-get-"
20338 #: ../fish/guestfish-actions.pod:2790
20339 msgid "part-get-parttype"
20343 #: ../fish/guestfish-actions.pod:2792
20346 " part-get-parttype device\n"
20351 #: ../fish/guestfish-actions.pod:2797
20353 "Common return values include: C<msdos> (a DOS/Windows style MBR partition "
20354 "table), C<gpt> (a GPT/EFI-style partition table). Other values are "
20355 "possible, although unusual. See L</part-init> for a full list."
20359 #: ../fish/guestfish-actions.pod:2802
20364 #: ../fish/guestfish-actions.pod:2804
20367 " part-init device parttype\n"
20372 #: ../fish/guestfish-actions.pod:2810
20374 "Initially there are no partitions. Following this, you should call L</part-"
20375 "add> for each partition required."
20379 #: ../fish/guestfish-actions.pod:2873
20384 #: ../fish/guestfish-actions.pod:2875
20387 " part-list device\n"
20392 #: ../fish/guestfish-actions.pod:2890
20394 "Start of the partition I<in bytes>. To get sectors you have to divide by "
20395 "the device's sector size, see L</blockdev-getss>."
20399 #: ../fish/guestfish-actions.pod:2903
20400 msgid "part-set-bootable"
20404 #: ../fish/guestfish-actions.pod:2905
20407 " part-set-bootable device partnum true|false\n"
20412 #: ../fish/guestfish-actions.pod:2914
20413 msgid "part-set-mbr-id"
20417 #: ../fish/guestfish-actions.pod:2916
20420 " part-set-mbr-id device partnum idbyte\n"
20425 #: ../fish/guestfish-actions.pod:2928
20426 msgid "part-set-name"
20430 #: ../fish/guestfish-actions.pod:2930
20433 " part-set-name device partnum name\n"
20438 #: ../fish/guestfish-actions.pod:2938
20439 msgid "part-to-dev"
20443 #: ../fish/guestfish-actions.pod:2940
20446 " part-to-dev partition\n"
20451 #: ../fish/guestfish-actions.pod:2946
20453 "The named partition must exist, for example as a string returned from L</"
20454 "list-partitions>."
20458 #: ../fish/guestfish-actions.pod:2949
20459 msgid "ping-daemon"
20463 #: ../fish/guestfish-actions.pod:2951
20471 #: ../fish/guestfish-actions.pod:2958
20476 #: ../fish/guestfish-actions.pod:2960
20479 " pread path count offset\n"
20484 #: ../fish/guestfish-actions.pod:2968 ../fish/guestfish-actions.pod:3061
20485 msgid "See also L</pwrite>."
20489 #: ../fish/guestfish-actions.pod:2973
20494 #: ../fish/guestfish-actions.pod:2975
20497 " pvcreate device\n"
20502 #: ../fish/guestfish-actions.pod:2981
20507 #: ../fish/guestfish-actions.pod:2983
20510 " pvremove device\n"
20515 #: ../fish/guestfish-actions.pod:2992
20520 #: ../fish/guestfish-actions.pod:2994
20523 " pvresize device\n"
20528 #: ../fish/guestfish-actions.pod:2999
20529 msgid "pvresize-size"
20533 #: ../fish/guestfish-actions.pod:3001
20536 " pvresize-size device size\n"
20541 #: ../fish/guestfish-actions.pod:3003
20543 "This command is the same as L</pvresize> except that it allows you to "
20544 "specify the new size (in bytes) explicitly."
20548 #: ../fish/guestfish-actions.pod:3006
20553 #: ../fish/guestfish-actions.pod:3008
20561 #: ../fish/guestfish-actions.pod:3016
20562 msgid "See also L</pvs-full>."
20566 #: ../fish/guestfish-actions.pod:3018
20571 #: ../fish/guestfish-actions.pod:3020
20579 #: ../fish/guestfish-actions.pod:3025
20584 #: ../fish/guestfish-actions.pod:3027
20592 #: ../fish/guestfish-actions.pod:3031
20597 #: ../fish/guestfish-actions.pod:3033
20600 " pwrite path content offset\n"
20605 #: ../fish/guestfish-actions.pod:3044
20606 msgid "See also L</pread>, L</pwrite-device>."
20610 #: ../fish/guestfish-actions.pod:3049
20611 msgid "pwrite-device"
20615 #: ../fish/guestfish-actions.pod:3051
20618 " pwrite-device device content offset\n"
20623 #: ../fish/guestfish-actions.pod:3066
20628 #: ../fish/guestfish-actions.pod:3068
20631 " read-file path\n"
20636 #: ../fish/guestfish-actions.pod:3073
20638 "Unlike L</cat>, this function can correctly handle files that contain "
20639 "embedded ASCII NUL characters. However unlike L</download>, this function "
20640 "is limited in the total size of file that can be handled."
20644 #: ../fish/guestfish-actions.pod:3081
20649 #: ../fish/guestfish-actions.pod:3083
20652 " read-lines path\n"
20657 #: ../fish/guestfish-actions.pod:3090
20659 "Note that this function cannot correctly handle binary files (specifically, "
20660 "files containing C<\\0> character which is treated as end of line). For "
20661 "those you need to use the L</read-file> function which has a more complex "
20666 #: ../fish/guestfish-actions.pod:3095
20671 #: ../fish/guestfish-actions.pod:3097
20679 #: ../fish/guestfish-actions.pod:3149
20681 "This function is primarily intended for use by programs. To get a simple "
20682 "list of names, use L</ls>. To get a printable directory for human "
20683 "consumption, use L</ll>."
20687 #: ../fish/guestfish-actions.pod:3153
20692 #: ../fish/guestfish-actions.pod:3155
20700 #: ../fish/guestfish-actions.pod:3159
20701 msgid "readlinklist"
20705 #: ../fish/guestfish-actions.pod:3161
20708 " readlinklist path 'names ...'\n"
20713 #: ../fish/guestfish-actions.pod:3185
20718 #: ../fish/guestfish-actions.pod:3187
20726 #: ../fish/guestfish-actions.pod:3192
20727 msgid "removexattr"
20731 #: ../fish/guestfish-actions.pod:3194
20734 " removexattr xattr path\n"
20739 #: ../fish/guestfish-actions.pod:3199
20740 msgid "See also: L</lremovexattr>, L<attr(5)>."
20744 #: ../fish/guestfish-actions.pod:3201
20749 #: ../fish/guestfish-actions.pod:3203
20752 " resize2fs device\n"
20757 #: ../fish/guestfish-actions.pod:3208
20759 "I<Note:> It is sometimes required that you run L</e2fsck-f> on the C<device> "
20760 "before calling this command. For unknown reasons C<resize2fs> sometimes "
20761 "gives an error about this and sometimes not. In any case, it is always safe "
20762 "to call L</e2fsck-f> before calling this function."
20766 #: ../fish/guestfish-actions.pod:3214
20767 msgid "resize2fs-size"
20771 #: ../fish/guestfish-actions.pod:3216
20774 " resize2fs-size device size\n"
20779 #: ../fish/guestfish-actions.pod:3218
20781 "This command is the same as L</resize2fs> except that it allows you to "
20782 "specify the new size (in bytes) explicitly."
20786 #: ../fish/guestfish-actions.pod:3221
20791 #: ../fish/guestfish-actions.pod:3223
20799 #: ../fish/guestfish-actions.pod:3227
20804 #: ../fish/guestfish-actions.pod:3229
20812 #: ../fish/guestfish-actions.pod:3235
20817 #: ../fish/guestfish-actions.pod:3237
20825 #: ../fish/guestfish-actions.pod:3241
20826 msgid "rmmountpoint"
20830 #: ../fish/guestfish-actions.pod:3243
20833 " rmmountpoint exemptpath\n"
20838 #: ../fish/guestfish-actions.pod:3245
20840 "This calls removes a mountpoint that was previously created with L</"
20841 "mkmountpoint>. See L</mkmountpoint> for full details."
20845 #: ../fish/guestfish-actions.pod:3249
20846 msgid "scrub-device"
20850 #: ../fish/guestfish-actions.pod:3251
20853 " scrub-device device\n"
20858 #: ../fish/guestfish-actions.pod:3262
20863 #: ../fish/guestfish-actions.pod:3264
20866 " scrub-file file\n"
20871 #: ../fish/guestfish-actions.pod:3274
20872 msgid "scrub-freespace"
20876 #: ../fish/guestfish-actions.pod:3276
20879 " scrub-freespace dir\n"
20884 #: ../fish/guestfish-actions.pod:3278
20886 "This command creates the directory C<dir> and then fills it with files until "
20887 "the filesystem is full, and scrubs the files as for L</scrub-file>, and "
20888 "deletes them. The intention is to scrub any free space on the partition "
20889 "containing C<dir>."
20893 #: ../fish/guestfish-actions.pod:3287
20898 #: ../fish/guestfish-actions.pod:3289
20903 #: ../fish/guestfish-actions.pod:3291
20906 " set-append append\n"
20911 #: ../fish/guestfish-actions.pod:3302
20912 msgid "set-autosync"
20916 #: ../fish/guestfish-actions.pod:3304
20921 #: ../fish/guestfish-actions.pod:3306
20924 " set-autosync true|false\n"
20929 #: ../fish/guestfish-actions.pod:3308
20931 "If C<autosync> is true, this enables autosync. Libguestfs will make a best "
20932 "effort attempt to run L</umount-all> followed by L</sync> when the handle is "
20933 "closed (also if the program exits without closing handles)."
20937 #: ../fish/guestfish-actions.pod:3316
20942 #: ../fish/guestfish-actions.pod:3318
20947 #: ../fish/guestfish-actions.pod:3320
20950 " set-direct true|false\n"
20955 #: ../fish/guestfish-actions.pod:3326
20957 "One consequence of this is that log messages aren't caught by the library "
20958 "and handled by L</set-log-message-callback>, but go straight to stdout."
20962 #: ../fish/guestfish-actions.pod:3335
20963 msgid "set-e2label"
20967 #: ../fish/guestfish-actions.pod:3337
20970 " set-e2label device label\n"
20975 #: ../fish/guestfish-actions.pod:3343
20977 "You can use either L</tune2fs-l> or L</get-e2label> to return the existing "
20978 "label on a filesystem."
20982 #: ../fish/guestfish-actions.pod:3346
20987 #: ../fish/guestfish-actions.pod:3348
20990 " set-e2uuid device uuid\n"
20995 #: ../fish/guestfish-actions.pod:3355
20997 "You can use either L</tune2fs-l> or L</get-e2uuid> to return the existing "
20998 "UUID of a filesystem."
21002 #: ../fish/guestfish-actions.pod:3358
21003 msgid "set-memsize"
21007 #: ../fish/guestfish-actions.pod:3360
21012 #: ../fish/guestfish-actions.pod:3362
21015 " set-memsize memsize\n"
21020 #: ../fish/guestfish-actions.pod:3364
21022 "This sets the memory size in megabytes allocated to the qemu subprocess. "
21023 "This only has any effect if called before L</launch>."
21027 #: ../fish/guestfish-actions.pod:3375
21028 msgid "set-network"
21032 #: ../fish/guestfish-actions.pod:3377
21037 #: ../fish/guestfish-actions.pod:3379
21040 " set-network true|false\n"
21045 #: ../fish/guestfish-actions.pod:3387
21047 "You must call this before calling L</launch>, otherwise it has no effect."
21051 #: ../fish/guestfish-actions.pod:3390
21056 #: ../fish/guestfish-actions.pod:3392
21061 #: ../fish/guestfish-actions.pod:3394
21064 " set-path searchpath\n"
21069 #: ../fish/guestfish-actions.pod:3403
21074 #: ../fish/guestfish-actions.pod:3405
21079 #: ../fish/guestfish-actions.pod:3407
21087 #: ../fish/guestfish-actions.pod:3427
21088 msgid "set-recovery-proc"
21092 #: ../fish/guestfish-actions.pod:3429
21093 msgid "recovery-proc"
21097 #: ../fish/guestfish-actions.pod:3431
21100 " set-recovery-proc true|false\n"
21105 #: ../fish/guestfish-actions.pod:3433
21107 "If this is called with the parameter C<false> then L</launch> does not "
21108 "create a recovery process. The purpose of the recovery process is to stop "
21109 "runaway qemu processes in the case where the main program aborts abruptly."
21113 #: ../fish/guestfish-actions.pod:3438
21115 "This only has any effect if called before L</launch>, and the default is "
21120 #: ../fish/guestfish-actions.pod:3447
21121 msgid "set-selinux"
21125 #: ../fish/guestfish-actions.pod:3449
21130 #: ../fish/guestfish-actions.pod:3451
21133 " set-selinux true|false\n"
21138 #: ../fish/guestfish-actions.pod:3462
21143 #: ../fish/guestfish-actions.pod:3464
21148 #: ../fish/guestfish-actions.pod:3466
21151 " set-trace true|false\n"
21156 #: ../fish/guestfish-actions.pod:3482
21157 msgid "set-verbose"
21161 #: ../fish/guestfish-actions.pod:3484
21166 #: ../fish/guestfish-actions.pod:3486
21169 " set-verbose true|false\n"
21174 #: ../fish/guestfish-actions.pod:3493
21179 #: ../fish/guestfish-actions.pod:3495
21182 " setcon context\n"
21187 #: ../fish/guestfish-actions.pod:3502
21192 #: ../fish/guestfish-actions.pod:3504
21195 " setxattr xattr val vallen path\n"
21200 #: ../fish/guestfish-actions.pod:3510
21201 msgid "See also: L</lsetxattr>, L<attr(5)>."
21205 #: ../fish/guestfish-actions.pod:3512
21210 #: ../fish/guestfish-actions.pod:3514
21213 " sfdisk device cyls heads sectors 'lines ...'\n"
21218 #: ../fish/guestfish-actions.pod:3536
21219 msgid "See also: L</sfdisk-l>, L</sfdisk-N>, L</part-init>"
21223 #: ../fish/guestfish-actions.pod:3542
21228 #: ../fish/guestfish-actions.pod:3544
21231 " sfdiskM device 'lines ...'\n"
21236 #: ../fish/guestfish-actions.pod:3546
21238 "This is a simplified interface to the L</sfdisk> command, where partition "
21239 "sizes are specified in megabytes only (rounded to the nearest cylinder) and "
21240 "you don't need to specify the cyls, heads and sectors parameters which were "
21241 "rarely if ever used anyway."
21245 #: ../fish/guestfish-actions.pod:3552
21246 msgid "See also: L</sfdisk>, the L<sfdisk(8)> manpage and L</part-disk>"
21250 #: ../fish/guestfish-actions.pod:3558
21255 #: ../fish/guestfish-actions.pod:3560
21258 " sfdisk-N device partnum cyls heads sectors line\n"
21263 #: ../fish/guestfish-actions.pod:3565
21265 "For other parameters, see L</sfdisk>. You should usually pass C<0> for the "
21266 "cyls/heads/sectors parameters."
21270 #: ../fish/guestfish-actions.pod:3568
21271 msgid "See also: L</part-add>"
21275 #: ../fish/guestfish-actions.pod:3573
21276 msgid "sfdisk-disk-geometry"
21280 #: ../fish/guestfish-actions.pod:3575
21283 " sfdisk-disk-geometry device\n"
21288 #: ../fish/guestfish-actions.pod:3577
21290 "This displays the disk geometry of C<device> read from the partition table. "
21291 "Especially in the case where the underlying block device has been resized, "
21292 "this can be different from the kernel's idea of the geometry (see L</sfdisk-"
21293 "kernel-geometry>)."
21297 #: ../fish/guestfish-actions.pod:3585
21298 msgid "sfdisk-kernel-geometry"
21302 #: ../fish/guestfish-actions.pod:3587
21305 " sfdisk-kernel-geometry device\n"
21310 #: ../fish/guestfish-actions.pod:3594
21315 #: ../fish/guestfish-actions.pod:3596
21318 " sfdisk-l device\n"
21323 #: ../fish/guestfish-actions.pod:3602
21324 msgid "See also: L</part-list>"
21328 #: ../fish/guestfish-actions.pod:3604
21333 #: ../fish/guestfish-actions.pod:3606
21341 #: ../fish/guestfish-actions.pod:3611
21342 msgid "This is like L</command>, but passes the command to:"
21346 #: ../fish/guestfish-actions.pod:3619
21347 msgid "All the provisos about L</command> apply to this call."
21351 #: ../fish/guestfish-actions.pod:3621
21356 #: ../fish/guestfish-actions.pod:3623
21359 " sh-lines command\n"
21364 #: ../fish/guestfish-actions.pod:3625
21365 msgid "This is the same as L</sh>, but splits the result into a list of lines."
21369 #: ../fish/guestfish-actions.pod:3628
21370 msgid "See also: L</command-lines>"
21374 #: ../fish/guestfish-actions.pod:3630
21379 #: ../fish/guestfish-actions.pod:3632
21387 #: ../fish/guestfish-actions.pod:3636
21392 #: ../fish/guestfish-actions.pod:3638
21400 #: ../fish/guestfish-actions.pod:3644
21405 #: ../fish/guestfish-actions.pod:3646
21413 #: ../fish/guestfish-actions.pod:3654
21418 #: ../fish/guestfish-actions.pod:3656
21426 #: ../fish/guestfish-actions.pod:3664
21431 #: ../fish/guestfish-actions.pod:3666
21434 " strings-e encoding path\n"
21439 #: ../fish/guestfish-actions.pod:3668
21441 "This is like the L</strings> command, but allows you to specify the encoding "
21442 "of strings that are looked for in the source file C<path>."
21446 #: ../fish/guestfish-actions.pod:3678
21448 "Single 7-bit-byte characters like ASCII and the ASCII-compatible parts of "
21449 "ISO-8859-X (this is what L</strings> uses)."
21453 #: ../fish/guestfish-actions.pod:3710
21454 msgid "swapoff-device"
21458 #: ../fish/guestfish-actions.pod:3712
21461 " swapoff-device device\n"
21466 #: ../fish/guestfish-actions.pod:3714
21468 "This command disables the libguestfs appliance swap device or partition "
21469 "named C<device>. See L</swapon-device>."
21473 #: ../fish/guestfish-actions.pod:3718
21474 msgid "swapoff-file"
21478 #: ../fish/guestfish-actions.pod:3720
21481 " swapoff-file file\n"
21486 #: ../fish/guestfish-actions.pod:3724
21487 msgid "swapoff-label"
21491 #: ../fish/guestfish-actions.pod:3726
21494 " swapoff-label label\n"
21499 #: ../fish/guestfish-actions.pod:3731
21500 msgid "swapoff-uuid"
21504 #: ../fish/guestfish-actions.pod:3733
21507 " swapoff-uuid uuid\n"
21512 #: ../fish/guestfish-actions.pod:3738
21513 msgid "swapon-device"
21517 #: ../fish/guestfish-actions.pod:3740
21520 " swapon-device device\n"
21525 #: ../fish/guestfish-actions.pod:3742
21527 "This command enables the libguestfs appliance to use the swap device or "
21528 "partition named C<device>. The increased memory is made available for all "
21529 "commands, for example those run using L</command> or L</sh>."
21533 #: ../fish/guestfish-actions.pod:3754
21534 msgid "swapon-file"
21538 #: ../fish/guestfish-actions.pod:3756
21541 " swapon-file file\n"
21546 #: ../fish/guestfish-actions.pod:3758
21548 "This command enables swap to a file. See L</swapon-device> for other notes."
21552 #: ../fish/guestfish-actions.pod:3761
21553 msgid "swapon-label"
21557 #: ../fish/guestfish-actions.pod:3763
21560 " swapon-label label\n"
21565 #: ../fish/guestfish-actions.pod:3765
21567 "This command enables swap to a labeled swap partition. See L</swapon-"
21568 "device> for other notes."
21572 #: ../fish/guestfish-actions.pod:3768
21573 msgid "swapon-uuid"
21577 #: ../fish/guestfish-actions.pod:3770
21580 " swapon-uuid uuid\n"
21585 #: ../fish/guestfish-actions.pod:3772
21587 "This command enables swap to a swap partition with the given UUID. See L</"
21588 "swapon-device> for other notes."
21592 #: ../fish/guestfish-actions.pod:3775
21597 #: ../fish/guestfish-actions.pod:3777
21605 #: ../fish/guestfish-actions.pod:3785
21610 #: ../fish/guestfish-actions.pod:3787
21618 #: ../fish/guestfish-actions.pod:3795
21623 #: ../fish/guestfish-actions.pod:3797
21626 " tail-n nrlines path\n"
21631 #: ../fish/guestfish-actions.pod:3810
21636 #: ../fish/guestfish-actions.pod:3812
21639 " tar-in (tarfile|-) directory\n"
21644 #: ../fish/guestfish-actions.pod:3817
21645 msgid "To upload a compressed tarball, use L</tgz-in> or L</txz-in>."
21649 #: ../fish/guestfish-actions.pod:3822
21654 #: ../fish/guestfish-actions.pod:3824
21657 " tar-out directory (tarfile|-)\n"
21662 #: ../fish/guestfish-actions.pod:3829
21663 msgid "To download a compressed tarball, use L</tgz-out> or L</txz-out>."
21667 #: ../fish/guestfish-actions.pod:3834
21672 #: ../fish/guestfish-actions.pod:3836
21675 " tgz-in (tarball|-) directory\n"
21680 #: ../fish/guestfish-actions.pod:3841
21681 msgid "To upload an uncompressed tarball, use L</tar-in>."
21685 #: ../fish/guestfish-actions.pod:3845
21690 #: ../fish/guestfish-actions.pod:3847
21693 " tgz-out directory (tarball|-)\n"
21698 #: ../fish/guestfish-actions.pod:3852
21699 msgid "To download an uncompressed tarball, use L</tar-out>."
21703 #: ../fish/guestfish-actions.pod:3856
21708 #: ../fish/guestfish-actions.pod:3858
21716 #: ../fish/guestfish-actions.pod:3867
21721 #: ../fish/guestfish-actions.pod:3869
21729 #: ../fish/guestfish-actions.pod:3874
21730 msgid "truncate-size"
21734 #: ../fish/guestfish-actions.pod:3876
21737 " truncate-size path size\n"
21742 #: ../fish/guestfish-actions.pod:3881
21744 "If the current file size is less than C<size> then the file is extended to "
21745 "the required size with zero bytes. This creates a sparse file (ie. disk "
21746 "blocks are not allocated for the file until you write to it). To create a "
21747 "non-sparse file of zeroes, use L</fallocate64> instead."
21751 #: ../fish/guestfish-actions.pod:3887
21756 #: ../fish/guestfish-actions.pod:3889
21759 " tune2fs-l device\n"
21764 #: ../fish/guestfish-actions.pod:3899
21769 #: ../fish/guestfish-actions.pod:3901
21772 " txz-in (tarball|-) directory\n"
21777 #: ../fish/guestfish-actions.pod:3908
21782 #: ../fish/guestfish-actions.pod:3910
21785 " txz-out directory (tarball|-)\n"
21790 #: ../fish/guestfish-actions.pod:3917
21795 #: ../fish/guestfish-actions.pod:3919
21803 #: ../fish/guestfish-actions.pod:3933
21804 msgid "See also L</get-umask>, L<umask(2)>, L</mknod>, L</mkdir>."
21808 #: ../fish/guestfish-actions.pod:3938
21813 #: ../fish/guestfish-actions.pod:3940
21818 #: ../fish/guestfish-actions.pod:3942
21821 " umount pathordevice\n"
21826 #: ../fish/guestfish-actions.pod:3948
21831 #: ../fish/guestfish-actions.pod:3950
21832 msgid "unmount-all"
21836 #: ../fish/guestfish-actions.pod:3952
21844 #: ../fish/guestfish-actions.pod:3958
21849 #: ../fish/guestfish-actions.pod:3960
21852 " upload (filename|-) remotefilename\n"
21857 #: ../fish/guestfish-actions.pod:3967
21858 msgid "See also L</download>."
21862 #: ../fish/guestfish-actions.pod:3971
21863 msgid "upload-offset"
21867 #: ../fish/guestfish-actions.pod:3973
21870 " upload-offset (filename|-) remotefilename offset\n"
21875 #: ../fish/guestfish-actions.pod:3985
21877 "Note that there is no limit on the amount of data that can be uploaded with "
21878 "this call, unlike with L</pwrite>, and this call always writes the full "
21879 "amount unless an error occurs."
21883 #: ../fish/guestfish-actions.pod:3990
21884 msgid "See also L</upload>, L</pwrite>."
21888 #: ../fish/guestfish-actions.pod:3994
21893 #: ../fish/guestfish-actions.pod:3996
21896 " utimens path atsecs atnsecs mtsecs mtnsecs\n"
21901 #: ../fish/guestfish-actions.pod:4015
21906 #: ../fish/guestfish-actions.pod:4017
21914 #: ../fish/guestfish-actions.pod:4044
21916 "I<Note:> Don't use this call to test for availability of features. In "
21917 "enterprise distributions we backport features from later versions into "
21918 "earlier versions, making this an unreliable way to test for features. Use "
21919 "L</available> instead."
21923 #: ../fish/guestfish-actions.pod:4050
21928 #: ../fish/guestfish-actions.pod:4052
21931 " vfs-label device\n"
21936 #: ../fish/guestfish-actions.pod:4059
21937 msgid "To find a filesystem from the label, use L</findfs-label>."
21941 #: ../fish/guestfish-actions.pod:4061
21946 #: ../fish/guestfish-actions.pod:4063
21949 " vfs-type device\n"
21954 #: ../fish/guestfish-actions.pod:4073
21959 #: ../fish/guestfish-actions.pod:4075
21962 " vfs-uuid device\n"
21967 #: ../fish/guestfish-actions.pod:4082
21968 msgid "To find a filesystem from the UUID, use L</findfs-uuid>."
21972 #: ../fish/guestfish-actions.pod:4084
21973 msgid "vg-activate"
21977 #: ../fish/guestfish-actions.pod:4086
21980 " vg-activate true|false 'volgroups ...'\n"
21985 #: ../fish/guestfish-actions.pod:4099
21986 msgid "vg-activate-all"
21990 #: ../fish/guestfish-actions.pod:4101
21993 " vg-activate-all true|false\n"
21998 #: ../fish/guestfish-actions.pod:4111
22003 #: ../fish/guestfish-actions.pod:4113
22006 " vgcreate volgroup 'physvols ...'\n"
22011 #: ../fish/guestfish-actions.pod:4118
22016 #: ../fish/guestfish-actions.pod:4120
22019 " vglvuuids vgname\n"
22024 #: ../fish/guestfish-actions.pod:4125
22026 "You can use this along with L</lvs> and L</lvuuid> calls to associate "
22027 "logical volumes and volume groups."
22031 #: ../fish/guestfish-actions.pod:4128
22032 msgid "See also L</vgpvuuids>."
22036 #: ../fish/guestfish-actions.pod:4130
22041 #: ../fish/guestfish-actions.pod:4132
22044 " vgpvuuids vgname\n"
22049 #: ../fish/guestfish-actions.pod:4137
22051 "You can use this along with L</pvs> and L</pvuuid> calls to associate "
22052 "physical volumes and volume groups."
22056 #: ../fish/guestfish-actions.pod:4140
22057 msgid "See also L</vglvuuids>."
22061 #: ../fish/guestfish-actions.pod:4142
22066 #: ../fish/guestfish-actions.pod:4144
22069 " vgremove vgname\n"
22074 #: ../fish/guestfish-actions.pod:4151
22079 #: ../fish/guestfish-actions.pod:4153
22082 " vgrename volgroup newvolgroup\n"
22087 #: ../fish/guestfish-actions.pod:4157
22092 #: ../fish/guestfish-actions.pod:4159
22100 #: ../fish/guestfish-actions.pod:4167
22101 msgid "See also L</vgs-full>."
22105 #: ../fish/guestfish-actions.pod:4169
22110 #: ../fish/guestfish-actions.pod:4171
22118 #: ../fish/guestfish-actions.pod:4176
22123 #: ../fish/guestfish-actions.pod:4178
22131 #: ../fish/guestfish-actions.pod:4183
22136 #: ../fish/guestfish-actions.pod:4185
22144 #: ../fish/guestfish-actions.pod:4189
22149 #: ../fish/guestfish-actions.pod:4191
22157 #: ../fish/guestfish-actions.pod:4196
22162 #: ../fish/guestfish-actions.pod:4198
22170 #: ../fish/guestfish-actions.pod:4203
22175 #: ../fish/guestfish-actions.pod:4205
22183 #: ../fish/guestfish-actions.pod:4210
22188 #: ../fish/guestfish-actions.pod:4212
22191 " write path content\n"
22196 #: ../fish/guestfish-actions.pod:4220
22201 #: ../fish/guestfish-actions.pod:4222
22204 " write-file path content size\n"
22209 #: ../fish/guestfish-actions.pod:4245
22214 #: ../fish/guestfish-actions.pod:4247
22217 " zegrep regex path\n"
22222 #: ../fish/guestfish-actions.pod:4255
22227 #: ../fish/guestfish-actions.pod:4257
22230 " zegrepi regex path\n"
22235 #: ../fish/guestfish-actions.pod:4265
22240 #: ../fish/guestfish-actions.pod:4267
22248 #: ../fish/guestfish-actions.pod:4275
22249 msgid "See also: L</zero-device>, L</scrub-device>."
22253 #: ../fish/guestfish-actions.pod:4277
22254 msgid "zero-device"
22258 #: ../fish/guestfish-actions.pod:4279
22261 " zero-device device\n"
22266 #: ../fish/guestfish-actions.pod:4281
22268 "This command writes zeroes over the entire C<device>. Compare with L</zero> "
22269 "which just zeroes the first few blocks of a device."
22273 #: ../fish/guestfish-actions.pod:4288
22278 #: ../fish/guestfish-actions.pod:4290
22281 " zerofree device\n"
22286 #: ../fish/guestfish-actions.pod:4303
22291 #: ../fish/guestfish-actions.pod:4305
22294 " zfgrep pattern path\n"
22299 #: ../fish/guestfish-actions.pod:4313
22304 #: ../fish/guestfish-actions.pod:4315
22307 " zfgrepi pattern path\n"
22312 #: ../fish/guestfish-actions.pod:4323
22317 #: ../fish/guestfish-actions.pod:4325
22320 " zfile meth path\n"
22325 #: ../fish/guestfish-actions.pod:4332
22327 "Since 1.0.63, use L</file> instead which can now process compressed files."
22331 #: ../fish/guestfish-actions.pod:4342
22336 #: ../fish/guestfish-actions.pod:4344
22339 " zgrep regex path\n"
22344 #: ../fish/guestfish-actions.pod:4352
22349 #: ../fish/guestfish-actions.pod:4354
22352 " zgrepi regex path\n"
22357 #: ../fish/guestfish-commands.pod:1
22362 #: ../fish/guestfish-commands.pod:3
22367 #: ../fish/guestfish-commands.pod:5
22370 " alloc filename size\n"
22375 #: ../fish/guestfish-commands.pod:7
22377 "This creates an empty (zeroed) file of the given size, and then adds so it "
22378 "can be further examined."
22382 #: ../fish/guestfish-commands.pod:10 ../fish/guestfish-commands.pod:168
22383 msgid "For more advanced image creation, see L<qemu-img(1)> utility."
22387 #: ../fish/guestfish-commands.pod:12 ../fish/guestfish-commands.pod:170
22388 msgid "Size can be specified using standard suffixes, eg. C<1M>."
22392 #: ../fish/guestfish-commands.pod:14
22394 "To create a sparse file, use L</sparse> instead. To create a prepared disk "
22395 "image, see L</PREPARED DISK IMAGES>."
22399 #: ../fish/guestfish-commands.pod:17
22404 #: ../fish/guestfish-commands.pod:19
22407 " copy-in local [local ...] /remotedir\n"
22412 #: ../fish/guestfish-commands.pod:21
22414 "C<copy-in> copies local files or directories recursively into the disk "
22415 "image, placing them in the directory called C</remotedir> (which must "
22416 "exist). This guestfish meta-command turns into a sequence of L</tar-in> and "
22417 "other commands as necessary."
22421 #: ../fish/guestfish-commands.pod:26
22423 "Multiple local files and directories can be specified, but the last "
22424 "parameter must always be a remote directory. Wildcards cannot be used."
22428 #: ../fish/guestfish-commands.pod:30
22433 #: ../fish/guestfish-commands.pod:32
22436 " copy-out remote [remote ...] localdir\n"
22441 #: ../fish/guestfish-commands.pod:34
22443 "C<copy-out> copies remote files or directories recursively out of the disk "
22444 "image, placing them on the host disk in a local directory called C<localdir> "
22445 "(which must exist). This guestfish meta-command turns into a sequence of L</"
22446 "download>, L</tar-out> and other commands as necessary."
22450 #: ../fish/guestfish-commands.pod:40
22452 "Multiple remote files and directories can be specified, but the last "
22453 "parameter must always be a local directory. To download to the current "
22454 "directory, use C<.> as in:"
22458 #: ../fish/guestfish-commands.pod:44
22461 " copy-out /home .\n"
22466 #: ../fish/guestfish-commands.pod:46
22468 "Wildcards cannot be used in the ordinary command, but you can use them with "
22469 "the help of L</glob> like this:"
22473 #: ../fish/guestfish-commands.pod:49
22476 " glob copy-out /home/* .\n"
22481 #: ../fish/guestfish-commands.pod:51
22486 #: ../fish/guestfish-commands.pod:53
22489 " echo [params ...]\n"
22494 #: ../fish/guestfish-commands.pod:55
22495 msgid "This echos the parameters to the terminal."
22499 #: ../fish/guestfish-commands.pod:57
22504 #: ../fish/guestfish-commands.pod:59
22509 #: ../fish/guestfish-commands.pod:61
22514 #: ../fish/guestfish-commands.pod:63
22522 #: ../fish/guestfish-commands.pod:65
22524 "This is used to edit a file. It downloads the file, edits it locally using "
22525 "your editor, then uploads the result."
22529 #: ../fish/guestfish-commands.pod:68
22531 "The editor is C<$EDITOR>. However if you use the alternate commands C<vi> "
22532 "or C<emacs> you will get those corresponding editors."
22536 #: ../fish/guestfish-commands.pod:72
22541 #: ../fish/guestfish-commands.pod:74
22544 " glob command args...\n"
22549 #: ../fish/guestfish-commands.pod:76
22551 "Expand wildcards in any paths in the args list, and run C<command> "
22552 "repeatedly on each matching path."
22556 #: ../fish/guestfish-commands.pod:79
22557 msgid "See L</WILDCARDS AND GLOBBING>."
22561 #: ../fish/guestfish-commands.pod:81
22566 #: ../fish/guestfish-commands.pod:83
22569 " hexedit <filename|device>\n"
22570 " hexedit <filename|device> <max>\n"
22571 " hexedit <filename|device> <start> <max>\n"
22576 #: ../fish/guestfish-commands.pod:87
22578 "Use hexedit (a hex editor) to edit all or part of a binary file or block "
22583 #: ../fish/guestfish-commands.pod:90
22585 "This command works by downloading potentially the whole file or device, "
22586 "editing it locally, then uploading it. If the file or device is large, you "
22587 "have to specify which part you wish to edit by using C<max> and/or C<start> "
22588 "C<max> parameters. C<start> and C<max> are specified in bytes, with the "
22589 "usual modifiers allowed such as C<1M> (1 megabyte)."
22593 #: ../fish/guestfish-commands.pod:97
22594 msgid "For example to edit the first few sectors of a disk you might do:"
22598 #: ../fish/guestfish-commands.pod:100
22601 " hexedit /dev/sda 1M\n"
22606 #: ../fish/guestfish-commands.pod:102
22608 "which would allow you to edit anywhere within the first megabyte of the disk."
22612 #: ../fish/guestfish-commands.pod:105
22613 msgid "To edit the superblock of an ext2 filesystem on C</dev/sda1>, do:"
22617 #: ../fish/guestfish-commands.pod:107
22620 " hexedit /dev/sda1 0x400 0x400\n"
22625 #: ../fish/guestfish-commands.pod:109
22626 msgid "(assuming the superblock is in the standard location)."
22630 #: ../fish/guestfish-commands.pod:111
22632 "This command requires the external L<hexedit(1)> program. You can specify "
22633 "another program to use by setting the C<HEXEDITOR> environment variable."
22637 #: ../fish/guestfish-commands.pod:115
22638 msgid "See also L</hexdump>."
22642 #: ../fish/guestfish-commands.pod:117
22647 #: ../fish/guestfish-commands.pod:119
22655 #: ../fish/guestfish-commands.pod:121
22657 "Change the local directory, ie. the current directory of guestfish itself."
22661 #: ../fish/guestfish-commands.pod:124
22662 msgid "Note that C<!cd> won't do what you might expect."
22666 #: ../fish/guestfish-commands.pod:126
22671 #: ../fish/guestfish-commands.pod:128
22676 #: ../fish/guestfish-commands.pod:130
22684 #: ../fish/guestfish-commands.pod:132
22685 msgid "Opens the manual page for guestfish."
22689 #: ../fish/guestfish-commands.pod:134
22694 #: ../fish/guestfish-commands.pod:136
22699 #: ../fish/guestfish-commands.pod:138
22707 #: ../fish/guestfish-commands.pod:140
22715 #: ../fish/guestfish-commands.pod:142
22716 msgid "This is used to view a file."
22720 #: ../fish/guestfish-commands.pod:144
22722 "The default viewer is C<$PAGER>. However if you use the alternate command "
22723 "C<less> you will get the C<less> command specifically."
22727 #: ../fish/guestfish-commands.pod:147
22732 #: ../fish/guestfish-commands.pod:149
22740 #: ../fish/guestfish-commands.pod:151
22742 "Close and reopen the libguestfs handle. It is not necessary to use this "
22743 "normally, because the handle is closed properly when guestfish exits. "
22744 "However this is occasionally useful for testing."
22748 #: ../fish/guestfish-commands.pod:155
22753 #: ../fish/guestfish-commands.pod:157
22756 " sparse filename size\n"
22761 #: ../fish/guestfish-commands.pod:159
22763 "This creates an empty sparse file of the given size, and then adds so it can "
22764 "be further examined."
22768 #: ../fish/guestfish-commands.pod:162
22770 "In all respects it works the same as the L</alloc> command, except that the "
22771 "image file is allocated sparsely, which means that disk blocks are not "
22772 "assigned to the file until they are needed. Sparse disk files only use "
22773 "space when written to, but they are slower and there is a danger you could "
22774 "run out of real disk space during a write operation."
22778 #: ../fish/guestfish-commands.pod:172
22783 #: ../fish/guestfish-commands.pod:174
22791 #: ../fish/guestfish-commands.pod:176
22793 "This command returns a list of the optional groups known to the daemon, and "
22794 "indicates which ones are supported by this build of the libguestfs appliance."
22798 #: ../fish/guestfish-commands.pod:180
22799 msgid "See also L<guestfs(3)/AVAILABILITY>."
22803 #: ../fish/guestfish-commands.pod:182
22808 #: ../fish/guestfish-commands.pod:184
22811 " time command args...\n"
22816 #: ../fish/guestfish-commands.pod:186
22818 "Run the command as usual, but print the elapsed time afterwards. This can "
22819 "be useful for benchmarking operations."
22823 #: ../test-tool/libguestfs-test-tool.pod:5
22824 msgid "libguestfs-test-tool - End user tests for libguestfs"
22828 #: ../test-tool/libguestfs-test-tool.pod:9
22831 " libguestfs-test-tool [--options]\n"
22836 #: ../test-tool/libguestfs-test-tool.pod:13
22838 "libguestfs-test-tool is a test program shipped with libguestfs to end users "
22839 "and developers, to allow them to check basic libguestfs functionality is "
22840 "working. This is needed because libguestfs occasionally breaks for reasons "
22841 "beyond our control: usually because of changes in the underlying qemu or "
22842 "kernel packages, or the host environment."
22846 #: ../test-tool/libguestfs-test-tool.pod:20
22847 msgid "If you suspect a problem in libguestfs, then just run:"
22851 #: ../test-tool/libguestfs-test-tool.pod:22
22854 " libguestfs-test-tool\n"
22859 #: ../test-tool/libguestfs-test-tool.pod:24
22860 msgid "It will print lots of diagnostic messages."
22864 #: ../test-tool/libguestfs-test-tool.pod:26
22865 msgid "If it runs to completion successfully, you will see this near the end:"
22869 #: ../test-tool/libguestfs-test-tool.pod:28
22872 " ===== TEST FINISHED OK =====\n"
22877 #: ../test-tool/libguestfs-test-tool.pod:30
22878 msgid "and the test tool will exit with code 0."
22882 #: ../test-tool/libguestfs-test-tool.pod:32
22884 "If it fails (and/or exits with non-zero error code), please paste the "
22885 "B<complete, unedited> output of the test tool into a bug report. More "
22886 "information about reporting bugs can be found on the L<http://libguestfs.org/"
22891 #: ../test-tool/libguestfs-test-tool.pod:41
22896 #: ../test-tool/libguestfs-test-tool.pod:43
22897 msgid "Display short usage information and exit."
22901 #: ../test-tool/libguestfs-test-tool.pod:45
22902 msgid "I<--helper /path/to/libguestfs-test-tool-helper>"
22906 #: ../test-tool/libguestfs-test-tool.pod:47
22908 "Pass an alternate name for the helper program. libguestfs-test-tool will "
22909 "normally look in the C<$libexec> directory that was configured when the tool "
22914 #: ../test-tool/libguestfs-test-tool.pod:51
22915 msgid "I<--qemu qemu_binary>"
22919 #: ../test-tool/libguestfs-test-tool.pod:53
22921 "If you have downloaded another qemu binary, point this option at the full "
22922 "path of the binary to try it."
22926 #: ../test-tool/libguestfs-test-tool.pod:56
22927 msgid "I<--qemudir qemu_source_dir>"
22931 #: ../test-tool/libguestfs-test-tool.pod:58
22933 "If you have compiled qemu from source, point this option at the source "
22934 "directory to try it."
22938 #: ../test-tool/libguestfs-test-tool.pod:61
22939 msgid "I<--timeout N>"
22943 #: ../test-tool/libguestfs-test-tool.pod:63
22945 "Set the launch timeout to C<N> seconds. The default is 120 seconds which "
22946 "does not usually need to be adjusted unless your machine is very slow."
22950 #: ../test-tool/libguestfs-test-tool.pod:69
22951 msgid "TRYING OUT A DIFFERENT VERSION OF QEMU"
22955 #: ../test-tool/libguestfs-test-tool.pod:71
22957 "If you have compiled another version of qemu from source and would like to "
22958 "try that, then you can use the I<--qemudir> option to point to the qemu "
22959 "source directory."
22963 #: ../test-tool/libguestfs-test-tool.pod:75
22965 "If you have downloaded a qemu binary from somewhere, use the I<--qemu> "
22966 "option to point to the binary."
22970 #: ../test-tool/libguestfs-test-tool.pod:78
22972 "When using an alternate qemu with libguestfs, usually you would need to "
22973 "write a qemu wrapper script (see section I<QEMU WRAPPERS> in L<guestfs(3)"
22974 ">). libguestfs-test-tool writes a temporary qemu wrapper script when you "
22975 "use either of the I<--qemudir> or I<--qemu> options."
22979 #: ../test-tool/libguestfs-test-tool.pod:85
22981 "libguestfs-test-tool returns I<0> if the tests completed without error, or "
22982 "I<1> if there was an error."
22986 #: ../test-tool/libguestfs-test-tool.pod:92
22987 msgid "/usr/libexec/libguestfs-test-tool-helper"
22991 #: ../test-tool/libguestfs-test-tool.pod:94
22993 "This helper program is run inside the appliance and provides additional "
22998 #: ../test-tool/libguestfs-test-tool.pod:97
22999 msgid "/usr/bin/mkisofs"
23003 #: ../test-tool/libguestfs-test-tool.pod:99
23005 "The C<mkisofs> command is required in order to construct a CD-ROM ISO file "
23006 "which is used as part of the tests."
23010 #: ../test-tool/libguestfs-test-tool.pod:106
23012 "For the full list of environment variables which may affect libguestfs, "
23013 "please see the L<guestfs(3)> manual page."
23017 #: ../test-tool/libguestfs-test-tool.pod:111
23018 msgid "L<guestfs(3)>, L<http://libguestfs.org/>, L<http://qemu.org/>."
23022 #: ../test-tool/libguestfs-test-tool.pod:121 ../fuse/guestmount.pod:195
23023 msgid "Copyright (C) 2009 Red Hat Inc. L<http://libguestfs.org/>"
23027 #: ../fuse/guestmount.pod:5
23029 "guestmount - Mount a guest filesystem on the host using FUSE and libguestfs"
23033 #: ../fuse/guestmount.pod:9
23036 " guestmount [--options] -a disk.img -m device [--ro] mountpoint\n"
23041 #: ../fuse/guestmount.pod:13
23043 "You must I<not> use C<guestmount> in read-write mode on live virtual "
23044 "machines. If you do this, you risk disk corruption in the VM."
23048 #: ../fuse/guestmount.pod:18
23050 "The guestmount program can be used to mount virtual machine filesystems and "
23051 "other disk images on the host. It uses libguestfs for access to the guest "
23052 "filesystem, and FUSE (the \"filesystem in userspace\") to make it appear as "
23053 "a mountable device."
23057 #: ../fuse/guestmount.pod:23
23059 "Along with other options, you have to give at least one device (I<-a> "
23060 "option) and at least one mountpoint (I<-m> option). How this works is "
23061 "better explained in the L<guestfish(1)> manual page, or you can use L<virt-"
23062 "inspector(1)> and/or the wrapper script C<guestmount-wrapper> to help you."
23066 #: ../fuse/guestmount.pod:29
23068 "FUSE lets you mount filesystems as non-root. The mountpoint must be owned "
23069 "by you, and the filesystem will not be visible to any other users unless you "
23070 "make certain global configuration changes to C</etc/fuse.conf>. To unmount "
23071 "the filesystem, use the C<fusermount -u> command."
23075 #: ../fuse/guestmount.pod:37
23077 "For a typical Windows guest which has its main filesystem on the first "
23082 #: ../fuse/guestmount.pod:40
23085 " guestmount -a windows.img -m /dev/sda1 --ro /mnt\n"
23090 #: ../fuse/guestmount.pod:42
23092 "For a typical Linux guest which has a /boot filesystem on the first "
23093 "partition, and the root filesystem on a logical volume:"
23097 #: ../fuse/guestmount.pod:45
23100 " guestmount -a linux.img -m /dev/VG/LV -m /dev/sda1:/boot --ro /mnt\n"
23105 #: ../fuse/guestmount.pod:47
23107 "To get L<virt-inspector(1)> to do the hard work of detecting guest "
23108 "mountpoints for you:"
23112 #: ../fuse/guestmount.pod:50
23115 " guestmount $(virt-inspector --ro-fish MyGuest) /mnt\n"
23120 #: ../fuse/guestmount.pod:52
23122 "(or use --fish if you don't want it to be a read only mount). The option is "
23123 "called I<--ro-fish> or I<--fish> because these parameters are compatible "
23124 "with L<guestfish(1)>."
23128 #: ../fuse/guestmount.pod:56
23130 "If you don't know what filesystems are contained in a guest or disk image, "
23131 "use L<virt-list-filesystems(1)> first:"
23135 #: ../fuse/guestmount.pod:59
23138 " virt-list-filesystems MyGuest\n"
23143 #: ../fuse/guestmount.pod:61
23145 "If you want to trace the libguestfs calls but without excessive debugging, "
23150 #: ../fuse/guestmount.pod:64
23153 " guestmount [-a ... -m ...] --trace /mnt\n"
23158 #: ../fuse/guestmount.pod:66
23159 msgid "If you want to debug the program, we recommend:"
23163 #: ../fuse/guestmount.pod:68
23166 " guestmount [-a ... -m ...] --trace --verbose /mnt\n"
23171 #: ../fuse/guestmount.pod:76
23172 msgid "Add a block device or virtual machine image."
23176 #: ../fuse/guestmount.pod:78
23177 msgid "B<--dir-cache-timeout N>"
23181 #: ../fuse/guestmount.pod:80
23183 "Set the readdir cache timeout to I<N> seconds, the default being 60 "
23184 "seconds. The readdir cache [actually, there are several semi-independent "
23185 "caches] is populated after a readdir(2) call with the stat and extended "
23186 "attributes of the files in the directory, in anticipation that they will be "
23187 "requested soon after."
23191 #: ../fuse/guestmount.pod:86
23193 "There is also a different attribute cache implemented by FUSE (see the FUSE "
23194 "option I<-o attr_timeout>), but the FUSE cache does not anticipate future "
23195 "requests, only cache existing ones."
23199 #: ../fuse/guestmount.pod:90
23200 msgid "B<--fuse-help>"
23204 #: ../fuse/guestmount.pod:92
23205 msgid "Display help on special FUSE options (see I<-o> below)."
23209 #: ../fuse/guestmount.pod:96
23210 msgid "Display brief help and exit."
23214 #: ../fuse/guestmount.pod:98
23215 msgid "B<-m dev[:mnt]> | B<--mount dev[:mnt]>"
23219 #: ../fuse/guestmount.pod:100
23221 "Mount the named partition or logical volume on the given mountpoint B<in the "
23222 "guest> (this has nothing to do with mountpoints in the host)."
23226 #: ../fuse/guestmount.pod:103
23228 "If the mountpoint is omitted, it defaults to C</>. You have to mount "
23229 "something on C</>."
23233 #: ../fuse/guestmount.pod:108
23235 "By default, we attempt to sync the guest disk when the FUSE mountpoint is "
23236 "unmounted. If you specify this option, then we don't attempt to sync the "
23237 "disk. See the discussion of autosync in the L<guestfs(3)> manpage."
23241 #: ../fuse/guestmount.pod:113
23242 msgid "B<-o option> | B<--option option>"
23246 #: ../fuse/guestmount.pod:115
23247 msgid "Pass extra options to FUSE."
23251 #: ../fuse/guestmount.pod:117
23253 "To get a list of all the extra options supported by FUSE, use the command "
23254 "below. Note that only the FUSE I<-o> options can be passed, and only some "
23255 "of them are a good idea."
23259 #: ../fuse/guestmount.pod:121
23262 " guestmount --fuse-help\n"
23267 #: ../fuse/guestmount.pod:123
23268 msgid "Some potentially useful FUSE options:"
23272 #: ../fuse/guestmount.pod:127
23273 msgid "B<-o allow_other>"
23277 #: ../fuse/guestmount.pod:129
23278 msgid "Allow other users to see the filesystem."
23282 #: ../fuse/guestmount.pod:131
23283 msgid "B<-o attr_timeout=N>"
23287 #: ../fuse/guestmount.pod:133
23288 msgid "Enable attribute caching by FUSE, and set the timeout to I<N> seconds."
23292 #: ../fuse/guestmount.pod:135
23293 msgid "B<-o kernel_cache>"
23297 #: ../fuse/guestmount.pod:137
23299 "Allow the kernel to cache files (reduces the number of reads that have to go "
23300 "through the L<guestfs(3)> API). This is generally a good idea if you can "
23301 "afford the extra memory usage."
23305 #: ../fuse/guestmount.pod:141
23306 msgid "B<-o uid=N> B<-o gid=N>"
23310 #: ../fuse/guestmount.pod:143
23312 "Use these options to map all UIDs and GIDs inside the guest filesystem to "
23313 "the chosen values."
23317 #: ../fuse/guestmount.pod:150
23319 "Add devices and mount everything read-only. Also disallow writes and make "
23320 "the disk appear read-only to FUSE."
23324 #: ../fuse/guestmount.pod:153
23326 "This is highly recommended if you are not going to edit the guest disk. If "
23327 "the guest is running and this option is I<not> supplied, then there is a "
23328 "strong risk of disk corruption in the guest. We try to prevent this from "
23329 "happening, but it is not always possible."
23333 #: ../fuse/guestmount.pod:160
23334 msgid "Enable SELinux support for the guest."
23338 #: ../fuse/guestmount.pod:162
23343 #: ../fuse/guestmount.pod:164
23344 msgid "Trace libguestfs calls (to stderr)."
23348 #: ../fuse/guestmount.pod:166
23349 msgid "This also stops the daemon from forking into the background."
23353 #: ../fuse/guestmount.pod:170
23354 msgid "Enable verbose messages from underlying libguestfs."
23358 #: ../fuse/guestmount.pod:174
23359 msgid "Display the program version and exit."
23363 #: ../fuse/guestmount.pod:180
23365 "L<guestfish(1)>, L<virt-inspector(1)>, L<virt-cat(1)>, L<virt-edit(1)>, "
23366 "L<virt-tar(1)>, L<guestfs(3)>, L<http://libguestfs.org/>, L<http://fuse.sf."
23371 #: ../inspector/virt-inspector.pl:40
23373 "virt-inspector - Display OS version, kernel, drivers, mount points, "
23374 "applications, etc. in a virtual machine"
23378 #: ../inspector/virt-inspector.pl:44
23381 " virt-inspector [--connect URI] domname\n"
23386 #: ../inspector/virt-inspector.pl:46
23389 " virt-inspector guest.img [guest.img ...]\n"
23394 #: ../inspector/virt-inspector.pl:50
23396 "B<virt-inspector> examines a virtual machine and tries to determine the "
23397 "version of the OS, the kernel version, what drivers are installed, whether "
23398 "the virtual machine is fully virtualized (FV) or para-virtualized (PV), what "
23399 "applications are installed and more."
23403 #: ../inspector/virt-inspector.pl:55
23405 "Virt-inspector can produce output in several formats, including a readable "
23406 "text report, and XML for feeding into other programs."
23410 #: ../inspector/virt-inspector.pl:58
23412 "In the normal usage, use C<virt-inspector domname> where C<domname> is the "
23413 "libvirt domain (see: C<virsh list --all>)."
23417 #: ../inspector/virt-inspector.pl:61
23419 "You can also run virt-inspector directly on disk images from a single "
23420 "virtual machine. Use C<virt-inspector guest.img>. In rare cases a domain "
23421 "has several block devices, in which case you should list them one after "
23422 "another, with the first corresponding to the guest's C</dev/sda>, the second "
23423 "to the guest's C</dev/sdb> and so on."
23427 #: ../inspector/virt-inspector.pl:67
23429 "Virt-inspector can only inspect and report upon I<one domain at a time>. To "
23430 "inspect several virtual machines, you have to run virt-inspector several "
23431 "times (for example, from a shell script for-loop)."
23435 #: ../inspector/virt-inspector.pl:72
23437 "Because virt-inspector needs direct access to guest images, it won't "
23438 "normally work over remote libvirt connections."
23442 #: ../inspector/virt-inspector.pl:85 ../tools/virt-edit.pl:83
23443 #: ../tools/virt-win-reg.pl:182 ../tools/virt-df.pl:81 ../tools/virt-ls.pl:89
23444 #: ../tools/virt-list-filesystems.pl:60 ../tools/virt-cat.pl:90
23445 #: ../tools/virt-tar.pl:109 ../tools/virt-rescue.pl:113
23446 #: ../tools/virt-make-fs.pl:163 ../tools/virt-list-partitions.pl:61
23447 msgid "Display brief help."
23451 #: ../inspector/virt-inspector.pl:91 ../tools/virt-edit.pl:89
23452 #: ../tools/virt-win-reg.pl:188 ../tools/virt-df.pl:87 ../tools/virt-ls.pl:95
23453 #: ../tools/virt-resize.pl:249 ../tools/virt-list-filesystems.pl:66
23454 #: ../tools/virt-cat.pl:96 ../tools/virt-tar.pl:115
23455 #: ../tools/virt-rescue.pl:119 ../tools/virt-make-fs.pl:169
23456 #: ../tools/virt-list-partitions.pl:67
23457 msgid "B<--version>"
23461 #: ../inspector/virt-inspector.pl:93 ../tools/virt-edit.pl:91
23462 #: ../tools/virt-win-reg.pl:190 ../tools/virt-df.pl:89 ../tools/virt-ls.pl:97
23463 #: ../tools/virt-resize.pl:251 ../tools/virt-list-filesystems.pl:68
23464 #: ../tools/virt-cat.pl:98 ../tools/virt-tar.pl:117
23465 #: ../tools/virt-rescue.pl:121 ../tools/virt-make-fs.pl:171
23466 #: ../tools/virt-list-partitions.pl:69
23467 msgid "Display version number and exit."
23471 #: ../inspector/virt-inspector.pl:99 ../tools/virt-edit.pl:113
23472 #: ../tools/virt-win-reg.pl:204 ../tools/virt-df.pl:95 ../tools/virt-ls.pl:103
23473 #: ../tools/virt-list-filesystems.pl:74 ../tools/virt-cat.pl:104
23474 #: ../tools/virt-tar.pl:123 ../tools/virt-rescue.pl:135
23475 #: ../tools/virt-list-partitions.pl:75
23476 msgid "B<--connect URI> | B<-c URI>"
23480 #: ../inspector/virt-inspector.pl:101 ../tools/virt-edit.pl:115
23481 #: ../tools/virt-win-reg.pl:206 ../tools/virt-df.pl:97 ../tools/virt-ls.pl:105
23482 #: ../tools/virt-list-filesystems.pl:76 ../tools/virt-cat.pl:106
23483 #: ../tools/virt-tar.pl:125 ../tools/virt-rescue.pl:137
23484 #: ../tools/virt-list-partitions.pl:77
23486 "If using libvirt, connect to the given I<URI>. If omitted, then we connect "
23487 "to the default libvirt hypervisor."
23491 #: ../inspector/virt-inspector.pl:104
23493 "Libvirt is only used if you specify a C<domname> on the command line. If "
23494 "you specify guest block devices directly, then libvirt is not used at all."
23498 #: ../inspector/virt-inspector.pl:114
23500 "The following options select the output format. Use only one of them. The "
23501 "default is a readable text report."
23505 #: ../inspector/virt-inspector.pl:119
23506 msgid "B<--text> (default)"
23510 #: ../inspector/virt-inspector.pl:121
23511 msgid "Plain text report."
23515 #: ../inspector/virt-inspector.pl:123
23520 #: ../inspector/virt-inspector.pl:125
23521 msgid "Produce no output at all."
23525 #: ../inspector/virt-inspector.pl:127
23530 #: ../inspector/virt-inspector.pl:129
23532 "If you select I<--xml> then you get XML output which can be fed to other "
23537 #: ../inspector/virt-inspector.pl:132
23542 #: ../inspector/virt-inspector.pl:134
23544 "If you select I<--yaml> then you get YAML output which can be fed to other "
23549 #: ../inspector/virt-inspector.pl:137
23554 #: ../inspector/virt-inspector.pl:139
23556 "If you select I<--perl> then you get Perl structures output which can be "
23557 "used directly in another Perl program."
23561 #: ../inspector/virt-inspector.pl:142
23566 #: ../inspector/virt-inspector.pl:144
23567 msgid "B<--ro-fish>"
23571 #: ../inspector/virt-inspector.pl:146
23573 "If you select I<--fish> then we print a L<guestfish(1)> command line which "
23574 "will automatically mount up the filesystems on the correct mount points. "
23575 "Try this for example:"
23579 #: ../inspector/virt-inspector.pl:150
23582 " guestfish $(virt-inspector --fish guest.img)\n"
23587 #: ../inspector/virt-inspector.pl:152
23589 "I<--ro-fish> is the same, but the I<--ro> option is passed to guestfish so "
23590 "that the filesystems are mounted read-only."
23594 #: ../inspector/virt-inspector.pl:155
23599 #: ../inspector/virt-inspector.pl:157
23601 "In \"query mode\" we answer common questions about the guest, such as "
23602 "whether it is fullvirt or needs a Xen hypervisor to run."
23606 #: ../inspector/virt-inspector.pl:160
23607 msgid "See section I<QUERY MODE> below."
23611 #: ../inspector/virt-inspector.pl:166
23612 msgid "B<--windows-registry>"
23616 #: ../inspector/virt-inspector.pl:168
23618 "This flag is ignored for compatibility with earlier releases of the software."
23622 #: ../inspector/virt-inspector.pl:171
23624 "In this version, if L<Win::Hivex(3)> is available, then we attempt to parse "
23625 "information out of the Registry for any Windows guest."
23629 #: ../inspector/virt-inspector.pl:218
23630 msgid "OUTPUT FORMAT"
23634 #: ../inspector/virt-inspector.pl:220
23637 " Operating system(s)\n"
23638 " -------------------\n"
23639 " Linux (distro + version)\n"
23640 " Windows (version)\n"
23643 " +--- Filesystems ---------- Installed apps --- Kernel & drivers\n"
23644 " ----------- -------------- ----------------\n"
23645 " mount point => device List of apps Extra information\n"
23646 " mount point => device and versions about kernel(s)\n"
23647 " ... and drivers\n"
23648 " swap => swap device\n"
23649 " (plus lots of extra information\n"
23650 " about each filesystem)\n"
23655 #: ../inspector/virt-inspector.pl:235
23656 msgid "The output of virt-inspector is a complex two-level data structure."
23660 #: ../inspector/virt-inspector.pl:237
23662 "At the top level is a list of the operating systems installed on the guest. "
23663 "(For the vast majority of guests, only a single OS is installed.) The data "
23664 "returned for the OS includes the name (Linux, Windows), the distribution and "
23669 #: ../inspector/virt-inspector.pl:242
23670 msgid "The diagram above shows what we return for each OS."
23674 #: ../inspector/virt-inspector.pl:244
23676 "With the I<--xml> option the output is mapped into an XML document. There "
23677 "is a RELAX-NG schema for this XML in the file I<virt-inspector.rng> which "
23678 "normally ships with virt-inspector, or can be found in the source."
23682 #: ../inspector/virt-inspector.pl:249
23684 "With the I<--fish> or I<--ro-fish> option the mount points are mapped to "
23685 "L<guestfish(1)> command line parameters, so that you can go in afterwards "
23686 "and inspect the guest with everything mounted in the right place. For "
23691 #: ../inspector/virt-inspector.pl:254
23694 " guestfish $(virt-inspector --ro-fish guest.img)\n"
23695 " ==> guestfish --ro -a guest.img -m /dev/VG/LV:/ -m /dev/sda1:/boot\n"
23700 #: ../inspector/virt-inspector.pl:589
23705 #: ../inspector/virt-inspector.pl:591
23707 "When you use C<virt-inspector --query>, the output is a series of lines of "
23712 #: ../inspector/virt-inspector.pl:594
23718 " xen_pv_drivers=no\n"
23723 #: ../inspector/virt-inspector.pl:599
23725 "(each answer is usually C<yes> or C<no>, or the line is completely missing "
23726 "if we could not determine the answer at all)."
23730 #: ../inspector/virt-inspector.pl:602
23732 "If the guest is multiboot, you can get apparently conflicting answers (eg. "
23733 "C<windows=yes> and C<linux=yes>, or a guest which is both fullvirt and has a "
23734 "Xen PV kernel). This is normal, and just means that the guest can do both "
23735 "things, although it might require operator intervention such as selecting a "
23736 "boot option when the guest is booting."
23740 #: ../inspector/virt-inspector.pl:609
23741 msgid "This section describes the full range of answers possible."
23745 #: ../inspector/virt-inspector.pl:630
23746 msgid "windows=(yes|no)"
23750 #: ../inspector/virt-inspector.pl:632
23751 msgid "Answer C<yes> if Microsoft Windows is installed in the guest."
23755 #: ../inspector/virt-inspector.pl:645
23756 msgid "linux=(yes|no)"
23760 #: ../inspector/virt-inspector.pl:647
23761 msgid "Answer C<yes> if a Linux kernel is installed in the guest."
23765 #: ../inspector/virt-inspector.pl:660
23766 msgid "rhel=(yes|no)"
23770 #: ../inspector/virt-inspector.pl:662
23771 msgid "Answer C<yes> if the guest contains Red Hat Enterprise Linux."
23775 #: ../inspector/virt-inspector.pl:676
23776 msgid "fedora=(yes|no)"
23780 #: ../inspector/virt-inspector.pl:678
23781 msgid "Answer C<yes> if the guest contains the Fedora Linux distribution."
23785 #: ../inspector/virt-inspector.pl:691
23786 msgid "debian=(yes|no)"
23790 #: ../inspector/virt-inspector.pl:693
23791 msgid "Answer C<yes> if the guest contains the Debian Linux distribution."
23795 #: ../inspector/virt-inspector.pl:706
23796 msgid "fullvirt=(yes|no)"
23800 #: ../inspector/virt-inspector.pl:708
23802 "Answer C<yes> if there is at least one operating system kernel installed in "
23803 "the guest which runs fully virtualized. Such a guest would require a "
23804 "hypervisor which supports full system virtualization."
23808 #: ../inspector/virt-inspector.pl:731
23809 msgid "xen_domU_kernel=(yes|no)"
23813 #: ../inspector/virt-inspector.pl:733
23815 "Answer C<yes> if there is at least one Linux kernel installed in the guest "
23816 "which is compiled as a Xen DomU (a Xen paravirtualized guest)."
23820 #: ../inspector/virt-inspector.pl:753
23821 msgid "xen_pv_drivers=(yes|no)"
23825 #: ../inspector/virt-inspector.pl:755
23827 "Answer C<yes> if the guest has Xen paravirtualized drivers installed "
23828 "(usually the kernel itself will be fully virtualized, but the PV drivers "
23829 "have been installed by the administrator for performance reasons)."
23833 #: ../inspector/virt-inspector.pl:777
23834 msgid "virtio_drivers=(yes|no)"
23838 #: ../inspector/virt-inspector.pl:779
23840 "Answer C<yes> if the guest has virtio paravirtualized drivers installed. "
23841 "Virtio drivers are commonly used to improve the performance of KVM."
23845 #: ../inspector/virt-inspector.pl:800
23846 msgid "userspace_arch=(x86_64|...)"
23850 #: ../inspector/virt-inspector.pl:802
23851 msgid "Print the architecture of userspace."
23855 #: ../inspector/virt-inspector.pl:804 ../inspector/virt-inspector.pl:825
23856 msgid "NB. For multi-boot VMs this can print several lines."
23860 #: ../inspector/virt-inspector.pl:821
23861 msgid "kernel_arch=(x86_64|...)"
23865 #: ../inspector/virt-inspector.pl:823
23866 msgid "Print the architecture of the kernel."
23870 #: ../inspector/virt-inspector.pl:848 ../tools/virt-df.pl:538
23872 "L<guestfs(3)>, L<guestfish(1)>, L<Sys::Guestfs(3)>, L<Sys::Guestfs::Lib(3)>, "
23873 "L<Sys::Virt(3)>, L<http://libguestfs.org/>."
23877 #: ../inspector/virt-inspector.pl:857 ../tools/virt-edit.pl:339
23878 #: ../tools/virt-win-reg.pl:489 ../tools/virt-df.pl:547
23879 #: ../tools/virt-ls.pl:223 ../tools/virt-resize.pl:1409
23880 #: ../tools/virt-list-filesystems.pl:205 ../tools/virt-cat.pl:175
23881 #: ../tools/virt-tar.pl:270 ../tools/virt-rescue.pl:243
23882 #: ../tools/virt-make-fs.pl:554 ../tools/virt-list-partitions.pl:242
23883 msgid "Richard W.M. Jones L<http://people.redhat.com/~rjones/>"
23887 #: ../inspector/virt-inspector.pl:859
23888 msgid "Matthew Booth L<mbooth@redhat.com>"
23892 #: ../inspector/virt-inspector.pl:863 ../tools/virt-ls.pl:227
23893 #: ../tools/virt-list-filesystems.pl:209 ../tools/virt-cat.pl:179
23894 #: ../tools/virt-tar.pl:274
23895 msgid "Copyright (C) 2009 Red Hat Inc."
23899 #: ../tools/virt-edit.pl:35
23900 msgid "virt-edit - Edit a file in a virtual machine"
23904 #: ../tools/virt-edit.pl:39
23907 " virt-edit [--options] domname file\n"
23912 #: ../tools/virt-edit.pl:41
23915 " virt-edit [--options] disk.img [disk.img ...] file\n"
23920 #: ../tools/virt-edit.pl:43
23923 " virt-edit [domname|disk.img] file -e 'expr'\n"
23928 #: ../tools/virt-edit.pl:47
23930 "You must I<not> use C<virt-edit> on live virtual machines. If you do this, "
23931 "you risk disk corruption in the VM. C<virt-edit> tries to stop you from "
23932 "doing this, but doesn't catch all cases."
23936 #: ../tools/virt-edit.pl:53
23938 "C<virt-edit> is a command line tool to edit C<file> where C<file> exists in "
23939 "the named virtual machine (or disk image)."
23943 #: ../tools/virt-edit.pl:56
23945 "If you want to just view a file, use L<virt-cat(1)>. For more complex cases "
23946 "you should look at the L<guestfish(1)> tool."
23950 #: ../tools/virt-edit.pl:61
23951 msgid "Edit the named files interactively:"
23955 #: ../tools/virt-edit.pl:63
23958 " virt-edit mydomain /boot/grub/grub.conf\n"
23963 #: ../tools/virt-edit.pl:65
23966 " virt-edit mydomain /etc/passwd\n"
23971 #: ../tools/virt-edit.pl:67
23973 "You can also edit files non-interactively (see L</NON-INTERACTIVE EDITING> "
23974 "below). To change the init default level to 5:"
23978 #: ../tools/virt-edit.pl:71
23981 " virt-edit mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'\n"
23986 #: ../tools/virt-edit.pl:97
23987 msgid "B<--backup extension> | B<-b extension>"
23991 #: ../tools/virt-edit.pl:99
23993 "Create a backup of the original file I<in the guest disk image>. The backup "
23994 "has the original filename with C<extension> added."
23998 #: ../tools/virt-edit.pl:102
24000 "Usually the first character of C<extension> would be a dot C<.> so you would "
24005 #: ../tools/virt-edit.pl:105
24008 " virt-edit -b .orig [etc]\n"
24013 #: ../tools/virt-edit.pl:107
24014 msgid "By default, no backup file is made."
24018 #: ../tools/virt-edit.pl:118 ../tools/virt-win-reg.pl:209
24019 #: ../tools/virt-df.pl:100 ../tools/virt-ls.pl:108
24020 #: ../tools/virt-list-filesystems.pl:79 ../tools/virt-cat.pl:109
24021 #: ../tools/virt-tar.pl:128 ../tools/virt-rescue.pl:140
24022 #: ../tools/virt-list-partitions.pl:80
24024 "If you specify guest block devices directly, then libvirt is not used at all."
24028 #: ../tools/virt-edit.pl:125
24029 msgid "B<--expr EXPR> | B<-e EXPR>"
24033 #: ../tools/virt-edit.pl:127
24035 "Instead of launching the external editor, non-interactively apply the Perl "
24036 "expression C<EXPR> to each line in the file. See L</NON-INTERACTIVE "
24041 #: ../tools/virt-edit.pl:131
24043 "Be careful to properly quote the expression to prevent it from being altered "
24048 #: ../tools/virt-edit.pl:250
24049 msgid "NON-INTERACTIVE EDITING"
24053 #: ../tools/virt-edit.pl:252
24055 "C<virt-edit> normally calls out to C<$EDITOR> (or vi) so the system "
24056 "administrator can interactively edit the file."
24060 #: ../tools/virt-edit.pl:255
24062 "There are two ways also to use C<virt-edit> from scripts in order to make "
24063 "automated edits to files. (Note that although you I<can> use C<virt-edit> "
24064 "like this, it's less error-prone to write scripts directly using the "
24065 "libguestfs API and Augeas for configuration file editing.)"
24069 #: ../tools/virt-edit.pl:261
24071 "The first method is to temporarily set C<$EDITOR> to any script or program "
24072 "you want to run. The script is invoked as C<$EDITOR tmpfile> and it should "
24073 "update C<tmpfile> in place however it likes."
24077 #: ../tools/virt-edit.pl:265
24079 "The second method is to use the C<-e> parameter of C<virt-edit> to run a "
24080 "short Perl snippet in the style of L<sed(1)>. For example to replace all "
24081 "instances of C<foo> with C<bar> in a file:"
24085 #: ../tools/virt-edit.pl:269
24088 " virt-edit domname filename -e 's/foo/bar/'\n"
24093 #: ../tools/virt-edit.pl:271
24095 "The full power of Perl regular expressions can be used (see L<perlre(1)>). "
24096 "For example to delete root's password you could do:"
24100 #: ../tools/virt-edit.pl:274
24103 " virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'\n"
24108 #: ../tools/virt-edit.pl:276
24110 "What really happens is that the snippet is evaluated as a Perl expression "
24111 "for each line of the file. The line, including the final C<\\n>, is passed "
24112 "in C<$_> and the expression should update C<$_> or leave it unchanged."
24116 #: ../tools/virt-edit.pl:281
24118 "To delete a line, set C<$_> to the empty string. For example, to delete the "
24119 "C<apache> user account from the password file you can do:"
24123 #: ../tools/virt-edit.pl:284
24126 " virt-edit mydomain /etc/passwd -e '$_ = \"\" if /^apache:/'\n"
24131 #: ../tools/virt-edit.pl:286
24133 "To insert a line, prepend or append it to C<$_>. However appending lines to "
24134 "the end of the file is rather difficult this way since there is no concept "
24135 "of \"last line of the file\" - your expression just doesn't get called "
24136 "again. You might want to use the first method (setting C<$EDITOR>) if you "
24141 #: ../tools/virt-edit.pl:292
24143 "The variable C<$lineno> contains the current line number. As is "
24144 "traditional, the first line in the file is number C<1>."
24148 #: ../tools/virt-edit.pl:295
24150 "The return value from the expression is ignored, but the expression may call "
24151 "C<die> in order to abort the whole program, leaving the original file "
24156 #: ../tools/virt-edit.pl:299
24158 "Remember when matching the end of a line that C<$_> may contain the final C<"
24159 "\\n>, or (for DOS files) C<\\r\\n>, or if the file does not end with a "
24160 "newline then neither of these. Thus to match or substitute some text at the "
24161 "end of a line, use this regular expression:"
24165 #: ../tools/virt-edit.pl:304
24168 " /some text(\\r?\\n)?$/\n"
24173 #: ../tools/virt-edit.pl:306
24175 "Alternately, use the perl C<chomp> function, being careful not to chomp C<"
24176 "$_> itself (since that would remove all newlines from the file):"
24180 #: ../tools/virt-edit.pl:310
24183 " my $m = $_; chomp $m; $m =~ /some text$/\n"
24188 #: ../tools/virt-edit.pl:316
24193 #: ../tools/virt-edit.pl:318
24195 "If set, this string is used as the editor. It may contain arguments, eg. C<"
24200 #: ../tools/virt-edit.pl:321
24201 msgid "If not set, C<vi> is used."
24205 #: ../tools/virt-edit.pl:327
24207 "L<guestfs(3)>, L<guestfish(1)>, L<virt-cat(1)>, L<Sys::Guestfs(3)>, L<Sys::"
24208 "Guestfs::Lib(3)>, L<Sys::Virt(3)>, L<http://libguestfs.org/>, L<perl(1)>, "
24213 #: ../tools/virt-edit.pl:337 ../tools/virt-win-reg.pl:487
24214 #: ../tools/virt-df.pl:545 ../tools/virt-ls.pl:221
24215 #: ../tools/virt-resize.pl:1407 ../tools/virt-list-filesystems.pl:203
24216 #: ../tools/virt-cat.pl:173 ../tools/virt-tar.pl:268
24217 #: ../tools/virt-rescue.pl:241 ../tools/virt-make-fs.pl:552
24218 #: ../tools/virt-list-partitions.pl:240
24223 #: ../tools/virt-edit.pl:343 ../tools/virt-df.pl:551
24224 #: ../tools/virt-rescue.pl:247 ../tools/virt-list-partitions.pl:246
24225 msgid "Copyright (C) 2009-2010 Red Hat Inc."
24229 #: ../tools/virt-win-reg.pl:38
24231 "virt-win-reg - Export and merge Windows Registry entries from a Windows guest"
24235 #: ../tools/virt-win-reg.pl:42
24238 " virt-win-reg domname 'HKLM\\Path\\To\\Subkey'\n"
24243 #: ../tools/virt-win-reg.pl:44
24246 " virt-win-reg domname 'HKLM\\Path\\To\\Subkey' name\n"
24251 #: ../tools/virt-win-reg.pl:46
24254 " virt-win-reg domname 'HKLM\\Path\\To\\Subkey' @\n"
24259 #: ../tools/virt-win-reg.pl:48
24262 " virt-win-reg --merge domname [input.reg ...]\n"
24267 #: ../tools/virt-win-reg.pl:50
24270 " virt-win-reg [--options] disk.img ... # instead of domname\n"
24275 #: ../tools/virt-win-reg.pl:54
24277 "You must I<not> use C<virt-win-reg> with the C<--merge> option on live "
24278 "virtual machines. If you do this, you I<will> get irreversible disk "
24279 "corruption in the VM. C<virt-win-reg> tries to stop you from doing this, "
24280 "but doesn't catch all cases."
24284 #: ../tools/virt-win-reg.pl:59
24286 "Modifying the Windows Registry is an inherently risky operation. The format "
24287 "is deliberately obscure and undocumented, and Registry changes can leave the "
24288 "system unbootable. Therefore when using the C<--merge> option, make sure "
24289 "you have a reliable backup first."
24293 #: ../tools/virt-win-reg.pl:66
24295 "This program can export and merge Windows Registry entries from a Windows "
24300 #: ../tools/virt-win-reg.pl:69
24302 "The first parameter is the libvirt guest name or the raw disk image of a "
24307 #: ../tools/virt-win-reg.pl:72
24309 "If C<--merge> is I<not> specified, then the chosen registry key is displayed/"
24310 "exported (recursively). For example:"
24314 #: ../tools/virt-win-reg.pl:75
24317 " $ virt-win-reg Windows7 'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft'\n"
24322 #: ../tools/virt-win-reg.pl:77
24324 "You can also display single values from within registry keys, for example:"
24328 #: ../tools/virt-win-reg.pl:80
24331 " $ cvkey='HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion'\n"
24332 " $ virt-win-reg Windows7 $cvkey ProductName\n"
24333 " Windows 7 Enterprise\n"
24338 #: ../tools/virt-win-reg.pl:84
24340 "With C<--merge>, you can merge a textual regedit file into the Windows "
24345 #: ../tools/virt-win-reg.pl:87
24348 " $ virt-win-reg --merge Windows7 changes.reg\n"
24353 #: ../tools/virt-win-reg.pl:89
24354 msgid "SUPPORTED SYSTEMS"
24358 #: ../tools/virt-win-reg.pl:91
24360 "The program currently supports Windows NT-derived guests starting with "
24361 "Windows XP through to at least Windows 7."
24365 #: ../tools/virt-win-reg.pl:94
24367 "Registry support is done for C<HKEY_LOCAL_MACHINE\\SAM>, C<HKEY_LOCAL_MACHINE"
24368 "\\SECURITY>, C<HKEY_LOCAL_MACHINE\\SOFTWARE>, C<HKEY_LOCAL_MACHINE\\SYSTEM> "
24369 "and C<HKEY_USERS\\.DEFAULT>."
24373 #: ../tools/virt-win-reg.pl:98
24375 "You can use C<HKLM> as a shorthand for C<HKEY_LOCAL_MACHINE>, and C<HKU> for "
24380 #: ../tools/virt-win-reg.pl:101
24382 "C<HKEY_USERS\\$SID> and C<HKEY_CURRENT_USER> are B<not> supported at this "
24387 #: ../tools/virt-win-reg.pl:104
24392 #: ../tools/virt-win-reg.pl:106
24394 "This program is only meant for simple access to the registry. If you want "
24395 "to do complicated things with the registry, we suggest you download the "
24396 "Registry hive files from the guest using L<libguestfs(3)> or L<guestfish(1)> "
24397 "and access them locally, eg. using L<hivex(3)>, L<hivexsh(1)> or "
24398 "L<hivexregedit(1)>."
24402 #: ../tools/virt-win-reg.pl:112
24407 #: ../tools/virt-win-reg.pl:114
24409 "C<virt-win-reg> expects that regedit files have already been reencoded in "
24410 "the local encoding. Usually on Linux hosts, this means UTF-8 with Unix-"
24411 "style line endings. Since Windows regedit files are often in UTF-16LE with "
24412 "Windows-style line endings, you may need to reencode the whole file before "
24413 "or after processing."
24417 #: ../tools/virt-win-reg.pl:120
24419 "To reencode a file from Windows format to Linux (before processing it with "
24420 "the C<--merge> option), you would do something like this:"
24424 #: ../tools/virt-win-reg.pl:123
24427 " iconv -f utf-16le -t utf-8 < win.reg | dos2unix > linux.reg\n"
24432 #: ../tools/virt-win-reg.pl:125
24434 "To go in the opposite direction, after exporting and before sending the file "
24435 "to a Windows user, do something like this:"
24439 #: ../tools/virt-win-reg.pl:128
24442 " unix2dos linux.reg | iconv -f utf-8 -t utf-16le > win.reg\n"
24447 #: ../tools/virt-win-reg.pl:130
24448 msgid "For more information about encoding, see L<Win::Hivex::Regedit(3)>."
24452 #: ../tools/virt-win-reg.pl:132
24454 "If you are unsure about the current encoding, use the L<file(1)> command. "
24455 "Recent versions of Windows regedit.exe produce a UTF-16LE file with Windows-"
24456 "style (CRLF) line endings, like this:"
24460 #: ../tools/virt-win-reg.pl:136
24463 " $ file software.reg\n"
24464 " software.reg: Little-endian UTF-16 Unicode text, with very long lines,\n"
24465 " with CRLF line terminators\n"
24470 #: ../tools/virt-win-reg.pl:140
24471 msgid "This file would need conversion before you could C<--merge> it."
24475 #: ../tools/virt-win-reg.pl:142
24476 msgid "SHELL QUOTING"
24480 #: ../tools/virt-win-reg.pl:144
24482 "Be careful when passing parameters containing C<\\> (backslash) in the "
24483 "shell. Usually you will have to use 'single quotes' or double backslashes "
24484 "(but not both) to protect them from the shell."
24488 #: ../tools/virt-win-reg.pl:148
24489 msgid "Paths and value names are case-insensitive."
24493 #: ../tools/virt-win-reg.pl:150
24494 msgid "CurrentControlSet etc."
24498 #: ../tools/virt-win-reg.pl:152
24500 "Registry keys like C<CurrentControlSet> don't really exist in the Windows "
24501 "Registry at the level of the hive file, and therefore you cannot modify "
24506 #: ../tools/virt-win-reg.pl:156
24508 "C<CurrentControlSet> is usually an alias for C<ControlSet001>. In some "
24509 "circumstances it might refer to another control set. The way to find out is "
24510 "to look at the C<HKLM\\SYSTEM\\Select> key:"
24514 #: ../tools/virt-win-reg.pl:160
24517 " # virt-win-reg WindowsGuest 'HKLM\\SYSTEM\\Select'\n"
24518 " [HKEY_LOCAL_MACHINE\\SYSTEM\\Select]\n"
24519 " \"Current\"=dword:00000001\n"
24520 " \"Default\"=dword:00000001\n"
24521 " \"Failed\"=dword:00000000\n"
24522 " \"LastKnownGood\"=dword:00000002\n"
24527 #: ../tools/virt-win-reg.pl:167
24528 msgid "\"Default\" is the one which Windows will choose when it boots."
24532 #: ../tools/virt-win-reg.pl:169
24534 "Similarly, other C<Current...> keys in the path may need to be replaced."
24538 #: ../tools/virt-win-reg.pl:196 ../tools/virt-make-fs.pl:177
24543 #: ../tools/virt-win-reg.pl:198 ../tools/virt-resize.pl:477
24544 msgid "Enable debugging messages."
24548 #: ../tools/virt-win-reg.pl:216
24553 #: ../tools/virt-win-reg.pl:218
24555 "In merge mode, this merges a textual regedit file into the Windows Registry "
24556 "of the virtual machine. If this flag is I<not> given then virt-win-reg "
24557 "displays or exports Registry entries instead."
24561 #: ../tools/virt-win-reg.pl:222
24563 "Note that C<--merge> is I<unsafe> to use on live virtual machines, and will "
24564 "result in disk corruption. However exporting (without this flag) is always "
24569 #: ../tools/virt-win-reg.pl:230
24570 msgid "B<--encoding> UTF-16LE|ASCII"
24574 #: ../tools/virt-win-reg.pl:232
24576 "When merging (only), you may need to specify the encoding for strings to be "
24577 "used in the hive file. This is explained in detail in L<Win::Hivex::Regedit"
24578 "(3)/ENCODING STRINGS>."
24582 #: ../tools/virt-win-reg.pl:236
24584 "The default is to use UTF-16LE, which should work with recent versions of "
24589 #: ../tools/virt-win-reg.pl:463
24591 "L<hivex(3)>, L<hivexsh(1)>, L<hivexregedit(1)>, L<guestfs(3)>, L<guestfish(1)"
24592 ">, L<virt-cat(1)>, L<Sys::Guestfs(3)>, L<Sys::Guestfs::Lib(3)>, L<Win::Hivex"
24593 "(3)>, L<Win::Hivex::Regedit(3)>, L<Sys::Virt(3)>, L<http://libguestfs.org/>."
24597 #: ../tools/virt-win-reg.pl:478 ../tools/virt-make-fs.pl:543
24599 "When reporting bugs, please enable debugging and capture the I<complete> "
24604 #: ../tools/virt-win-reg.pl:481
24607 " export LIBGUESTFS_DEBUG=1\n"
24608 " virt-win-reg --debug [... rest ...] > /tmp/virt-win-reg.log 2>&1\n"
24613 #: ../tools/virt-win-reg.pl:484
24615 "Attach /tmp/virt-win-reg.log to a new bug report at L<https://bugzilla."
24620 #: ../tools/virt-win-reg.pl:493 ../tools/virt-resize.pl:1413
24621 #: ../tools/virt-make-fs.pl:558
24622 msgid "Copyright (C) 2010 Red Hat Inc."
24626 #: ../tools/virt-df.pl:36
24627 msgid "virt-df - Display free space on virtual filesystems"
24631 #: ../tools/virt-df.pl:40
24634 " virt-df [--options]\n"
24639 #: ../tools/virt-df.pl:42
24642 " virt-df [--options] domname\n"
24647 #: ../tools/virt-df.pl:44
24650 " virt-df [--options] disk.img [disk.img ...]\n"
24655 #: ../tools/virt-df.pl:48
24657 "C<virt-df> is a command line tool to display free space on virtual machine "
24658 "filesystems. Unlike other tools, it doesn't just display the amount of "
24659 "space allocated to a virtual machine, but can look inside the virtual "
24660 "machine to see how much space is really being used."
24664 #: ../tools/virt-df.pl:53
24666 "It is like the L<df(1)> command, but for virtual machines, except that it "
24667 "also works for Windows virtual machines."
24671 #: ../tools/virt-df.pl:56
24673 "If used without any arguments, C<virt-df> checks with libvirt to get a list "
24674 "of all active and inactive guests, and performs a C<df>-type operation on "
24675 "each one in turn, printing out the results."
24679 #: ../tools/virt-df.pl:60
24681 "If used with any argument(s), C<virt-df> performs a C<df>-type operation on "
24682 "either the single named libvirt domain, or on the disk image(s) listed on "
24683 "the command line (which must all belong to a single VM). In this mode (with "
24684 "arguments), C<virt-df> will I<only work for a single guest>. If you want to "
24685 "run on multiple guests, then you have to invoke C<virt-df> multiple times."
24689 #: ../tools/virt-df.pl:67
24691 "Use the C<--csv> option to get a format which can be easily parsed by other "
24692 "programs. Other options are mostly similar to standard C<df> options. See "
24693 "below for the complete list."
24697 #: ../tools/virt-df.pl:107
24702 #: ../tools/virt-df.pl:109
24704 "Write out the results in CSV format (comma-separated values). This format "
24705 "can be imported easily into databases and spreadsheets, but read L</NOTE "
24706 "ABOUT CSV FORMAT> below."
24710 #: ../tools/virt-df.pl:117
24711 msgid "B<--human-readable> | B<-h>"
24715 #: ../tools/virt-df.pl:119
24716 msgid "Print sizes in human-readable format."
24720 #: ../tools/virt-df.pl:121
24721 msgid "You are not allowed to use I<-h> and I<--csv> at the same time."
24725 #: ../tools/virt-df.pl:127
24726 msgid "B<--inodes> | B<-i>"
24730 #: ../tools/virt-df.pl:129
24731 msgid "Print inodes instead of blocks."
24735 #: ../tools/virt-df.pl:135
24736 msgid "B<--one-per-guest>"
24740 #: ../tools/virt-df.pl:137
24742 "Run one libguestfs appliance per guest. Normally C<virt-df> will add the "
24743 "disks from several guests to a single libguestfs appliance."
24747 #: ../tools/virt-df.pl:140
24748 msgid "You might use this option in the following circumstances:"
24752 #: ../tools/virt-df.pl:146
24754 "If you think an untrusted guest might actively try to exploit the libguestfs "
24755 "appliance kernel, then this prevents one guest from interfering with the "
24756 "stats printed for another guest."
24760 #: ../tools/virt-df.pl:152
24762 "If the kernel has a bug which stops it from accessing a filesystem in one "
24763 "guest (see for example RHBZ#635373) then this allows libguestfs to continue "
24764 "and report stats for further guests."
24768 #: ../tools/virt-df.pl:512
24769 msgid "NOTE ABOUT CSV FORMAT"
24773 #: ../tools/virt-df.pl:514
24775 "Comma-separated values (CSV) is a deceptive format. It I<seems> like it "
24776 "should be easy to parse, but it is definitely not easy to parse."
24780 #: ../tools/virt-df.pl:517
24782 "Myth: Just split fields at commas. Reality: This does I<not> work "
24783 "reliably. This example has two columns:"
24787 #: ../tools/virt-df.pl:520
24790 " \"foo,bar\",baz\n"
24795 #: ../tools/virt-df.pl:522
24797 "Myth: Read the file one line at a time. Reality: This does I<not> work "
24798 "reliably. This example has one row:"
24802 #: ../tools/virt-df.pl:525
24811 #: ../tools/virt-df.pl:528
24813 "For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv> also "
24814 "packaged in major Linux distributions)."
24818 #: ../tools/virt-df.pl:531
24820 "For other languages, use a CSV processing library (eg. C<Text::CSV> for Perl "
24821 "or Python's built-in csv library)."
24825 #: ../tools/virt-df.pl:534
24826 msgid "Most spreadsheets and databases can import CSV directly."
24830 #: ../tools/virt-ls.pl:35
24831 msgid "virt-ls - List files in a virtual machine"
24835 #: ../tools/virt-ls.pl:39
24838 " virt-ls [--options] domname directory\n"
24843 #: ../tools/virt-ls.pl:41
24846 " virt-ls [--options] disk.img [disk.img ...] directory\n"
24851 #: ../tools/virt-ls.pl:45
24853 "C<virt-ls> is a command line tool to list the names of files in a directory "
24854 "inside a virtual machine or disk image."
24858 #: ../tools/virt-ls.pl:48
24860 "C<virt-ls> is just a simple wrapper around L<libguestfs(3)> functionality. "
24861 "For more complex cases you should look at the L<guestfish(1)> tool."
24865 #: ../tools/virt-ls.pl:52
24867 "C<virt-ls> can be used in one of three modes: simple, long and recursive. A "
24868 "simple listing is like the ordinary L<ls(1)> command:"
24872 #: ../tools/virt-ls.pl:55
24875 " $ virt-ls myguest /\n"
24883 #: ../tools/virt-ls.pl:60
24884 msgid "With the C<-l> (C<--long>) option, C<virt-ls> shows more detail:"
24888 #: ../tools/virt-ls.pl:62
24891 " $ virt-ls -l myguest /\n"
24893 " dr-xr-xr-x. 2 root root 4096 2009-08-25 19:06 bin\n"
24894 " dr-xr-xr-x. 5 root root 3072 2009-08-25 19:06 boot\n"
24900 #: ../tools/virt-ls.pl:68
24902 "With the C<-R> (C<--recursive>) option, C<virt-ls> lists the names of files "
24903 "and directories recursively:"
24907 #: ../tools/virt-ls.pl:71
24910 " $ virt-ls -R myguest /tmp\n"
24918 #: ../tools/virt-ls.pl:76
24920 "You I<cannot> combine these options. To do more complicated things, use "
24925 #: ../tools/virt-ls.pl:115 ../tools/virt-list-filesystems.pl:86
24926 #: ../tools/virt-list-partitions.pl:95
24927 msgid "B<-l> | B<--long>"
24931 #: ../tools/virt-ls.pl:117
24932 msgid "B<-R> | B<--recursive>"
24936 #: ../tools/virt-ls.pl:119
24938 "Select the mode. With neither of these options, C<virt-ls> produces a "
24939 "simple, flat list of the files in the named directory."
24943 #: ../tools/virt-ls.pl:122
24945 "C<virt-ls -l> produces a \"long listing\", which shows more detail (just "
24946 "like the plain C<ls -l> command)."
24950 #: ../tools/virt-ls.pl:125
24952 "C<virt-ls -R> produces a recursive list of files starting at the named "
24953 "directory. See the documentation for the C<guestfs_find> command L<guestfs"
24954 "(3)> for precise details."
24958 #: ../tools/virt-ls.pl:129
24959 msgid "You cannot combine these options."
24963 #: ../tools/virt-ls.pl:212
24965 "L<guestfs(3)>, L<guestfish(1)>, L<virt-cat(1)>, L<virt-tar(1)>, L<Sys::"
24966 "Guestfs(3)>, L<Sys::Guestfs::Lib(3)>, L<Sys::Virt(3)>, L<http://libguestfs."
24971 #: ../tools/virt-resize.pl:42
24972 msgid "virt-resize - Resize a virtual machine disk"
24976 #: ../tools/virt-resize.pl:46
24979 " virt-resize [--resize /dev/sdaN=[+/-]<size>[%]]\n"
24980 " [--expand /dev/sdaN] [--shrink /dev/sdaN]\n"
24981 " [--ignore /dev/sdaN] [--delete /dev/sdaN] [...] indisk outdisk\n"
24986 #: ../tools/virt-resize.pl:52
24988 "Virt-resize is a tool which can resize a virtual machine disk, making it "
24989 "larger or smaller overall, and resizing or deleting any partitions contained "
24994 #: ../tools/virt-resize.pl:56
24996 "Virt-resize B<cannot> resize disk images in-place. Virt-resize B<should "
24997 "not> be used on live virtual machines - for consistent results, shut the "
24998 "virtual machine down before resizing it."
25002 #: ../tools/virt-resize.pl:60
25004 "If you are not familiar with the associated tools: L<virt-list-partitions(1)"
25005 ">, L<virt-list-filesystems(1)> and L<virt-df(1)>, we recommend you go and "
25006 "read those manual pages first."
25010 #: ../tools/virt-resize.pl:68
25012 "Copy C<olddisk> to C<newdisk>, extending one of the guest's partitions to "
25013 "fill the extra 5GB of space."
25017 #: ../tools/virt-resize.pl:71
25020 " truncate -r olddisk newdisk; truncate -s +5G newdisk\n"
25021 " virt-list-partitions -lht olddisk\n"
25022 " # Note \"/dev/sda2\" is a partition inside the \"olddisk\" file.\n"
25023 " virt-resize --expand /dev/sda2 olddisk newdisk\n"
25028 #: ../tools/virt-resize.pl:76
25030 "As above, but make the /boot partition 200MB bigger, while giving the "
25031 "remaining space to /dev/sda2:"
25035 #: ../tools/virt-resize.pl:79
25038 " virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 olddisk newdisk\n"
25043 #: ../tools/virt-resize.pl:81
25044 msgid "DETAILED USAGE"
25048 #: ../tools/virt-resize.pl:83
25049 msgid "EXPANDING A VIRTUAL MACHINE DISK"
25053 #: ../tools/virt-resize.pl:87
25054 msgid "1. Shut down the virtual machine"
25058 #: ../tools/virt-resize.pl:89
25059 msgid "2. Locate input disk image"
25063 #: ../tools/virt-resize.pl:91
25065 "Locate the input disk image (ie. the file or device on the host containing "
25066 "the guest's disk). If the guest is managed by libvirt, you can use C<virsh "
25067 "dumpxml> like this to find the disk image name:"
25071 #: ../tools/virt-resize.pl:95
25074 " # virsh dumpxml guestname | xpath /domain/devices/disk/source\n"
25075 " Found 1 nodes:\n"
25077 " <source dev=\"/dev/vg/lv_guest\" />\n"
25082 #: ../tools/virt-resize.pl:100
25083 msgid "3. Look at current sizing"
25087 #: ../tools/virt-resize.pl:102
25089 "Use L<virt-list-partitions(1)> to display the current partitions and sizes:"
25093 #: ../tools/virt-resize.pl:105
25096 " # virt-list-partitions -lht /dev/vg/lv_guest\n"
25097 " /dev/sda1 ext3 101.9M\n"
25098 " /dev/sda2 pv 7.9G\n"
25099 " /dev/sda device 8.0G\n"
25104 #: ../tools/virt-resize.pl:110
25106 "(This example is a virtual machine with an 8 GB disk which we would like to "
25107 "expand up to 10 GB)."
25111 #: ../tools/virt-resize.pl:113
25112 msgid "4. Create output disk"
25116 #: ../tools/virt-resize.pl:115
25118 "Virt-resize cannot do in-place disk modifications. You have to have space "
25119 "to store the resized output disk."
25123 #: ../tools/virt-resize.pl:118
25125 "To store the resized disk image in a file, create a file of a suitable size:"
25129 #: ../tools/virt-resize.pl:121
25132 " # rm -f outdisk\n"
25133 " # truncate -s 10G outdisk\n"
25138 #: ../tools/virt-resize.pl:124
25139 msgid "Or use L<lvcreate(1)> to create a logical volume:"
25143 #: ../tools/virt-resize.pl:126
25146 " # lvcreate -L 10G -n lv_name vg_name\n"
25151 #: ../tools/virt-resize.pl:128
25152 msgid "Or use L<virsh(1)> vol-create-as to create a libvirt storage volume:"
25156 #: ../tools/virt-resize.pl:130
25159 " # virsh pool-list\n"
25160 " # virsh vol-create-as poolname newvol 10G\n"
25165 #: ../tools/virt-resize.pl:133
25170 #: ../tools/virt-resize.pl:135
25172 "virt-resize takes two mandatory parameters, the input disk (eg. device or "
25173 "file) and the output disk. The output disk is the one created in the "
25178 #: ../tools/virt-resize.pl:139
25181 " # virt-resize indisk outdisk\n"
25186 #: ../tools/virt-resize.pl:141
25188 "This command just copies disk image C<indisk> to disk image C<outdisk> "
25189 "I<without> resizing or changing any existing partitions. If C<outdisk> is "
25190 "larger, then an extra, empty partition is created at the end of the disk "
25191 "covering the extra space. If C<outdisk> is smaller, then it will give an "
25196 #: ../tools/virt-resize.pl:147
25198 "More realistically you'd want to expand existing partitions in the disk "
25199 "image by passing extra options (for the full list see the L</OPTIONS> "
25204 #: ../tools/virt-resize.pl:151
25206 "L</--expand> is the most useful option. It expands the named partition "
25207 "within the disk to fill any extra space:"
25211 #: ../tools/virt-resize.pl:154
25214 " # virt-resize --expand /dev/sda2 indisk outdisk\n"
25219 #: ../tools/virt-resize.pl:156
25221 "(In this case, an extra partition is I<not> created at the end of the disk, "
25222 "because there will be no unused space)."
25226 #: ../tools/virt-resize.pl:159
25228 "L</--resize> is the other commonly used option. The following would "
25229 "increase the size of /dev/sda1 by 200M, and expand /dev/sda2 to fill the "
25230 "rest of the available space:"
25234 #: ../tools/virt-resize.pl:163
25237 " # virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 \\\n"
25238 " indisk outdisk\n"
25243 #: ../tools/virt-resize.pl:166
25245 "If the expanded partition in the image contains a filesystem or LVM PV, then "
25246 "if virt-resize knows how, it will resize the contents, the equivalent of "
25247 "calling a command such as L<pvresize(8)>, L<resize2fs(8)> or L<ntfsresize(8)"
25248 ">. However virt-resize does not know how to resize some filesystems, so you "
25249 "would have to online resize them after booting the guest. And virt-resize "
25250 "also does not resize anything inside an LVM PV, it just resizes the PV "
25251 "itself and leaves the user to resize any LVs inside that PV as desired."
25255 #: ../tools/virt-resize.pl:175
25256 msgid "Other options are covered below."
25260 #: ../tools/virt-resize.pl:177
25265 #: ../tools/virt-resize.pl:179
25266 msgid "Thoroughly test the new disk image I<before> discarding the old one."
25270 #: ../tools/virt-resize.pl:181
25271 msgid "If you are using libvirt, edit the XML to point at the new disk:"
25275 #: ../tools/virt-resize.pl:183
25278 " # virsh edit guestname\n"
25283 #: ../tools/virt-resize.pl:185
25285 "Change E<lt>source ...E<gt>, see L<http://libvirt.org/formatdomain."
25286 "html#elementsDisks>"
25290 #: ../tools/virt-resize.pl:188
25291 msgid "Then start up the domain with the new, resized disk:"
25295 #: ../tools/virt-resize.pl:190
25298 " # virsh start guestname\n"
25303 #: ../tools/virt-resize.pl:192
25305 "and check that it still works. See also the L</NOTES> section below for "
25306 "additional information."
25310 #: ../tools/virt-resize.pl:195
25311 msgid "7. Resize LVs etc inside the guest"
25315 #: ../tools/virt-resize.pl:197
25316 msgid "(This can also be done offline using L<guestfish(1)>)"
25320 #: ../tools/virt-resize.pl:199
25322 "Once the guest has booted you should see the new space available, at least "
25323 "for filesystems that virt-resize knows how to resize, and for PVs. The user "
25324 "may need to resize LVs inside PVs, and also resize filesystem types that "
25325 "virt-resize does not know how to expand."
25329 #: ../tools/virt-resize.pl:206
25330 msgid "SHRINKING A VIRTUAL MACHINE DISK"
25334 #: ../tools/virt-resize.pl:208
25336 "Shrinking is somewhat more complex than expanding, and only an overview is "
25341 #: ../tools/virt-resize.pl:211
25343 "Firstly virt-resize will not attempt to shrink any partition content (PVs, "
25344 "filesystems). The user has to shrink content before passing the disk image "
25345 "to virt-resize, and virt-resize will check that the content has been shrunk "
25350 #: ../tools/virt-resize.pl:216
25351 msgid "(Shrinking can also be done offline using L<guestfish(1)>)"
25355 #: ../tools/virt-resize.pl:218
25357 "After shrinking PVs and filesystems, shut down the guest, and proceed with "
25358 "steps 3 and 4 above to allocate a new disk image."
25362 #: ../tools/virt-resize.pl:221
25364 "Then run virt-resize with any of the C<--shrink> and/or C<--resize> options."
25368 #: ../tools/virt-resize.pl:224
25369 msgid "IGNORING OR DELETING PARTITIONS"
25373 #: ../tools/virt-resize.pl:226
25375 "virt-resize also gives a convenient way to ignore or delete partitions when "
25376 "copying from the input disk to the output disk. Ignoring a partition speeds "
25377 "up the copy where you don't care about the existing contents of a "
25378 "partition. Deleting a partition removes it completely, but note that it "
25379 "also renumbers any partitions after the one which is deleted, which can "
25380 "leave some guests unbootable."
25384 #: ../tools/virt-resize.pl:243
25385 msgid "Display help."
25389 #: ../tools/virt-resize.pl:257
25390 msgid "B<--resize part=size>"
25394 #: ../tools/virt-resize.pl:259
25396 "Resize the named partition (expanding or shrinking it) so that it has the "
25401 #: ../tools/virt-resize.pl:262
25403 "C<size> can be expressed as an absolute number followed by b/K/M/G/T/P/E to "
25404 "mean bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Petabytes or "
25405 "Exabytes; or as a percentage of the current size; or as a relative number or "
25406 "percentage. For example:"
25410 #: ../tools/virt-resize.pl:267
25413 " --resize /dev/sda2=10G\n"
25418 #: ../tools/virt-resize.pl:269
25421 " --resize /dev/sda4=90%\n"
25426 #: ../tools/virt-resize.pl:271
25429 " --resize /dev/sda2=+1G\n"
25434 #: ../tools/virt-resize.pl:273
25437 " --resize /dev/sda2=-200M\n"
25442 #: ../tools/virt-resize.pl:275
25445 " --resize /dev/sda1=+128K\n"
25450 #: ../tools/virt-resize.pl:277
25453 " --resize /dev/sda1=+10%\n"
25458 #: ../tools/virt-resize.pl:279
25461 " --resize /dev/sda1=-10%\n"
25466 #: ../tools/virt-resize.pl:281
25468 "You can increase the size of any partition. Virt-resize will expand the "
25469 "direct content of the partition if it knows how (see C<--expand> below)."
25473 #: ../tools/virt-resize.pl:285
25475 "You can only I<decrease> the size of partitions that contain filesystems or "
25476 "PVs which have already been shrunk. Virt-resize will check this has been "
25477 "done before proceeding, or else will print an error (see also C<--resize-"
25482 #: ../tools/virt-resize.pl:290 ../tools/virt-resize.pl:382
25483 #: ../tools/virt-resize.pl:399
25484 msgid "You can give this option multiple times."
25488 #: ../tools/virt-resize.pl:296
25489 msgid "B<--resize-force part=size>"
25493 #: ../tools/virt-resize.pl:298
25495 "This is the same as C<--resize> except that it will let you decrease the "
25496 "size of any partition. Generally this means you will lose any data which "
25497 "was at the end of the partition you shrink, but you may not care about that "
25498 "(eg. if shrinking an unused partition, or if you can easily recreate it such "
25499 "as a swap partition)."
25503 #: ../tools/virt-resize.pl:304
25504 msgid "See also the C<--ignore> option."
25508 #: ../tools/virt-resize.pl:310
25509 msgid "B<--expand part>"
25513 #: ../tools/virt-resize.pl:312
25515 "Expand the named partition so it uses up all extra space (space left over "
25516 "after any other resize changes that you request have been done)."
25520 #: ../tools/virt-resize.pl:315
25522 "If virt-resize knows how, it will expand the direct content of the "
25523 "partition. For example, if the partition is an LVM PV, it will expand the "
25524 "PV to fit (like calling L<pvresize(8)>). Virt-resize leaves any other "
25525 "content it doesn't know about alone."
25529 #: ../tools/virt-resize.pl:320
25530 msgid "Currently virt-resize can resize:"
25534 #: ../tools/virt-resize.pl:326
25536 "ext2, ext3 and ext4 filesystems when they are contained directly inside a "
25541 #: ../tools/virt-resize.pl:331
25543 "NTFS filesystems contained directly in a partition, if libguestfs was "
25544 "compiled with support for NTFS."
25548 #: ../tools/virt-resize.pl:334
25550 "The filesystem must have been shut down consistently last time it was used. "
25551 "Additionally, L<ntfsresize(8)> marks the resized filesystem as requiring a "
25552 "consistency check, so at the first boot after resizing Windows will check "
25557 #: ../tools/virt-resize.pl:341
25559 "LVM PVs (physical volumes). However virt-resize does I<not> resize anything "
25560 "inside the PV. The user will have to resize LVs as desired."
25564 #: ../tools/virt-resize.pl:347 ../tools/virt-resize.pl:369
25565 msgid "Note that you cannot use C<--expand> and C<--shrink> together."
25569 #: ../tools/virt-resize.pl:353
25570 msgid "B<--shrink part>"
25574 #: ../tools/virt-resize.pl:355
25576 "Shrink the named partition until the overall disk image fits in the "
25577 "destination. The named partition B<must> contain a filesystem or PV which "
25578 "has already been shrunk using another tool (eg. L<guestfish(1)> or other "
25579 "online tools). Virt-resize will check this and give an error if it has not "
25584 #: ../tools/virt-resize.pl:361
25586 "The amount by which the overall disk must be shrunk (after carrying out all "
25587 "other operations requested by the user) is called the \"deficit\". For "
25588 "example, a straight copy (assume no other operations) from a 5GB disk image "
25589 "to a 4GB disk image results in a 1GB deficit. In this case, virt-resize "
25590 "would give an error unless the user specified a partition to shrink and that "
25591 "partition had more than a gigabyte of free space."
25595 #: ../tools/virt-resize.pl:375
25596 msgid "B<--ignore part>"
25600 #: ../tools/virt-resize.pl:377
25602 "Ignore the named partition. Effectively this means the partition is "
25603 "allocated on the destination disk, but the content is not copied across from "
25604 "the source disk. The content of the partition will be blank (all zero "
25609 #: ../tools/virt-resize.pl:388
25610 msgid "B<--delete part>"
25614 #: ../tools/virt-resize.pl:390
25616 "Delete the named partition. It would be more accurate to describe this as "
25617 "\"don't copy it over\", since virt-resize doesn't do in-place changes and "
25618 "the original disk image is left intact."
25622 #: ../tools/virt-resize.pl:394
25624 "Note that when you delete a partition, then anything contained in the "
25625 "partition is also deleted. Furthermore, this causes any partitions that "
25626 "come after to be I<renumbered>, which can easily make your guest unbootable."
25630 #: ../tools/virt-resize.pl:405
25631 msgid "B<--LV-expand logvol>"
25635 #: ../tools/virt-resize.pl:407
25637 "This takes the logical volume and, as a final step, expands it to fill all "
25638 "the space available in its volume group. A typical usage, assuming a Linux "
25639 "guest with a single PV C</dev/sda2> and a root device called C</dev/vg_guest/"
25640 "lv_root> would be:"
25644 #: ../tools/virt-resize.pl:412
25647 " virt-resize indisk outdisk \\\n"
25648 " --expand /dev/sda2 --LV-expand /dev/vg_guest/lv_root\n"
25653 #: ../tools/virt-resize.pl:415
25655 "This would first expand the partition (and PV), and then expand the root "
25656 "device to fill the extra space in the PV."
25660 #: ../tools/virt-resize.pl:418
25662 "The contents of the LV are also resized if virt-resize knows how to do "
25663 "that. You can stop virt-resize from trying to expand the content by using "
25664 "the option C<--no-expand-content>."
25668 #: ../tools/virt-resize.pl:422
25669 msgid "Use L<virt-list-filesystems(1)> to list the filesystems in the guest."
25673 #: ../tools/virt-resize.pl:425
25675 "You can give this option multiple times, I<but> it doesn't make sense to do "
25676 "this unless the logical volumes you specify are all in different volume "
25681 #: ../tools/virt-resize.pl:433
25682 msgid "B<--no-copy-boot-loader>"
25686 #: ../tools/virt-resize.pl:435
25688 "By default, virt-resize copies over some sectors at the start of the disk "
25689 "(up to the beginning of the first partition). Commonly these sectors "
25690 "contain the Master Boot Record (MBR) and the boot loader, and are required "
25691 "in order for the guest to boot correctly."
25695 #: ../tools/virt-resize.pl:440
25697 "If you specify this flag, then this initial copy is not done. You may need "
25698 "to reinstall the boot loader in this case."
25702 #: ../tools/virt-resize.pl:448
25703 msgid "B<--no-extra-partition>"
25707 #: ../tools/virt-resize.pl:450
25709 "By default, virt-resize creates an extra partition if there is any extra, "
25710 "unused space after all resizing has happened. Use this option to prevent "
25711 "the extra partition from being created. If you do this then the extra space "
25712 "will be inaccessible until you run fdisk, parted, or some other partitioning "
25713 "tool in the guest."
25717 #: ../tools/virt-resize.pl:456
25719 "Note that if the surplus space is smaller than 10 MB, no extra partition "
25724 #: ../tools/virt-resize.pl:463
25725 msgid "B<--no-expand-content>"
25729 #: ../tools/virt-resize.pl:465
25731 "By default, virt-resize will try to expand the direct contents of "
25732 "partitions, if it knows how (see C<--expand> option above)."
25736 #: ../tools/virt-resize.pl:468
25738 "If you give the C<--no-expand-content> option then virt-resize will not "
25743 #: ../tools/virt-resize.pl:475
25744 msgid "B<-d> | B<--debug>"
25748 #: ../tools/virt-resize.pl:483
25749 msgid "B<-n> | B<--dryrun>"
25753 #: ../tools/virt-resize.pl:485
25754 msgid "Print a summary of what would be done, but don't do anything."
25758 #: ../tools/virt-resize.pl:491
25759 msgid "B<-q> | B<--quiet>"
25763 #: ../tools/virt-resize.pl:493
25764 msgid "Don't print the summary."
25768 #: ../tools/virt-resize.pl:1350 ../tools/virt-rescue.pl:90
25773 #: ../tools/virt-resize.pl:1352
25774 msgid "\"Partition 1 does not end on cylinder boundary.\""
25778 #: ../tools/virt-resize.pl:1354
25780 "Virt-resize aligns partitions to multiples of 64 sectors. Usually this "
25781 "means the partitions will not be aligned to the ancient CHS geometry. "
25782 "However CHS geometry is meaningless for disks manufactured since the early "
25783 "1990s, and doubly so for virtual hard drives. Alignment of partitions to "
25784 "cylinders is not required by any modern operating system."
25788 #: ../tools/virt-resize.pl:1361
25789 msgid "RESIZING WINDOWS VIRTUAL MACHINES"
25793 #: ../tools/virt-resize.pl:1363
25795 "In Windows Vista and later versions, Microsoft switched to using a separate "
25796 "boot partition. In these VMs, typically C</dev/sda1> is the boot partition "
25797 "and C</dev/sda2> is the main (C:) drive. We have not had any luck resizing "
25798 "the boot partition. Doing so seems to break the guest completely. However "
25799 "expanding the second partition (ie. C: drive) should work."
25803 #: ../tools/virt-resize.pl:1370
25805 "Windows may initiate a lengthy \"chkdsk\" on first boot after a resize, if "
25806 "NTFS partitions have been expanded. This is just a safety check and (unless "
25807 "it find errors) is nothing to worry about."
25811 #: ../tools/virt-resize.pl:1374
25812 msgid "ALTERNATIVE TOOLS"
25816 #: ../tools/virt-resize.pl:1376
25818 "There are several proprietary tools for resizing partitions. We won't "
25819 "mention any here."
25823 #: ../tools/virt-resize.pl:1379
25825 "L<parted(8)> and its graphical shell gparted can do some types of resizing "
25826 "operations on disk images. They can resize and move partitions, but I don't "
25827 "think they can do anything with the contents, and they certainly don't "
25832 #: ../tools/virt-resize.pl:1384
25834 "L<guestfish(1)> can do everything that virt-resize can do and a lot more, "
25835 "but at a much lower level. You will probably end up hand-calculating sector "
25836 "offsets, which is something that virt-resize was designed to avoid. If you "
25837 "want to see the guestfish-equivalent commands that virt-resize runs, use the "
25842 #: ../tools/virt-resize.pl:1392
25844 "L<virt-list-partitions(1)>, L<virt-list-filesystems(1)>, L<virt-df(1)>, "
25845 "L<guestfs(3)>, L<guestfish(1)>, L<lvm(8)>, L<pvresize(8)>, L<lvresize(8)>, "
25846 "L<resize2fs(8)>, L<ntfsresize(8)>, L<virsh(1)>, L<parted(8)>, L<Sys::Guestfs"
25847 "(3)>, L<http://libguestfs.org/>."
25851 #: ../tools/virt-list-filesystems.pl:32
25853 "virt-list-filesystems - List filesystems in a virtual machine or disk image"
25857 #: ../tools/virt-list-filesystems.pl:36
25860 " virt-list-filesystems [--options] domname\n"
25865 #: ../tools/virt-list-filesystems.pl:38
25868 " virt-list-filesystems [--options] disk.img [disk.img ...]\n"
25873 #: ../tools/virt-list-filesystems.pl:42
25875 "C<virt-list-filesystems> is a command line tool to list the filesystems that "
25876 "are contained in a virtual machine or disk image."
25880 #: ../tools/virt-list-filesystems.pl:46
25882 "C<virt-list-filesystems> is just a simple wrapper around L<libguestfs(3)> "
25883 "functionality. For more complex cases you should look at the L<guestfish(1)"
25888 #: ../tools/virt-list-filesystems.pl:88
25890 "With this option, C<virt-list-filesystems> displays the type of each "
25891 "filesystem too (where \"type\" means C<ext3>, C<xfs> etc.)"
25895 #: ../tools/virt-list-filesystems.pl:95
25896 msgid "B<-a> | B<--all>"
25900 #: ../tools/virt-list-filesystems.pl:97
25902 "Normally we only show mountable filesystems. If this option is given then "
25903 "swap devices are shown too."
25907 #: ../tools/virt-list-filesystems.pl:193
25909 "L<guestfs(3)>, L<guestfish(1)>, L<virt-cat(1)>, L<virt-tar(1)>, L<virt-list-"
25910 "partitions(1)>, L<Sys::Guestfs(3)>, L<Sys::Guestfs::Lib(3)>, L<Sys::Virt(3)"
25911 ">, L<http://libguestfs.org/>."
25915 #: ../tools/virt-cat.pl:34
25916 msgid "virt-cat - Display a file in a virtual machine"
25920 #: ../tools/virt-cat.pl:38
25923 " virt-cat [--options] domname file\n"
25928 #: ../tools/virt-cat.pl:40
25931 " virt-cat [--options] disk.img [disk.img ...] file\n"
25936 #: ../tools/virt-cat.pl:44
25938 "C<virt-cat> is a command line tool to display the contents of C<file> where "
25939 "C<file> exists in the named virtual machine (or disk image)."
25943 #: ../tools/virt-cat.pl:47
25945 "C<virt-cat> can be used to quickly view a single file. To edit a file, use "
25946 "C<virt-edit>. For more complex cases you should look at the L<guestfish(1)> "
25951 #: ../tools/virt-cat.pl:53
25953 "Display C</etc/fstab> file from inside the libvirt VM called C<mydomain>:"
25957 #: ../tools/virt-cat.pl:56
25960 " virt-cat mydomain /etc/fstab\n"
25965 #: ../tools/virt-cat.pl:58
25966 msgid "List syslog messages from a VM:"
25970 #: ../tools/virt-cat.pl:60
25973 " virt-cat mydomain /var/log/messages | tail\n"
25978 #: ../tools/virt-cat.pl:62
25979 msgid "Find out what DHCP IP address a VM acquired:"
25983 #: ../tools/virt-cat.pl:64
25986 " virt-cat mydomain /var/log/messages | grep 'dhclient: bound to' | tail\n"
25991 #: ../tools/virt-cat.pl:66
25992 msgid "Find out what packages were recently installed:"
25996 #: ../tools/virt-cat.pl:68
25999 " virt-cat mydomain /var/log/yum.log | tail\n"
26004 #: ../tools/virt-cat.pl:70
26005 msgid "Find out who is logged on inside a virtual machine:"
26009 #: ../tools/virt-cat.pl:72
26012 " virt-cat mydomain /var/run/utmp > /tmp/utmp\n"
26018 #: ../tools/virt-cat.pl:75
26019 msgid "or who was logged on:"
26023 #: ../tools/virt-cat.pl:77
26026 " virt-cat mydomain /var/log/wtmp > /tmp/wtmp\n"
26027 " last -f /tmp/wtmp\n"
26032 #: ../tools/virt-cat.pl:165
26034 "L<guestfs(3)>, L<guestfish(1)>, L<virt-edit(1)>, L<Sys::Guestfs(3)>, L<Sys::"
26035 "Guestfs::Lib(3)>, L<Sys::Virt(3)>, L<http://libguestfs.org/>."
26039 #: ../tools/virt-tar.pl:34
26040 msgid "virt-tar - Extract or upload files to a virtual machine"
26044 #: ../tools/virt-tar.pl:38
26047 " virt-tar [--options] -x domname directory tarball\n"
26052 #: ../tools/virt-tar.pl:40
26055 " virt-tar [--options] -u domname tarball directory\n"
26060 #: ../tools/virt-tar.pl:42
26063 " virt-tar [--options] disk.img [disk.img ...] -x directory tarball\n"
26068 #: ../tools/virt-tar.pl:44
26071 " virt-tar [--options] disk.img [disk.img ...] -u tarball directory\n"
26076 #: ../tools/virt-tar.pl:48
26077 msgid "Download C</home> from the VM into a local tarball:"
26081 #: ../tools/virt-tar.pl:50
26084 " virt-tar -x domname /home home.tar\n"
26089 #: ../tools/virt-tar.pl:52
26092 " virt-tar -zx domname /home home.tar.gz\n"
26097 #: ../tools/virt-tar.pl:54
26098 msgid "Upload a local tarball and unpack it inside C</tmp> in the VM:"
26102 #: ../tools/virt-tar.pl:56
26105 " virt-tar -u domname uploadstuff.tar /tmp\n"
26110 #: ../tools/virt-tar.pl:58
26113 " virt-tar -zu domname uploadstuff.tar.gz /tmp\n"
26118 #: ../tools/virt-tar.pl:62
26120 "You must I<not> use C<virt-tar> with the C<-u> option (upload) on live "
26121 "virtual machines. If you do this, you risk disk corruption in the VM. "
26122 "C<virt-tar> tries to stop you from doing this, but doesn't catch all cases."
26126 #: ../tools/virt-tar.pl:67
26128 "You can use C<-x> (extract) on live virtual machines, but you might get "
26129 "inconsistent results or errors if there is filesystem activity inside the "
26130 "VM. If the live VM is synched and quiescent, then C<virt-tar> will usually "
26131 "work, but the only way to guarantee consistent results is if the virtual "
26132 "machine is shut down."
26136 #: ../tools/virt-tar.pl:75
26138 "C<virt-tar> is a general purpose archive tool for downloading and uploading "
26139 "parts of a guest filesystem. There are many possibilities: making backups, "
26140 "uploading data files, snooping on guest activity, fixing or customizing "
26145 #: ../tools/virt-tar.pl:80
26147 "If you want to just view a single file, use L<virt-cat(1)>. If you just "
26148 "want to edit a single file, use L<virt-edit(1)>. For more complex cases you "
26149 "should look at the L<guestfish(1)> tool."
26153 #: ../tools/virt-tar.pl:84
26155 "There are two modes of operation: C<-x> (eXtract) downloads a directory and "
26156 "its contents (recursively) from the virtual machine into a local tarball. "
26157 "C<-u> uploads from a local tarball, unpacking it into a directory inside the "
26158 "virtual machine. You cannot use these two options together."
26162 #: ../tools/virt-tar.pl:90
26164 "In addition, you may need to use the C<-z> (gZip) option to enable "
26165 "compression. When uploading, you have to specify C<-z> if the upload file "
26166 "is compressed because virt-tar won't detect this on its own."
26170 #: ../tools/virt-tar.pl:94
26172 "C<virt-tar> can only handle tar (optionally gzipped) format tarballs. For "
26173 "example it cannot do PKZip files or bzip2 compression. If you want that "
26174 "then you'll have to rebuild the tarballs yourself. (This is a limitation of "
26175 "the L<libguestfs(3)> API)."
26179 #: ../tools/virt-tar.pl:135
26180 msgid "B<-x> | B<--extract> | B<--download>"
26184 #: ../tools/virt-tar.pl:137
26185 msgid "B<-u> | B<--upload>"
26189 #: ../tools/virt-tar.pl:139
26191 "Use C<-x> to extract (download) a directory from a virtual machine to a "
26196 #: ../tools/virt-tar.pl:142
26198 "Use C<-u> to upload and unpack from a local tarball into a virtual machine. "
26199 "Please read the L</WARNING> section above before using this option."
26203 #: ../tools/virt-tar.pl:146
26204 msgid "You must specify exactly one of these options."
26208 #: ../tools/virt-tar.pl:152
26209 msgid "B<-z> | B<--gzip>"
26213 #: ../tools/virt-tar.pl:154
26214 msgid "Specify that the input or output tarball is gzip-compressed."
26218 #: ../tools/virt-tar.pl:259
26220 "L<guestfs(3)>, L<guestfish(1)>, L<virt-cat(1)>, L<virt-edit(1)>, L<Sys::"
26221 "Guestfs(3)>, L<Sys::Guestfs::Lib(3)>, L<Sys::Virt(3)>, L<http://libguestfs."
26226 #: ../tools/virt-rescue.pl:33
26227 msgid "virt-rescue - Run a rescue shell on a virtual machine"
26231 #: ../tools/virt-rescue.pl:37
26234 " virt-rescue [--options] domname\n"
26239 #: ../tools/virt-rescue.pl:39
26242 " virt-rescue [--options] disk.img [disk.img ...]\n"
26247 #: ../tools/virt-rescue.pl:43
26249 "You must I<not> use C<virt-rescue> on live virtual machines. Doing so will "
26250 "probably result in disk corruption in the VM. C<virt-rescue> tries to stop "
26251 "you from doing this, but doesn't catch all cases."
26255 #: ../tools/virt-rescue.pl:47
26257 "However if you use the I<--ro> (read only) option, then you can attach a "
26258 "shell to a live virtual machine. The results might be strange or "
26259 "inconsistent at times but you won't get disk corruption."
26263 #: ../tools/virt-rescue.pl:53
26265 "virt-rescue is like a Rescue CD, but for virtual machines, and without the "
26266 "need for a CD. virt-rescue gives you a rescue shell and some simple "
26267 "recovery tools which you can use to examine or rescue a virtual machine or "
26272 #: ../tools/virt-rescue.pl:58
26274 "You can run virt-rescue on any virtual machine known to libvirt, or directly "
26275 "on disk image(s):"
26279 #: ../tools/virt-rescue.pl:61
26282 " virt-rescue GuestName\n"
26287 #: ../tools/virt-rescue.pl:63
26290 " virt-rescue --ro /path/to/disk.img\n"
26295 #: ../tools/virt-rescue.pl:65
26298 " virt-rescue /dev/sdc\n"
26303 #: ../tools/virt-rescue.pl:67
26304 msgid "For live VMs you I<must> use the --ro option."
26308 #: ../tools/virt-rescue.pl:69
26310 "When you run virt-rescue on a virtual machine or disk image, you are placed "
26311 "in an interactive bash shell where you can use many ordinary Linux "
26312 "commands. What you see in C</> (C</bin>, C</lib> etc) is the rescue "
26313 "appliance. You must mount the virtual machine's filesystems by hand. There "
26314 "is an empty directory called C</sysroot> where you can mount filesystems."
26318 #: ../tools/virt-rescue.pl:76
26320 "In the example below, we list logical volumes, then choose one to mount "
26321 "under C</sysroot>:"
26325 #: ../tools/virt-rescue.pl:79
26329 " LV VG Attr LSize Origin Snap% Move Log Copy% Convert\n"
26330 " lv_root vg_f11x64 -wi-a- 8.83G\n"
26331 " lv_swap vg_f11x64 -wi-a- 992.00M\n"
26332 " ><rescue> mount /dev/vg_f11x64/lv_root /sysroot\n"
26333 " ><rescue> ls /sysroot\n"
26338 #: ../tools/virt-rescue.pl:86
26340 "If you don't know what filesystems are available on the virtual machine then "
26341 "you can use commands such as L<parted(8)> and L<lvs(8)> to find out."
26345 #: ../tools/virt-rescue.pl:92
26347 "Virt-rescue can be used on I<any> disk image file or device, not just a "
26348 "virtual machine. For example you can use it on a blank file if you want to "
26349 "partition that file (although we would recommend using L<guestfish(1)> "
26350 "instead as it is more suitable for this purpose). You can even use virt-"
26351 "rescue on things like SD cards."
26355 #: ../tools/virt-rescue.pl:98
26357 "This tool is just designed for quick interactive hacking on a virtual "
26358 "machine. For more structured access to a virtual machine disk image, you "
26359 "should use L<guestfs(3)>. To get a structured shell that you can use to "
26360 "make scripted changes to guests, use L<guestfish(1)>."
26364 #: ../tools/virt-rescue.pl:127
26365 msgid "B<--append kernelopts>"
26369 #: ../tools/virt-rescue.pl:129
26370 msgid "Pass additional options to the rescue kernel."
26374 #: ../tools/virt-rescue.pl:147
26375 msgid "B<--memsize MB> | B<-m MB>"
26379 #: ../tools/virt-rescue.pl:149
26381 "Change the amount of memory allocated to the rescue system. The default is "
26382 "set by libguestfs and is small but adequate for running system tools. The "
26383 "occasional program might need more memory. The parameter is specified in "
26388 #: ../tools/virt-rescue.pl:158
26389 msgid "B<--ro> | B<-r>"
26393 #: ../tools/virt-rescue.pl:160
26394 msgid "Open the image read-only."
26398 #: ../tools/virt-rescue.pl:172
26400 "Enable SELinux in the rescue appliance. You should read L<guestfs(3)/"
26401 "SELINUX> before using this option."
26405 #: ../tools/virt-rescue.pl:228
26407 "Several environment variables affect virt-rescue. See L<guestfs(3)/"
26408 "ENVIRONMENT VARIABLES> for the complete list."
26412 #: ../tools/virt-rescue.pl:233
26414 "L<guestfs(3)>, L<guestfish(1)>, L<virt-cat(1)>, L<Sys::Guestfs(3)>, L<Sys::"
26415 "Guestfs::Lib(3)>, L<Sys::Virt(3)>, L<http://libguestfs.org/>."
26419 #: ../tools/virt-make-fs.pl:37
26420 msgid "virt-make-fs - Make a filesystem from a tar archive or files"
26424 #: ../tools/virt-make-fs.pl:41
26427 " virt-make-fs [--options] input.tar output.img\n"
26432 #: ../tools/virt-make-fs.pl:43
26435 " virt-make-fs [--options] input.tar.gz output.img\n"
26440 #: ../tools/virt-make-fs.pl:45
26443 " virt-make-fs [--options] directory output.img\n"
26448 #: ../tools/virt-make-fs.pl:49
26450 "Virt-make-fs is a command line tool for creating a filesystem from a tar "
26451 "archive or some files in a directory. It is similar to tools like L<mkisofs"
26452 "(1)>, L<genisoimage(1)> and L<mksquashfs(1)>. Unlike those tools, it can "
26453 "create common filesystem types like ext2/3 or NTFS, which can be useful if "
26454 "you want to attach these filesystems to existing virtual machines (eg. to "
26455 "import large amounts of read-only data to a VM)."
26459 #: ../tools/virt-make-fs.pl:57
26460 msgid "Basic usage is:"
26464 #: ../tools/virt-make-fs.pl:59
26467 " virt-make-fs input output\n"
26472 #: ../tools/virt-make-fs.pl:61
26474 "where C<input> is either a directory containing files that you want to add, "
26475 "or a tar archive (either uncompressed tar or gzip-compressed tar); and "
26476 "C<output> is a disk image. The input type is detected automatically. The "
26477 "output disk image defaults to a raw ext2 image unless you specify extra "
26478 "flags (see L</OPTIONS> below)."
26482 #: ../tools/virt-make-fs.pl:67
26483 msgid "EXTRA SPACE"
26487 #: ../tools/virt-make-fs.pl:69
26489 "Unlike formats such as tar and squashfs, a filesystem does not \"just fit\" "
26490 "the files that it contains, but might have extra space. Depending on how "
26491 "you are going to use the output, you might think this extra space is wasted "
26492 "and want to minimize it, or you might want to leave space so that more files "
26493 "can be added later. Virt-make-fs defaults to minimizing the extra space, "
26494 "but you can use the C<--size> flag to leave space in the filesystem if you "
26499 #: ../tools/virt-make-fs.pl:77
26501 "An alternative way to leave extra space but not make the output image any "
26502 "bigger is to use an alternative disk image format (instead of the default "
26503 "\"raw\" format). Using C<--format=qcow2> will use the native QEmu/KVM qcow2 "
26504 "image format (check your hypervisor supports this before using it). This "
26505 "allows you to choose a large C<--size> but the extra space won't actually be "
26506 "allocated in the image until you try to store something in it."
26510 #: ../tools/virt-make-fs.pl:85
26512 "Don't forget that you can also use local commands including L<resize2fs(8)> "
26513 "and L<virt-resize(1)> to resize existing filesystems, or rerun virt-make-"
26514 "resize to build another image from scratch."
26518 #: ../tools/virt-make-fs.pl:89 ../tools/virt-make-fs.pl:123
26519 #: ../tools/virt-make-fs.pl:142
26524 #: ../tools/virt-make-fs.pl:91
26527 " virt-make-fs --format=qcow2 --size=+200M input output.img\n"
26532 #: ../tools/virt-make-fs.pl:93
26533 msgid "FILESYSTEM TYPE"
26537 #: ../tools/virt-make-fs.pl:95
26539 "The default filesystem type is C<ext2>. Just about any filesystem type that "
26540 "libguestfs supports can be used (but I<not> read-only formats like "
26541 "ISO9660). Here are some of the more common choices:"
26545 #: ../tools/virt-make-fs.pl:101
26550 #: ../tools/virt-make-fs.pl:103
26552 "Note that ext3 filesystems contain a journal, typically 1-32 MB in size. If "
26553 "you are not going to use the filesystem in a way that requires the journal, "
26554 "then this is just wasted overhead."
26558 #: ../tools/virt-make-fs.pl:107
26559 msgid "I<ntfs> or I<vfat>"
26563 #: ../tools/virt-make-fs.pl:109
26564 msgid "Useful if exporting data to a Windows guest."
26568 #: ../tools/virt-make-fs.pl:111
26570 "I<Note for vfat>: The tar archive or local directory must only contain files "
26571 "which are owned by root (ie. UID:GID = 0:0). The reason is that the tar "
26572 "program running within libguestfs is unable to change the ownership of non-"
26573 "root files, since vfat itself does not support this."
26577 #: ../tools/virt-make-fs.pl:116
26582 #: ../tools/virt-make-fs.pl:118
26584 "Lower overhead than C<ext2>, but certain limitations on filename length and "
26585 "total filesystem size."
26589 #: ../tools/virt-make-fs.pl:125
26592 " virt-make-fs --type=minix input minixfs.img\n"
26597 #: ../tools/virt-make-fs.pl:127
26598 msgid "TO PARTITION OR NOT TO PARTITION"
26602 #: ../tools/virt-make-fs.pl:129
26603 msgid "Optionally virt-make-fs can add a partition table to the output disk."
26607 #: ../tools/virt-make-fs.pl:131
26609 "Adding a partition can make the disk image more compatible with certain "
26610 "virtualized operating systems which don't expect to see a filesystem "
26611 "directly located on a block device (Linux doesn't care and will happily "
26612 "handle both types)."
26616 #: ../tools/virt-make-fs.pl:136
26618 "On the other hand, if you have a partition table then the output image is no "
26619 "longer a straight filesystem. For example you cannot run L<fsck(8)> "
26620 "directly on a partitioned disk image. (However libguestfs tools such as "
26621 "L<guestfish(1)> and L<virt-resize(1)> can still be used)."
26625 #: ../tools/virt-make-fs.pl:144
26626 msgid "Add an MBR partition:"
26630 #: ../tools/virt-make-fs.pl:146
26633 " virt-make-fs --partition -- input disk.img\n"
26638 #: ../tools/virt-make-fs.pl:148
26640 "If the output disk image could be terabyte-sized or larger, it's better to "
26641 "use an EFI/GPT-compatible partition table:"
26645 #: ../tools/virt-make-fs.pl:151
26648 " virt-make-fs --partition=gpt --size=+4T --format=qcow2 input disk.img\n"
26653 #: ../tools/virt-make-fs.pl:179
26654 msgid "Enable debugging information."
26658 #: ../tools/virt-make-fs.pl:185
26659 msgid "B<--size=E<lt>NE<gt>>"
26663 #: ../tools/virt-make-fs.pl:187
26664 msgid "B<--size=+E<lt>NE<gt>>"
26668 #: ../tools/virt-make-fs.pl:189
26669 msgid "B<-s E<lt>NE<gt>>"
26673 #: ../tools/virt-make-fs.pl:191
26674 msgid "B<-s +E<lt>NE<gt>>"
26678 #: ../tools/virt-make-fs.pl:193
26680 "Use the C<--size> (or C<-s>) option to choose the size of the output image."
26684 #: ../tools/virt-make-fs.pl:196
26686 "If this option is I<not> given, then the output image will be just large "
26687 "enough to contain all the files, with not much wasted space."
26691 #: ../tools/virt-make-fs.pl:199
26693 "To choose a fixed size output disk, specify an absolute number followed by b/"
26694 "K/M/G/T/P/E to mean bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, "
26695 "Petabytes or Exabytes. This must be large enough to contain all the input "
26696 "files, else you will get an error."
26700 #: ../tools/virt-make-fs.pl:204
26702 "To leave extra space, specify C<+> (plus sign) and a number followed by b/K/"
26703 "M/G/T/P/E to mean bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, "
26704 "Petabytes or Exabytes. For example: C<--size=+200M> means enough space for "
26705 "the input files, and (approximately) an extra 200 MB free space."
26709 #: ../tools/virt-make-fs.pl:210
26711 "Note that virt-make-fs estimates free space, and therefore will not produce "
26712 "filesystems containing precisely the free space requested. (It is much more "
26713 "expensive and time-consuming to produce a filesystem which has precisely the "
26714 "desired free space)."
26718 #: ../tools/virt-make-fs.pl:219
26719 msgid "B<--format=E<lt>fmtE<gt>>"
26723 #: ../tools/virt-make-fs.pl:221
26724 msgid "B<-F E<lt>fmtE<gt>>"
26728 #: ../tools/virt-make-fs.pl:223
26729 msgid "Choose the output disk image format."
26733 #: ../tools/virt-make-fs.pl:225
26734 msgid "The default is C<raw> (raw disk image)."
26738 #: ../tools/virt-make-fs.pl:227
26740 "For other choices, see the L<qemu-img(1)> manpage. The only other choice "
26741 "that would really make sense here is C<qcow2>."
26745 #: ../tools/virt-make-fs.pl:234
26746 msgid "B<--type=E<lt>fsE<gt>>"
26750 #: ../tools/virt-make-fs.pl:236
26751 msgid "B<-t E<lt>fsE<gt>>"
26755 #: ../tools/virt-make-fs.pl:238
26756 msgid "Choose the output filesystem type."
26760 #: ../tools/virt-make-fs.pl:240
26761 msgid "The default is C<ext2>."
26765 #: ../tools/virt-make-fs.pl:242
26767 "Any filesystem which is supported read-write by libguestfs can be used here."
26771 #: ../tools/virt-make-fs.pl:249
26772 msgid "B<--partition>"
26776 #: ../tools/virt-make-fs.pl:251
26777 msgid "B<--partition=E<lt>parttypeE<gt>>"
26781 #: ../tools/virt-make-fs.pl:253
26783 "If specified, this flag adds an MBR partition table to the output disk image."
26787 #: ../tools/virt-make-fs.pl:256
26789 "You can change the partition table type, eg. C<--partition=gpt> for large "
26794 #: ../tools/virt-make-fs.pl:259
26796 "Note that if you just use a lonesome C<--partition>, the Perl option parser "
26797 "might consider the next parameter to be the partition type. For example:"
26801 #: ../tools/virt-make-fs.pl:263
26804 " virt-make-fs --partition input.tar ...\n"
26809 #: ../tools/virt-make-fs.pl:265
26811 "would cause virt-make-fs to think you wanted to use a partition type of "
26812 "C<input.tar> which is completely wrong. To avoid this, use C<--> (a double "
26813 "dash) between options and the input file argument:"
26817 #: ../tools/virt-make-fs.pl:269
26820 " virt-make-fs --partition -- input.tar ...\n"
26825 #: ../tools/virt-make-fs.pl:529
26827 "L<guestfish(1)>, L<virt-resize(1)>, L<virt-tar(1)>, L<mkisofs(1)>, "
26828 "L<genisoimage(1)>, L<mksquashfs(1)>, L<mke2fs(8)>, L<resize2fs(8)>, L<guestfs"
26829 "(3)>, L<Sys::Guestfs(3)>, L<http://libguestfs.org/>."
26833 #: ../tools/virt-make-fs.pl:546
26836 " export LIBGUESTFS_DEBUG=1\n"
26837 " virt-make-fs --debug [...] > /tmp/virt-make-fs.log 2>&1\n"
26842 #: ../tools/virt-make-fs.pl:549
26844 "Attach /tmp/virt-make-fs.log to a new bug report at L<https://bugzilla."
26849 #: ../tools/virt-list-partitions.pl:32
26851 "virt-list-partitions - List partitions in a virtual machine or disk image"
26855 #: ../tools/virt-list-partitions.pl:36
26858 " virt-list-partitions [--options] domname\n"
26863 #: ../tools/virt-list-partitions.pl:38
26866 " virt-list-partitions [--options] disk.img [disk.img ...]\n"
26871 #: ../tools/virt-list-partitions.pl:42
26873 "C<virt-list-partitions> is a command line tool to list the partitions that "
26874 "are contained in a virtual machine or disk image. It is mainly useful as a "
26875 "first step to using L<virt-resize(1)>."
26879 #: ../tools/virt-list-partitions.pl:47
26881 "C<virt-list-partitions> is just a simple wrapper around L<libguestfs(3)> "
26882 "functionality. For more complex cases you should look at the L<guestfish(1)"
26887 #: ../tools/virt-list-partitions.pl:87
26888 msgid "B<-h> | B<--human-readable>"
26892 #: ../tools/virt-list-partitions.pl:89
26893 msgid "Show sizes in human-readable form (eg. \"1G\")."
26897 #: ../tools/virt-list-partitions.pl:97
26899 "With this option, C<virt-list-partitions> displays the type and size of each "
26900 "partition too (where \"type\" means C<ext3>, C<pv> etc.)"
26904 #: ../tools/virt-list-partitions.pl:104
26905 msgid "B<-t> | B<--total>"
26909 #: ../tools/virt-list-partitions.pl:106
26911 "Display the total size of each block device (as a separate row or rows)."
26915 #: ../tools/virt-list-partitions.pl:231
26917 "L<guestfs(3)>, L<guestfish(1)>, L<virt-list-filesystems(1)>, L<virt-resize(1)"
26918 ">, L<Sys::Guestfs(3)>, L<Sys::Guestfs::Lib(3)>, L<Sys::Virt(3)>, L<http://"
26919 "libguestfs.org/>."