+=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 (g, 1);
+
+to have the unmount/sync done automatically for you when the handle 'g'
+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)> 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.
+
+=item Mount option C<-o sync> should not be the default.
+
+If you use L</guestfs_mount>, then C<-o sync,noatime> are added
+implicitly. However C<-o sync> does not add any reliability benefit,
+but does have a very large performance impact.
+
+The work around is to use L</guestfs_mount_options> and set the mount
+options that you actually want to use.
+
+=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
+L</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. In earlier versions of guestfish
+the error message was also unintuitive, but we have corrected this
+since. Like the Bourne shell, we should have used C<guestfish -c
+command> to run commands.
+
+=item guestfish megabyte modifiers don't work right on all commands
+
+In recent guestfish you can use C<1M> to mean 1 megabyte (and
+similarly for other modifiers). What guestfish actually does is to
+multiply the number part by the modifier part and pass the result to
+the C API. However this doesn't work for a few APIs which aren't
+expecting bytes, but are already expecting some other unit
+(eg. megabytes).
+
+The most common is L</guestfs_lvcreate>. The guestfish command:
+
+ lvcreate LV VG 100M
+
+does not do what you might expect. Instead because
+L</guestfs_lvcreate> is already expecting megabytes, this tries to
+create a 100 I<terabyte> (100 megabytes * megabytes) logical volume.
+The error message you get from this is also a little obscure.
+
+This could be fixed in the generator by specially marking parameters
+and return values which take bytes or other units.
+
+=item Library should return errno with error messages.
+
+It would be a nice-to-have to be able to get the original value of
+'errno' from inside the appliance along error paths (where set).
+Currently L<guestmount(1)> goes through hoops to try to reverse the
+error message string into an errno, see the function error() in
+fuse/guestmount.c.
+
+In libguestfs 1.5.4, the protocol was changed so that the
+Linux errno is sent back from the daemon.
+
+=item Ambiguity between devices and paths
+
+There is a subtle ambiguity in the API between a device name
+(eg. C</dev/sdb2>) and a similar pathname. A file might just happen
+to be called C<sdb2> in the directory C</dev> (consider some non-Unix
+VM image).
+
+In the current API we usually resolve this ambiguity by having two
+separate calls, for example L</guestfs_checksum> and
+L</guestfs_checksum_device>. Some API calls are ambiguous and
+(incorrectly) resolve the problem by detecting if the path supplied
+begins with C</dev/>.
+
+To avoid both the ambiguity and the need to duplicate some calls, we
+could make paths/devices into structured names. One way to do this
+would be to use a notation like grub (C<hd(0,0)>), although nobody
+really likes this aspect of grub. Another way would be to use a
+structured type, equivalent to this OCaml type:
+
+ type path = Path of string | Device of int | Partition of int * int
+
+which would allow you to pass arguments like:
+
+ Path "/foo/bar"
+ Device 1 (* /dev/sdb, or perhaps /dev/sda *)
+ Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
+ Path "/dev/sdb2" (* not a device *)
+
+As you can see there are still problems to resolve even with this
+representation. Also consider how it might work in guestfish.
+
+=back
+
+=head2 PROTOCOL LIMITS
+
+Internally libguestfs uses a message-based protocol to pass API calls
+and their responses to and from a small "appliance" (see L</INTERNALS>
+for plenty more detail about this). The maximum message size used by
+the protocol is slightly less than 4 MB. For some API calls you may
+need to be aware of this limit. The API calls which may be affected
+are individually documented, with a link back to this section of the
+documentation.
+
+A simple call such as L</guestfs_cat> returns its result (the file
+data) in a simple string. Because this string is at some point
+internally encoded as a message, the maximum size that it can return
+is slightly under 4 MB. If the requested file is larger than this
+then you will get an error.
+
+In order to transfer large files into and out of the guest filesystem,
+you need to use particular calls that support this. The sections
+L</UPLOADING> and L</DOWNLOADING> document how to do this.
+
+You might also consider mounting the disk image using our FUSE
+filesystem support (L<guestmount(1)>).
+
+=head2 KEYS AND PASSPHRASES
+
+Certain libguestfs calls take a parameter that contains sensitive key
+material, passed in as a C string.
+
+In the future we would hope to change the libguestfs implementation so
+that keys are L<mlock(2)>-ed into physical RAM, and thus can never end
+up in swap. However this is I<not> done at the moment, because of the
+complexity of such an implementation.
+
+Therefore you should be aware that any key parameter you pass to
+libguestfs might end up being written out to the swap partition. If
+this is a concern, scrub the swap partition or don't use libguestfs on
+encrypted devices.
+