+#. 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
+#: ../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
+#: ../src/guestfs.pod:966
+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:970
+#, no-wrap
+msgid ""
+" LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish\n"
+"\n"
+msgstr ""
+
+#. 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<Note (1):> This is B<highly experimental> and has a tendency to eat "
+"babies. Use with caution."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:980
+msgid ""
+"I<Note (2):> 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<guestfish(1)> 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</guestfs_set_attach_method> you can change how the library "
+"connects to the C<guestfsd> daemon in L</guestfs_launch> (read "
+"L</ARCHITECTURE> for some background)."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:990
+msgid ""
+"The normal attach method is C<appliance>, 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<unix:I<path>> (where I<path> is the path of a "
+"Unix domain socket) causes L</guestfs_launch> 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<guestfsd> 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</guestfs_add_domain> provides some help for getting the correct attach "
+"method. If you pass the C<live> 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 ""
+" <domain>\n"
+" ...\n"
+" <devices>\n"
+" ...\n"
+" <channel type='unix'>\n"
+" <source mode='bind' path='/path/to/socket'/>\n"
+" <target type='virtio' name='org.libguestfs.channel.0'/>\n"
+" </channel>\n"
+" ...\n"
+" </devices>\n"
+" </domain>\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1021
+msgid ""
+"L</guestfs_add_domain> extracts C</path/to/socket> and sets the attach "
+"method to C<unix:/path/to/socket>."
+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</guestfs_add_domain> 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
+#: ../src/guestfs.pod:1032
+msgid "ABI GUARANTEE"
+msgstr ""
+
+#. 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: =head2
+#: ../src/guestfs.pod:1040
+msgid "BLOCK DEVICE NAMING"
+msgstr ""
+
+#. 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<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: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
+#: ../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
+#: ../src/guestfs.pod:1063
+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:1069
+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:1074
+msgid "ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION"
+msgstr ""
+
+#. 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</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:1082
+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:1090
+msgid "Is the string a parameter which is a device or partition name?"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1094
+msgid "Does the string begin with C</dev/sd>?"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1098
+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:1103
+msgid "Replace initial C</dev/sd> string with C</dev/hd>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1105
+msgid "For example, change C</dev/sda2> to C</dev/hda2>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1107
+msgid "If that named device exists, use it. If not, continue."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1111
+msgid "Replace initial C</dev/sd> string with C</dev/vd>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1113
+msgid "If that named device exists, use it. If not, return an error."
+msgstr ""
+
+#. type: =head3
+#: ../src/guestfs.pod:1117
+msgid "PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING"
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1123
+msgid ""
+"Where possible for maximum future portability programs using libguestfs "
+"should use these future-proof techniques:"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1130
+msgid ""
+"Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list actual "
+"device names, and then use those names directly."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1133
+msgid "Since those device names exist by definition, they will never be translated."
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1143
+msgid "SECURITY"
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1148
+msgid "GENERAL SECURITY CONSIDERATIONS"
+msgstr ""
+
+#. 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</guestfs_download> 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
+#: ../src/guestfs.pod:1160
+msgid "the data (file etc) not being present"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1164
+msgid "being present but empty"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1168
+msgid "being much larger than normal"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1172
+msgid "containing arbitrary 8 bit data"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1176
+msgid "being in an unexpected character encoding"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1180
+msgid "containing homoglyphs."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1184
+msgid "SECURITY OF MOUNTING FILESYSTEMS"
+msgstr ""
+
+#. 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
+#: ../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
+#: ../src/guestfs.pod:1210
+msgid ""
+"In any case callers can reduce the attack surface by forcing the filesystem "
+"type when mounting (use L</guestfs_mount_vfs>)."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1213
+msgid "PROTOCOL SECURITY"
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1221
+msgid "INSPECTION SECURITY"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1223
+msgid ""
+"Parts of the inspection API (see L</INSPECTION>) 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
+#: ../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</etc/sysconfig/network> that we find in the "
+"guest, but the guest administrator can easily manipulate these files to "
+"provide the wrong hostname."
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1243
+msgid "RUNNING UNTRUSTED GUEST COMMANDS"
+msgstr ""
+
+#. 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</RUNNING COMMANDS>."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1251
+msgid "CVE-2010-3851"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1253
+msgid "https://bugzilla.redhat.com/642934"
+msgstr ""
+
+#. 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
+#: ../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
+#: ../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
+#: ../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
+#: ../src/guestfs.pod:1276
+msgid "In libguestfs this is rather hard to exploit except under two circumstances:"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1283
+msgid "You have enabled the network or have opened the disk in write mode."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1287
+msgid ""
+"You are also running untrusted code from the guest (see L</RUNNING "
+"COMMANDS>)."
+msgstr ""
+
+#. 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<format> option to L</guestfs_add_drive_opts>). You "
+"should always do this if the disk is raw format, and it's a good idea for "
+"other cases too."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1297
+msgid ""
+"For disks added from libvirt using calls like L</guestfs_add_domain>, the "
+"format is fetched from libvirt and passed through."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1300
+msgid ""
+"For libguestfs tools, use the I<--format> command line parameter as "
+"appropriate."
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:1303
+msgid "CONNECTION MANAGEMENT"
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1305
+msgid "guestfs_h *"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1307
+msgid ""
+"C<guestfs_h> is the opaque type representing a connection handle. Create a "
+"handle by calling L</guestfs_create>. Call L</guestfs_close> to free the "
+"handle and release all resources used."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1311
+msgid ""
+"For information on using multiple handles and threads, see the section "
+"L</MULTIPLE HANDLES AND MULTIPLE THREADS> below."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1314
+msgid "guestfs_create"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1316
+#, no-wrap
+msgid ""
+" guestfs_h *guestfs_create (void);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1318
+msgid "Create a connection handle."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1320
+msgid ""
+"You have to call L</guestfs_add_drive_opts> (or one of the equivalent calls) "
+"on the handle at least once."
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1326
+msgid "After configuring the handle, you have to call L</guestfs_launch>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1328
+msgid ""
+"You may also want to configure error handling for the handle. See L</ERROR "
+"HANDLING> section below."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1331
+msgid "guestfs_close"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1333
+#, no-wrap
+msgid ""
+" void guestfs_close (guestfs_h *g);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1335
+msgid "This closes the connection handle and frees up all resources used."
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:1337
+msgid "ERROR HANDLING"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1339
+msgid ""
+"API functions can return errors. For example, almost all functions that "
+"return C<int> will return C<-1> to indicate an error."
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1346
+msgid ""
+"You can get at the additional information about the last error on the handle "
+"by calling L</guestfs_last_error>, L</guestfs_last_errno>, and/or by setting "
+"up an error handler with L</guestfs_set_error_handler>."
+msgstr ""
+
+#. 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<stderr>. For small short-running "
+"command line programs it is sufficient to do:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1355
+#, no-wrap
+msgid ""
+" if (guestfs_launch (g) == -1)\n"
+" exit (EXIT_FAILURE);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1358
+msgid ""
+"since the default error handler will ensure that an error message has been "
+"printed to C<stderr> before the program exits."
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1364
+#, no-wrap
+msgid ""
+" g = guestfs_create ();\n"
+" \n"
+msgstr ""
+
+#. 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
+#: ../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
+#: ../src/guestfs.pod:1378
+msgid ""
+"Out of memory errors are handled differently. The default action is to call "
+"L<abort(3)>. If this is undesirable, then you can set a handler using "
+"L</guestfs_set_out_of_memory_handler>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1382
+msgid ""
+"L</guestfs_create> returns C<NULL> 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</guestfs_create> is supposed to be a "
+"lightweight operation which can only fail because of insufficient memory (it "
+"returns NULL in this case)."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1388
+msgid "guestfs_last_error"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1390
+#, no-wrap
+msgid ""
+" const char *guestfs_last_error (guestfs_h *g);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1392
+msgid ""
+"This returns the last error message that happened on C<g>. If there has not "
+"been an error since the handle was created, then this returns C<NULL>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1396
+msgid ""
+"The lifetime of the returned string is until the next error occurs, or "
+"L</guestfs_close> is called."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1399
+msgid "guestfs_last_errno"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1401
+#, no-wrap
+msgid ""
+" int guestfs_last_errno (guestfs_h *g);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1403
+msgid "This returns the last error number (errno) that happened on C<g>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1405
+msgid "If successful, an errno integer not equal to zero is returned."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1407
+msgid "If no error, this returns 0. This call can return 0 in three situations:"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1414
+msgid "There has not been any error on the handle."
+msgstr ""
+
+#. 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
+#: ../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
+#: ../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<EINVAL>. In practice this should "
+"only happen in very rare circumstances."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1438
+msgid "guestfs_set_error_handler"
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1447
+msgid ""
+"The callback C<cb> 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
+#: ../src/guestfs.pod:1451
+msgid ""
+"C<errno> is not passed to the callback. To get that the callback must call "
+"L</guestfs_last_errno>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1454
+msgid ""
+"Note that the message string C<msg> 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
+#: ../src/guestfs.pod:1458
+msgid "The default handler prints messages on C<stderr>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1460
+msgid "If you set C<cb> to C<NULL> then I<no> handler is called."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1462
+msgid "guestfs_get_error_handler"
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1467
+msgid "Returns the current error handler callback."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1469
+msgid "guestfs_set_out_of_memory_handler"
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1475
+msgid ""
+"The callback C<cb> will be called if there is an out of memory situation. "
+"I<Note this callback must not return>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1478
+msgid "The default is to call L<abort(3)>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1480
+msgid "You cannot set C<cb> to C<NULL>. You can't ignore out of memory situations."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1483
+msgid "guestfs_get_out_of_memory_handler"
+msgstr ""
+
+#. 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
+#: ../src/guestfs.pod:1487
+msgid "This returns the current out of memory handler."
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:1489
+msgid "API CALLS"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1491 ../fish/guestfish.pod:1003
+msgid "@ACTIONS@"
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:1493
+msgid "STRUCTURES"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1495
+msgid "@STRUCTS@"
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:1497
+msgid "AVAILABILITY"
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1499
+msgid "GROUPS OF FUNCTIONALITY IN THE APPLIANCE"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1501
+msgid ""
+"Using L</guestfs_available> 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
+#: ../src/guestfs.pod:1506
+msgid "@AVAILABILITY@"
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1508
+msgid "GUESTFISH supported COMMAND"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1510
+msgid ""
+"In L<guestfish(3)> there is a handy interactive command C<supported> which "
+"prints out the available groups and whether they are supported by this build "
+"of libguestfs. Note however that you have to do C<run> first."
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:1515
+msgid "SINGLE CALLS AT COMPILE TIME"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1517
+msgid ""
+"Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols for each C API "
+"function, such as:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1520
+#, no-wrap
git.annexia.org / libguestfs.git / blobdiff