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
-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.
@@ -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.
 
+=item B<C#>
+
+The C# bindings are highly experimental.  Please read the warnings
+at the top of C<csharp/Libguestfs.cs>.
+
 =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>
 
@@ -518,6 +524,61 @@ For documentation see L<guestfish(1)>.
 
 =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 *