guestfs-examples(3)					      Virtualization Support					       guestfs-examples(3)

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
");
	    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
");
	    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
";
	  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
");
	    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
");
	    exit (EXIT_FAILURE);
	  }

	  for (j = 0; roots[j] != NULL; ++j) {
	    root = roots[j];

	    printf ("Root device: %s
", root);

	    /* Print basic information about the operating system. */
	    str = guestfs_inspect_get_product_name (g, root);
	    if (str)
	      printf ("  Product name: %s
", str);
	    free (str);

	    printf ("  Version:      %d.%d
",
		    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
", str);
	    free (str);
	    str = guestfs_inspect_get_distro (g, root);
	    if (str)
	      printf ("  Distro:       %s
", 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 ---
");
	      lines = guestfs_head_n (g, 3, "/etc/issue.net");
	      if (lines == NULL)
		exit (EXIT_FAILURE);
	      for (i = 0; lines[i] != NULL; ++i) {
		printf ("%s
", 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

libguestfs-1.18.1						    2013-12-07						       guestfs-examples(3)