X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=src%2Fguestfs.pod;h=68fca7d5e75bf7809e4e2c575d54c930c30aec4b;hb=c8f302a17453ad58acccd137342438795763606a;hp=30759602f45cfe3aeb6351ad60182a2e4b78b4c8;hpb=8980c01b46eafcf4b5dc127e4696c2cbe1bff09f;p=libguestfs.git diff --git a/src/guestfs.pod b/src/guestfs.pod index 3075960..68fca7d 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -8,13 +8,18 @@ guestfs - Library for accessing and modifying virtual machine images #include - guestfs_h *handle = guestfs_create (); - guestfs_add_drive (handle, "guest.img"); - guestfs_launch (handle); - guestfs_mount (handle, "/dev/sda1", "/"); - guestfs_touch (handle, "/hello"); - guestfs_sync (handle); - guestfs_close (handle); + guestfs_h *g = guestfs_create (); + guestfs_add_drive (g, "guest.img"); + guestfs_launch (g); + guestfs_mount (g, "/dev/sda1", "/"); + guestfs_touch (g, "/hello"); + guestfs_umount (g, "/"); + guestfs_sync (g); + guestfs_close (g); + + cc prog.c -o prog -lguestfs +or: + cc prog.c -o prog `pkg-config libguestfs --cflags --libs` =head1 DESCRIPTION @@ -33,11 +38,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. @@ -56,43 +63,48 @@ from reading about the individual calls below. Before you can use libguestfs calls, you have to create a handle. Then you must add at least one disk image to the handle, followed by launching the handle, then performing whatever operations you want, -and finally closing the handle. So the general structure of all -libguestfs-using programs looks like this: +and finally closing the handle. By convention we use the single +letter C for the name of the handle variable, although of course +you can use any name you want. - guestfs_h *handle = guestfs_create (); +The general structure of all libguestfs-using programs looks like +this: + + guestfs_h *g = guestfs_create (); /* Call guestfs_add_drive additional times if there are * multiple disk images. */ - guestfs_add_drive (handle, "guest.img"); + guestfs_add_drive (g, "guest.img"); /* Most manipulation calls won't work until you've launched - * the handle. You have to do this _after_ adding drives + * the handle 'g'. You have to do this _after_ adding drives * and _before_ other commands. */ - guestfs_launch (handle); + guestfs_launch (g); /* Now you can examine what partitions, LVs etc are available. */ - char **partitions = guestfs_list_partitions (handle); - char **logvols = guestfs_lvs (handle); + char **partitions = guestfs_list_partitions (g); + char **logvols = guestfs_lvs (g); /* To access a filesystem in the image, you must mount it. */ - guestfs_mount (handle, "/dev/sda1", "/"); + guestfs_mount (g, "/dev/sda1", "/"); /* Now you can perform filesystem actions on the guest * disk image. */ - guestfs_touch (handle, "/hello"); + guestfs_touch (g, "/hello"); /* You only need to call guestfs_sync if you have made - * changes to the guest image. + * changes to the guest image. (But if you've made changes + * then you *must* sync). */ - guestfs_sync (handle); + guestfs_sync (g); - /* Close the handle. */ - guestfs_close (handle); + /* Close the handle 'g'. */ + guestfs_close (g); The code above doesn't include any error checking. In real code you should check return values carefully for errors. In general all @@ -135,7 +147,7 @@ filesystems using C. If you already know that a disk image contains (for example) one partition with a filesystem on that partition, then you can mount it directly: - guestfs_mount (handle, "/dev/sda1", "/"); + guestfs_mount (g, "/dev/sda1", "/"); where C means literally the first partition (C<1>) of the first disk image that we added (C). If the disk contains @@ -165,7 +177,7 @@ Specify filenames as full paths including the mount point. For example, if you mounted a filesystem at C<"/"> and you want to read the file called C<"etc/passwd"> then you could do: - char *data = guestfs_cat (handle, "/etc/passwd"); + char *data = guestfs_cat (g, "/etc/passwd"); This would return C as a newly allocated buffer containing the full content of that file (with some conditions: see also @@ -174,11 +186,11 @@ L below), or C if there was an error. As another example, to create a top-level directory on that filesystem called C<"var"> you would do: - guestfs_mkdir (handle, "/var"); + guestfs_mkdir (g, "/var"); To create a symlink you could do: - guestfs_ln_s (handle, "/etc/init.d/portmap", + guestfs_ln_s (g, "/etc/init.d/portmap", "/etc/rc3.d/S30portmap"); Libguestfs will reject attempts to use relative paths. There is no @@ -190,7 +202,7 @@ conditions after each call. (Other language bindings turn these errors into exceptions). File writes are affected by the per-handle umask, set by calling -C and defaulting to 022. +C and defaulting to 022. See L. =head2 PARTITIONING @@ -425,6 +437,23 @@ When new files are created, you may need to label them explicitly, for example by running the external command C. +=head2 UMASK + +Certain calls are affected by the current file mode creation mask (the +"umask"). In particular ones which create files or directories, such +as C, C or C. This +affects either the default mode that the file is created with or +modifies the mode that you supply. + +The default umask is C<022>, so files are created with modes such as +C<0644> and directories with C<0755>. + +There are two ways to avoid being affected by umask. Either set umask +to 0 (call C early after launching). Or call +C after creating each file or directory. + +For more information about umask, see L. + =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS Libguestfs can mount NTFS partitions. It does this using the @@ -448,10 +477,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 @@ -460,9 +489,9 @@ Although we don't want to discourage you from using the C API, we will mention here that the same API is also available in other languages. The API is broadly identical in all supported languages. This means -that the C call C is -C<$handle-Emount($path)> in Perl, C in Python, -and C in OCaml. In other words, a +that the C call C is +C<$g-Emount($path)> in Perl, C in Python, +and C in OCaml. In other words, a straightforward, predictable isomorphism between each language. Error messages are automatically transformed @@ -480,11 +509,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 +552,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 (g, 1); + +to have the unmount/sync done automatically for you when the handle 'g' +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 * @@ -547,7 +668,7 @@ L section below. =head2 guestfs_close - void guestfs_close (guestfs_h *handle); + void guestfs_close (guestfs_h *g); This closes the connection handle and frees up all resources used. @@ -566,9 +687,9 @@ handler using C. =head2 guestfs_last_error - const char *guestfs_last_error (guestfs_h *handle); + const char *guestfs_last_error (guestfs_h *g); -This returns the last error message that happened on C. If +This returns the last error message that happened on C. If there has not been an error since the handle was created, then this returns C. @@ -581,10 +702,10 @@ largest number of results. =head2 guestfs_set_error_handler - typedef void (*guestfs_error_handler_cb) (guestfs_h *handle, + typedef void (*guestfs_error_handler_cb) (guestfs_h *g, void *data, const char *msg); - void guestfs_set_error_handler (guestfs_h *handle, + void guestfs_set_error_handler (guestfs_h *g, guestfs_error_handler_cb cb, void *data); @@ -602,7 +723,7 @@ If you set C to C then I handler is called. =head2 guestfs_get_error_handler - guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle, + guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g, void **data_rtn); Returns the current error handler callback. @@ -610,7 +731,7 @@ Returns the current error handler callback. =head2 guestfs_set_out_of_memory_handler typedef void (*guestfs_abort_cb) (void); - int guestfs_set_out_of_memory_handler (guestfs_h *handle, + int guestfs_set_out_of_memory_handler (guestfs_h *g, guestfs_abort_cb); The callback C will be called if there is an out of memory @@ -623,7 +744,7 @@ situations. =head2 guestfs_get_out_of_memory_handler - guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle); + guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g); This returns the current out of memory handler. @@ -713,7 +834,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); @@ -864,7 +985,7 @@ this function with C set to C. typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, char *buf, int len); - void guestfs_set_log_message_callback (guestfs_h *handle, + void guestfs_set_log_message_callback (guestfs_h *g, guestfs_log_message_cb cb, void *opaque); @@ -879,7 +1000,7 @@ discarded. =head2 guestfs_set_subprocess_quit_callback typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque); - void guestfs_set_subprocess_quit_callback (guestfs_h *handle, + void guestfs_set_subprocess_quit_callback (guestfs_h *g, guestfs_subprocess_quit_cb cb, void *opaque); @@ -891,7 +1012,7 @@ any state to the CONFIG state). =head2 guestfs_set_launch_done_callback typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque); - void guestfs_set_launch_done_callback (guestfs_h *handle, + void guestfs_set_launch_done_callback (guestfs_h *g, guestfs_ready_cb cb, void *opaque); @@ -1179,6 +1300,69 @@ For example: Note that libguestfs also calls qemu with the -help and -version options in order to determine features. +=head1 LIBGUESTFS VERSION NUMBERS + +Since April 2010, libguestfs has started to make separate development +and stable releases, along with corresponding branches in our git +repository. These separate releases can be identified by version +number: + + even numbers for stable: 1.2.x, 1.4.x, ... + .-------- odd numbers for development: 1.3.x, 1.5.x, ... + | + v + 1 . 3 . 5 + ^ ^ + | | + | `-------- sub-version + | + `------ always '1' because we don't change the ABI + +Thus "1.3.5" is the 5th update to the development branch "1.3". + +As time passes we cherry pick fixes from the development branch and +backport those into the stable branch, the effect being that the +stable branch should get more stable and less buggy over time. So the +stable releases are ideal for people who don't need new features but +would just like the software to work. + +Our criteria for backporting changes are: + +=over 4 + +=item * + +Documentation changes which don't affect any code are +backported unless the documentation refers to a future feature +which is not in stable. + +=item * + +Bug fixes which are not controversial, fix obvious problems, and +have been well tested are backported. + +=item * + +Simple rearrangements of code which shouldn't affect how it works get +backported. This is so that the code in the two branches doesn't get +too far out of step, allowing us to backport future fixes more easily. + +=item * + +We I backport new features, new APIs, new tools etc, except in +one exceptional case: the new feature is required in order to +implement an important bug fix. + +=back + +A new stable branch starts when we think the new features in +development are substantial and compelling enough over the current +stable branch to warrant it. When that happens we create new stable +and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new +dot-oh release won't necessarily be so stable at this point, but by +backporting fixes from development, that branch will stabilize over +time. + =head1 ENVIRONMENT VARIABLES =over 4 @@ -1190,7 +1374,7 @@ Pass additional options to the guest kernel. =item LIBGUESTFS_DEBUG Set C to enable verbose messages. This -has the same effect as calling C. +has the same effect as calling C. =item LIBGUESTFS_MEMSIZE @@ -1215,7 +1399,7 @@ See also L above. =item LIBGUESTFS_TRACE Set C to enable command traces. This -has the same effect as calling C. +has the same effect as calling C. =item TMPDIR @@ -1232,8 +1416,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: