Create a handle by calling C<guestfs_create>. Call C<guestfs_close>
to free the handle and release all resources used.
-Handles and operations on handles are not thread safe. However you
-can use a separate handle for each thread (but not on the same disk
-image).
+For information on using multiple handles and threads, see the section
+MULTIPLE HANDLES AND MULTIPLE THREADS below.
=head2 guestfs_create
=head2 NON-BLOCKING ACTIONS
-XXX NOT IMPLEMENTED YET XXX
+XXX This section was documented in previous versions but never
+implemented in a way which matched the documentation. For now I have
+removed the documentation, pending a working implementation. See also
+C<src/guestfs-actions.c> in the source.
-C<guestfs_set_reply_callback> is the most interesting callback to
-play with, since it allows you to perform actions without blocking.
-For example:
+=head2 guestfs_set_send_callback
- do_it ()
- {
- start_call ();
- guestfs_main_loop_run (); /* --> blocks, then calls my_cb */
- }
+ typedef void (*guestfs_send_cb) (guestfs_h *g, void *opaque);
+ void guestfs_set_send_callback (guestfs_h *handle,
+ guestfs_send_cb cb,
+ void *opaque);
- start_call ()
- {
- guestfs_set_reply_callback (handle, my_cb, data);
- guestfs_nb_[action] (handle, [other parameters ...]);
- /* returns immediately */
- }
-
- my_cb (guestfs_h *handle, void *data, XDR *xdr)
- {
- retval = guestfs_nb_[action]_r (handle, xdr);
- /* ... */
- }
-
-There are C<guestfs_nb_*> and C<guestfs_nb_*_r> functions
-corresponding to every C<guestfs_*> action in the high-level API.
+The callback function C<cb> will be called whenever a message
+which is queued for sending, has been sent.
=head2 guestfs_set_reply_callback
=head2 EVENT MAIN LOOP
-To use the low-level event API, you have to provide an event "main
-loop". You can write your own, but if you don't want to write one,
-two are provided for you:
+To use the low-level event API and/or to use handles from multiple
+threads, you have to provide an event "main loop". You can write your
+own, but if you don't want to write one, two types are provided for
+you:
=over 4
A simple main loop that is implemented using L<select(2)>.
-This is the default main loop unless you call C<guestfs_set_main_loop>
-or C<guestfs_glib_set_main_loop>.
+This is the default main loop for new guestfs handles, unless you
+call C<guestfs_set_main_loop> after a handle is created.
=item libguestfs-glib
=back
-=head2 guestfs_set_main_loop
+=head2 MULTIPLE HANDLES AND MULTIPLE THREADS
- void guestfs_set_main_loop (guestfs_main_loop *);
+The support for multiple handles and multiple threads is modelled
+after glib (although doesn't require glib, if you use the select-based
+main loop).
-This call sets the current main loop to the list of callbacks
-contained in the C<guestfs_main_loop> structure.
+L<http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html>
-Only one main loop implementation can be used by libguestfs, so
-calling this replaces the previous one. (So this is something that
-has to be done by the main program, but only the main program "knows"
-that it is a GTK+ program or whatever).
+You will need to create one main loop for each thread that wants to
+use libguestfs. Each guestfs handle should be confined to one thread.
+If you try to pass guestfs handles between threads, you will get
+undefined results.
-You should call this early in the main program, certainly before
-calling C<guestfs_create>.
+If you only want to use guestfs handles from one thread in your
+program, but your program has other threads doing other things, then
+you don't need to do anything special.
-=head2 guestfs_glib_set_main_loop
+=head2 SINGLE THREAD CASE
- void guestfs_glib_set_main_loop (GMainLoop *);
+In the single thread case, there is a single select-based main loop
+created for you. All guestfs handles will use this main loop to
+execute high level API actions.
-This helper calls C<guestfs_set_main_loop> with the correct callbacks
-for integrating with the GLib main loop.
+=head2 MULTIPLE THREADS CASE
-The libguestfs-glib main loop is contained in a separate library, so
-that libguestfs doesn't depend on the whole of GLib:
+In the multiple threads case, you will need to create a main loop for
+each thread that wants to use libguestfs.
- #include <glib.h>
- #include <guestfs-glib.h>
+To create main loops for other threads, use
+C<guestfs_create_main_loop> or C<guestfs_glib_create_main_loop>.
- main ()
- {
- GMainLoop *loop =
- g_main_loop_new (g_main_context_default (), 1);
- ...
- guestfs_glib_set_main_loop (loop);
- ...
- g_main_loop_run (loop);
- }
+Then you will need to attach each handle to the thread-specific main
+loop by calling:
+
+ handle = guestfs_create ();
+ guestfs_set_main_loop (handle, main_loop_of_current_thread);
+
+=head2 guestfs_set_main_loop
+
+ void guestfs_set_main_loop (guestfs_h *handle,
+ guestfs_main_loop *main_loop);
+
+Sets the main loop used by high level API actions for this handle. By
+default, the select-based main loop is used (see
+C<guestfs_get_default_main_loop>).
-To use this main loop you must link with C<-lguestfs-glib>. (See also
-the GLib and GTK+ documentation).
+You only need to use this in multi-threaded programs, where multiple
+threads want to use libguestfs. Create a main loop for each thread,
+then call this function.
-=head2 guestfs_main_loop_run
+You cannot pass guestfs handles between threads.
- void guestfs_main_loop_run (void);
+=head2 guestfs_get_main_loop
-This calls the main loop.
+ guestfs_main_loop *guestfs_get_main_loop (guestfs_h *handle);
-For some types of main loop you may want or prefer to call another
-function, eg. C<g_main_loop_run>, or the main loop may already be
-invoked by another part of your program. In those cases, ignore this
-call.
+Return the main loop used by C<handle>.
-=head2 guestfs_main_loop_quit
+=head2 guestfs_get_default_main_loop
- void guestfs_main_loop_quit (void);
+ guestfs_main_loop *guestfs_get_default_main_loop (void);
-This instructs the main loop to quit. In other words,
-C<guestfs_main_loop_run> will return.
+Return the default select-based main loop.
-For some types of main loop you may want or prefer to call another
-function, eg. C<g_main_loop_quit>. In those cases, ignore this call.
+=head2 guestfs_create_main_loop
+
+ guestfs_main_loop *guestfs_create_main_loop (void);
+
+This creates a select-based main loop. You should create one main
+loop for each additional thread that needs to use libguestfs.
+
+=head2 guestfs_free_main_loop
+
+ void guestfs_free_main_loop (guestfs_main_loop *);
+
+Free the select-based main loop which was previously allocated with
+C<guestfs_create_main_loop>.
=head2 WRITING A CUSTOM MAIN LOOP
This isn't documented. Please see the libguestfs-select and
libguestfs-glib implementations.
+=head1 INTERNALS
+
+=head2 COMMUNICATION PROTOCOL
+
+Don't rely on using this protocol directly. This section documents
+how it currently works, but it may change at any time.
+
+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).
+
+The detailed format of structures is in C<src/guestfs_protocol.x>
+(note: this file is automatically generated).
+
+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.
+
+=head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
+
+For ordinary functions, the request message is:
+
+ total length (header + arguments,
+ but not including the length word itself)
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_args (encoded as XDR)
+
+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.
+
+Note also that many functions don't take any arguments, in which case
+the C<guestfs_I<foo>_args> is completely omitted.
+
+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.
+
+The reply message for ordinary functions is:
+
+ total length (header + ret,
+ but not including the length word itself)
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_ret (encoded as XDR)
+
+As above the C<guestfs_I<foo>_ret> structure may be completely omitted
+for functions that return no formal return values.
+
+As above the total length of the reply is limited to
+C<GUESTFS_MESSAGE_MAX>.
+
+In the case of an error, a flag is set in the header, and the reply
+message is slightly changed:
+
+ total length (header + error,
+ but not including the length word itself)
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_message_error (encoded as XDR)
+
+The C<guestfs_message_error> structure contains the error message as a
+string.
+
+=head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS
+
+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.
+
+ total length (header + arguments,
+ but not including the length word itself,
+ and not including the chunks)
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_args (encoded as XDR)
+ sequence of chunks for FileIn param #0
+ sequence of chunks for FileIn param #1 etc.
+
+The "sequence of chunks" is:
+
+ length of chunk (not including length word itself)
+ struct guestfs_chunk (encoded as XDR)
+ length of chunk
+ struct guestfs_chunk (encoded as XDR)
+ ...
+ length of chunk
+ struct guestfs_chunk (with data.data_len == 0)
+
+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.
+
+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).
+
+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.
+
+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.
+
+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.
+
+=head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
+
+The protocol for FileOut parameters is exactly the same as for FileIn
+parameters, but with the roles of daemon and library reversed.
+
+ total length (header + ret,
+ but not including the length word itself,
+ and not including the chunks)
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_ret (encoded as XDR)
+ sequence of chunks for FileOut param #0
+ sequence of chunks for FileOut param #1 etc.
+
+=head3 INITIAL MESSAGE
+
+Because the underlying channel (QEmu -net channel) doesn't have any
+sort of connection control, 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 C<guestfs_wait_ready> waits for.
+
=head1 ENVIRONMENT VARIABLES
=over 4
git.annexia.org / libguestfs.git / blobdiff