X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=cf70d5d17e0b28b29944e67fd813144e97a1a125;hp=84eec6359caefec1c4287b06d77e25a97112213c;hb=2e0f3ed54b978925c79ca0d33e76bec338b23631;hpb=c0baa7bdb2b404e8c808700984b3fc1a699d8dd7;ds=sidebyside diff --git a/src/guestfs.pod b/src/guestfs.pod index 84eec63..cf70d5d 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,7 +38,8 @@ 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, @@ -57,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 @@ -136,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 @@ -166,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 @@ -175,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 @@ -449,10 +460,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 @@ -461,9 +472,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 @@ -544,10 +555,10 @@ 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); + guestfs_set_autosync (g, 1); -to have the unmount/sync done automatically for you when the handle is -closed. (This feature is called "autosync", L +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 @@ -558,6 +569,15 @@ 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 @@ -579,6 +599,29 @@ 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 * @@ -608,7 +651,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. @@ -627,9 +670,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. @@ -642,10 +685,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); @@ -663,7 +706,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. @@ -671,7 +714,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 @@ -684,7 +727,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. @@ -774,7 +817,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); @@ -925,7 +968,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); @@ -940,7 +983,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); @@ -952,7 +995,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); @@ -1251,7 +1294,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 @@ -1276,7 +1319,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 @@ -1293,8 +1336,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: