X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=1c7a02aa035cf4e5b5d785c1bb87621f32adba8e;hp=30759602f45cfe3aeb6351ad60182a2e4b78b4c8;hb=9a608a1516bd339dc6d5ebe9952d3bced273c416;hpb=8980c01b46eafcf4b5dc127e4696c2cbe1bff09f diff --git a/src/guestfs.pod b/src/guestfs.pod index 3075960..1c7a02a 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -33,11 +33,13 @@ schemes, qcow, qcow2, vmdk. 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. @@ -448,10 +450,10 @@ Where we can help is in resolving the case insensitivity of paths. For this, call C. Libguestfs also provides some help for decoding Windows Registry -"hive" files, through the library C which is part of -libguestfs. You have to locate and download the hive file(s) -yourself, and then pass them to C functions. See also the -programs L, L and L for more +"hive" files, through the library C which is part of the +libguestfs project. You have to locate and download the hive file(s) +yourself, and then pass them to C functions. See also the +programs L, L and L for more help on this issue. =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES @@ -480,11 +482,16 @@ You can use the I header file from C++ programs. The C++ API is identical to the C API. C++ classes and exceptions are not implemented. +=item B + +The C# bindings are highly experimental. Please read the warnings +at the top of C. + =item B -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 @@ -518,6 +525,93 @@ For documentation see L. =back +=head2 LIBGUESTFS GOTCHAS + +L: "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 +unmount all filesystems and call L 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 +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 I. 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, 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 and set the mount +options that you actually want to use. + +=item Read-only should be the default. + +In L, 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 to guarantee that the disk is not changed. + +=item guestfish command line is hard to use. + +C doesn't do what people expect (open C +for examination). It tries to run a guestfish command C +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 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 +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 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 and L document how to do this. + +You might also consider mounting the disk image using our FUSE +filesystem support (L). + =head1 CONNECTION MANAGEMENT =head2 guestfs_h * @@ -713,7 +807,7 @@ need the compile time check as well): 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); @@ -1232,8 +1326,21 @@ enough. =head1 SEE ALSO L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, L, L, +L, L. Tools with a similar purpose: