X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=779ecc55ad7da1e30e5c37e1e7f4c68aaf5c59e5;hp=2e608c6ecf7f67f7e44137c8a6ce13aa36661303;hb=c2a8efc548d6f997049cbb3d63bab360b0d946b6;hpb=a8c3723e3818b5a7a31520043c6831115ab9d0e0 diff --git a/src/guestfs.pod b/src/guestfs.pod index 2e608c6..779ecc5 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 @@ -58,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 @@ -137,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 @@ -167,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 @@ -176,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 @@ -192,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 @@ -427,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 @@ -462,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 @@ -545,10 +572,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 @@ -641,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. @@ -660,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. @@ -675,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); @@ -696,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. @@ -704,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 @@ -717,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. @@ -807,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); @@ -958,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); @@ -973,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); @@ -985,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); @@ -1284,7 +1311,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 @@ -1309,7 +1336,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 @@ -1326,8 +1353,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: