guestfs_download (g, filename, "/dev/stdout");
-and you can write tar output to a pipe C<fd> by doing:
+and you can write tar output to a file descriptor C<fd> by doing:
char devfd[64];
snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
=item Autosync / forgetting to sync.
+I<Update:> Autosync is enabled by default for all API users starting
+from libguestfs 1.5.24. This section only applies to older versions.
+
When modifying a filesystem from C or another language, you B<must>
unmount all filesystems and call L</guestfs_sync> explicitly before
you close the libguestfs handle. You can also call:
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.
-Update: Autosync is enabled by default for all API users starting from
-libguestfs 1.5.24.
-
=item Mount option C<-o sync> should not be the default.
If you use L</guestfs_mount>, then C<-o sync,noatime> are added
to free the handle and release all resources used.
For information on using multiple handles and threads, see the section
-L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
+L</MULTIPLE HANDLES AND MULTIPLE THREADS> above.
=head2 guestfs_create
Create a connection handle.
-You have to call L</guestfs_add_drive_opts> (or one of the equivalent
-calls) on the handle at least once.
+On success this returns a non-NULL pointer to a handle. On error it
+returns NULL.
-This function returns a non-NULL pointer to a handle on success or
-NULL on error.
+You have to "configure" the handle after creating it. This includes
+calling L</guestfs_add_drive_opts> (or one of the equivalent calls) on
+the handle at least once.
After configuring the handle, you have to call L</guestfs_launch>.
-You may also want to configure error handling for the handle. See
+You may also want to configure error handling for the handle. See the
L</ERROR HANDLING> section below.
=head2 guestfs_close
This closes the connection handle and frees up all resources used.
+If autosync was set on the handle and the handle was launched, then
+this implicitly calls various functions to unmount filesystems and
+sync the disk. See L</guestfs_set_autosync> for more details.
+
+If a close callback was set on the handle, then it is called.
+
=head1 ERROR HANDLING
API functions can return errors. For example, almost all functions
C<guestfs_set_subprocess_quit_callback>,
C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> and
C<guestfs_set_progress_callback> are no longer documented in this
-manual page.
+manual page. Because of the ABI guarantee, the old functions continue
+to work.
Handles generate events when certain things happen, such as log
messages being generated, progress messages during long-running
syslog (priority, "event 0x%lx: %s", event, buf);
}
+=head1 CANCELLING LONG TRANSFERS
+
+Some operations can be cancelled by the caller while they are in
+progress. Currently only operations that involve uploading or
+downloading data can be cancelled (technically: operations that have
+C<FileIn> or C<FileOut> parameters in the generator).
+
+=head2 guestfs_user_cancel
+
+ void guestfs_user_cancel (guestfs_h *g);
+
+C<guestfs_user_cancel> cancels the current upload or download
+operation.
+
+Unlike most other libguestfs calls, this function is signal safe and
+thread safe. You can call it from a signal handler or from another
+thread, without needing to do any locking.
+
+The transfer that was in progress (if there is one) will stop shortly
+afterwards, and will return an error. The errno (see
+L</guestfs_last_errno>) is set to C<EINTR>, so you can test for this
+to find out if the operation was cancelled or failed because of
+another error.
+
+No cleanup is performed: for example, if a file was being uploaded
+then after cancellation there may be a partially uploaded file. It is
+the caller's responsibility to clean up if necessary.
+
+There are two common places that you might call C<guestfs_user_cancel>.
+
+In an interactive text-based program, you might call it from a
+C<SIGINT> signal handler so that pressing C<^C> cancels the current
+operation. (You also need to call L</guestfs_set_pgroup> so that
+child processes don't receive the C<^C> signal).
+
+In a graphical program, when the main thread is displaying a progress
+bar with a cancel button, wire up the cancel button to call this
+function.
+
=head1 PRIVATE DATA AREA
You can attach named pieces of private data to the libguestfs handle,
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.
+same key is overwritten.
-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.
+You can use any C<key> you want, but your key should I<not> start with
+an underscore character. Keys beginning with an underscore character
+are reserved for internal libguestfs purposes (eg. for implementing
+language bindings). It is recommended that you prefix the key with
+some unique string to avoid collisions with other users.
To retrieve the pointer, use:
The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
and documentation.
+=item C<caution>
+
+Safety and liveness tests of components that libguestfs depends upon
+(not of libguestfs itself). Mainly this is for qemu and the kernel.
+
=item C<contrib>
Outside contributions, experimental parts.
L<virt-df(1)> command and documentation.
+=item C<edit>
+
+L<virt-edit(1)> command and documentation.
+
=item C<examples>
C API example code.
1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
host filesystem.
+Although libguestfs probably does not impose any limit, the underlying
+host storage will. If you store disk images on a host ext4
+filesystem, then the maximum size will be limited by the maximum ext4
+file size (currently 16 TB). If you store disk images as host logical
+volumes then you are limited by the maximum size of an LV.
+
+For the hugest disk image files, we recommend using XFS on the host
+for storage.
+
=head2 MAXIMUM SIZE OF A PARTITION
The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector