+#: ../src/guestfs.pod:774
+msgid "Ambiguity between devices and paths"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:776
+msgid ""
+"There is a subtle ambiguity in the API between a device name "
+"(eg. C</dev/sdb2>) and a similar pathname. A file might just happen to be "
+"called C<sdb2> in the directory C</dev> (consider some non-Unix VM image)."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:781
+msgid ""
+"In the current API we usually resolve this ambiguity by having two separate "
+"calls, for example L</guestfs_checksum> and L</guestfs_checksum_device>. "
+"Some API calls are ambiguous and (incorrectly) resolve the problem by "
+"detecting if the path supplied begins with C</dev/>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:787
+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<hd(0,0)>), 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
+#: ../src/guestfs.pod:793
+#, no-wrap
+msgid ""
+" type path = Path of string | Device of int | Partition of int * int\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:795
+msgid "which would allow you to pass arguments like:"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:797
+#, 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
+#: ../src/guestfs.pod:802
+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
+#: ../src/guestfs.pod:807
+msgid "PROTOCOL LIMITS"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:809
+msgid ""
+"Internally libguestfs uses a message-based protocol to pass API calls and "
+"their responses to and from a small \"appliance\" (see L</INTERNALS> 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
+#: ../src/guestfs.pod:817
+msgid ""
+"A simple call such as L</guestfs_cat> 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
+#: ../src/guestfs.pod:823
+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</UPLOADING> "
+"and L</DOWNLOADING> document how to do this."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:827
+msgid ""
+"You might also consider mounting the disk image using our FUSE filesystem "
+"support (L<guestmount(1)>)."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:830
+msgid "KEYS AND PASSPHRASES"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:832
+msgid ""
+"Certain libguestfs calls take a parameter that contains sensitive key "
+"material, passed in as a C string."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:835
+msgid ""
+"In the future we would hope to change the libguestfs implementation so that "
+"keys are L<mlock(2)>-ed into physical RAM, and thus can never end up in "
+"swap. However this is I<not> done at the moment, because of the complexity "
+"of such an implementation."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:840
+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: =head2
+#: ../src/guestfs.pod:845
+msgid "MULTIPLE HANDLES AND MULTIPLE THREADS"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:847
+msgid ""
+"All high-level libguestfs actions are synchronous. If you want to use "
+"libguestfs asynchronously then you must create a thread."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:850
+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
+#: ../src/guestfs.pod:854
+msgid ""
+"See the graphical program guestfs-browser for one possible architecture for "
+"multithreaded programs using libvirt and libguestfs."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:857
+msgid "PATH"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:859
+msgid ""
+"Libguestfs needs a kernel and initrd.img, which it finds by looking along an "
+"internal path."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:862
+msgid ""
+"By default it looks for these in the directory C<$libdir/guestfs> "
+"(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>)."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:865
+msgid ""
+"Use L</guestfs_set_path> or set the environment variable L</LIBGUESTFS_PATH> "
+"to change the directories that libguestfs will search in. The value is a "
+"colon-separated list of paths. The current directory is I<not> searched "
+"unless the path contains an empty element or C<.>. For example "
+"C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would search the current directory and "
+"then C</usr/lib/guestfs>."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:872
+msgid "QEMU WRAPPERS"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:874
+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
+#: ../src/guestfs.pod:878
+msgid ""
+"There is one important rule to remember: you I<must C<exec qemu>> 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
+#: ../src/guestfs.pod:883
+msgid ""
+"Here is an example of a wrapper, where I have built my own copy of qemu from "
+"source:"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:886
+#, 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
+#: ../src/guestfs.pod:890
+msgid ""
+"Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>, and "
+"then use it by setting the LIBGUESTFS_QEMU environment variable. For "
+"example:"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:894
+#, no-wrap
+msgid ""
+" LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:896
+msgid ""
+"Note that libguestfs also calls qemu with the -help and -version options in "
+"order to determine features."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:899
+msgid "ABI GUARANTEE"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:901
+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: =head2
+#: ../src/guestfs.pod:907
+msgid "BLOCK DEVICE NAMING"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:909
+msgid ""
+"In the kernel there is now quite a profusion of schemata for naming block "
+"devices (in this context, by I<block device> I mean a physical or virtual "
+"hard drive). The original Linux IDE driver used names starting with "
+"C</dev/hd*>. SCSI devices have historically used a different naming scheme, "
+"C</dev/sd*>. When the Linux kernel I<libata> driver became a popular "
+"replacement for the old IDE driver (particularly for SATA devices) those "
+"devices also used the C</dev/sd*> scheme. Additionally we now have virtual "
+"machines with paravirtualized drivers. This has created several different "
+"naming systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for "
+"Xen PV disks."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:921
+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
+#: ../src/guestfs.pod:925
+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
+#: ../src/guestfs.pod:930
+msgid ""
+"Therefore libguestfs defines C</dev/sd*> as the I<standard naming scheme>. "
+"Internally C</dev/sd*> names are translated, if necessary, to other names as "
+"required. For example, under RHEL 5 which uses the C</dev/hd*> scheme, any "
+"device parameter C</dev/sda2> is translated to C</dev/hda2> transparently."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:936
+msgid ""
+"Note that this I<only> applies to parameters. The L</guestfs_list_devices>, "
+"L</guestfs_list_partitions> and similar calls return the true names of the "
+"devices and partitions as known to the appliance."
+msgstr ""
+
+# type: =head3
+#: ../src/guestfs.pod:941
+msgid "ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:943
+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</guestfs_config> to add a mixture of virtio and IDE devices to the "
+"qemu-based appliance, so have a mixture of C</dev/sd*> and C</dev/vd*> "
+"devices."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:949
+msgid ""
+"The algorithm is applied only to I<parameters> which are known to be either "
+"device or partition names. Return values from functions such as "
+"L</guestfs_list_devices> are never changed."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:957
+msgid "Is the string a parameter which is a device or partition name?"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:961
+msgid "Does the string begin with C</dev/sd>?"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:965
+msgid ""
+"Does the named device exist? If so, we use that device. However if I<not> "
+"then we continue with this algorithm."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:970
+msgid "Replace initial C</dev/sd> string with C</dev/hd>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:972
+msgid "For example, change C</dev/sda2> to C</dev/hda2>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:974
+msgid "If that named device exists, use it. If not, continue."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:978
+msgid "Replace initial C</dev/sd> string with C</dev/vd>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:980
+msgid "If that named device exists, use it. If not, return an error."
+msgstr ""
+
+# type: =head3
+#: ../src/guestfs.pod:984
+msgid "PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING"