#include <guestfs.h>
- 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
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<g> 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
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</dev/sda1> means literally the first partition (C<1>) of the
first disk image that we added (C</dev/sda>). If the disk contains
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<data> as a newly allocated buffer containing the
full content of that file (with some conditions: see also
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
errors into exceptions).
File writes are affected by the per-handle umask, set by calling
-C<guestfs_umask> and defaulting to 022.
+C<guestfs_umask> and defaulting to 022. See L</UMASK>.
=head2 PARTITIONING
for example by running the external command
C<restorecon pathname>.
+=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<guestfs_touch>, C<guestfs_mknod> or C<guestfs_mkdir>. 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<guestfs_umask (g, 0)> early after launching). Or call
+C<guestfs_chmod> after creating each file or directory.
+
+For more information about umask, see L<umask(2)>.
+
=head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
Libguestfs can mount NTFS partitions. It does this using the
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<guestfs_mount(handle,path)> is
-C<$handle-E<gt>mount($path)> in Perl, C<handle.mount(path)> in Python,
-and C<Guestfs.mount handle path> in OCaml. In other words, a
+that the C call C<guestfs_mount(g,path)> is
+C<$g-E<gt>mount($path)> in Perl, C<g.mount(path)> in Python,
+and C<Guestfs.mount g path> in OCaml. In other words, a
straightforward, predictable isomorphism between each language.
Error messages are automatically transformed
unmount all filesystems and call L</guestfs_sync> 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</guestfs_set_autosync>
+to have the unmount/sync done automatically for you when the handle 'g'
+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
=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.
=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<handle>. If
+This returns the last error message that happened on C<g>. If
there has not been an error since the handle was created, then this
returns C<NULL>.
=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);
=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.
=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<cb> will be called if there is an out of memory
=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.
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);
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);
=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);
=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);
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<don't> 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
=item LIBGUESTFS_DEBUG
Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This
-has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
+has the same effect as calling C<guestfs_set_verbose (g, 1)>.
=item LIBGUESTFS_MEMSIZE
=item LIBGUESTFS_TRACE
Set C<LIBGUESTFS_TRACE=1> to enable command traces. This
-has the same effect as calling C<guestfs_set_trace (handle, 1)>.
+has the same effect as calling C<guestfs_set_trace (g, 1)>.
=item TMPDIR
=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