+#. type: verbatim
+#: ../src/guestfs.pod:1898
+#, no-wrap
+msgid ""
+" typedef void (*guestfs_event_callback) (\n"
+" guestfs_h *g,\n"
+" void *opaque,\n"
+" uint64_t event,\n"
+" int event_handle,\n"
+" int flags,\n"
+" const char *buf, size_t buf_len,\n"
+" const uint64_t *array, size_t array_len);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1907
+msgid "This is the type of the event callback function that you have to provide."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1910
+msgid ""
+"The basic parameters are: the handle (C<g>), the opaque user pointer "
+"(C<opaque>), the event class (eg. C<GUESTFS_EVENT_PROGRESS>), the event "
+"handle, and C<flags> which in the current API you should ignore."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1914
+msgid ""
+"The remaining parameters contain the event payload (if any). Each event may "
+"contain a payload, which usually relates to the event class, but for future "
+"proofing your code should be written to handle any payload for any event "
+"class."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1919
+msgid ""
+"C<buf> and C<buf_len> contain a message buffer (if C<buf_len == 0>, then "
+"there is no message buffer). Note that this message buffer can contain "
+"arbitrary 8 bit data, including NUL bytes."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1923
+msgid ""
+"C<array> and C<array_len> is an array of 64 bit unsigned integers. At the "
+"moment this is only used for progress messages."
+msgstr ""
+
+#. type: =head3
+#: ../src/guestfs.pod:1926
+msgid "EXAMPLE: CAPTURING LOG MESSAGES"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1928
+msgid ""
+"One motivation for the generic event API was to allow GUI programs to "
+"capture debug and other messages. In libguestfs E<le> 1.8 these were sent "
+"unconditionally to C<stderr>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1932
+msgid ""
+"Events associated with log messages are: C<GUESTFS_EVENT_LIBRARY>, "
+"C<GUESTFS_EVENT_APPLIANCE> and C<GUESTFS_EVENT_TRACE>. (Note that error "
+"messages are not events; you must capture error messages separately)."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1937
+msgid ""
+"Programs have to set up a callback to capture the classes of events of "
+"interest:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1940
+#, no-wrap
+msgid ""
+" int eh =\n"
+" guestfs_set_event_callback\n"
+" (g, message_callback,\n"
+" GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_APPLIANCE|\n"
+" GUESTFS_EVENT_TRACE,\n"
+" 0, NULL) == -1)\n"
+" if (eh == -1) {\n"
+" // handle error in the usual way\n"
+" }\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1950
+msgid ""
+"The callback can then direct messages to the appropriate place. In this "
+"example, messages are directed to syslog:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1953
+#, no-wrap
+msgid ""
+" static void\n"
+" message_callback (\n"
+" guestfs_h *g,\n"
+" void *opaque,\n"
+" uint64_t event,\n"
+" int event_handle,\n"
+" int flags,\n"
+" const char *buf, size_t buf_len,\n"
+" const uint64_t *array, size_t array_len)\n"
+" {\n"
+" const int priority = LOG_USER|LOG_INFO;\n"
+" if (buf_len > 0)\n"
+" syslog (priority, \"event 0x%lx: %s\", event, buf);\n"
+" }\n"
+"\n"
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:1968
+msgid "PRIVATE DATA AREA"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1970
+msgid ""
+"You can attach named pieces of private data to the libguestfs handle, fetch "
+"them by name, and walk over them, for the lifetime of the handle. This is "
+"called the private data area and is only available from the C API."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1975
+msgid "To attach a named piece of data, use the following call:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1977
+#, no-wrap
+msgid ""
+" void guestfs_set_private (guestfs_h *g, const char *key, void *data);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1979
+msgid ""
+"C<key> is the name to associate with this data, and C<data> is an arbitrary "
+"pointer (which can be C<NULL>). Any previous item with the same name is "
+"overwritten."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1983
+msgid ""
+"You can use any C<key> 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
+#: ../src/guestfs.pod:1988
+msgid "To retrieve the pointer, use:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:1990
+#, no-wrap
+msgid ""
+" void *guestfs_get_private (guestfs_h *g, const char *key);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1992
+msgid ""
+"This function returns C<NULL> if either no data is found associated with "
+"C<key>, or if the user previously set the C<key>'s C<data> pointer to "
+"C<NULL>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:1996
+msgid ""
+"Libguestfs does not try to look at or interpret the C<data> pointer in any "
+"way. As far as libguestfs is concerned, it need not be a valid pointer at "
+"all. In particular, libguestfs does I<not> 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</guestfs_close> or must set up a close callback to "
+"do it (see L</GUESTFS_EVENT_CLOSE>)."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2003
+msgid "To walk over all entries, use these two functions:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2005
+#, no-wrap
+msgid ""
+" void *guestfs_first_private (guestfs_h *g, const char **key_rtn);\n"
+"\n"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2007
+#, no-wrap
+msgid ""
+" void *guestfs_next_private (guestfs_h *g, const char **key_rtn);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2009
+msgid ""
+"C<guestfs_first_private> returns the first key, pointer pair (\"first\" does "
+"not have any particular meaning -- keys are not returned in any defined "
+"order). A pointer to the key is returned in C<*key_rtn> and the "
+"corresponding data pointer is returned from the function. C<NULL> is "
+"returned if there are no keys stored in the handle."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2015
+msgid ""
+"C<guestfs_next_private> returns the next key, pointer pair. The return "
+"value of this function is also C<NULL> is there are no further entries to "
+"return."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2019
+msgid "Notes about walking over entries:"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2025
+msgid "You must not call C<guestfs_set_private> while walking over the entries."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2030
+msgid ""
+"The handle maintains an internal iterator which is reset when you call "
+"C<guestfs_first_private>. This internal iterator is invalidated when you "
+"call C<guestfs_set_private>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2036
+msgid "If you have set the data pointer associated with a key to C<NULL>, ie:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2038
+#, no-wrap
+msgid ""
+" guestfs_set_private (g, key, NULL);\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2040
+msgid "then that C<key> is not returned when walking."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2044
+msgid ""
+"C<*key_rtn> is only valid until the next call to C<guestfs_first_private>, "
+"C<guestfs_next_private> or C<guestfs_set_private>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2050
+msgid ""
+"The following example code shows how to print all keys and data pointers "
+"that are associated with the handle C<g>:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2053
+#, no-wrap
+msgid ""
+" const char *key;\n"
+" void *data = guestfs_first_private (g, &key);\n"
+" while (data != NULL)\n"
+" {\n"
+" printf (\"key = %s, data = %p\\n\", key, data);\n"
+" data = guestfs_next_private (g, &key);\n"
+" }\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2061
+msgid ""
+"More commonly you are only interested in keys that begin with an "
+"application-specific prefix C<foo_>. Modify the loop like so:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2064
+#, no-wrap
+msgid ""
+" const char *key;\n"
+" void *data = guestfs_first_private (g, &key);\n"
+" while (data != NULL)\n"
+" {\n"
+" if (strncmp (key, \"foo_\", strlen (\"foo_\")) == 0)\n"
+" printf (\"key = %s, data = %p\\n\", key, data);\n"
+" data = guestfs_next_private (g, &key);\n"
+" }\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2073
+msgid ""
+"If you need to modify keys while walking, then you have to jump back to the "
+"beginning of the loop. For example, to delete all keys prefixed with "
+"C<foo_>:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2077
+#, no-wrap
+msgid ""
+" const char *key;\n"
+" void *data;\n"
+" again:\n"
+" data = guestfs_first_private (g, &key);\n"
+" while (data != NULL)\n"
+" {\n"
+" if (strncmp (key, \"foo_\", strlen (\"foo_\")) == 0)\n"
+" {\n"
+" guestfs_set_private (g, key, NULL);\n"
+" /* note that 'key' pointer is now invalid, and so is\n"
+" the internal iterator */\n"
+" goto again;\n"
+" }\n"
+" data = guestfs_next_private (g, &key);\n"
+" }\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2093
+msgid ""
+"Note that the above loop is guaranteed to terminate because the keys are "
+"being deleted, but other manipulations of keys within the loop might not "
+"terminate unless you also maintain an indication of which keys have been "
+"visited."
+msgstr ""
+
+#. type: =end
+#: ../src/guestfs.pod:2098 ../src/guestfs.pod:2103
+msgid "html"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2100
+msgid ""
+"<!-- old anchor for the next section --> <a "
+"name=\"state_machine_and_low_level_event_api\"/>"
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:2105
+msgid "ARCHITECTURE"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2107
+msgid ""
+"Internally, libguestfs is implemented by running an appliance (a special "
+"type of small virtual machine) using L<qemu(1)>. Qemu runs as a child "
+"process of the main program."
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2111
+#, 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
+#: ../src/guestfs.pod:2131
+msgid ""
+"The library, linked to the main program, creates the child process and hence "
+"the appliance in the L</guestfs_launch> function."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2134
+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</guestfsd>. The library talks to L</guestfsd> 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
+#: ../src/guestfs.pod:2143
+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
+#: ../src/guestfs.pod:2150
+msgid "STATE MACHINE"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2152
+msgid "libguestfs uses a state machine to model the child process:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2154
+#, 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
+#: ../src/guestfs.pod:2176
+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
+#: ../src/guestfs.pod:2181
+msgid ""
+"The guest may be killed by L</guestfs_kill_subprocess>, 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
+#: ../src/guestfs.pod:2185
+msgid ""
+"Configuration commands for qemu such as L</guestfs_add_drive> can only be "
+"issued when in the CONFIG state."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2188
+msgid ""
+"The API offers one call that goes from CONFIG through LAUNCHING to READY. "
+"L</guestfs_launch> blocks until the child process is READY to accept "
+"commands (or until some failure or timeout). L</guestfs_launch> internally "
+"moves the state from CONFIG to LAUNCHING while it is running."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2194
+msgid ""
+"API actions such as L</guestfs_mount> 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
+#: ../src/guestfs.pod:2200
+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
+#: ../src/guestfs.pod:2204
+msgid "INTERNALS"
+msgstr ""
+
+#. type: =head2
+#: ../src/guestfs.pod:2206
+msgid "COMMUNICATION PROTOCOL"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2208
+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
+#: ../src/guestfs.pod:2211
+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
+#: ../src/guestfs.pod:2215
+msgid ""
+"The detailed format of structures is in C<src/guestfs_protocol.x> (note: "
+"this file is automatically generated)."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2218
+msgid ""
+"There are two broad cases, ordinary functions that don't have any C<FileIn> "
+"and C<FileOut> parameters, which are handled with very simple request/reply "
+"messages. Then there are functions that have any C<FileIn> or C<FileOut> "
+"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
+#: ../src/guestfs.pod:2225
+msgid "ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2227
+msgid "For ordinary functions, the request message is:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2229
+#, 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_<foo>_args (encoded as XDR)\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2234
+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<GUESTFS_MESSAGE_MAX> bytes (currently 4MB), which means the "
+"effective size of any request is limited to somewhere under this size."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2240
+msgid ""
+"Note also that many functions don't take any arguments, in which case the "
+"C<guestfs_I<foo>_args> is completely omitted."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2243
+msgid ""
+"The header contains the procedure number (C<guestfs_proc>) which is how the "
+"receiver knows what type of args structure to expect, or none at all."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2247
+msgid ""
+"For functions that take optional arguments, the optional arguments are "
+"encoded in the C<guestfs_I<foo>_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
+#: ../src/guestfs.pod:2255
+msgid "The reply message for ordinary functions is:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2257
+#, 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_<foo>_ret (encoded as XDR)\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2262
+msgid ""
+"As above the C<guestfs_I<foo>_ret> structure may be completely omitted for "
+"functions that return no formal return values."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2265
+msgid "As above the total length of the reply is limited to C<GUESTFS_MESSAGE_MAX>."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2268
+msgid ""
+"In the case of an error, a flag is set in the header, and the reply message "
+"is slightly changed:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2271
+#, 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
+#: ../src/guestfs.pod:2276
+msgid ""
+"The C<guestfs_message_error> structure contains the error message as a "
+"string."
+msgstr ""
+
+#. type: =head3
+#: ../src/guestfs.pod:2279
+msgid "FUNCTIONS THAT HAVE FILEIN PARAMETERS"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2281
+msgid ""
+"A C<FileIn> parameter indicates that we transfer a file I<into> the guest. "
+"The normal request message is sent (see above). However this is followed by "
+"a sequence of file chunks."
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2285
+#, 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_<foo>_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
+#: ../src/guestfs.pod:2293
+msgid "The \"sequence of chunks\" is:"
+msgstr ""
+
+#. type: verbatim
+#: ../src/guestfs.pod:2295
+#, 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
+#: ../src/guestfs.pod:2303
+msgid ""
+"The final chunk has the C<data_len> field set to zero. Additionally a flag "
+"is set in the final chunk to indicate either successful completion or early "
+"cancellation."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2307
+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
+#: ../src/guestfs.pod:2312
+msgid ""
+"Both the library (sender) I<and> 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<not> send any reply, and goes back to reading the next request."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2318
+msgid ""
+"The daemon may also cancel. It does this by writing a special word "
+"C<GUESTFS_CANCEL_FLAG> 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
+#: ../src/guestfs.pod:2327
+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<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the daemon need "
+"to keep much in memory."
+msgstr ""
+
+#. type: =head3
+#: ../src/guestfs.pod:2333
+msgid "FUNCTIONS THAT HAVE FILEOUT PARAMETERS"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2335
+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
+#: ../src/guestfs.pod:2338
+#, 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_<foo>_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
+#: ../src/guestfs.pod:2346
+msgid "INITIAL MESSAGE"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2348
+msgid ""
+"When the daemon launches it sends an initial word (C<GUESTFS_LAUNCH_FLAG>) "
+"which indicates that the guest and daemon is alive. This is what "
+"L</guestfs_launch> waits for."
+msgstr ""
+
+#. type: =head3
+#: ../src/guestfs.pod:2352
+msgid "PROGRESS NOTIFICATION MESSAGES"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2354
+msgid ""
+"The daemon may send progress notification messages at any time. These are "
+"distinguished by the normal length word being replaced by "
+"C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2358
+msgid ""
+"The library turns them into progress callbacks (see "
+"L</GUESTFS_EVENT_PROGRESS>) if there is a callback registered, or discards "
+"them if not."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2362
+msgid ""
+"The daemon self-limits the frequency of progress messages it sends (see "
+"C<daemon/proto.c:notify_progress>). Not all calls generate progress "
+"messages."
+msgstr ""
+
+#. type: =head1
+#: ../src/guestfs.pod:2366
+msgid "LIBGUESTFS VERSION NUMBERS"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2368
+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
+#: ../src/guestfs.pod:2373
+#, 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
+#: ../src/guestfs.pod:2384
+msgid "Thus \"1.3.5\" is the 5th update to the development branch \"1.3\"."
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2386
+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
+#: ../src/guestfs.pod:2392
+msgid "Our criteria for backporting changes are:"
+msgstr ""
+
+#. type: textblock
+#: ../src/guestfs.pod:2398