# SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR Free Software Foundation, Inc. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: libguestfs@redhat.com\n" "POT-Creation-Date: 2011-03-08 16:20+0000\n" "PO-Revision-Date: 2010-09-02 14:46+0100\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:3 ../fish/guestfish.pod:3 #: ../test-tool/libguestfs-test-tool.pod:3 ../fuse/guestmount.pod:3 #: ../tools/virt-edit.pl:32 ../tools/virt-win-reg.pl:35 #: ../tools/virt-resize.pl:40 ../tools/virt-list-filesystems.pl:30 #: ../tools/virt-tar.pl:31 ../tools/virt-make-fs.pl:35 #: ../tools/virt-list-partitions.pl:30 msgid "NAME" msgstr "名前" # type: textblock #. type: textblock #: ../src/guestfs.pod:5 msgid "guestfs - Library for accessing and modifying virtual machine images" msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:7 ../fish/guestfish.pod:7 #: ../test-tool/libguestfs-test-tool.pod:7 ../fuse/guestmount.pod:7 #: ../tools/virt-edit.pl:36 ../tools/virt-win-reg.pl:39 #: ../tools/virt-resize.pl:44 ../tools/virt-list-filesystems.pl:34 #: ../tools/virt-tar.pl:35 ../tools/virt-make-fs.pl:39 #: ../tools/virt-list-partitions.pl:34 msgid "SYNOPSIS" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:9 #, no-wrap msgid "" " #include \n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:11 #, no-wrap msgid "" " guestfs_h *g = guestfs_create ();\n" " guestfs_add_drive (g, \"guest.img\");\n" " guestfs_launch (g);\n" " guestfs_mount (g, \"/dev/sda1\", \"/\");\n" " guestfs_touch (g, \"/hello\");\n" " guestfs_umount (g, \"/\");\n" " guestfs_close (g);\n" "\n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:19 #, no-wrap msgid "" " cc prog.c -o prog -lguestfs\n" "or:\n" " cc prog.c -o prog `pkg-config libguestfs --cflags --libs`\n" "\n" msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:23 ../fish/guestfish.pod:30 #: ../test-tool/libguestfs-test-tool.pod:11 ../fuse/guestmount.pod:20 #: ../tools/virt-edit.pl:50 ../tools/virt-win-reg.pl:63 #: ../tools/virt-resize.pl:50 ../tools/virt-list-filesystems.pl:40 #: ../tools/virt-tar.pl:77 ../tools/virt-make-fs.pl:47 #: ../tools/virt-list-partitions.pl:40 msgid "DESCRIPTION" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:25 msgid "" "Libguestfs is a library for accessing and modifying guest disk images. " "Amongst the things this is good for: making batch configuration changes to " "guests, getting disk used/free statistics (see also: virt-df), migrating " "between virtualization systems (see also: virt-p2v), performing partial " "backups, performing partial guest clones, cloning guests and changing " "registry/UUID/hostname info, and much else besides." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:33 msgid "" "Libguestfs uses Linux kernel and qemu code, and can access any type of guest " "filesystem that Linux and qemu can, including but not limited to: ext2/3/4, " "btrfs, FAT and NTFS, LVM, many different disk partition schemes, qcow, " "qcow2, vmdk." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:38 msgid "" "Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, " "what filesystem is in each LV, etc.). It can also run commands in the " "context of the guest. Also you can access filesystems over FUSE." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:43 msgid "" "Libguestfs is a library that can be linked with C and C++ management " "programs (or management programs written in OCaml, Perl, Python, Ruby, Java, " "PHP, Haskell or C#). You can also use it from shell scripts or the command " "line." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:48 msgid "" "You don't need to be root to use libguestfs, although obviously you do need " "enough permissions to access the disk images." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:51 msgid "" "Libguestfs is a large API because it can do many things. For a gentle " "introduction, please read the L section next." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:54 msgid "" "There are also some example programs in the L manual " "page." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:57 msgid "API OVERVIEW" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:59 msgid "" "This section provides a gentler overview of the libguestfs API. We also try " "to group API calls together, where that may not be obvious from reading " "about the individual calls in the main section of this manual." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:64 msgid "HANDLES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:66 msgid "" "Before you can use libguestfs calls, you have to create a handle. Then you " "must add at least one disk image to the handle, followed by launching the " "handle, then performing whatever operations you want, and finally closing " "the handle. By convention we use the single letter C for the name of the " "handle variable, although of course you can use any name you want." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:73 msgid "The general structure of all libguestfs-using programs looks like this:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:76 #, no-wrap msgid "" " guestfs_h *g = guestfs_create ();\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:78 #, no-wrap msgid "" " /* Call guestfs_add_drive additional times if there are\n" " * multiple disk images.\n" " */\n" " guestfs_add_drive (g, \"guest.img\");\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:83 #, no-wrap msgid "" " /* Most manipulation calls won't work until you've launched\n" " * the handle 'g'. You have to do this _after_ adding drives\n" " * and _before_ other commands.\n" " */\n" " guestfs_launch (g);\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:89 #, no-wrap msgid "" " /* Now you can examine what partitions, LVs etc are available.\n" " */\n" " char **partitions = guestfs_list_partitions (g);\n" " char **logvols = guestfs_lvs (g);\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:94 #, no-wrap msgid "" " /* To access a filesystem in the image, you must mount it.\n" " */\n" " guestfs_mount (g, \"/dev/sda1\", \"/\");\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:98 #, no-wrap msgid "" " /* Now you can perform filesystem actions on the guest\n" " * disk image.\n" " */\n" " guestfs_touch (g, \"/hello\");\n" "\n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:103 #, no-wrap msgid "" " /* This is only needed for libguestfs < 1.5.24. Since then\n" " * it is done automatically when you close the handle. See\n" " * discussion of autosync in this page.\n" " */\n" " guestfs_sync (g);\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:109 #, no-wrap msgid "" " /* Close the handle 'g'. */\n" " guestfs_close (g);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:112 msgid "" "The code above doesn't include any error checking. In real code you should " "check return values carefully for errors. In general all functions that " "return integers return C<-1> on error, and all functions that return " "pointers return C on error. See section L below for " "how to handle errors, and consult the documentation for each function call " "below to see precisely how they return error indications. See L for fully worked examples." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:121 msgid "DISK IMAGES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:123 msgid "" "The image filename (C<\"guest.img\"> in the example above) could be a disk " "image from a virtual machine, a L copy of a physical hard disk, an " "actual block device, or simply an empty file of zeroes that you have created " "through L. Libguestfs lets you do useful things to all " "of these." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:129 msgid "" "The call you should use in modern code for adding drives is L. To add a disk image, allowing writes, and " "specifying that the format is raw, do:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:133 #, no-wrap msgid "" " guestfs_add_drive_opts (g, filename,\n" " GUESTFS_ADD_DRIVE_OPTS_FORMAT, \"raw\",\n" " -1);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:137 msgid "You can add a disk read-only using:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:139 #, no-wrap msgid "" " guestfs_add_drive_opts (g, filename,\n" " GUESTFS_ADD_DRIVE_OPTS_FORMAT, \"raw\",\n" " GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,\n" " -1);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:144 msgid "" "or by calling the older function L. In either case " "libguestfs won't modify the file." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:147 msgid "" "Be extremely cautious if the disk image is in use, eg. if it is being used " "by a virtual machine. Adding it read-write will almost certainly cause disk " "corruption, but adding it read-only is safe." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:151 msgid "" "You must add at least one disk image, and you may add multiple disk images. " "In the API, the disk images are usually referred to as C (for the " "first one you added), C (for the second one you added), etc." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:156 msgid "" "Once L has been called you cannot add any more images. You " "can call L to get a list of the device names, in the " "order that you added them. See also L below." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:161 msgid "MOUNTING" msgstr "" #. type: textblock #: ../src/guestfs.pod:163 msgid "" "Before you can read or write files, create directories and so on in a disk " "image that contains filesystems, you have to mount those filesystems using " "L or L. If you already know that " "a disk image contains (for example) one partition with a filesystem on that " "partition, then you can mount it directly:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:170 #, no-wrap msgid "" " guestfs_mount_options (g, \"\", \"/dev/sda1\", \"/\");\n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:172 msgid "" "where C means literally the first partition (C<1>) of the first " "disk image that we added (C). If the disk contains Linux LVM2 " "logical volumes you could refer to those instead (eg. C). Note " "that these are libguestfs virtual devices, and are nothing to do with host " "devices." msgstr "" #. type: textblock #: ../src/guestfs.pod:178 msgid "" "If you are given a disk image and you don't know what it contains then you " "have to find out. Libguestfs can do that too: use L and L to list possible partitions and " "LVs, and either try mounting each to see what is mountable, or else examine " "them with L or L. To list just " "filesystems, use L." msgstr "" #. type: textblock #: ../src/guestfs.pod:186 msgid "" "Libguestfs also has a set of APIs for inspection of unknown disk images (see " "L below). But you might find it easier to look at higher level " "programs built on top of libguestfs, in particular L." msgstr "" #. type: textblock #: ../src/guestfs.pod:191 msgid "" "To mount a filesystem read-only, use L. There are " "several other variations of the C call." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:194 msgid "FILESYSTEM ACCESS AND MODIFICATION" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:196 msgid "" "The majority of the libguestfs API consists of fairly low-level calls for " "accessing and modifying the files, directories, symlinks etc on mounted " "filesystems. There are over a hundred such calls which you can find listed " "in detail below in this man page, and we don't even pretend to cover them " "all in this overview." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:202 msgid "" "Specify filenames as full paths, starting with C<\"/\"> and including the " "mount point." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:205 msgid "" "For example, if you mounted a filesystem at C<\"/\"> and you want to read " "the file called C<\"etc/passwd\"> then you could do:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:208 #, no-wrap msgid "" " char *data = guestfs_cat (g, \"/etc/passwd\");\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:210 msgid "" "This would return C as a newly allocated buffer containing the full " "content of that file (with some conditions: see also L below), " "or C if there was an error." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:214 msgid "" "As another example, to create a top-level directory on that filesystem " "called C<\"var\"> you would do:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:217 #, no-wrap msgid "" " guestfs_mkdir (g, \"/var\");\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:219 msgid "To create a symlink you could do:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:221 #, no-wrap msgid "" " guestfs_ln_s (g, \"/etc/init.d/portmap\",\n" " \"/etc/rc3.d/S30portmap\");\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:224 msgid "" "Libguestfs will reject attempts to use relative paths and there is no " "concept of a current working directory." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:227 msgid "" "Libguestfs can return errors in many situations: for example if the " "filesystem isn't writable, or if a file or directory that you requested " "doesn't exist. If you are using the C API (documented here) you have to " "check for those error conditions after each call. (Other language bindings " "turn these errors into exceptions)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:233 msgid "" "File writes are affected by the per-handle umask, set by calling L and defaulting to 022. See L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:236 msgid "PARTITIONING" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:238 msgid "" "Libguestfs contains API calls to read, create and modify partition tables on " "disk images." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:241 msgid "" "In the common case where you want to create a single partition covering the " "whole disk, you should use the L call:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:245 #, no-wrap msgid "" " const char *parttype = \"mbr\";\n" " if (disk_is_larger_than_2TB)\n" " parttype = \"gpt\";\n" " guestfs_part_disk (g, \"/dev/sda\", parttype);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:250 msgid "" "Obviously this effectively wipes anything that was on that disk image before." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:253 msgid "LVM2" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:255 msgid "" "Libguestfs provides access to a large part of the LVM2 API, such as L and L. It won't make much sense unless " "you familiarize yourself with the concepts of physical volumes, volume " "groups and logical volumes." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:260 msgid "" "This author strongly recommends reading the LVM HOWTO, online at L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:263 msgid "DOWNLOADING" msgstr "" #. type: textblock #: ../src/guestfs.pod:265 msgid "" "Use L to download small, text only files. This call is " "limited to files which are less than 2 MB and which cannot contain any ASCII " "NUL (C<\\0>) characters. However the API is very simple to use." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:269 msgid "" "L can be used to read files which contain arbitrary 8 " "bit data, since it returns a (pointer, size) pair. However it is still " "limited to \"small\" files, less than 2 MB." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:273 msgid "" "L can be used to download any file, with no limits on " "content or size (even files larger than 4 GB)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:276 msgid "" "To download multiple files, see L and L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:279 msgid "UPLOADING" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:281 msgid "" "It's often the case that you want to write a file or files to the disk image." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:284 msgid "" "To write a small file with fixed content, use L. To create " "a file of all zeroes, use L (sparse) or L (with all disk blocks allocated). There are a variety " "of other functions for creating test files, for example L and " "L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:290 msgid "" "To upload a single file, use L. This call has no limits on " "file content or size (even files larger than 4 GB)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:293 msgid "" "To upload multiple files, see L and L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:295 msgid "" "However the fastest way to upload I is to " "turn them into a squashfs or CD ISO (see L and L), then attach this using L. If you add the drive " "in a predictable way (eg. adding it last after all other drives) then you " "can get the device name from L and mount it directly " "using L. Note that squashfs images are sometimes non-" "portable between kernel versions, and they don't support labels or UUIDs. " "If you want to pre-build an image or you need to mount it using a label or " "UUID, use an ISO image instead." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:306 msgid "COPYING" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:308 msgid "" "There are various different commands for copying between files and devices " "and in and out of the guest filesystem. These are summarised in the table " "below." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:314 msgid "B to B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:316 msgid "" "Use L to copy a single file, or L to copy " "directories recursively." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:319 msgid "B to B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:321 msgid "" "Use L which efficiently uses L to copy between files and " "devices in the guest." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:324 msgid "Example: duplicate the contents of an LV:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:326 #, no-wrap msgid "" " guestfs_dd (g, \"/dev/VG/Original\", \"/dev/VG/Copy\");\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:328 msgid "" "The destination (C) must be at least as large as the source " "(C). To copy less than the whole source device, use L." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:332 msgid "B to B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:334 msgid "Use L. See L above." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:336 msgid "B to B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:338 msgid "Use L. See L above." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:342 msgid "UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:344 msgid "" "Calls like L, L, L, L etc appear to only take filenames as arguments, so it " "appears you can only upload and download to files. However many Un*x-like " "hosts let you use the special device files C, C, C and C to read and write from stdin, stdout, stderr, " "and arbitrary file descriptor N." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:352 msgid "For example, L writes its output to stdout by doing:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:355 #, no-wrap msgid "" " guestfs_download (g, filename, \"/dev/stdout\");\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:357 msgid "and you can write tar output to a pipe C by doing:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:359 #, no-wrap msgid "" " char devfd[64];\n" " snprintf (devfd, sizeof devfd, \"/dev/fd/%d\", fd);\n" " guestfs_tar_out (g, \"/\", devfd);\n" "\n" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:363 msgid "LISTING FILES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:365 msgid "" "L is just designed for humans to read (mainly when using the " "L-equivalent command C)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:368 msgid "" "L is a quick way to get a list of files in a directory from " "programs, as a flat list of strings." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:371 msgid "" "L is a programmatic way to get a list of files in a " "directory, plus additional information about each one. It is more " "equivalent to using the L call on a local filesystem." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:375 msgid "" "L and L can be used to recursively list files." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:378 msgid "RUNNING COMMANDS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:380 msgid "" "Although libguestfs is primarily an API for manipulating files inside guest " "images, we also provide some limited facilities for running commands inside " "guests." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:384 msgid "There are many limitations to this:" msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:388 ../src/guestfs.pod:393 ../src/guestfs.pod:398 #: ../src/guestfs.pod:402 ../src/guestfs.pod:407 ../src/guestfs.pod:411 #: ../src/guestfs.pod:416 ../src/guestfs.pod:421 ../src/guestfs.pod:1088 #: ../src/guestfs.pod:1092 ../src/guestfs.pod:1096 ../src/guestfs.pod:1101 #: ../src/guestfs.pod:1109 ../src/guestfs.pod:1128 ../src/guestfs.pod:1136 #: ../src/guestfs.pod:1158 ../src/guestfs.pod:1162 ../src/guestfs.pod:1166 #: ../src/guestfs.pod:1170 ../src/guestfs.pod:1174 ../src/guestfs.pod:1178 #: ../src/guestfs.pod:1660 ../src/guestfs.pod:1665 ../src/guestfs.pod:1669 #: ../src/guestfs.pod:1779 ../src/guestfs.pod:1784 ../src/guestfs.pod:1788 #: ../src/guestfs.pod:2140 ../src/guestfs.pod:2146 ../src/guestfs.pod:2151 #: ../src/guestfs.pod:2157 ../src/guestfs.pod:2622 ../src/guestfs.pod:2626 #: ../src/guestfs.pod:2630 ../src/guestfs.pod:2634 #: ../src/guestfs-actions.pod:15 ../src/guestfs-actions.pod:22 #: ../src/guestfs-actions.pod:577 ../src/guestfs-actions.pod:585 #: ../src/guestfs-actions.pod:592 ../src/guestfs-actions.pod:599 #: ../src/guestfs-actions.pod:1595 ../src/guestfs-actions.pod:1599 #: ../src/guestfs-actions.pod:1603 ../src/guestfs-actions.pod:1607 #: ../src/guestfs-actions.pod:1615 ../src/guestfs-actions.pod:1619 #: ../src/guestfs-actions.pod:1623 ../src/guestfs-actions.pod:1633 #: ../src/guestfs-actions.pod:1637 ../src/guestfs-actions.pod:1641 #: ../src/guestfs-actions.pod:1779 ../src/guestfs-actions.pod:1783 #: ../src/guestfs-actions.pod:1788 ../src/guestfs-actions.pod:1793 #: ../src/guestfs-actions.pod:1854 ../src/guestfs-actions.pod:1858 #: ../src/guestfs-actions.pod:1863 ../fish/guestfish.pod:432 #: ../fish/guestfish.pod:436 ../fish/guestfish.pod:440 #: ../fish/guestfish.pod:444 ../fish/guestfish-actions.pod:13 #: ../fish/guestfish-actions.pod:20 ../fish/guestfish-actions.pod:380 #: ../fish/guestfish-actions.pod:388 ../fish/guestfish-actions.pod:395 #: ../fish/guestfish-actions.pod:402 ../fish/guestfish-actions.pod:1072 #: ../fish/guestfish-actions.pod:1076 ../fish/guestfish-actions.pod:1080 #: ../fish/guestfish-actions.pod:1084 ../fish/guestfish-actions.pod:1092 #: ../fish/guestfish-actions.pod:1096 ../fish/guestfish-actions.pod:1100 #: ../fish/guestfish-actions.pod:1110 ../fish/guestfish-actions.pod:1114 #: ../fish/guestfish-actions.pod:1118 ../fish/guestfish-actions.pod:1208 #: ../fish/guestfish-actions.pod:1212 ../fish/guestfish-actions.pod:1217 #: ../fish/guestfish-actions.pod:1222 ../fish/guestfish-actions.pod:1264 #: ../fish/guestfish-actions.pod:1268 ../fish/guestfish-actions.pod:1273 #: ../tools/virt-win-reg.pl:536 ../tools/virt-win-reg.pl:542 #: ../tools/virt-win-reg.pl:548 ../tools/virt-resize.pl:345 #: ../tools/virt-resize.pl:350 ../tools/virt-resize.pl:360 msgid "*" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:390 msgid "" "The kernel version that the command runs under will be different from what " "it expects." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:395 msgid "" "If the command needs to communicate with daemons, then most likely they " "won't be running." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:400 msgid "The command will be running in limited memory." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:404 msgid "" "The network may not be available unless you enable it (see L)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:409 msgid "Only supports Linux guests (not Windows, BSD, etc)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:413 msgid "" "Architecture limitations (eg. won't work for a PPC guest on an X86 host)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:418 msgid "" "For SELinux guests, you may need to enable SELinux and load policy first. " "See L in this manpage." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:423 msgid "" "I It is not safe to run commands from untrusted, possibly " "malicious guests. These commands may attempt to exploit your program by " "sending unexpected output. They could also try to exploit the Linux kernel " "or qemu provided by the libguestfs appliance. They could use the network " "provided by the libguestfs appliance to bypass ordinary network partitions " "and firewalls. They could use the elevated privileges or different SELinux " "context of your program to their advantage." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:432 msgid "" "A secure alternative is to use libguestfs to install a \"firstboot\" script " "(a script which runs when the guest next boots normally), and to have this " "script run the commands you want in the normal context of the running guest, " "network security and so on. For information about other security issues, " "see L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:440 msgid "" "The two main API calls to run commands are L and L (there are also variations)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:443 msgid "" "The difference is that L runs commands using the shell, so any " "shell globs, redirections, etc will work." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:446 msgid "CONFIGURATION FILES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:448 msgid "" "To read and write configuration files in Linux guest filesystems, we " "strongly recommend using Augeas. For example, Augeas understands how to " "read and write, say, a Linux shadow password file or X.org configuration " "file, and so avoids you having to write that code." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:453 msgid "" "The main Augeas calls are bound through the C APIs. We don't " "document Augeas itself here because there is excellent documentation on the " "L website." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:457 msgid "" "If you don't want to use Augeas (you fool!) then try calling L to get the file as a list of lines which you can iterate " "over." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:461 msgid "SELINUX" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:463 msgid "" "We support SELinux guests. To ensure that labeling happens correctly in " "SELinux guests, you need to enable SELinux and load the guest's policy:" msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:469 ../src/guestfs.pod:1281 ../src/guestfs.pod:1412 #: ../src/guestfs.pod:2185 msgid "1." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:471 msgid "Before launching, do:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:473 #, no-wrap msgid "" " guestfs_set_selinux (g, 1);\n" "\n" msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:475 ../src/guestfs.pod:1285 ../src/guestfs.pod:1416 #: ../src/guestfs.pod:2210 msgid "2." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:477 msgid "" "After mounting the guest's filesystem(s), load the policy. This is best " "done by running the L command in the guest itself:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:481 #, no-wrap msgid "" " guestfs_sh (g, \"/usr/sbin/load_policy\");\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:483 msgid "" "(Older versions of C require you to specify the name of the " "policy file)." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:486 ../src/guestfs.pod:1422 msgid "3." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:488 msgid "" "Optionally, set the security context for the API. The correct security " "context to use can only be known by inspecting the guest. As an example:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:492 #, no-wrap msgid "" " guestfs_setcon (g, \"unconfined_u:unconfined_r:unconfined_t:s0\");\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:496 msgid "This will work for running commands and editing existing files." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:498 msgid "" "When new files are created, you may need to label them explicitly, for " "example by running the external command C." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:502 msgid "UMASK" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:504 msgid "" "Certain calls are affected by the current file mode creation mask (the " "\"umask\"). In particular ones which create files or directories, such as " "L, L or L. This affects " "either the default mode that the file is created with or modifies the mode " "that you supply." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:510 msgid "" "The default umask is C<022>, so files are created with modes such as C<0644> " "and directories with C<0755>." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:513 msgid "" "There are two ways to avoid being affected by umask. Either set umask to 0 " "(call C early after launching). Or call L after creating each file or directory." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:517 msgid "For more information about umask, see L." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:519 ../fish/guestfish.pod:751 msgid "ENCRYPTED DISKS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:521 msgid "" "Libguestfs allows you to access Linux guests which have been encrypted using " "whole disk encryption that conforms to the Linux Unified Key Setup (LUKS) " "standard. This includes nearly all whole disk encryption systems used by " "modern Linux guests." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:527 msgid "" "Use L to identify LUKS-encrypted block devices (it " "returns the string C)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:530 msgid "" "Then open these devices by calling L. Obviously you " "will require the passphrase!" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:533 msgid "" "Opening a LUKS device creates a new device mapper device called C (where C is the string you supply to L). Reads and writes to this mapper device are decrypted " "from and encrypted to the underlying block device respectively." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:539 msgid "" "LVM volume groups on the device can be made visible by calling L followed by L. The logical volume" "(s) can now be mounted in the usual way." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:543 msgid "" "Use the reverse process to close a LUKS device. Unmount any logical volumes " "on it, deactivate the volume groups by caling C. Then close the mapper device by calling L on the C device (I the " "underlying encrypted block device)." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:550 msgid "INSPECTION" msgstr "" #. type: textblock #: ../src/guestfs.pod:552 msgid "" "Libguestfs has APIs for inspecting an unknown disk image to find out if it " "contains operating systems, an install CD or a live CD. (These APIs used to " "be in a separate Perl-only library called L but since " "version 1.5.3 the most frequently used part of this library has been " "rewritten in C and moved into the core code)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:559 msgid "" "Add all disks belonging to the unknown virtual machine and call L in the usual way." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:562 msgid "" "Then call L. This function uses other libguestfs calls " "and certain heuristics, and returns a list of operating systems that were " "found. An empty list means none were found. A single element is the root " "filesystem of the operating system. For dual- or multi-boot guests, " "multiple roots can be returned, each one corresponding to a separate " "operating system. (Multi-boot virtual machines are extremely rare in the " "world of virtualization, but since this scenario can happen, we have built " "libguestfs to deal with it.)" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:571 msgid "" "For each root, you can then call various C functions " "to get additional details about that operating system. For example, call L to return the string C or C for " "Windows and Linux-based operating systems respectively." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:577 msgid "" "Un*x-like and Linux-based operating systems usually consist of several " "filesystems which are mounted at boot time (for example, a separate boot " "partition mounted on C). The inspection rules are able to detect how " "filesystems correspond to mount points. Call " "C to get this mapping. It might return a " "hash table like this example:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:584 #, no-wrap msgid "" " /boot => /dev/sda1\n" " / => /dev/vg_guest/lv_root\n" " /usr => /dev/vg_guest/lv_usr\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:588 msgid "" "The caller can then make calls to L to mount the " "filesystems as suggested." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:591 msgid "" "Be careful to mount filesystems in the right order (eg. C before C). Sorting the keys of the hash by length, shortest first, should work." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:595 msgid "" "Inspection currently only works for some common operating systems. " "Contributors are welcome to send patches for other operating systems that we " "currently cannot detect." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:599 msgid "" "Encrypted disks must be opened before inspection. See L " "for more details. The L function just ignores any " "encrypted devices." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:603 msgid "" "A note on the implementation: The call L performs " "inspection and caches the results in the guest handle. Subsequent calls to " "C return this cached information, but I re-" "read the disks. If you change the content of the guest disks, you can redo " "inspection by calling L again. (L works a little differently from the other " "calls and does read the disks. See documentation for that function for " "details)." msgstr "" #. type: =head3 #: ../src/guestfs.pod:612 msgid "INSPECTING INSTALL DISKS" msgstr "" #. type: textblock #: ../src/guestfs.pod:614 msgid "" "Libguestfs (since 1.9.4) can detect some install disks, install CDs, live " "CDs and more." msgstr "" #. type: textblock #: ../src/guestfs.pod:617 msgid "" "Call L to return the format of the operating " "system, which currently can be C (a regular operating system) or " "C (some sort of install disk)." msgstr "" #. type: textblock #: ../src/guestfs.pod:621 msgid "" "Further information is available about the operating system that can be " "installed using the regular inspection APIs like L, L etc." msgstr "" #. type: textblock #: ../src/guestfs.pod:626 msgid "" "Some additional information specific to installer disks is also available " "from the L, L and L calls." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:631 msgid "SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:633 msgid "" "Libguestfs can mount NTFS partitions. It does this using the L driver." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:636 msgid "DRIVE LETTERS AND PATHS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:638 msgid "" "DOS and Windows still use drive letters, and the filesystems are always " "treated as case insensitive by Windows itself, and therefore you might find " "a Windows configuration file referring to a path like C. When the filesystem is mounted in libguestfs, that directory " "might be referred to as C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:644 msgid "" "Drive letter mappings are outside the scope of libguestfs. You have to use " "libguestfs to read the appropriate Windows Registry and configuration files, " "to determine yourself how drives are mapped (see also L and L)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:649 msgid "" "Replacing backslash characters with forward slash characters is also outside " "the scope of libguestfs, but something that you can easily do." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:652 msgid "" "Where we can help is in resolving the case insensitivity of paths. For " "this, call L." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:655 msgid "ACCESSING THE WINDOWS REGISTRY" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:657 msgid "" "Libguestfs also provides some help for decoding Windows Registry \"hive\" " "files, through the library C which is part of the libguestfs project " "although ships as a separate tarball. You have to locate and download the " "hive file(s) yourself, and then pass them to C functions. See also " "the programs L, L, L and L for more help on this issue." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:665 msgid "SYMLINKS ON NTFS-3G FILESYSTEMS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:667 msgid "" "Ntfs-3g tries to rewrite \"Junction Points\" and NTFS \"symbolic links\" to " "provide something which looks like a Linux symlink. The way it tries to do " "the rewriting is described here:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:671 msgid "" "L" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:673 msgid "" "The essential problem is that ntfs-3g simply does not have enough " "information to do a correct job. NTFS links can contain drive letters and " "references to external device GUIDs that ntfs-3g has no way of resolving. " "It is almost certainly the case that libguestfs callers should ignore what " "ntfs-3g does (ie. don't use L on NTFS volumes)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:680 msgid "" "Instead if you encounter a symbolic link on an ntfs-3g filesystem, use L to read the C extended " "attribute, and read the raw reparse data from that (you can find the format " "documented in various places around the web)." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:685 msgid "EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:687 msgid "" "There are other useful extended attributes that can be read from ntfs-3g " "filesystems (using L). See:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:690 msgid "" "L" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:692 msgid "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:694 msgid "" "Although we don't want to discourage you from using the C API, we will " "mention here that the same API is also available in other languages." msgstr "" #. type: textblock #: ../src/guestfs.pod:697 msgid "" "The API is broadly identical in all supported languages. This means that " "the C call C is C<$g-Eadd_drive_ro($file)> " "in Perl, C in Python, and C in " "OCaml. In other words, a straightforward, predictable isomorphism between " "each language." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:703 msgid "" "Error messages are automatically transformed into exceptions if the language " "supports it." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:706 msgid "" "We don't try to \"object orientify\" parts of the API in OO languages, " "although contributors are welcome to write higher level APIs above what we " "provide in their favourite languages if they wish." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:712 msgid "B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:714 msgid "" "You can use the I header file from C++ programs. The C++ API is " "identical to the C API. C++ classes and exceptions are not used." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:718 msgid "B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:720 msgid "" "The C# bindings are highly experimental. Please read the warnings at the " "top of C." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:723 msgid "B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:725 msgid "" "This is the only language binding that is working but incomplete. Only " "calls which return simple integers have been bound in Haskell, and we are " "looking for help to complete this binding." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:729 msgid "B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:731 msgid "" "Full documentation is contained in the Javadoc which is distributed with " "libguestfs." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:734 msgid "B" msgstr "" #. type: textblock #: ../src/guestfs.pod:736 msgid "See L." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:738 msgid "B" msgstr "" #. type: textblock #: ../src/guestfs.pod:740 msgid "See L and L." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:742 msgid "B" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:744 msgid "" "For documentation see C supplied with libguestfs sources or in " "the php-libguestfs package for your distribution." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:747 msgid "The PHP binding only works correctly on 64 bit machines." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:749 msgid "B" msgstr "" #. type: textblock #: ../src/guestfs.pod:751 msgid "See L." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:753 msgid "B" msgstr "" #. type: textblock #: ../src/guestfs.pod:755 msgid "See L." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:757 msgid "B" msgstr "" #. type: textblock #: ../src/guestfs.pod:759 msgid "See L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:763 msgid "LIBGUESTFS GOTCHAS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:765 msgid "" "L: \"A feature of a " "system [...] that works in the way it is documented but is counterintuitive " "and almost invites mistakes.\"" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:769 msgid "" "Since we developed libguestfs and the associated tools, there are several " "things we would have designed differently, but are now stuck with for " "backwards compatibility or other reasons. If there is ever a libguestfs 2.0 " "release, you can expect these to change. Beware of them." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:777 msgid "Autosync / forgetting to sync." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:779 msgid "" "When modifying a filesystem from C or another language, you B unmount " "all filesystems and call L explicitly before you close the " "libguestfs handle. You can also call:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:783 #, no-wrap msgid "" " guestfs_set_autosync (g, 1);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:785 msgid "" "to have the unmount/sync done automatically for you when the handle 'g' is " "closed. (This feature is called \"autosync\", L q.v.)" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:789 msgid "" "If you forget to do this, then it is entirely possible that your changes " "won't be written out, or will be partially written, or (very rarely) that " "you'll get disk corruption." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:793 msgid "" "Note that in L autosync is the default. So quick and dirty " "guestfish scripts that forget to sync will work just fine, which can make " "this very puzzling if you are trying to debug a problem." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:797 msgid "" "Update: Autosync is enabled by default for all API users starting from " "libguestfs 1.5.24." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:800 msgid "Mount option C<-o sync> should not be the default." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:802 msgid "" "If you use L, then C<-o sync,noatime> are added implicitly. " "However C<-o sync> does not add any reliability benefit, but does have a " "very large performance impact." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:806 msgid "" "The work around is to use L and set the mount " "options that you actually want to use." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:809 msgid "Read-only should be the default." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:811 msgid "" "In L, I<--ro> should be the default, and you should have to " "specify I<--rw> if you want to make changes to the image." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:814 msgid "This would reduce the potential to corrupt live VM images." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:816 msgid "" "Note that many filesystems change the disk when you just mount and unmount, " "even if you didn't perform any writes. You need to use L to guarantee that the disk is not changed." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:820 msgid "guestfish command line is hard to use." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:822 msgid "" "C doesn't do what people expect (open C for " "examination). It tries to run a guestfish command C which doesn't " "exist, so it fails. In earlier versions of guestfish the error message was " "also unintuitive, but we have corrected this since. Like the Bourne shell, " "we should have used C to run commands." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:829 msgid "guestfish megabyte modifiers don't work right on all commands" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:831 msgid "" "In recent guestfish you can use C<1M> to mean 1 megabyte (and similarly for " "other modifiers). What guestfish actually does is to multiply the number " "part by the modifier part and pass the result to the C API. However this " "doesn't work for a few APIs which aren't expecting bytes, but are already " "expecting some other unit (eg. megabytes)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:838 msgid "The most common is L. The guestfish command:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:840 #, no-wrap msgid "" " lvcreate LV VG 100M\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:842 msgid "" "does not do what you might expect. Instead because L is " "already expecting megabytes, this tries to create a 100 I (100 " "megabytes * megabytes) logical volume. The error message you get from this " "is also a little obscure." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:847 msgid "" "This could be fixed in the generator by specially marking parameters and " "return values which take bytes or other units." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:850 msgid "Ambiguity between devices and paths" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:852 msgid "" "There is a subtle ambiguity in the API between a device name (eg. C) and a similar pathname. A file might just happen to be called " "C in the directory C (consider some non-Unix VM image)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:857 msgid "" "In the current API we usually resolve this ambiguity by having two separate " "calls, for example L and L. " "Some API calls are ambiguous and (incorrectly) resolve the problem by " "detecting if the path supplied begins with C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:863 msgid "" "To avoid both the ambiguity and the need to duplicate some calls, we could " "make paths/devices into structured names. One way to do this would be to " "use a notation like grub (C), although nobody really likes this " "aspect of grub. Another way would be to use a structured type, equivalent " "to this OCaml type:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:869 #, no-wrap msgid "" " type path = Path of string | Device of int | Partition of int * int\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:871 msgid "which would allow you to pass arguments like:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:873 #, no-wrap msgid "" " Path \"/foo/bar\"\n" " Device 1 (* /dev/sdb, or perhaps /dev/sda *)\n" " Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)\n" " Path \"/dev/sdb2\" (* not a device *)\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:878 msgid "" "As you can see there are still problems to resolve even with this " "representation. Also consider how it might work in guestfish." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:883 msgid "PROTOCOL LIMITS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:885 msgid "" "Internally libguestfs uses a message-based protocol to pass API calls and " "their responses to and from a small \"appliance\" (see L for " "plenty more detail about this). The maximum message size used by the " "protocol is slightly less than 4 MB. For some API calls you may need to be " "aware of this limit. The API calls which may be affected are individually " "documented, with a link back to this section of the documentation." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:893 msgid "" "A simple call such as L returns its result (the file data) in " "a simple string. Because this string is at some point internally encoded as " "a message, the maximum size that it can return is slightly under 4 MB. If " "the requested file is larger than this then you will get an error." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:899 msgid "" "In order to transfer large files into and out of the guest filesystem, you " "need to use particular calls that support this. The sections L " "and L document how to do this." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:903 msgid "" "You might also consider mounting the disk image using our FUSE filesystem " "support (L)." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:906 msgid "KEYS AND PASSPHRASES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:908 msgid "" "Certain libguestfs calls take a parameter that contains sensitive key " "material, passed in as a C string." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:911 msgid "" "In the future we would hope to change the libguestfs implementation so that " "keys are L-ed into physical RAM, and thus can never end up in " "swap. However this is I done at the moment, because of the complexity " "of such an implementation." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:916 msgid "" "Therefore you should be aware that any key parameter you pass to libguestfs " "might end up being written out to the swap partition. If this is a concern, " "scrub the swap partition or don't use libguestfs on encrypted devices." msgstr "" # type: =head1 #. type: =head2 #: ../src/guestfs.pod:921 msgid "MULTIPLE HANDLES AND MULTIPLE THREADS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:923 msgid "" "All high-level libguestfs actions are synchronous. If you want to use " "libguestfs asynchronously then you must create a thread." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:926 msgid "" "Only use the handle from a single thread. Either use the handle exclusively " "from one thread, or provide your own mutex so that two threads cannot issue " "calls on the same handle at the same time." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:930 msgid "" "See the graphical program guestfs-browser for one possible architecture for " "multithreaded programs using libvirt and libguestfs." msgstr "" # type: =head1 #. type: =head2 #: ../src/guestfs.pod:933 msgid "PATH" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:935 msgid "" "Libguestfs needs a kernel and initrd.img, which it finds by looking along an " "internal path." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:938 msgid "" "By default it looks for these in the directory C<$libdir/guestfs> (eg. C or C)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:941 msgid "" "Use L or set the environment variable L " "to change the directories that libguestfs will search in. The value is a " "colon-separated list of paths. The current directory is I searched " "unless the path contains an empty element or C<.>. For example " "C would search the current directory and " "then C." msgstr "" # type: =head1 #. type: =head2 #: ../src/guestfs.pod:948 msgid "QEMU WRAPPERS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:950 msgid "" "If you want to compile your own qemu, run qemu from a non-standard location, " "or pass extra arguments to qemu, then you can write a shell-script wrapper " "around qemu." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:954 msgid "" "There is one important rule to remember: you I> as the " "last command in the shell script (so that qemu replaces the shell and " "becomes the direct child of the libguestfs-using program). If you don't do " "this, then the qemu process won't be cleaned up correctly." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:959 msgid "" "Here is an example of a wrapper, where I have built my own copy of qemu from " "source:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:962 #, no-wrap msgid "" " #!/bin/sh -\n" " qemudir=/home/rjones/d/qemu\n" " exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios \"$@\"\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:966 msgid "" "Save this script as C (or wherever), C, and " "then use it by setting the LIBGUESTFS_QEMU environment variable. For " "example:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:970 #, no-wrap msgid "" " LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:972 msgid "" "Note that libguestfs also calls qemu with the -help and -version options in " "order to determine features." msgstr "" #. type: =head2 #: ../src/guestfs.pod:975 msgid "ATTACHING TO RUNNING DAEMONS" msgstr "" #. type: textblock #: ../src/guestfs.pod:977 msgid "" "I This is B and has a tendency to eat " "babies. Use with caution." msgstr "" #. type: textblock #: ../src/guestfs.pod:980 msgid "" "I This section explains how to attach to a running daemon from a " "low level perspective. For most users, simply using virt tools such as " "L with the I<--live> option will \"just work\"." msgstr "" #. type: =head3 #: ../src/guestfs.pod:984 msgid "Using guestfs_set_attach_method" msgstr "" #. type: textblock #: ../src/guestfs.pod:986 msgid "" "By calling L you can change how the library " "connects to the C daemon in L (read L for some background)." msgstr "" #. type: textblock #: ../src/guestfs.pod:990 msgid "" "The normal attach method is C, where a small appliance is created " "containing the daemon, and then the library connects to this." msgstr "" #. type: textblock #: ../src/guestfs.pod:993 msgid "" "Setting attach method to C> (where I is the path of a " "Unix domain socket) causes L to connect to an existing " "daemon over the Unix domain socket." msgstr "" #. type: textblock #: ../src/guestfs.pod:997 msgid "" "The normal use for this is to connect to a running virtual machine that " "contains a C daemon, and send commands so you can read and write " "files inside the live virtual machine." msgstr "" #. type: =head3 #: ../src/guestfs.pod:1001 msgid "Using guestfs_add_domain with live flag" msgstr "" #. type: textblock #: ../src/guestfs.pod:1003 msgid "" "L provides some help for getting the correct attach " "method. If you pass the C option to this function, then (if the " "virtual machine is running) it will examine the libvirt XML looking for a " "virtio-serial channel to connect to:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:1009 #, no-wrap msgid "" " \n" " ...\n" " \n" " ...\n" " \n" " \n" " \n" " \n" " ...\n" " \n" " \n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:1021 msgid "" "L extracts C and sets the attach " "method to C." msgstr "" #. type: textblock #: ../src/guestfs.pod:1024 msgid "" "Some of the libguestfs tools (including guestfish) support a I<--live> " "option which is passed through to L thus allowing you " "to attach to and modify live virtual machines." msgstr "" #. type: textblock #: ../src/guestfs.pod:1028 msgid "" "The virtual machine needs to have been set up beforehand so that it has the " "virtio-serial channel and so that guestfsd is running inside it." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1032 msgid "ABI GUARANTEE" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1034 msgid "" "We guarantee the libguestfs ABI (binary interface), for public, high-level " "actions as outlined in this section. Although we will deprecate some " "actions, for example if they get replaced by newer calls, we will keep the " "old actions forever. This allows you the developer to program in confidence " "against the libguestfs API." msgstr "" # type: =head1 #. type: =head2 #: ../src/guestfs.pod:1040 msgid "BLOCK DEVICE NAMING" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1042 msgid "" "In the kernel there is now quite a profusion of schemata for naming block " "devices (in this context, by I I mean a physical or virtual " "hard drive). The original Linux IDE driver used names starting with C. SCSI devices have historically used a different naming scheme, C. When the Linux kernel I driver became a popular replacement " "for the old IDE driver (particularly for SATA devices) those devices also " "used the C scheme. Additionally we now have virtual machines with " "paravirtualized drivers. This has created several different naming systems, " "such as C for virtio disks and C for Xen PV disks." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1054 msgid "" "As discussed above, libguestfs uses a qemu appliance running an embedded " "Linux kernel to access block devices. We can run a variety of appliances " "based on a variety of Linux kernels." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1058 msgid "" "This causes a problem for libguestfs because many API calls use device or " "partition names. Working scripts and the recipe (example) scripts that we " "make available over the internet could fail if the naming scheme changes." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1063 msgid "" "Therefore libguestfs defines C as the I. " "Internally C names are translated, if necessary, to other names as " "required. For example, under RHEL 5 which uses the C scheme, any " "device parameter C is translated to C transparently." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1069 msgid "" "Note that this I applies to parameters. The L, " "L and similar calls return the true names of the " "devices and partitions as known to the appliance." msgstr "" # type: =head2 #. type: =head3 #: ../src/guestfs.pod:1074 msgid "ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1076 msgid "" "Usually this translation is transparent. However in some (very rare) cases " "you may need to know the exact algorithm. Such cases include where you use " "L to add a mixture of virtio and IDE devices to the qemu-" "based appliance, so have a mixture of C and C devices." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1082 msgid "" "The algorithm is applied only to I which are known to be either " "device or partition names. Return values from functions such as L are never changed." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1090 msgid "Is the string a parameter which is a device or partition name?" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1094 msgid "Does the string begin with C?" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1098 msgid "" "Does the named device exist? If so, we use that device. However if I " "then we continue with this algorithm." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1103 msgid "Replace initial C string with C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1105 msgid "For example, change C to C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1107 msgid "If that named device exists, use it. If not, continue." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1111 msgid "Replace initial C string with C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1113 msgid "If that named device exists, use it. If not, return an error." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:1117 msgid "PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1119 msgid "" "Although the standard naming scheme and automatic translation is useful for " "simple programs and guestfish scripts, for larger programs it is best not to " "rely on this mechanism." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1123 msgid "" "Where possible for maximum future portability programs using libguestfs " "should use these future-proof techniques:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1130 msgid "" "Use L or L to list actual " "device names, and then use those names directly." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1133 msgid "" "Since those device names exist by definition, they will never be translated." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1138 msgid "" "Use higher level ways to identify filesystems, such as LVM names, UUIDs and " "filesystem labels." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1143 msgid "SECURITY" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1145 msgid "" "This section discusses security implications of using libguestfs, " "particularly with untrusted or malicious guests or disk images." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1148 msgid "GENERAL SECURITY CONSIDERATIONS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1150 msgid "" "Be careful with any files or data that you download from a guest (by " "\"download\" we mean not just the L command but any " "command that reads files, filenames, directories or anything else from a " "disk image). An attacker could manipulate the data to fool your program " "into doing the wrong thing. Consider cases such as:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1160 msgid "the data (file etc) not being present" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1164 msgid "being present but empty" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1168 msgid "being much larger than normal" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1172 msgid "containing arbitrary 8 bit data" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1176 msgid "being in an unexpected character encoding" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1180 msgid "containing homoglyphs." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1184 msgid "SECURITY OF MOUNTING FILESYSTEMS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1186 msgid "" "When you mount a filesystem under Linux, mistakes in the kernel filesystem " "(VFS) module can sometimes be escalated into exploits by deliberately " "creating a malicious, malformed filesystem. These exploits are very severe " "for two reasons. Firstly there are very many filesystem drivers in the " "kernel, and many of them are infrequently used and not much developer " "attention has been paid to the code. Linux userspace helps potential " "crackers by detecting the filesystem type and automatically choosing the " "right VFS driver, even if that filesystem type is obscure or unexpected for " "the administrator. Secondly, a kernel-level exploit is like a local root " "exploit (worse in some ways), giving immediate and total access to the " "system right down to the hardware level." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1199 msgid "" "That explains why you should never mount a filesystem from an untrusted " "guest on your host kernel. How about libguestfs? We run a Linux kernel " "inside a qemu virtual machine, usually running as a non-root user. The " "attacker would need to write a filesystem which first exploited the kernel, " "and then exploited either qemu virtualization (eg. a faulty qemu driver) or " "the libguestfs protocol, and finally to be as serious as the host kernel " "exploit it would need to escalate its privileges to root. This multi-step " "escalation, performed by a static piece of data, is thought to be extremely " "hard to do, although we never say 'never' about security issues." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1210 msgid "" "In any case callers can reduce the attack surface by forcing the filesystem " "type when mounting (use L)." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1213 msgid "PROTOCOL SECURITY" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1215 msgid "" "The protocol is designed to be secure, being based on RFC 4506 (XDR) with a " "defined upper message size. However a program that uses libguestfs must " "also take care - for example you can write a program that downloads a binary " "from a disk image and executes it locally, and no amount of protocol " "security will save you from the consequences." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1221 msgid "INSPECTION SECURITY" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1223 msgid "" "Parts of the inspection API (see L) return untrusted strings " "directly from the guest, and these could contain any 8 bit data. Callers " "should be careful to escape these before printing them to a structured file " "(for example, use HTML escaping if creating a web page)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1229 msgid "" "Guest configuration may be altered in unusual ways by the administrator of " "the virtual machine, and may not reflect reality (particularly for untrusted " "or actively malicious guests). For example we parse the hostname from " "configuration files like C that we find in the " "guest, but the guest administrator can easily manipulate these files to " "provide the wrong hostname." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1237 msgid "" "The inspection API parses guest configuration using two external libraries: " "Augeas (Linux configuration) and hivex (Windows Registry). Both are " "designed to be robust in the face of malicious data, although denial of " "service attacks are still possible, for example with oversized configuration " "files." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1243 msgid "RUNNING UNTRUSTED GUEST COMMANDS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1245 msgid "" "Be very cautious about running commands from the guest. By running a " "command in the guest, you are giving CPU time to a binary that you do not " "control, under the same user account as the library, albeit wrapped in qemu " "virtualization. More information and alternatives can be found in the " "section L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1251 msgid "CVE-2010-3851" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1253 msgid "https://bugzilla.redhat.com/642934" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1255 msgid "" "This security bug concerns the automatic disk format detection that qemu " "does on disk images." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1258 msgid "" "A raw disk image is just the raw bytes, there is no header. Other disk " "images like qcow2 contain a special header. Qemu deals with this by looking " "for one of the known headers, and if none is found then assuming the disk " "image must be raw." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1263 msgid "" "This allows a guest which has been given a raw disk image to write some " "other header. At next boot (or when the disk image is accessed by " "libguestfs) qemu would do autodetection and think the disk image format was, " "say, qcow2 based on the header written by the guest." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1268 msgid "" "This in itself would not be a problem, but qcow2 offers many features, one " "of which is to allow a disk image to refer to another image (called the " "\"backing disk\"). It does this by placing the path to the backing disk " "into the qcow2 header. This path is not validated and could point to any " "host file (eg. \"/etc/passwd\"). The backing disk is then exposed through " "\"holes\" in the qcow2 disk image, which of course is completely under the " "control of the attacker." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1276 msgid "" "In libguestfs this is rather hard to exploit except under two circumstances:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1283 msgid "You have enabled the network or have opened the disk in write mode." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1287 msgid "" "You are also running untrusted code from the guest (see L)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1292 msgid "" "The way to avoid this is to specify the expected disk format when adding " "disks (the optional C option to L). You " "should always do this if the disk is raw format, and it's a good idea for " "other cases too." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1297 msgid "" "For disks added from libvirt using calls like L, the " "format is fetched from libvirt and passed through." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1300 msgid "" "For libguestfs tools, use the I<--format> command line parameter as " "appropriate." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1303 msgid "CONNECTION MANAGEMENT" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1305 msgid "guestfs_h *" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1307 msgid "" "C is the opaque type representing a connection handle. Create a " "handle by calling L. Call L to free the " "handle and release all resources used." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1311 msgid "" "For information on using multiple handles and threads, see the section L below." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1314 msgid "guestfs_create" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1316 #, no-wrap msgid "" " guestfs_h *guestfs_create (void);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1318 msgid "Create a connection handle." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1320 msgid "" "You have to call L (or one of the equivalent calls) " "on the handle at least once." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1323 msgid "" "This function returns a non-NULL pointer to a handle on success or NULL on " "error." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1326 msgid "After configuring the handle, you have to call L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1328 msgid "" "You may also want to configure error handling for the handle. See L section below." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1331 msgid "guestfs_close" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1333 #, no-wrap msgid "" " void guestfs_close (guestfs_h *g);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1335 msgid "This closes the connection handle and frees up all resources used." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1337 msgid "ERROR HANDLING" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1339 msgid "" "API functions can return errors. For example, almost all functions that " "return C will return C<-1> to indicate an error." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1342 msgid "" "Additional information is available for errors: an error message string and " "optionally an error number (errno) if the thing that failed was a system " "call." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1346 msgid "" "You can get at the additional information about the last error on the handle " "by calling L, L, and/or by setting " "up an error handler with L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1351 msgid "" "When the handle is created, a default error handler is installed which " "prints the error message string to C. For small short-running " "command line programs it is sufficient to do:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1355 #, no-wrap msgid "" " if (guestfs_launch (g) == -1)\n" " exit (EXIT_FAILURE);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1358 msgid "" "since the default error handler will ensure that an error message has been " "printed to C before the program exits." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1361 msgid "" "For other programs the caller will almost certainly want to install an " "alternate error handler or do error handling in-line like this:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1364 #, no-wrap msgid "" " g = guestfs_create ();\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1366 #, no-wrap msgid "" " /* This disables the default behaviour of printing errors\n" " on stderr. */\n" " guestfs_set_error_handler (g, NULL, NULL);\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1370 #, no-wrap msgid "" " if (guestfs_launch (g) == -1) {\n" " /* Examine the error message and print it etc. */\n" " char *msg = guestfs_last_error (g);\n" " int errnum = guestfs_last_errno (g);\n" " fprintf (stderr, \"%s\\n\", msg);\n" " /* ... */\n" " }\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1378 msgid "" "Out of memory errors are handled differently. The default action is to call " "L. If this is undesirable, then you can set a handler using L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1382 msgid "" "L returns C if the handle cannot be created, and " "because there is no handle if this happens there is no way to get additional " "error information. However L is supposed to be a " "lightweight operation which can only fail because of insufficient memory (it " "returns NULL in this case)." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1388 msgid "guestfs_last_error" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1390 #, no-wrap msgid "" " const char *guestfs_last_error (guestfs_h *g);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1392 msgid "" "This returns the last error message that happened on C. If there has not " "been an error since the handle was created, then this returns C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1396 msgid "" "The lifetime of the returned string is until the next error occurs, or L is called." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1399 msgid "guestfs_last_errno" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1401 #, no-wrap msgid "" " int guestfs_last_errno (guestfs_h *g);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1403 msgid "This returns the last error number (errno) that happened on C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1405 msgid "If successful, an errno integer not equal to zero is returned." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1407 msgid "" "If no error, this returns 0. This call can return 0 in three situations:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1414 msgid "There has not been any error on the handle." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1418 msgid "" "There has been an error but the errno was meaningless. This corresponds to " "the case where the error did not come from a failed system call, but for " "some other reason." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1424 msgid "" "There was an error from a failed system call, but for some reason the errno " "was not captured and returned. This usually indicates a bug in libguestfs." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1430 msgid "" "Libguestfs tries to convert the errno from inside the applicance into a " "corresponding errno for the caller (not entirely trivial: the appliance " "might be running a completely different operating system from the library " "and error numbers are not standardized across Un*xen). If this could not be " "done, then the error is translated to C. In practice this should " "only happen in very rare circumstances." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1438 msgid "guestfs_set_error_handler" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1440 #, no-wrap msgid "" " typedef void (*guestfs_error_handler_cb) (guestfs_h *g,\n" " void *opaque,\n" " const char *msg);\n" " void guestfs_set_error_handler (guestfs_h *g,\n" " guestfs_error_handler_cb cb,\n" " void *opaque);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1447 msgid "" "The callback C will be called if there is an error. The parameters " "passed to the callback are an opaque data pointer and the error message " "string." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1451 msgid "" "C is not passed to the callback. To get that the callback must call " "L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1454 msgid "" "Note that the message string C is freed as soon as the callback " "function returns, so if you want to stash it somewhere you must make your " "own copy." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1458 msgid "The default handler prints messages on C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1460 msgid "If you set C to C then I handler is called." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1462 msgid "guestfs_get_error_handler" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1464 #, no-wrap msgid "" " guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,\n" " void **opaque_rtn);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1467 msgid "Returns the current error handler callback." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1469 msgid "guestfs_set_out_of_memory_handler" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1471 #, no-wrap msgid "" " typedef void (*guestfs_abort_cb) (void);\n" " int guestfs_set_out_of_memory_handler (guestfs_h *g,\n" " guestfs_abort_cb);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1475 msgid "" "The callback C will be called if there is an out of memory situation. " "I." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1478 msgid "The default is to call L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1480 msgid "" "You cannot set C to C. You can't ignore out of memory situations." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1483 msgid "guestfs_get_out_of_memory_handler" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1485 #, no-wrap msgid "" " guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1487 msgid "This returns the current out of memory handler." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1489 msgid "API CALLS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1491 ../fish/guestfish.pod:989 msgid "@ACTIONS@" msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1493 msgid "STRUCTURES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1495 msgid "@STRUCTS@" msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1497 msgid "AVAILABILITY" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1499 msgid "GROUPS OF FUNCTIONALITY IN THE APPLIANCE" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1501 msgid "" "Using L you can test availability of the following " "groups of functions. This test queries the appliance to see if the " "appliance you are currently using supports the functionality." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1506 msgid "@AVAILABILITY@" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1508 msgid "GUESTFISH supported COMMAND" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1510 msgid "" "In L there is a handy interactive command C which " "prints out the available groups and whether they are supported by this build " "of libguestfs. Note however that you have to do C first." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1515 msgid "SINGLE CALLS AT COMPILE TIME" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1517 msgid "" "Since version 1.5.8, Cguestfs.hE> defines symbols for each C API " "function, such as:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1520 #, no-wrap msgid "" " #define LIBGUESTFS_HAVE_DD 1\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1522 msgid "if L is available." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1524 msgid "" "Before version 1.5.8, if you needed to test whether a single libguestfs " "function is available at compile time, we recommended using build tools such " "as autoconf or cmake. For example in autotools you could use:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1529 #, no-wrap msgid "" " AC_CHECK_LIB([guestfs],[guestfs_create])\n" " AC_CHECK_FUNCS([guestfs_dd])\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1532 msgid "" "which would result in C being either defined or not defined " "in your program." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1535 msgid "SINGLE CALLS AT RUN TIME" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1537 msgid "" "Testing at compile time doesn't guarantee that a function really exists in " "the library. The reason is that you might be dynamically linked against a " "previous I (dynamic library) which doesn't have the call. " "This situation unfortunately results in a segmentation fault, which is a " "shortcoming of the C dynamic linking system itself." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1544 msgid "" "You can use L to test if a function is available at run time, as " "in this example program (note that you still need the compile time check as " "well):" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1548 #, no-wrap msgid "" " #include \n" " #include \n" " #include \n" " #include \n" " #include \n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1554 #, no-wrap msgid "" " main ()\n" " {\n" " #ifdef LIBGUESTFS_HAVE_DD\n" " void *dl;\n" " int has_function;\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1560 #, no-wrap msgid "" " /* Test if the function guestfs_dd is really available. */\n" " dl = dlopen (NULL, RTLD_LAZY);\n" " if (!dl) {\n" " fprintf (stderr, \"dlopen: %s\\n\", dlerror ());\n" " exit (EXIT_FAILURE);\n" " }\n" " has_function = dlsym (dl, \"guestfs_dd\") != NULL;\n" " dlclose (dl);\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1569 #, no-wrap msgid "" " if (!has_function)\n" " printf (\"this libguestfs.so does NOT have guestfs_dd function\\n\");\n" " else {\n" " printf (\"this libguestfs.so has guestfs_dd function\\n\");\n" " /* Now it's safe to call\n" " guestfs_dd (g, \"foo\", \"bar\");\n" " */\n" " }\n" " #else\n" " printf (\"guestfs_dd function was not found at compile time\\n\");\n" " #endif\n" " }\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1582 msgid "" "You may think the above is an awful lot of hassle, and it is. There are " "other ways outside of the C linking system to ensure that this kind of " "incompatibility never arises, such as using package versioning:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1587 #, no-wrap msgid "" " Requires: libguestfs >= 1.0.80\n" "\n" msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1589 msgid "CALLS WITH OPTIONAL ARGUMENTS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1591 msgid "" "A recent feature of the API is the introduction of calls which take optional " "arguments. In C these are declared 3 ways. The main way is as a call which " "takes variable arguments (ie. C<...>), as in this example:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1596 #, no-wrap msgid "" " int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1598 msgid "" "Call this with a list of optional arguments, terminated by C<-1>. So to " "call with no optional arguments specified:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1601 #, no-wrap msgid "" " guestfs_add_drive_opts (g, filename, -1);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1603 msgid "With a single optional argument:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1605 #, no-wrap msgid "" " guestfs_add_drive_opts (g, filename,\n" " GUESTFS_ADD_DRIVE_OPTS_FORMAT, \"qcow2\",\n" " -1);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1609 msgid "With two:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1611 #, no-wrap msgid "" " guestfs_add_drive_opts (g, filename,\n" " GUESTFS_ADD_DRIVE_OPTS_FORMAT, \"qcow2\",\n" " GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,\n" " -1);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1616 msgid "" "and so forth. Don't forget the terminating C<-1> otherwise Bad Things will " "happen!" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1619 msgid "USING va_list FOR OPTIONAL ARGUMENTS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1621 msgid "" "The second variant has the same name with the suffix C<_va>, which works the " "same way but takes a C. See the C manual for details. For the " "example function, this is declared:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1625 #, no-wrap msgid "" " int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,\n" " va_list args);\n" "\n" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1628 msgid "CONSTRUCTING OPTIONAL ARGUMENTS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1630 msgid "" "The third variant is useful where you need to construct these calls. You " "pass in a structure where you fill in the optional fields. The structure " "has a bitmask as the first element which you must set to indicate which " "fields you have filled in. For our example function the structure and call " "are declared:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1636 #, no-wrap msgid "" " struct guestfs_add_drive_opts_argv {\n" " uint64_t bitmask;\n" " int readonly;\n" " const char *format;\n" " /* ... */\n" " };\n" " int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,\n" " const struct guestfs_add_drive_opts_argv *optargs);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1645 msgid "You could call it like this:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1647 #, no-wrap msgid "" " struct guestfs_add_drive_opts_argv optargs = {\n" " .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |\n" " GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,\n" " .readonly = 1,\n" " .format = \"qcow2\"\n" " };\n" " \n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1654 #, no-wrap msgid "" " guestfs_add_drive_opts_argv (g, filename, &optargs);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1656 ../src/guestfs-actions.pod:11 #: ../src/guestfs-actions.pod:1850 ../fish/guestfish-actions.pod:9 #: ../fish/guestfish-actions.pod:1260 ../tools/virt-win-reg.pl:532 msgid "Notes:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1662 msgid "The C<_BITMASK> suffix on each option name when specifying the bitmask." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1667 msgid "You do not need to fill in all fields of the structure." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1671 msgid "" "There must be a one-to-one correspondence between fields of the structure " "that are filled in, and bits set in the bitmask." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1676 msgid "OPTIONAL ARGUMENTS IN OTHER LANGUAGES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1678 msgid "" "In other languages, optional arguments are expressed in the way that is " "natural for that language. We refer you to the language-specific " "documentation for more details on that." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1682 msgid "For guestfish, see L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1684 msgid "SETTING CALLBACKS TO HANDLE EVENTS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1686 msgid "" "The child process generates events in some situations. Current events " "include: receiving a log message, the child process exits." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1689 msgid "" "Use the C functions to set a callback for different " "types of events." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1692 msgid "" "Only I can be registered for each handle. " "Calling C again overwrites the previous callback of " "that type. Cancel all callbacks of this type by calling this function with " "C set to C." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1697 msgid "guestfs_set_log_message_callback" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1699 #, no-wrap msgid "" " typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,\n" " char *buf, int len);\n" " void guestfs_set_log_message_callback (guestfs_h *g,\n" " guestfs_log_message_cb cb,\n" " void *opaque);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1705 msgid "" "The callback function C will be called whenever qemu or the guest writes " "anything to the console." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1708 msgid "Use this function to capture kernel messages and similar." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1710 msgid "" "Normally there is no log message handler, and log messages are just " "discarded." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1713 msgid "guestfs_set_subprocess_quit_callback" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1715 #, no-wrap msgid "" " typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);\n" " void guestfs_set_subprocess_quit_callback (guestfs_h *g,\n" " guestfs_subprocess_quit_cb cb,\n" " void *opaque);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1720 msgid "" "The callback function C will be called when the child process quits, " "either asynchronously or if killed by L. (This " "corresponds to a transition from any state to the CONFIG state)." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1725 msgid "guestfs_set_launch_done_callback" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1727 #, no-wrap msgid "" " typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);\n" " void guestfs_set_launch_done_callback (guestfs_h *g,\n" " guestfs_launch_done_cb cb,\n" " void *opaque);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1732 msgid "" "The callback function C will be called when the child process becomes " "ready first time after it has been launched. (This corresponds to a " "transition from LAUNCHING to the READY state)." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1736 msgid "guestfs_set_close_callback" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1738 #, no-wrap msgid "" " typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);\n" " void guestfs_set_close_callback (guestfs_h *g,\n" " guestfs_close_cb cb,\n" " void *opaque);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1743 msgid "" "The callback function C will be called while the handle is being closed " "(synchronously from L)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1746 msgid "" "Note that libguestfs installs an L handler to try to clean up " "handles that are open when the program exits. This means that this callback " "might be called indirectly from L, which can cause unexpected " "problems in higher-level languages (eg. if your HLL interpreter has already " "been cleaned up by the time this is called, and if your callback then jumps " "into some HLL function)." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1754 msgid "guestfs_set_progress_callback" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1756 #, no-wrap msgid "" " typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,\n" " int proc_nr, int serial,\n" " uint64_t position, uint64_t total);\n" " void guestfs_set_progress_callback (guestfs_h *g,\n" " guestfs_progress_cb cb,\n" " void *opaque);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1763 msgid "" "Some long-running operations can generate progress messages. If this " "callback is registered, then it will be called each time a progress message " "is generated (usually two seconds after the operation started, and three " "times per second thereafter until it completes, although the frequency may " "change in future versions)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1769 msgid "" "The callback receives two numbers: C and C. The units of " "C are not defined, although for some operations C may relate " "in some way to the amount of data to be transferred (eg. in bytes or " "megabytes), and C may be the portion which has been transferred." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1775 msgid "The only defined and stable parts of the API are:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1781 msgid "" "The callback can display to the user some type of progress bar or indicator " "which shows the ratio of C:C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1786 msgid "0 E= C E= C" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1790 msgid "" "If any progress notification is sent during a call, then a final progress " "notification is always sent when C = C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1793 msgid "" "This is to simplify caller code, so callers can easily set the progress " "indicator to \"100%\" at the end of the operation, without requiring special " "code to detect this case." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1799 msgid "" "The callback also receives the procedure number and serial number of the " "call. These are only useful for debugging protocol issues, and the callback " "can normally ignore them. The callback may want to print these numbers in " "error messages or debugging messages." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1804 msgid "PRIVATE DATA AREA" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1806 msgid "" "You can attach named pieces of private data to the libguestfs handle, and " "fetch them by name for the lifetime of the handle. This is called the " "private data area and is only available from the C API." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1810 msgid "To attach a named piece of data, use the following call:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1812 #, no-wrap msgid "" " void guestfs_set_private (guestfs_h *g, const char *key, void *data);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1814 msgid "" "C is the name to associate with this data, and C is an arbitrary " "pointer (which can be C). Any previous item with the same name is " "overwritten." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1818 msgid "" "You can use any C you want, but names beginning with an underscore " "character are reserved for internal libguestfs purposes (for implementing " "language bindings). It is recommended to prefix the name with some unique " "string to avoid collisions with other users." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1823 msgid "To retrieve the pointer, use:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1825 #, no-wrap msgid "" " void *guestfs_get_private (guestfs_h *g, const char *key);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1827 msgid "" "This function returns C if either no data is found associated with " "C, or if the user previously set the C's C pointer to " "C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1831 msgid "" "Libguestfs does not try to look at or interpret the C pointer in any " "way. As far as libguestfs is concerned, it need not be a valid pointer at " "all. In particular, libguestfs does I try to free the data when the " "handle is closed. If the data must be freed, then the caller must either " "free it before calling L or must set up a close callback to " "do it (see L, and note that only one callback " "can be registered for a handle)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1839 msgid "" "The private data area is implemented using a hash table, and should be " "reasonably efficient for moderate numbers of keys." msgstr "" # type: =end #. type: =end #: ../src/guestfs.pod:1842 ../src/guestfs.pod:1847 msgid "html" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1844 msgid "" " " msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1849 msgid "ARCHITECTURE" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1851 msgid "" "Internally, libguestfs is implemented by running an appliance (a special " "type of small virtual machine) using L. Qemu runs as a child " "process of the main program." msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1855 #, no-wrap msgid "" " ___________________\n" " / \\\n" " | main program |\n" " | |\n" " | | child process / appliance\n" " | | __________________________\n" " | | / qemu \\\n" " +-------------------+ RPC | +-----------------+ |\n" " | libguestfs <--------------------> guestfsd | |\n" " | | | +-----------------+ |\n" " \\___________________/ | | Linux kernel | |\n" " | +--^--------------+ |\n" " \\_________|________________/\n" " |\n" " _______v______\n" " / \\\n" " | Device or |\n" " | disk image |\n" " \\______________/\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1875 msgid "" "The library, linked to the main program, creates the child process and hence " "the appliance in the L function." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1878 msgid "" "Inside the appliance is a Linux kernel and a complete stack of userspace " "tools (such as LVM and ext2 programs) and a small controlling daemon called " "L. The library talks to L using remote procedure " "calls (RPC). There is a mostly one-to-one correspondence between libguestfs " "API calls and RPC calls to the daemon. Lastly the disk image(s) are " "attached to the qemu process which translates device access by the " "appliance's Linux kernel into accesses to the image." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1887 msgid "" "A common misunderstanding is that the appliance \"is\" the virtual machine. " "Although the disk image you are attached to might also be used by some " "virtual machine, libguestfs doesn't know or care about this. (But you will " "care if both libguestfs's qemu process and your virtual machine are trying " "to update the disk image at the same time, since these usually results in " "massive disk corruption)." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1894 msgid "STATE MACHINE" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1896 msgid "libguestfs uses a state machine to model the child process:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1898 #, no-wrap msgid "" " |\n" " guestfs_create\n" " |\n" " |\n" " ____V_____\n" " / \\\n" " | CONFIG |\n" " \\__________/\n" " ^ ^ ^ \\\n" " / | \\ \\ guestfs_launch\n" " / | _\\__V______\n" " / | / \\\n" " / | | LAUNCHING |\n" " / | \\___________/\n" " / | /\n" " / | guestfs_launch\n" " / | /\n" " ______ / __|____V\n" " / \\ ------> / \\\n" " | BUSY | | READY |\n" " \\______/ <------ \\________/\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1920 msgid "" "The normal transitions are (1) CONFIG (when the handle is created, but there " "is no child process), (2) LAUNCHING (when the child process is booting up), " "(3) alternating between READY and BUSY as commands are issued to, and " "carried out by, the child process." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1925 msgid "" "The guest may be killed by L, or may die " "asynchronously at any time (eg. due to some internal error), and that causes " "the state to transition back to CONFIG." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1929 msgid "" "Configuration commands for qemu such as L can only be " "issued when in the CONFIG state." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1932 msgid "" "The API offers one call that goes from CONFIG through LAUNCHING to READY. " "L blocks until the child process is READY to accept " "commands (or until some failure or timeout). L internally " "moves the state from CONFIG to LAUNCHING while it is running." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1938 msgid "" "API actions such as L can only be issued when in the READY " "state. These API calls block waiting for the command to be carried out (ie. " "the state to transition to BUSY and then back to READY). There are no non-" "blocking versions, and no way to issue more than one command per handle at " "the same time." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1944 msgid "" "Finally, the child process sends asynchronous messages back to the main " "program, such as kernel log messages. You can register a callback to " "receive these messages." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:1948 msgid "INTERNALS" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs.pod:1950 msgid "COMMUNICATION PROTOCOL" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1952 msgid "" "Don't rely on using this protocol directly. This section documents how it " "currently works, but it may change at any time." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1955 msgid "" "The protocol used to talk between the library and the daemon running inside " "the qemu virtual machine is a simple RPC mechanism built on top of XDR (RFC " "1014, RFC 1832, RFC 4506)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1959 msgid "" "The detailed format of structures is in C (note: " "this file is automatically generated)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1962 msgid "" "There are two broad cases, ordinary functions that don't have any C " "and C parameters, which are handled with very simple request/reply " "messages. Then there are functions that have any C or C " "parameters, which use the same request and reply messages, but they may also " "be followed by files sent using a chunked encoding." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:1969 msgid "ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1971 msgid "For ordinary functions, the request message is:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:1973 #, no-wrap msgid "" " total length (header + arguments,\n" " but not including the length word itself)\n" " struct guestfs_message_header (encoded as XDR)\n" " struct guestfs__args (encoded as XDR)\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1978 msgid "" "The total length field allows the daemon to allocate a fixed size buffer " "into which it slurps the rest of the message. As a result, the total length " "is limited to C bytes (currently 4MB), which means the " "effective size of any request is limited to somewhere under this size." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1984 msgid "" "Note also that many functions don't take any arguments, in which case the " "C_args> is completely omitted." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1987 msgid "" "The header contains the procedure number (C) which is how the " "receiver knows what type of args structure to expect, or none at all." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1991 msgid "" "For functions that take optional arguments, the optional arguments are " "encoded in the C_args> structure in the same way as ordinary " "arguments. A bitmask in the header indicates which optional arguments are " "meaningful. The bitmask is also checked to see if it contains bits set " "which the daemon does not know about (eg. if more optional arguments were " "added in a later version of the library), and this causes the call to be " "rejected." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:1999 msgid "The reply message for ordinary functions is:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:2001 #, no-wrap msgid "" " total length (header + ret,\n" " but not including the length word itself)\n" " struct guestfs_message_header (encoded as XDR)\n" " struct guestfs__ret (encoded as XDR)\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2006 msgid "" "As above the C_ret> structure may be completely omitted for " "functions that return no formal return values." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2009 msgid "" "As above the total length of the reply is limited to C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2012 msgid "" "In the case of an error, a flag is set in the header, and the reply message " "is slightly changed:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:2015 #, no-wrap msgid "" " total length (header + error,\n" " but not including the length word itself)\n" " struct guestfs_message_header (encoded as XDR)\n" " struct guestfs_message_error (encoded as XDR)\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2020 msgid "" "The C structure contains the error message as a " "string." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:2023 msgid "FUNCTIONS THAT HAVE FILEIN PARAMETERS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2025 msgid "" "A C parameter indicates that we transfer a file I the guest. " "The normal request message is sent (see above). However this is followed by " "a sequence of file chunks." msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:2029 #, no-wrap msgid "" " total length (header + arguments,\n" " but not including the length word itself,\n" " and not including the chunks)\n" " struct guestfs_message_header (encoded as XDR)\n" " struct guestfs__args (encoded as XDR)\n" " sequence of chunks for FileIn param #0\n" " sequence of chunks for FileIn param #1 etc.\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2037 msgid "The \"sequence of chunks\" is:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:2039 #, no-wrap msgid "" " length of chunk (not including length word itself)\n" " struct guestfs_chunk (encoded as XDR)\n" " length of chunk\n" " struct guestfs_chunk (encoded as XDR)\n" " ...\n" " length of chunk\n" " struct guestfs_chunk (with data.data_len == 0)\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2047 msgid "" "The final chunk has the C field set to zero. Additionally a flag " "is set in the final chunk to indicate either successful completion or early " "cancellation." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2051 msgid "" "At time of writing there are no functions that have more than one FileIn " "parameter. However this is (theoretically) supported, by sending the " "sequence of chunks for each FileIn parameter one after another (from left to " "right)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2056 msgid "" "Both the library (sender) I the daemon (receiver) may cancel the " "transfer. The library does this by sending a chunk with a special flag set " "to indicate cancellation. When the daemon sees this, it cancels the whole " "RPC, does I send any reply, and goes back to reading the next request." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2062 msgid "" "The daemon may also cancel. It does this by writing a special word " "C to the socket. The library listens for this during " "the transfer, and if it gets it, it will cancel the transfer (it sends a " "cancel chunk). The special word is chosen so that even if cancellation " "happens right at the end of the transfer (after the library has finished " "writing and has started listening for the reply), the \"spurious\" cancel " "flag will not be confused with the reply message." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2071 msgid "" "This protocol allows the transfer of arbitrary sized files (no 32 bit " "limit), and also files where the size is not known in advance (eg. from " "pipes or sockets). However the chunks are rather small " "(C), so that neither the library nor the daemon need " "to keep much in memory." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:2077 msgid "FUNCTIONS THAT HAVE FILEOUT PARAMETERS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2079 msgid "" "The protocol for FileOut parameters is exactly the same as for FileIn " "parameters, but with the roles of daemon and library reversed." msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:2082 #, no-wrap msgid "" " total length (header + ret,\n" " but not including the length word itself,\n" " and not including the chunks)\n" " struct guestfs_message_header (encoded as XDR)\n" " struct guestfs__ret (encoded as XDR)\n" " sequence of chunks for FileOut param #0\n" " sequence of chunks for FileOut param #1 etc.\n" "\n" msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:2090 msgid "INITIAL MESSAGE" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2092 msgid "" "When the daemon launches it sends an initial word (C) " "which indicates that the guest and daemon is alive. This is what L waits for." msgstr "" # type: =head3 #. type: =head3 #: ../src/guestfs.pod:2096 msgid "PROGRESS NOTIFICATION MESSAGES" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2098 msgid "" "The daemon may send progress notification messages at any time. These are " "distinguished by the normal length word being replaced by " "C, followed by a fixed size progress message." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2102 msgid "" "The library turns them into progress callbacks (see " "C) if there is a callback registered, or " "discards them if not." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2106 msgid "" "The daemon self-limits the frequency of progress messages it sends (see " "C). Not all calls generate progress " "messages." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:2110 msgid "LIBGUESTFS VERSION NUMBERS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2112 msgid "" "Since April 2010, libguestfs has started to make separate development and " "stable releases, along with corresponding branches in our git repository. " "These separate releases can be identified by version number:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:2117 #, no-wrap msgid "" " even numbers for stable: 1.2.x, 1.4.x, ...\n" " .-------- odd numbers for development: 1.3.x, 1.5.x, ...\n" " |\n" " v\n" " 1 . 3 . 5\n" " ^ ^\n" " | |\n" " | `-------- sub-version\n" " |\n" " `------ always '1' because we don't change the ABI\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2128 msgid "Thus \"1.3.5\" is the 5th update to the development branch \"1.3\"." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2130 msgid "" "As time passes we cherry pick fixes from the development branch and backport " "those into the stable branch, the effect being that the stable branch should " "get more stable and less buggy over time. So the stable releases are ideal " "for people who don't need new features but would just like the software to " "work." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2136 msgid "Our criteria for backporting changes are:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2142 msgid "" "Documentation changes which don't affect any code are backported unless the " "documentation refers to a future feature which is not in stable." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2148 msgid "" "Bug fixes which are not controversial, fix obvious problems, and have been " "well tested are backported." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2153 msgid "" "Simple rearrangements of code which shouldn't affect how it works get " "backported. This is so that the code in the two branches doesn't get too " "far out of step, allowing us to backport future fixes more easily." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2159 msgid "" "We I backport new features, new APIs, new tools etc, except in one " "exceptional case: the new feature is required in order to implement an " "important bug fix." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2165 msgid "" "A new stable branch starts when we think the new features in development are " "substantial and compelling enough over the current stable branch to warrant " "it. When that happens we create new stable and development versions 1.N.0 " "and 1.(N+1).0 [N is even]. The new dot-oh release won't necessarily be so " "stable at this point, but by backporting fixes from development, that branch " "will stabilize over time." msgstr "" #. type: =head1 #: ../src/guestfs.pod:2173 msgid "EXTENDING LIBGUESTFS" msgstr "" #. type: =head2 #: ../src/guestfs.pod:2175 msgid "ADDING A NEW API ACTION" msgstr "" #. type: textblock #: ../src/guestfs.pod:2177 msgid "" "Large amounts of boilerplate code in libguestfs (RPC, bindings, " "documentation) are generated, and this makes it easy to extend the " "libguestfs API." msgstr "" #. type: textblock #: ../src/guestfs.pod:2181 msgid "To add a new API action there are two changes:" msgstr "" #. type: textblock #: ../src/guestfs.pod:2187 msgid "" "You need to add a description of the call (name, parameters, return type, " "tests, documentation) to C." msgstr "" #. type: textblock #: ../src/guestfs.pod:2190 msgid "" "There are two sorts of API action, depending on whether the call goes " "through to the daemon in the appliance, or is serviced entirely by the " "library (see L above). L is an example of the " "former, since the sync is done in the appliance. L is " "an example of the latter, since a trace flag is maintained in the handle and " "all tracing is done on the library side." msgstr "" #. type: textblock #: ../src/guestfs.pod:2198 msgid "" "Most new actions are of the first type, and get added to the " "C list. Each function has a unique procedure number used " "in the RPC protocol which is assigned to that action when we publish " "libguestfs and cannot be reused. Take the latest procedure number and " "increment it." msgstr "" #. type: textblock #: ../src/guestfs.pod:2204 msgid "" "For library-only actions of the second type, add to the " "C list. Since these functions are serviced by the " "library and do not travel over the RPC mechanism to the daemon, these " "functions do not need a procedure number, and so the procedure number is set " "to C<-1>." msgstr "" #. type: textblock #: ../src/guestfs.pod:2212 msgid "Implement the action (in C):" msgstr "" #. type: textblock #: ../src/guestfs.pod:2214 msgid "" "For daemon actions, implement the function CnameE> in the " "C directory." msgstr "" #. type: textblock #: ../src/guestfs.pod:2217 msgid "" "For library actions, implement the function CnameE> " "(note: double underscore) in the C directory." msgstr "" #. type: textblock #: ../src/guestfs.pod:2220 msgid "In either case, use another function as an example of what to do." msgstr "" #. type: textblock #: ../src/guestfs.pod:2224 msgid "After making these changes, use C to compile." msgstr "" #. type: textblock #: ../src/guestfs.pod:2226 msgid "" "Note that you don't need to implement the RPC, language bindings, manual " "pages or anything else. It's all automatically generated from the OCaml " "description." msgstr "" #. type: =head2 #: ../src/guestfs.pod:2230 msgid "ADDING TESTS FOR AN API ACTION" msgstr "" #. type: textblock #: ../src/guestfs.pod:2232 msgid "" "You can supply zero or as many tests as you want per API call. The tests " "can either be added as part of the API description (C), or in some rarer cases you may want to drop a script " "into C. Note that adding a script to C is " "slower, so if possible use the first method." msgstr "" #. type: textblock #: ../src/guestfs.pod:2238 msgid "" "The following describes the test environment used when you add an API test " "in C." msgstr "" #. type: textblock #: ../src/guestfs.pod:2241 msgid "The test environment has 4 block devices:" msgstr "" #. type: =item #: ../src/guestfs.pod:2245 msgid "C 500MB" msgstr "" #. type: textblock #: ../src/guestfs.pod:2247 msgid "General block device for testing." msgstr "" #. type: =item #: ../src/guestfs.pod:2249 msgid "C 50MB" msgstr "" #. type: textblock #: ../src/guestfs.pod:2251 msgid "" "C is an ext2 filesystem used for testing filesystem write " "operations." msgstr "" #. type: =item #: ../src/guestfs.pod:2254 msgid "C 10MB" msgstr "" #. type: textblock #: ../src/guestfs.pod:2256 msgid "Used in a few tests where two block devices are needed." msgstr "" #. type: =item #: ../src/guestfs.pod:2258 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2260 msgid "ISO with fixed content (see C)." msgstr "" #. type: textblock #: ../src/guestfs.pod:2264 msgid "" "To be able to run the tests in a reasonable amount of time, the libguestfs " "appliance and block devices are reused between tests. So don't try testing " "L :-x" msgstr "" #. type: textblock #: ../src/guestfs.pod:2268 msgid "" "Each test starts with an initial scenario, selected using one of the " "C expressions, described in C. These " "initialize the disks mentioned above in a particular way as documented in " "C. You should not assume anything about the previous " "contents of other disks that are not initialized." msgstr "" #. type: textblock #: ../src/guestfs.pod:2274 msgid "" "You can add a prerequisite clause to any individual test. This is a run-" "time check, which, if it fails, causes the test to be skipped. Useful if " "testing a command which might not work on all variations of libguestfs " "builds. A test that has prerequisite of C means to run " "unconditionally." msgstr "" #. type: textblock #: ../src/guestfs.pod:2280 msgid "" "In addition, packagers can skip individual tests by setting environment " "variables before running C." msgstr "" #. type: verbatim #: ../src/guestfs.pod:2283 #, no-wrap msgid "" " SKIP_TEST__=1\n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:2285 msgid "eg: C skips test #3 of L." msgstr "" #. type: textblock #: ../src/guestfs.pod:2287 msgid "or:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:2289 #, no-wrap msgid "" " SKIP_TEST_=1\n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:2291 msgid "eg: C skips all L tests." msgstr "" #. type: textblock #: ../src/guestfs.pod:2293 msgid "Packagers can run only certain tests by setting for example:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:2295 #, no-wrap msgid "" " TEST_ONLY=\"vfs_type zerofree\"\n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:2297 msgid "" "See C for more details of how these environment variables " "work." msgstr "" #. type: =head2 #: ../src/guestfs.pod:2300 msgid "DEBUGGING NEW API ACTIONS" msgstr "" #. type: textblock #: ../src/guestfs.pod:2302 msgid "Test new actions work before submitting them." msgstr "" #. type: textblock #: ../src/guestfs.pod:2304 msgid "You can use guestfish to try out new commands." msgstr "" #. type: textblock #: ../src/guestfs.pod:2306 msgid "" "Debugging the daemon is a problem because it runs inside a minimal " "environment. However you can fprintf messages in the daemon to stderr, and " "they will show up if you use C." msgstr "" #. type: =head2 #: ../src/guestfs.pod:2310 msgid "FORMATTING CODE AND OTHER CONVENTIONS" msgstr "" #. type: textblock #: ../src/guestfs.pod:2312 msgid "" "Our C source code generally adheres to some basic code-formatting " "conventions. The existing code base is not totally consistent on this " "front, but we do prefer that contributed code be formatted similarly. In " "short, use spaces-not-TABs for indentation, use 2 spaces for each " "indentation level, and other than that, follow the K&R style." msgstr "" #. type: textblock #: ../src/guestfs.pod:2318 msgid "" "If you use Emacs, add the following to one of one of your start-up files (e." "g., ~/.emacs), to help ensure that you get indentation right:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:2321 #, no-wrap msgid "" " ;;; In libguestfs, indent with spaces everywhere (not TABs).\n" " ;;; Exceptions: Makefile and ChangeLog modes.\n" " (add-hook 'find-file-hook\n" " '(lambda () (if (and buffer-file-name\n" " (string-match \"/libguestfs\\\\>\"\n" " (buffer-file-name))\n" " (not (string-equal mode-name \"Change Log\"))\n" " (not (string-equal mode-name \"Makefile\")))\n" " (setq indent-tabs-mode nil))))\n" " \n" msgstr "" #. type: verbatim #: ../src/guestfs.pod:2331 #, no-wrap msgid "" " ;;; When editing C sources in libguestfs, use this style.\n" " (defun libguestfs-c-mode ()\n" " \"C mode with adjusted defaults for use with libguestfs.\"\n" " (interactive)\n" " (c-set-style \"K&R\")\n" " (setq c-indent-level 2)\n" " (setq c-basic-offset 2))\n" " (add-hook 'c-mode-hook\n" " '(lambda () (if (string-match \"/libguestfs\\\\>\"\n" " (buffer-file-name))\n" " (libguestfs-c-mode))))\n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:2343 msgid "Enable warnings when compiling (and fix any problems this finds):" msgstr "" #. type: verbatim #: ../src/guestfs.pod:2346 #, no-wrap msgid "" " ./configure --enable-gcc-warnings\n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:2348 msgid "Useful targets are:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:2350 #, no-wrap msgid "" " make syntax-check # checks the syntax of the C code\n" " make check # runs the test suite\n" "\n" msgstr "" #. type: =head2 #: ../src/guestfs.pod:2353 msgid "DAEMON CUSTOM PRINTF FORMATTERS" msgstr "" #. type: textblock #: ../src/guestfs.pod:2355 msgid "" "In the daemon code we have created custom printf formatters C<%Q> and C<%R>, " "which are used to do shell quoting." msgstr "" #. type: =item #: ../src/guestfs.pod:2360 msgid "%Q" msgstr "" #. type: textblock #: ../src/guestfs.pod:2362 msgid "" "Simple shell quoted string. Any spaces or other shell characters are " "escaped for you." msgstr "" #. type: =item #: ../src/guestfs.pod:2365 msgid "%R" msgstr "" #. type: textblock #: ../src/guestfs.pod:2367 msgid "" "Same as C<%Q> except the string is treated as a path which is prefixed by " "the sysroot." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2372 ../fish/guestfish.pod:240 ../fish/guestfish.pod:599 msgid "For example:" msgstr "" #. type: verbatim #: ../src/guestfs.pod:2374 #, no-wrap msgid "" " asprintf (&cmd, \"cat %R\", path);\n" "\n" msgstr "" #. type: textblock #: ../src/guestfs.pod:2376 msgid "would produce C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2378 msgid "" "I Do I use these when you are passing parameters to the C functions. These parameters do NOT need to be quoted because " "they are not passed via the shell (instead, straight to exec). You probably " "want to use the C function however." msgstr "" #. type: =head2 #: ../src/guestfs.pod:2384 msgid "SUBMITTING YOUR NEW API ACTIONS" msgstr "" #. type: textblock #: ../src/guestfs.pod:2386 msgid "" "Submit patches to the mailing list: L and CC to L." msgstr "" #. type: =head2 #: ../src/guestfs.pod:2390 msgid "INTERNATIONALIZATION (I18N) SUPPORT" msgstr "" #. type: textblock #: ../src/guestfs.pod:2392 msgid "We support i18n (gettext anyhow) in the library." msgstr "" #. type: textblock #: ../src/guestfs.pod:2394 msgid "" "However many messages come from the daemon, and we don't translate those at " "the moment. One reason is that the appliance generally has all locale files " "removed from it, because they take up a lot of space. So we'd have to readd " "some of those, as well as copying our PO files into the appliance." msgstr "" #. type: textblock #: ../src/guestfs.pod:2400 msgid "" "Debugging messages are never translated, since they are intended for the " "programmers." msgstr "" #. type: =head2 #: ../src/guestfs.pod:2403 msgid "SOURCE CODE SUBDIRECTORIES" msgstr "" #. type: =item #: ../src/guestfs.pod:2407 ../src/guestfs-actions.pod:5686 #: ../fish/guestfish-actions.pod:3808 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2409 msgid "The libguestfs appliance, build scripts and so on." msgstr "" #. type: =item #: ../src/guestfs.pod:2411 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2413 msgid "Automated tests of the C API." msgstr "" #. type: =item #: ../src/guestfs.pod:2415 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2417 msgid "" "The L, L and L commands and " "documentation." msgstr "" #. type: =item #: ../src/guestfs.pod:2420 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2422 msgid "Outside contributions, experimental parts." msgstr "" #. type: =item #: ../src/guestfs.pod:2424 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2426 msgid "" "The daemon that runs inside the libguestfs appliance and carries out actions." msgstr "" #. type: =item #: ../src/guestfs.pod:2429 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2431 msgid "L command and documentation." msgstr "" #. type: =item #: ../src/guestfs.pod:2433 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2435 msgid "C API example code." msgstr "" #. type: =item #: ../src/guestfs.pod:2437 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2439 msgid "" "L, the command-line shell, and various shell scripts built on " "top such as L, L, L, " "L." msgstr "" #. type: =item #: ../src/guestfs.pod:2443 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2445 msgid "" "L, FUSE (userspace filesystem) built on top of libguestfs." msgstr "" #. type: =item #: ../src/guestfs.pod:2447 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2449 msgid "" "The crucially important generator, used to automatically generate large " "amounts of boilerplate C code for things like RPC and bindings." msgstr "" #. type: =item #: ../src/guestfs.pod:2452 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2454 msgid "Files used by the test suite." msgstr "" #. type: textblock #: ../src/guestfs.pod:2456 msgid "Some \"phony\" guest images which we test against." msgstr "" #. type: =item #: ../src/guestfs.pod:2458 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2460 msgid "L, the virtual machine image inspector." msgstr "" #. type: =item #: ../src/guestfs.pod:2462 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2464 msgid "Logo used on the website. The fish is called Arthur by the way." msgstr "" #. type: =item #: ../src/guestfs.pod:2466 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2468 msgid "M4 macros used by autoconf." msgstr "" #. type: =item #: ../src/guestfs.pod:2470 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2472 msgid "Translations of simple gettext strings." msgstr "" #. type: =item #: ../src/guestfs.pod:2474 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2476 msgid "" "The build infrastructure and PO files for translations of manpages and POD " "files. Eventually this will be combined with the C directory, but that " "is rather complicated." msgstr "" #. type: =item #: ../src/guestfs.pod:2480 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2482 msgid "Regression tests." msgstr "" #. type: =item #: ../src/guestfs.pod:2484 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2486 msgid "L command and documentation." msgstr "" #. type: =item #: ../src/guestfs.pod:2488 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2490 msgid "Source code to the C library." msgstr "" #. type: =item #: ../src/guestfs.pod:2492 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2494 msgid "Command line tools written in Perl (L and many others)." msgstr "" #. type: =item #: ../src/guestfs.pod:2496 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2498 msgid "" "Test tool for end users to test if their qemu/kernel combination will work " "with libguestfs." msgstr "" #. type: =item #: ../src/guestfs.pod:2501 msgid "C" msgstr "" #. type: =item #: ../src/guestfs.pod:2503 msgid "C" msgstr "" #. type: =item #: ../src/guestfs.pod:2505 msgid "C" msgstr "" #. type: =item #: ../src/guestfs.pod:2507 msgid "C" msgstr "" #. type: =item #: ../src/guestfs.pod:2509 msgid "C" msgstr "" #. type: =item #: ../src/guestfs.pod:2511 msgid "C" msgstr "" #. type: =item #: ../src/guestfs.pod:2513 msgid "C" msgstr "" #. type: =item #: ../src/guestfs.pod:2515 msgid "C" msgstr "" #. type: textblock #: ../src/guestfs.pod:2517 msgid "Language bindings." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:2521 ../fish/guestfish.pod:996 #: ../test-tool/libguestfs-test-tool.pod:104 ../tools/virt-edit.pl:330 msgid "ENVIRONMENT VARIABLES" msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:2525 ../fish/guestfish.pod:1022 msgid "LIBGUESTFS_APPEND" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2527 ../fish/guestfish.pod:1024 msgid "Pass additional options to the guest kernel." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:2529 ../fish/guestfish.pod:1026 msgid "LIBGUESTFS_DEBUG" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2531 msgid "" "Set C to enable verbose messages. This has the same " "effect as calling C." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:2534 ../fish/guestfish.pod:1031 msgid "LIBGUESTFS_MEMSIZE" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2536 ../fish/guestfish.pod:1033 msgid "" "Set the memory allocated to the qemu process, in megabytes. For example:" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs.pod:2539 ../fish/guestfish.pod:1036 #, no-wrap msgid "" " LIBGUESTFS_MEMSIZE=700\n" "\n" msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:2541 ../fish/guestfish.pod:1038 msgid "LIBGUESTFS_PATH" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2543 msgid "" "Set the path that libguestfs uses to search for kernel and initrd.img. See " "the discussion of paths in section PATH above." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:2546 ../fish/guestfish.pod:1043 msgid "LIBGUESTFS_QEMU" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2548 ../fish/guestfish.pod:1045 msgid "" "Set the default qemu binary that libguestfs uses. If not set, then the qemu " "which was found at compile time by the configure script is used." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2552 msgid "See also L above." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:2554 ../fish/guestfish.pod:1049 msgid "LIBGUESTFS_TRACE" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2556 msgid "" "Set C to enable command traces. This has the same " "effect as calling C." msgstr "" # type: =item #. type: =item #: ../src/guestfs.pod:2559 ../fish/guestfish.pod:1058 msgid "TMPDIR" msgstr "" #. type: textblock #: ../src/guestfs.pod:2561 ../fish/guestfish.pod:1060 msgid "" "Location of temporary directory, defaults to C except for the cached " "supermin appliance which defaults to C." msgstr "" #. type: textblock #: ../src/guestfs.pod:2564 ../fish/guestfish.pod:1063 msgid "" "If libguestfs was compiled to use the supermin appliance then the real " "appliance is cached in this directory, shared between all handles belonging " "to the same EUID. You can use C<$TMPDIR> to configure another directory to " "use in case C is not large enough." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:2572 ../fish/guestfish.pod:1121 #: ../test-tool/libguestfs-test-tool.pod:109 ../fuse/guestmount.pod:238 #: ../tools/virt-edit.pl:350 ../tools/virt-win-reg.pl:572 #: ../tools/virt-resize.pl:1483 ../tools/virt-list-filesystems.pl:189 #: ../tools/virt-tar.pl:286 ../tools/virt-make-fs.pl:539 #: ../tools/virt-list-partitions.pl:257 msgid "SEE ALSO" msgstr "" #. type: textblock #: ../src/guestfs.pod:2574 msgid "" "L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2601 msgid "" "Tools with a similar purpose: L, L, L, L, L." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:2608 ../tools/virt-win-reg.pl:587 #: ../tools/virt-make-fs.pl:553 msgid "BUGS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2610 msgid "To get a list of bugs against libguestfs use this link:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2612 msgid "" "L" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2614 msgid "To report a new bug against libguestfs use this link:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2616 msgid "" "L" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2618 msgid "When reporting a bug, please check:" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2624 msgid "That the bug hasn't been reported already." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2628 msgid "That you are testing a recent version." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2632 msgid "Describe the bug accurately, and give a way to reproduce it." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2636 msgid "" "Run libguestfs-test-tool and paste the B output into the " "bug report." msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:2641 ../fish/guestfish.pod:1144 #: ../test-tool/libguestfs-test-tool.pod:115 ../fuse/guestmount.pod:249 msgid "AUTHORS" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2643 ../fish/guestfish.pod:1146 #: ../test-tool/libguestfs-test-tool.pod:117 ../fuse/guestmount.pod:251 msgid "Richard W.M. Jones (C)" msgstr "" # type: =head1 #. type: =head1 #: ../src/guestfs.pod:2645 ../fish/guestfish.pod:1148 #: ../test-tool/libguestfs-test-tool.pod:119 ../fuse/guestmount.pod:253 #: ../tools/virt-edit.pl:368 ../tools/virt-win-reg.pl:602 #: ../tools/virt-resize.pl:1508 ../tools/virt-list-filesystems.pl:206 #: ../tools/virt-tar.pl:305 ../tools/virt-make-fs.pl:568 #: ../tools/virt-list-partitions.pl:273 msgid "COPYRIGHT" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2647 ../fish/guestfish.pod:1150 #: ../fuse/guestmount.pod:255 msgid "Copyright (C) 2009-2010 Red Hat Inc. L" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2650 msgid "" "This library is free software; you can redistribute it and/or modify it " "under the terms of the GNU Lesser General Public License as published by the " "Free Software Foundation; either version 2 of the License, or (at your " "option) any later version." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2655 msgid "" "This library is distributed in the hope that it will be useful, but WITHOUT " "ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or " "FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License " "for more details." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs.pod:2660 msgid "" "You should have received a copy of the GNU Lesser General Public License " "along with this library; if not, write to the Free Software Foundation, " "Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:1 msgid "guestfs_add_cdrom" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:3 #, no-wrap msgid "" " int\n" " guestfs_add_cdrom (guestfs_h *g,\n" " const char *filename);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:7 ../fish/guestfish-actions.pod:5 msgid "This function adds a virtual CD-ROM disk image to the guest." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:9 ../fish/guestfish-actions.pod:7 msgid "This is equivalent to the qemu parameter C<-cdrom filename>." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:17 msgid "" "This call checks for the existence of C. This stops you from " "specifying other types of drive which are supported by qemu such as C " "and C URLs. To specify those, use the general C call " "instead." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:24 msgid "" "If you just want to add an ISO file (often you use this as an efficient way " "to transfer large files into the guest), then you should probably use " "C instead." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:30 ../src/guestfs-actions.pod:134 #: ../src/guestfs-actions.pod:195 ../src/guestfs-actions.pod:232 #: ../src/guestfs-actions.pod:246 ../src/guestfs-actions.pod:267 #: ../src/guestfs-actions.pod:287 ../src/guestfs-actions.pod:301 #: ../src/guestfs-actions.pod:416 ../src/guestfs-actions.pod:436 #: ../src/guestfs-actions.pod:450 ../src/guestfs-actions.pod:495 #: ../src/guestfs-actions.pod:523 ../src/guestfs-actions.pod:541 #: ../src/guestfs-actions.pod:608 ../src/guestfs-actions.pod:641 #: ../src/guestfs-actions.pod:655 ../src/guestfs-actions.pod:670 #: ../src/guestfs-actions.pod:769 ../src/guestfs-actions.pod:787 #: ../src/guestfs-actions.pod:801 ../src/guestfs-actions.pod:815 #: ../src/guestfs-actions.pod:976 ../src/guestfs-actions.pod:996 #: ../src/guestfs-actions.pod:1014 ../src/guestfs-actions.pod:1098 #: ../src/guestfs-actions.pod:1116 ../src/guestfs-actions.pod:1135 #: ../src/guestfs-actions.pod:1149 ../src/guestfs-actions.pod:1169 #: ../src/guestfs-actions.pod:1239 ../src/guestfs-actions.pod:1270 #: ../src/guestfs-actions.pod:1295 ../src/guestfs-actions.pod:1332 #: ../src/guestfs-actions.pod:1438 ../src/guestfs-actions.pod:1472 #: ../src/guestfs-actions.pod:1690 ../src/guestfs-actions.pod:1712 #: ../src/guestfs-actions.pod:1799 ../src/guestfs-actions.pod:2261 #: ../src/guestfs-actions.pod:2405 ../src/guestfs-actions.pod:2466 #: ../src/guestfs-actions.pod:2501 ../src/guestfs-actions.pod:3336 #: ../src/guestfs-actions.pod:3351 ../src/guestfs-actions.pod:3371 #: ../src/guestfs-actions.pod:3526 ../src/guestfs-actions.pod:3540 #: ../src/guestfs-actions.pod:3553 ../src/guestfs-actions.pod:3567 #: ../src/guestfs-actions.pod:3582 ../src/guestfs-actions.pod:3618 #: ../src/guestfs-actions.pod:3690 ../src/guestfs-actions.pod:3710 #: ../src/guestfs-actions.pod:3727 ../src/guestfs-actions.pod:3750 #: ../src/guestfs-actions.pod:3773 ../src/guestfs-actions.pod:3805 #: ../src/guestfs-actions.pod:3824 ../src/guestfs-actions.pod:3843 #: ../src/guestfs-actions.pod:3878 ../src/guestfs-actions.pod:3890 #: ../src/guestfs-actions.pod:3926 ../src/guestfs-actions.pod:3942 #: ../src/guestfs-actions.pod:3955 ../src/guestfs-actions.pod:3970 #: ../src/guestfs-actions.pod:3987 ../src/guestfs-actions.pod:4080 #: ../src/guestfs-actions.pod:4100 ../src/guestfs-actions.pod:4113 #: ../src/guestfs-actions.pod:4164 ../src/guestfs-actions.pod:4182 #: ../src/guestfs-actions.pod:4200 ../src/guestfs-actions.pod:4216 #: ../src/guestfs-actions.pod:4230 ../src/guestfs-actions.pod:4244 #: ../src/guestfs-actions.pod:4261 ../src/guestfs-actions.pod:4276 #: ../src/guestfs-actions.pod:4296 ../src/guestfs-actions.pod:4354 #: ../src/guestfs-actions.pod:4427 ../src/guestfs-actions.pod:4458 #: ../src/guestfs-actions.pod:4477 ../src/guestfs-actions.pod:4496 #: ../src/guestfs-actions.pod:4508 ../src/guestfs-actions.pod:4525 #: ../src/guestfs-actions.pod:4538 ../src/guestfs-actions.pod:4553 #: ../src/guestfs-actions.pod:4568 ../src/guestfs-actions.pod:4603 #: ../src/guestfs-actions.pod:4618 ../src/guestfs-actions.pod:4638 #: ../src/guestfs-actions.pod:4652 ../src/guestfs-actions.pod:4669 #: ../src/guestfs-actions.pod:4718 ../src/guestfs-actions.pod:4755 #: ../src/guestfs-actions.pod:4769 ../src/guestfs-actions.pod:4797 #: ../src/guestfs-actions.pod:4814 ../src/guestfs-actions.pod:4832 #: ../src/guestfs-actions.pod:4966 ../src/guestfs-actions.pod:5023 #: ../src/guestfs-actions.pod:5045 ../src/guestfs-actions.pod:5063 #: ../src/guestfs-actions.pod:5095 ../src/guestfs-actions.pod:5161 #: ../src/guestfs-actions.pod:5178 ../src/guestfs-actions.pod:5191 #: ../src/guestfs-actions.pod:5205 ../src/guestfs-actions.pod:5494 #: ../src/guestfs-actions.pod:5513 ../src/guestfs-actions.pod:5532 #: ../src/guestfs-actions.pod:5544 ../src/guestfs-actions.pod:5556 #: ../src/guestfs-actions.pod:5570 ../src/guestfs-actions.pod:5582 #: ../src/guestfs-actions.pod:5596 ../src/guestfs-actions.pod:5612 #: ../src/guestfs-actions.pod:5633 ../src/guestfs-actions.pod:5652 #: ../src/guestfs-actions.pod:5671 ../src/guestfs-actions.pod:5701 #: ../src/guestfs-actions.pod:5717 ../src/guestfs-actions.pod:5740 #: ../src/guestfs-actions.pod:5758 ../src/guestfs-actions.pod:5777 #: ../src/guestfs-actions.pod:5798 ../src/guestfs-actions.pod:5817 #: ../src/guestfs-actions.pod:5834 ../src/guestfs-actions.pod:5862 #: ../src/guestfs-actions.pod:5886 ../src/guestfs-actions.pod:5905 #: ../src/guestfs-actions.pod:5929 ../src/guestfs-actions.pod:5944 #: ../src/guestfs-actions.pod:5959 ../src/guestfs-actions.pod:5978 #: ../src/guestfs-actions.pod:6015 ../src/guestfs-actions.pod:6038 #: ../src/guestfs-actions.pod:6064 ../src/guestfs-actions.pod:6172 #: ../src/guestfs-actions.pod:6293 ../src/guestfs-actions.pod:6305 #: ../src/guestfs-actions.pod:6318 ../src/guestfs-actions.pod:6331 #: ../src/guestfs-actions.pod:6353 ../src/guestfs-actions.pod:6366 #: ../src/guestfs-actions.pod:6379 ../src/guestfs-actions.pod:6392 #: ../src/guestfs-actions.pod:6407 ../src/guestfs-actions.pod:6466 #: ../src/guestfs-actions.pod:6483 ../src/guestfs-actions.pod:6499 #: ../src/guestfs-actions.pod:6515 ../src/guestfs-actions.pod:6532 #: ../src/guestfs-actions.pod:6545 ../src/guestfs-actions.pod:6565 #: ../src/guestfs-actions.pod:6601 ../src/guestfs-actions.pod:6615 #: ../src/guestfs-actions.pod:6656 ../src/guestfs-actions.pod:6669 #: ../src/guestfs-actions.pod:6687 ../src/guestfs-actions.pod:6721 #: ../src/guestfs-actions.pod:6757 ../src/guestfs-actions.pod:6876 #: ../src/guestfs-actions.pod:6894 ../src/guestfs-actions.pod:6908 #: ../src/guestfs-actions.pod:6963 ../src/guestfs-actions.pod:6976 #: ../src/guestfs-actions.pod:7021 ../src/guestfs-actions.pod:7054 #: ../src/guestfs-actions.pod:7108 ../src/guestfs-actions.pod:7134 #: ../src/guestfs-actions.pod:7200 ../src/guestfs-actions.pod:7219 #: ../src/guestfs-actions.pod:7248 msgid "This function returns 0 on success or -1 on error." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:32 ../src/guestfs-actions.pod:248 #: ../src/guestfs-actions.pod:269 ../fish/guestfish-actions.pod:28 #: ../fish/guestfish-actions.pod:158 ../fish/guestfish-actions.pod:172 msgid "" "This function is deprecated. In new code, use the C call " "instead." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:35 ../src/guestfs-actions.pod:251 #: ../src/guestfs-actions.pod:272 ../src/guestfs-actions.pod:1443 #: ../src/guestfs-actions.pod:1939 ../src/guestfs-actions.pod:1960 #: ../src/guestfs-actions.pod:4301 ../src/guestfs-actions.pod:7142 #: ../src/guestfs-actions.pod:7311 ../fish/guestfish-actions.pod:31 #: ../fish/guestfish-actions.pod:161 ../fish/guestfish-actions.pod:175 #: ../fish/guestfish-actions.pod:956 ../fish/guestfish-actions.pod:1319 #: ../fish/guestfish-actions.pod:1333 ../fish/guestfish-actions.pod:2908 #: ../fish/guestfish-actions.pod:4762 ../fish/guestfish-actions.pod:4859 msgid "" "Deprecated functions will not be removed from the API, but the fact that " "they are deprecated indicates that there are problems with correct use of " "these functions." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:39 ../src/guestfs-actions.pod:136 #: ../src/guestfs-actions.pod:1100 ../src/guestfs-actions.pod:1911 #: ../src/guestfs-actions.pod:2009 ../src/guestfs-actions.pod:2112 #: ../src/guestfs-actions.pod:3338 ../src/guestfs-actions.pod:3353 #: ../src/guestfs-actions.pod:4605 ../src/guestfs-actions.pod:5719 #: ../src/guestfs-actions.pod:5836 ../src/guestfs-actions.pod:5946 #: ../src/guestfs-actions.pod:6409 ../src/guestfs-actions.pod:6534 #: ../src/guestfs-actions.pod:7056 msgid "(Added in 0.3)" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:41 msgid "guestfs_add_domain" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:43 #, no-wrap msgid "" " int\n" " guestfs_add_domain (guestfs_h *g,\n" " const char *dom,\n" " ...);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:48 ../src/guestfs-actions.pod:145 #: ../src/guestfs-actions.pod:4315 msgid "" "You may supply a list of optional arguments to this call. Use zero or more " "of the following pairs of parameters, and terminate the list with C<-1> on " "its own. See L." msgstr "" #. type: verbatim #: ../src/guestfs-actions.pod:53 #, no-wrap msgid "" " GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,\n" " GUESTFS_ADD_DOMAIN_READONLY, int readonly,\n" " GUESTFS_ADD_DOMAIN_IFACE, const char *iface,\n" " GUESTFS_ADD_DOMAIN_LIVE, int live,\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:58 msgid "" "This function adds the disk(s) attached to the named libvirt domain C. " "It works by connecting to libvirt, requesting the domain and domain XML from " "libvirt, parsing it for disks, and calling C on each " "one." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:63 ../fish/guestfish-actions.pod:46 msgid "" "The number of disks added is returned. This operation is atomic: if an " "error is returned, then no disks are added." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:66 ../fish/guestfish-actions.pod:49 msgid "" "This function does some minimal checks to make sure the libvirt domain is " "not running (unless C is true). In a future version we will try " "to acquire the libvirt lock on each disk." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:70 ../fish/guestfish-actions.pod:53 msgid "" "Disks must be accessible locally. This often means that adding disks from a " "remote libvirt connection (see L) will fail " "unless those disks are accessible via the same device path locally too." msgstr "" #. type: textblock #: ../src/guestfs-actions.pod:75 ../fish/guestfish-actions.pod:58 msgid "" "The optional C parameter sets the libvirt URI (see L). If this is not set then we connect to the default " "libvirt URI (or one set through an environment variable, see the libvirt " "documentation for full details)." msgstr "" #. type: textblock #: ../src/guestfs-actions.pod:81 ../fish/guestfish-actions.pod:64 msgid "" "The optional C flag controls whether this call will try to connect to " "a running virtual machine C process if it sees a suitable " "EchannelE element in the libvirt XML definition. The default (if " "the flag is omitted) is never to try. See L for more information." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:88 msgid "" "The other optional parameters are passed directly through to " "C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:91 ../src/guestfs-actions.pod:344 #: ../src/guestfs-actions.pod:509 ../src/guestfs-actions.pod:687 #: ../src/guestfs-actions.pod:718 ../src/guestfs-actions.pod:736 #: ../src/guestfs-actions.pod:755 ../src/guestfs-actions.pod:1315 #: ../src/guestfs-actions.pod:1669 ../src/guestfs-actions.pod:1872 #: ../src/guestfs-actions.pod:1981 ../src/guestfs-actions.pod:2021 #: ../src/guestfs-actions.pod:2076 ../src/guestfs-actions.pod:2099 #: ../src/guestfs-actions.pod:2392 ../src/guestfs-actions.pod:2719 #: ../src/guestfs-actions.pod:2740 ../src/guestfs-actions.pod:4741 #: ../src/guestfs-actions.pod:4869 ../src/guestfs-actions.pod:5275 #: ../src/guestfs-actions.pod:5301 ../src/guestfs-actions.pod:6642 #: ../src/guestfs-actions.pod:7067 ../src/guestfs-actions.pod:7080 #: ../src/guestfs-actions.pod:7093 msgid "On error this function returns -1." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:93 msgid "(Added in 1.7.4)" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:95 msgid "guestfs_add_domain_va" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:97 #, no-wrap msgid "" " int\n" " guestfs_add_domain_va (guestfs_h *g,\n" " const char *dom,\n" " va_list args);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:102 msgid "This is the \"va_list variant\" of L." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:104 ../src/guestfs-actions.pod:115 #: ../src/guestfs-actions.pod:208 ../src/guestfs-actions.pod:219 #: ../src/guestfs-actions.pod:4368 ../src/guestfs-actions.pod:4380 msgid "See L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:106 msgid "guestfs_add_domain_argv" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:108 #, no-wrap msgid "" " int\n" " guestfs_add_domain_argv (guestfs_h *g,\n" " const char *dom,\n" " const struct guestfs_add_domain_argv *optargs);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:113 msgid "This is the \"argv variant\" of L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:117 msgid "guestfs_add_drive" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:119 #, no-wrap msgid "" " int\n" " guestfs_add_drive (guestfs_h *g,\n" " const char *filename);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:123 msgid "" "This function is the equivalent of calling C with no " "optional parameters, so the disk is added writable, with the format being " "detected automatically." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:127 msgid "" "Automatic detection of the format opens you up to a potential security hole " "when dealing with untrusted raw-format images. See CVE-2010-3851 and " "RHBZ#642934. Specifying the format closes this security hole. Therefore " "you should think about replacing calls to this function with calls to " "C, and specifying the format." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:138 msgid "guestfs_add_drive_opts" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:140 #, no-wrap msgid "" " int\n" " guestfs_add_drive_opts (guestfs_h *g,\n" " const char *filename,\n" " ...);\n" "\n" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:150 #, no-wrap msgid "" " GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,\n" " GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,\n" " GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:154 ../fish/guestfish-actions.pod:97 msgid "" "This function adds a virtual machine disk image C to libguestfs. " "The first time you call this function, the disk appears as C, the " "second time as C, and so on." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:159 ../fish/guestfish-actions.pod:102 msgid "" "You don't necessarily need to be root when using libguestfs. However you " "obviously do need sufficient permissions to access the filename for whatever " "operations you want to perform (ie. read access if you just want to read the " "image or write access if you want to modify the image)." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:165 ../fish/guestfish-actions.pod:108 msgid "This call checks that C exists." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:167 ../src/guestfs-actions.pod:4326 #: ../fish/guestfish-actions.pod:110 ../fish/guestfish-actions.pod:2919 msgid "The optional arguments are:" msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:171 ../fish/guestfish-actions.pod:114 msgid "C" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:173 ../fish/guestfish-actions.pod:116 msgid "" "If true then the image is treated as read-only. Writes are still allowed, " "but they are stored in a temporary snapshot overlay which is discarded at " "the end. The disk that you add is not modified." msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:177 ../fish/guestfish-actions.pod:120 msgid "C" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:179 msgid "" "This forces the image format. If you omit this (or use C " "or C) then the format is automatically detected. " "Possible formats include C and C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:183 ../fish/guestfish-actions.pod:126 msgid "" "Automatic detection of the format opens you up to a potential security hole " "when dealing with untrusted raw-format images. See CVE-2010-3851 and " "RHBZ#642934. Specifying the format closes this security hole." msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:188 ../fish/guestfish-actions.pod:131 msgid "C" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:190 msgid "" "This rarely-used option lets you emulate the behaviour of the deprecated " "C call (q.v.)" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:197 msgid "(Added in 1.5.23)" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:199 msgid "guestfs_add_drive_opts_va" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:201 #, no-wrap msgid "" " int\n" " guestfs_add_drive_opts_va (guestfs_h *g,\n" " const char *filename,\n" " va_list args);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:206 msgid "This is the \"va_list variant\" of L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:210 msgid "guestfs_add_drive_opts_argv" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:212 #, no-wrap msgid "" " int\n" " guestfs_add_drive_opts_argv (guestfs_h *g,\n" " const char *filename,\n" " const struct guestfs_add_drive_opts_argv *optargs);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:217 msgid "This is the \"argv variant\" of L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:221 msgid "guestfs_add_drive_ro" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:223 #, no-wrap msgid "" " int\n" " guestfs_add_drive_ro (guestfs_h *g,\n" " const char *filename);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:227 msgid "" "This function is the equivalent of calling C with " "the optional parameter C set to 1, so the " "disk is added read-only, with the format being detected automatically." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:234 msgid "(Added in 1.0.38)" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:236 msgid "guestfs_add_drive_ro_with_if" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:238 #, no-wrap msgid "" " int\n" " guestfs_add_drive_ro_with_if (guestfs_h *g,\n" " const char *filename,\n" " const char *iface);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:243 msgid "" "This is the same as C but it allows you to specify the " "QEMU interface emulation to use at run time." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:255 ../src/guestfs-actions.pod:276 #: ../src/guestfs-actions.pod:2351 msgid "(Added in 1.0.84)" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:257 msgid "guestfs_add_drive_with_if" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:259 #, no-wrap msgid "" " int\n" " guestfs_add_drive_with_if (guestfs_h *g,\n" " const char *filename,\n" " const char *iface);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:264 msgid "" "This is the same as C but it allows you to specify the " "QEMU interface emulation to use at run time." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:278 msgid "guestfs_aug_clear" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:280 #, no-wrap msgid "" " int\n" " guestfs_aug_clear (guestfs_h *g,\n" " const char *augpath);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:284 ../fish/guestfish-actions.pod:183 msgid "" "Set the value associated with C to C. This is the same as the " "L C command." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:289 ../src/guestfs-actions.pod:2101 msgid "(Added in 1.3.4)" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:291 msgid "guestfs_aug_close" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:293 #, no-wrap msgid "" " int\n" " guestfs_aug_close (guestfs_h *g);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:296 msgid "" "Close the current Augeas handle and free up any resources used by it. After " "calling this, you have to call C again before you can use " "any other Augeas functions." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:303 ../src/guestfs-actions.pod:328 #: ../src/guestfs-actions.pod:346 ../src/guestfs-actions.pod:360 #: ../src/guestfs-actions.pod:418 ../src/guestfs-actions.pod:438 #: ../src/guestfs-actions.pod:452 ../src/guestfs-actions.pod:483 #: ../src/guestfs-actions.pod:497 ../src/guestfs-actions.pod:511 #: ../src/guestfs-actions.pod:525 ../src/guestfs-actions.pod:543 #: ../src/guestfs-actions.pod:5352 msgid "(Added in 0.7)" msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:305 msgid "guestfs_aug_defnode" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:307 #, no-wrap msgid "" " struct guestfs_int_bool *\n" " guestfs_aug_defnode (guestfs_h *g,\n" " const char *name,\n" " const char *expr,\n" " const char *val);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:313 ../fish/guestfish-actions.pod:199 msgid "" "Defines a variable C whose value is the result of evaluating C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:316 msgid "" "If C evaluates to an empty nodeset, a node is created, equivalent to " "calling C C, C. C will be the nodeset " "containing that single node." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:320 ../fish/guestfish-actions.pod:206 msgid "" "On success this returns a pair containing the number of nodes in the " "nodeset, and a boolean flag if a node was created." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:324 msgid "" "This function returns a C, or NULL if there was " "an error. I after use>." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:330 msgid "guestfs_aug_defvar" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:332 #, no-wrap msgid "" " int\n" " guestfs_aug_defvar (guestfs_h *g,\n" " const char *name,\n" " const char *expr);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:337 ../fish/guestfish-actions.pod:214 msgid "" "Defines an Augeas variable C whose value is the result of evaluating " "C. If C is NULL, then C is undefined." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:341 ../fish/guestfish-actions.pod:218 msgid "" "On success this returns the number of nodes in C, or C<0> if C " "evaluates to something which is not a nodeset." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:348 msgid "guestfs_aug_get" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:350 #, no-wrap msgid "" " char *\n" " guestfs_aug_get (guestfs_h *g,\n" " const char *augpath);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:354 ../fish/guestfish-actions.pod:225 msgid "" "Look up the value associated with C. If C matches exactly one " "node, the C is returned." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:357 ../src/guestfs-actions.pod:857 #: ../src/guestfs-actions.pod:875 ../src/guestfs-actions.pod:935 #: ../src/guestfs-actions.pod:951 ../src/guestfs-actions.pod:1054 #: ../src/guestfs-actions.pod:1184 ../src/guestfs-actions.pod:1201 #: ../src/guestfs-actions.pod:1220 ../src/guestfs-actions.pod:1349 #: ../src/guestfs-actions.pod:1540 ../src/guestfs-actions.pod:1652 #: ../src/guestfs-actions.pod:1815 ../src/guestfs-actions.pod:1832 #: ../src/guestfs-actions.pod:1899 ../src/guestfs-actions.pod:1933 #: ../src/guestfs-actions.pod:1954 ../src/guestfs-actions.pod:2124 #: ../src/guestfs-actions.pod:2316 ../src/guestfs-actions.pod:2523 #: ../src/guestfs-actions.pod:2604 ../src/guestfs-actions.pod:2671 #: ../src/guestfs-actions.pod:2691 ../src/guestfs-actions.pod:2805 #: ../src/guestfs-actions.pod:2836 ../src/guestfs-actions.pod:2860 #: ../src/guestfs-actions.pod:2922 ../src/guestfs-actions.pod:2945 #: ../src/guestfs-actions.pod:3512 ../src/guestfs-actions.pod:3862 #: ../src/guestfs-actions.pod:4032 ../src/guestfs-actions.pod:4142 #: ../src/guestfs-actions.pod:4887 ../src/guestfs-actions.pod:5080 #: ../src/guestfs-actions.pod:5250 ../src/guestfs-actions.pod:5428 #: ../src/guestfs-actions.pod:5477 ../src/guestfs-actions.pod:6085 #: ../src/guestfs-actions.pod:6101 ../src/guestfs-actions.pod:6118 #: ../src/guestfs-actions.pod:6142 ../src/guestfs-actions.pod:6816 #: ../src/guestfs-actions.pod:6835 ../src/guestfs-actions.pod:6853 #: ../src/guestfs-actions.pod:7033 ../src/guestfs-actions.pod:7305 msgid "" "This function returns a string, or NULL on error. I." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:362 msgid "guestfs_aug_init" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:364 #, no-wrap msgid "" " int\n" " guestfs_aug_init (guestfs_h *g,\n" " const char *root,\n" " int flags);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:369 ../fish/guestfish-actions.pod:232 msgid "" "Create a new Augeas handle for editing configuration files. If there was " "any previous Augeas handle associated with this guestfs session, then it is " "closed." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:373 msgid "You must call this before using any other C commands." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:376 ../fish/guestfish-actions.pod:239 msgid "" "C is the filesystem root. C must not be NULL, use C instead." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:379 ../fish/guestfish-actions.pod:242 msgid "" "The flags are the same as the flags defined in Eaugeas.hE, the " "logical I of the following integers:" msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:385 ../fish/guestfish-actions.pod:248 msgid "C = 1" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:387 ../fish/guestfish-actions.pod:250 msgid "Keep the original file with a C<.augsave> extension." msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:389 ../fish/guestfish-actions.pod:252 msgid "C = 2" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:391 ../fish/guestfish-actions.pod:254 msgid "" "Save changes into a file with extension C<.augnew>, and do not overwrite " "original. Overrides C." msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:394 ../fish/guestfish-actions.pod:257 msgid "C = 4" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:396 ../fish/guestfish-actions.pod:259 msgid "Typecheck lenses (can be expensive)." msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:398 ../fish/guestfish-actions.pod:261 msgid "C = 8" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:400 ../fish/guestfish-actions.pod:263 msgid "Do not use standard load path for modules." msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:402 ../fish/guestfish-actions.pod:265 msgid "C = 16" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:404 ../fish/guestfish-actions.pod:267 msgid "Make save a no-op, just record what would have been changed." msgstr "" # type: =item #. type: =item #: ../src/guestfs-actions.pod:406 ../fish/guestfish-actions.pod:269 msgid "C = 32" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:408 msgid "Do not load the tree in C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:412 msgid "To close the handle, you can call C." msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:414 ../fish/guestfish-actions.pod:277 msgid "To find out more about Augeas, see L." msgstr "" # type: =head2 #. type: =head2 #: ../src/guestfs-actions.pod:420 msgid "guestfs_aug_insert" msgstr "" # type: verbatim #. type: verbatim #: ../src/guestfs-actions.pod:422 #, no-wrap msgid "" " int\n" " guestfs_aug_insert (guestfs_h *g,\n" " const char *augpath,\n" " const char *label,\n" " int before);\n" "\n" msgstr "" # type: textblock #. type: textblock #: ../src/guestfs-actions.pod:428 ../fish/guestfish-actions.pod:283 msgid "" "Create a new sibling C