Libguestfs provides ways to enumerate guest storage (eg. partitions,
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.
+in the context of the guest. Also you can access filesystems over
+FUSE.
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.
For this, call C<guestfs_case_sensitive_path>.
Libguestfs also provides some help for decoding Windows Registry
-"hive" files, through the library C<libhivex> which is part of
-libguestfs. You have to locate and download the hive file(s)
-yourself, and then pass them to C<libhivex> functions. See also the
-programs L<hivexml(1)>, L<hivexget(1)> and L<virt-win-reg(1)> for more
+"hive" files, through the library C<hivex> which is part of the
+libguestfs project. You have to locate and download the hive file(s)
+yourself, and then pass them to C<hivex> functions. See also the
+programs L<hivexml(1)>, L<hivexsh(1)> and L<virt-win-reg(1)> for more
help on this issue.
=head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
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>
=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 Mount option C<-o sync> should not be the default.
+
+If you use C<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 C<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
+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
+
+=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 C<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)>).
+
=head1 CONNECTION MANAGEMENT
=head2 guestfs_h *
dl = dlopen (NULL, RTLD_LAZY);
if (!dl) {
fprintf (stderr, "dlopen: %s\n", dlerror ());
- exit (1);
+ exit (EXIT_FAILURE);
}
has_function = dlsym (dl, "guestfs_dd") != NULL;
dlclose (dl);
=head1 SEE ALSO
L<guestfish(1)>,
+L<guestmount(1)>,
+L<virt-cat(1)>,
+L<virt-df(1)>,
+L<virt-edit(1)>,
+L<virt-inspector(1)>,
+L<virt-list-filesystems(1)>,
+L<virt-list-partitions(1)>,
+L<virt-ls(1)>,
+L<virt-make-fs(1)>,
+L<virt-rescue(1)>,
+L<virt-tar(1)>,
+L<virt-win-reg(1)>,
L<qemu(1)>,
L<febootstrap(1)>,
+L<hivex(3)>,
L<http://libguestfs.org/>.
Tools with a similar purpose:
git.annexia.org / libguestfs.git / blobdiff