X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=db9d8f066c28cab951faea62f35e59eb73bb46e4;hp=b66c16c9fbb208151ed4f633c8d35698751cb109;hb=d025e91f6751505c70b7b5f492ee72c67e274ecf;hpb=470e373eea218c8d46b0c63dda93ee9ece48940f diff --git a/src/guestfs.pod b/src/guestfs.pod index b66c16c..db9d8f0 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -728,7 +728,7 @@ and we are looking for help to complete this binding. =item B Full documentation is contained in the Javadoc which is distributed -with libguestfs. +with libguestfs. For examples, see L. =item B @@ -775,6 +775,9 @@ them. =item Autosync / forgetting to sync. +I 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 unmount all filesystems and call L explicitly before you close the libguestfs handle. You can also call: @@ -793,9 +796,6 @@ Note that in L autosync is the default. So quick and 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, then C<-o sync,noatime> are added @@ -1285,7 +1285,7 @@ Create a handle by calling L. Call L to free the handle and release all resources used. For information on using multiple handles and threads, see the section -L below. +L above. =head2 guestfs_create @@ -1672,7 +1672,8 @@ old functions C, C, C, C and C 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 @@ -1948,6 +1949,45 @@ this example, messages are directed to syslog: 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 or C parameters in the generator). + +=head2 guestfs_user_cancel + + void guestfs_user_cancel (guestfs_h *g); + +C 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) is set to C, 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. + +In an interactive text-based program, you might call it from a +C signal handler so that pressing C<^C> cancels the current +operation. (You also need to call L 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, @@ -1961,12 +2001,13 @@ To attach a named piece of data, use the following call: C is the name to associate with this data, and C is an arbitrary pointer (which can be C). Any previous item with the -same name is overwritten. +same key is overwritten. -You can use any C 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 you want, but your key should I 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: @@ -2656,6 +2697,11 @@ Automated tests of the C API. The L, L and L commands and documentation. +=item C + +Safety and liveness tests of components that libguestfs depends upon +(not of libguestfs itself). Mainly this is for qemu and the kernel. + =item C Outside contributions, experimental parts. @@ -2669,6 +2715,10 @@ actions. L command and documentation. +=item C + +L command and documentation. + =item C C API example code. @@ -2757,6 +2807,56 @@ Language bindings. =back +=head2 MAKING A STABLE RELEASE + +When we make a stable release, there are several steps documented +here. See L for general information +about the stable branch policy. + +=over 4 + +=item * + +Finalize RELEASE-NOTES. + +=item * + +Update ROADMAP. + +=item * + +Run C. + +=item * + +Push and pull from Transifex. + +Run: + + tx push -s + +to push the latest POT files to Transifex. Then run: + + ./tx-pull.sh + +which is a wrapper to pull the latest translated C<*.po> files. + +=item * + +Create new stable and development directories under +L. + +=item * + +Create the branch in git: + + git tag -a 1.XX.0 -m "Version 1.XX.0 (stable)" + git tag -a 1.YY.0 -m "Version 1.YY.0 (development)" + git branch stable-1.XX + git push origin tag 1.XX.0 1.YY.0 stable-1.XX + +=back + =head1 LIMITS =head2 PROTOCOL LIMITS @@ -2817,6 +2917,15 @@ We have tested block devices up to 1 exabyte (2**60 or 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 @@ -2902,7 +3011,9 @@ enough. =head1 SEE ALSO L, +L, L, +L, L, L, L,