java: Add guestfs-java(3) man page.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index b66c16c..db9d8f0 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -728,7 +728,7 @@ and we are looking for help to complete this binding.
 =item B<Java>
 
 Full documentation is contained in the Javadoc which is distributed
 =item B<Java>
 
 Full documentation is contained in the Javadoc which is distributed

-with libguestfs.
+with libguestfs.  For examples, see L<guestfs-java(3)>.

 
 =item B<OCaml>
 
 
 =item B<OCaml>
 


@@ -775,6 +775,9 @@ them.
 
 =item Autosync / forgetting to sync.
 
 
 =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:
 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:


@@ -793,9 +796,6 @@ Note that in L<guestfish(3)> 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.
 
 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
 =item Mount option C<-o sync> should not be the default.
 
 If you use L</guestfs_mount>, then C<-o sync,noatime> are added


@@ -1285,7 +1285,7 @@ Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
 to free the handle and release all resources used.
 
 For information on using multiple handles and threads, see the section
 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
 
 
 =head2 guestfs_create
 


@@ -1672,7 +1672,8 @@ old functions C<guestfs_set_log_message_callback>,
 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
 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
 
 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);
  }
 
      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,
 =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<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
 
 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:
 
 
 To retrieve the pointer, use:
 


@@ -2656,6 +2697,11 @@ Automated tests of the C API.
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 
 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.
 =item C<contrib>
 
 Outside contributions, experimental parts.


@@ -2669,6 +2715,10 @@ actions.
 
 L<virt-df(1)> command and documentation.
 
 
 L<virt-df(1)> command and documentation.
 

+=item C<edit>
+
+L<virt-edit(1)> command and documentation.
+

 =item C<examples>
 
 C API example code.
 =item C<examples>
 
 C API example code.


@@ -2757,6 +2807,56 @@ Language bindings.
 
 =back
 
 
 =back
 

+=head2 MAKING A STABLE RELEASE
+
+When we make a stable release, there are several steps documented
+here.  See L</LIBGUESTFS VERSION NUMBERS> for general information
+about the stable branch policy.
+
+=over 4
+
+=item *
+
+Finalize RELEASE-NOTES.
+
+=item *
+
+Update ROADMAP.
+
+=item *
+
+Run C<src/api-support/update-from-tarballs.sh>.
+
+=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<http://libguestfs.org/download>.
+
+=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
 =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.
 
 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
 =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<guestfs-examples(3)>,
 =head1 SEE ALSO
 
 L<guestfs-examples(3)>,

+L<guestfs-java(3)>,

 L<guestfs-ocaml(3)>,
 L<guestfs-ocaml(3)>,

+L<guestfs-perl(3)>,

 L<guestfs-python(3)>,
 L<guestfs-ruby(3)>,
 L<guestfish(1)>,
 L<guestfs-python(3)>,
 L<guestfs-ruby(3)>,
 L<guestfish(1)>,