Documentation: Added a section on libguestfs gotchas.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 3075960..84eec63 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -36,8 +36,9 @@ LVs, what filesystem is in each LV, etc.).  It can also run commands
 in the context of the guest.  Also you can access filesystems over FTP.
 
 Libguestfs is a library that can be linked with C and C++ management
 in the context of the guest.  Also you can access filesystems over FTP.
 
 Libguestfs is a library that can be linked with C and C++ management

-programs (or management programs written in OCaml, Perl, Python, Ruby, Java
-or Haskell).  You can also use it from shell scripts or the command line.
+programs (or management programs written in OCaml, Perl, Python, Ruby,
+Java, Haskell or C#).  You can also use it from shell scripts or the
+command line.

 
 You don't need to be root to use libguestfs, although obviously you do
 need enough permissions to access the disk images.
 
 You don't need to be root to use libguestfs, although obviously you do
 need enough permissions to access the disk images.


@@ -480,11 +481,16 @@ You can use the I<guestfs.h> header file from C++ programs.  The C++
 API is identical to the C API.  C++ classes and exceptions are
 not implemented.
 
 API is identical to the C API.  C++ classes and exceptions are
 not implemented.
 

+=item B<C#>
+
+The C# bindings are highly experimental.  Please read the warnings
+at the top of C<csharp/Libguestfs.cs>.
+

 =item B<Haskell>
 
 =item B<Haskell>
 

-This is the only language binding that is incomplete.  Only calls
-which return simple integers have been bound in Haskell, and we are
-looking for help to complete this binding.
+This is the only language binding that working but incomplete.  Only
+calls which return simple integers have been bound in Haskell, and we
+are looking for help to complete this binding.

 
 =item B<Java>
 
 
 =item B<Java>
 


@@ -518,6 +524,61 @@ For documentation see L<guestfish(1)>.
 
 =back
 
 
 =back
 

+=head2 LIBGUESTFS GOTCHAS
+
+L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: "A feature of a
+system [...] that works in the way it is documented but is
+counterintuitive and almost invites mistakes."
+
+Since we developed libguestfs and the associated tools, there are
+several things we would have designed differently, but are now stuck
+with for backwards compatibility or other reasons.  If there is ever a
+libguestfs 2.0 release, you can expect these to change.  Beware of
+them.
+
+=over 4
+
+=item Autosync / forgetting to sync.
+
+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:
+
+ guestfs_set_autosync (handle, 1);
+
+to have the unmount/sync done automatically for you when the handle is
+closed.  (This feature is called "autosync", L</guestfs_set_autosync>
+q.v.)
+
+If you forget to do this, then it is entirely possible that your
+changes won't be written out, or will be partially written, or (very
+rarely) that you'll get disk corruption.
+
+Note that in L<guestfish(3)> I<autosync is the default>.  So quick and
+dirty guestfish scripts that forget to sync will work just fine, which
+can make this extra-puzzling if you are trying to debug a problem.
+
+=item Read-only should be the default.
+
+In L<guestfish(3)>, I<--ro> should be the default, and you should
+have to specify I<--rw> if you want to make changes to the image.
+
+This would reduce the potential to corrupt live VM images.
+
+Note that many filesystems change the disk when you just mount and
+unmount, even if you didn't perform any writes.  You need to use
+C<guestfs_add_drive_ro> to guarantee that the disk is not changed.
+
+=item guestfish command line is hard to use.
+
+C<guestfish disk.img> doesn't do what people expect (open C<disk.img>
+for examination).  It tries to run a guestfish command C<disk.img>
+which doesn't exist, so it fails, and it fails with a strange and
+unintuitive error message.  Like the Bourne shell, we should have used
+C<guestfish -c command> to run commands.
+
+=back
+

 =head1 CONNECTION MANAGEMENT
 
 =head2 guestfs_h *
 =head1 CONNECTION MANAGEMENT
 
 =head2 guestfs_h *