.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "guestfs-examples 3"
.TH guestfs-examples 3 "2013-12-07" "libguestfs-1.18.1" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
guestfs\-examples \- Examples of using libguestfs from C
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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\`
.Ve
.SH "DESCRIPTION"
.IX Header "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 \fIguestfs\fR\|(3).
.SH "EXAMPLE 1: CREATE A DISK IMAGE"
.IX Header "EXAMPLE 1: CREATE A DISK IMAGE"
.Vb 1
\& /* 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\en");
\&     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\en");
\&     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\en";
\&   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 \*(Aqautosync\*(Aq 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);
\& }
.Ve
.SH "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.IX Header "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.Vb 4
\& #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\en");
\&     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\en");
\&     exit (EXIT_FAILURE);
\&   }
\& 
\&   for (j = 0; roots[j] != NULL; ++j) {
\&     root = roots[j];
\& 
\&     printf ("Root device: %s\en", root);
\& 
\&     /* Print basic information about the operating system. */
\&     str = guestfs_inspect_get_product_name (g, root);
\&     if (str)
\&       printf ("  Product name: %s\en", str);
\&     free (str);
\& 
\&     printf ("  Version:      %d.%d\en",
\&             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\en", str);
\&     free (str);
\&     str = guestfs_inspect_get_distro (g, root);
\&     if (str)
\&       printf ("  Distro:       %s\en", 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\*(Aqs /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 \-\-\-\en");
\&       lines = guestfs_head_n (g, 3, "/etc/issue.net");
\&       if (lines == NULL)
\&         exit (EXIT_FAILURE);
\&       for (i = 0; lines[i] != NULL; ++i) {
\&         printf ("%s\en", 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);
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIguestfs\fR\|(3),
\&\fIguestfs\-erlang\fR\|(3),
\&\fIguestfs\-java\fR\|(3),
\&\fIguestfs\-ocaml\fR\|(3),
\&\fIguestfs\-perl\fR\|(3),
\&\fIguestfs\-python\fR\|(3),
\&\fIguestfs\-recipes\fR\|(1),
\&\fIguestfs\-ruby\fR\|(3),
<http://libguestfs.org/>.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2010 Red Hat Inc. <http://libguestfs.org/>
.PP
The examples in this manual page may be freely copied, modified and
distributed without any restrictions.
.PP
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
.PP
This library is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0 02110\-1301 \s-1USA\s0