NAME¶
guestfs-examples - Examples of using libguestfs from C
SYNOPSIS¶
#include <guestfs.h>
guestfs_h *g = guestfs_create ();
guestfs_add_drive_ro (g, "disk.img");
guestfs_launch (g);
cc prog.c -o prog -lguestfs
or:
cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
DESCRIPTION¶
This manual page contains examples of calling libguestfs from the C programming
language. If you are not familiar with using libguestfs, you also need to read
guestfs(3).
EXAMPLE 1: CREATE A DISK IMAGE¶
/* Example showing how to create a disk image. */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <unistd.h>
#include <guestfs.h>
int
main (int argc, char *argv[])
{
guestfs_h *g;
size_t i;
g = guestfs_create ();
if (g == NULL) {
perror ("failed to create libguestfs handle");
exit (EXIT_FAILURE);
}
/* Create a raw-format sparse disk image, 512 MB in size. */
int fd = open ("disk.img", O_CREAT|O_WRONLY|O_TRUNC|O_NOCTTY, 0666);
if (fd == -1) {
perror ("disk.img");
exit (EXIT_FAILURE);
}
if (ftruncate (fd, 512 * 1024 * 1024) == -1) {
perror ("disk.img: truncate");
exit (EXIT_FAILURE);
}
if (close (fd) == -1) {
perror ("disk.img: close");
exit (EXIT_FAILURE);
}
/* Set the trace flag so that we can see each libguestfs call. */
guestfs_set_trace (g, 1);
/* Set the autosync flag so that the disk will be synchronized
* automatically when the libguestfs handle is closed.
*/
guestfs_set_autosync (g, 1);
/* Add the disk image to libguestfs. */
if (guestfs_add_drive_opts (g, "disk.img",
GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw", /* raw format */
GUESTFS_ADD_DRIVE_OPTS_READONLY, 0, /* for write */
-1) /* this marks end of optional arguments */
== -1)
exit (EXIT_FAILURE);
/* Run the libguestfs back-end. */
if (guestfs_launch (g) == -1)
exit (EXIT_FAILURE);
/* Get the list of devices. Because we only added one drive
* above, we expect that this list should contain a single
* element.
*/
char **devices = guestfs_list_devices (g);
if (devices == NULL)
exit (EXIT_FAILURE);
if (devices[0] == NULL || devices[1] != NULL) {
fprintf (stderr, "error: expected a single device from list-devices\n");
exit (EXIT_FAILURE);
}
/* Partition the disk as one single MBR partition. */
if (guestfs_part_disk (g, devices[0], "mbr") == -1)
exit (EXIT_FAILURE);
/* Get the list of partitions. We expect a single element, which
* is the partition we have just created.
*/
char **partitions = guestfs_list_partitions (g);
if (partitions == NULL)
exit (EXIT_FAILURE);
if (partitions[0] == NULL || partitions[1] != NULL) {
fprintf (stderr, "error: expected a single partition from list-partitions\n");
exit (EXIT_FAILURE);
}
/* Create a filesystem on the partition. */
if (guestfs_mkfs (g, "ext4", partitions[0]) == -1)
exit (EXIT_FAILURE);
/* Now mount the filesystem so that we can add files. */
if (guestfs_mount_options (g, "", partitions[0], "/") == -1)
exit (EXIT_FAILURE);
/* Create some files and directories. */
if (guestfs_touch (g, "/empty") == -1)
exit (EXIT_FAILURE);
const char *message = "Hello, world\n";
if (guestfs_write (g, "/hello", message, strlen (message)) == -1)
exit (EXIT_FAILURE);
if (guestfs_mkdir (g, "/foo") == -1)
exit (EXIT_FAILURE);
/* This one uploads the local file /etc/resolv.conf into
* the disk image.
*/
if (guestfs_upload (g, "/etc/resolv.conf", "/foo/resolv.conf") == -1)
exit (EXIT_FAILURE);
/* Because 'autosync' was set (above) we can just close the handle
* and the disk contents will be synchronized. You can also do
* this manually by calling guestfs_umount_all and guestfs_sync.
*/
guestfs_close (g);
/* Free up the lists. */
for (i = 0; devices[i] != NULL; ++i)
free (devices[i]);
free (devices);
for (i = 0; partitions[i] != NULL; ++i)
free (partitions[i]);
free (partitions);
exit (EXIT_SUCCESS);
}
EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE¶
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <guestfs.h>
static int
compare_keys_len (const void *p1, const void *p2)
{
const char *key1 = * (char * const *) p1;
const char *key2 = * (char * const *) p2;
return strlen (key1) - strlen (key2);
}
static size_t
count_strings (char *const *argv)
{
size_t c;
for (c = 0; argv[c]; ++c)
;
return c;
}
int
main (int argc, char *argv[])
{
guestfs_h *g;
const char *disk;
char **roots, *root, *str, **mountpoints, **lines;
size_t i, j;
if (argc != 2) {
fprintf (stderr, "usage: inspect_vm disk.img\n");
exit (EXIT_FAILURE);
}
disk = argv[1];
g = guestfs_create ();
if (g == NULL) {
perror ("failed to create libguestfs handle");
exit (EXIT_FAILURE);
}
/* Attach the disk image read-only to libguestfs. */
if (guestfs_add_drive_opts (g, disk,
/* GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw", */
GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
-1) /* this marks end of optional arguments */
== -1)
exit (EXIT_FAILURE);
/* Run the libguestfs back-end. */
if (guestfs_launch (g) == -1)
exit (EXIT_FAILURE);
/* Ask libguestfs to inspect for operating systems. */
roots = guestfs_inspect_os (g);
if (roots == NULL)
exit (EXIT_FAILURE);
if (roots[0] == NULL) {
fprintf (stderr, "inspect_vm: no operating systems found\n");
exit (EXIT_FAILURE);
}
for (j = 0; roots[j] != NULL; ++j) {
root = roots[j];
printf ("Root device: %s\n", root);
/* Print basic information about the operating system. */
str = guestfs_inspect_get_product_name (g, root);
if (str)
printf (" Product name: %s\n", str);
free (str);
printf (" Version: %d.%d\n",
guestfs_inspect_get_major_version (g, root),
guestfs_inspect_get_minor_version (g, root));
str = guestfs_inspect_get_type (g, root);
if (str)
printf (" Type: %s\n", str);
free (str);
str = guestfs_inspect_get_distro (g, root);
if (str)
printf (" Distro: %s\n", str);
free (str);
/* Mount up the disks, like guestfish -i.
*
* Sort keys by length, shortest first, so that we end up
* mounting the filesystems in the correct order.
*/
mountpoints = guestfs_inspect_get_mountpoints (g, root);
if (mountpoints == NULL)
exit (EXIT_FAILURE);
qsort (mountpoints, count_strings (mountpoints) / 2, 2 * sizeof (char *),
compare_keys_len);
for (i = 0; mountpoints[i] != NULL; i += 2) {
/* Ignore failures from this call, since bogus entries can
* appear in the guest's /etc/fstab.
*/
guestfs_mount_ro (g, mountpoints[i+1], mountpoints[i]);
free (mountpoints[i]);
free (mountpoints[i+1]);
}
free (mountpoints);
/* If /etc/issue.net file exists, print up to 3 lines. */
if (guestfs_is_file (g, "/etc/issue.net") > 0) {
printf ("--- /etc/issue.net ---\n");
lines = guestfs_head_n (g, 3, "/etc/issue.net");
if (lines == NULL)
exit (EXIT_FAILURE);
for (i = 0; lines[i] != NULL; ++i) {
printf ("%s\n", lines[i]);
free (lines[i]);
}
free (lines);
}
/* Unmount everything. */
if (guestfs_umount_all (g) == -1)
exit (EXIT_FAILURE);
free (root);
}
free (roots);
guestfs_close (g);
exit (EXIT_SUCCESS);
}
SEE ALSO¶
guestfs(3),
guestfs-erlang(3),
guestfs-java(3),
guestfs-ocaml(3),
guestfs-perl(3),
guestfs-python(3),
guestfs-recipes(1),
guestfs-ruby(3),
<
http://libguestfs.org/>.
AUTHORS¶
Richard W.M. Jones ("rjones at redhat dot com")
COPYRIGHT¶
Copyright (C) 2010 Red Hat Inc. <
http://libguestfs.org/>
The examples in this manual page may be freely copied, modified and distributed
without any restrictions.
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
details.
You should have received a copy of the GNU Lesser General Public License along
with this library; if not, write to the Free Software Foundation, Inc., 51
Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
