Move docs/examples into examples/

* Makefile.am: Add examples/dominfo examples/domsuspend examples/python
  as SUBDIRS
* configure.in: Update AC_OUTPUT for new/old Makefiles
* docs/Makefile.am: Remove examples from SUBDIRS
* docs/examples/info1.c: Move to examples/dominfo/info1.c
* docs/examples/suspend.c: Move to examples/domsuspend/suspend.c
* docs/examples: Remove all remaining files
* docs/examples/python: Moved to examples/python/
* examples/dominfo/Makefile.am, examples/domsuspend/Makefile.am: New
  build files
* libvirt.spec.in: Update to take account of moved examples

examples/dominfo/.gitignore

@@ -0,0 +1,5 @@
+Makefile.in
+Makefile
+.deps
+.libs
+info1

examples/dominfo/Makefile.am

@@ -0,0 +1,10 @@
+
+INCLUDES = -I$(top_builddir)/include -I$(top_srcdir)/include -I@srcdir@/include
+LDADDS = @STATIC_BINARIES@ $(WARN_CFLAGS) $(top_builddir)/src/libvirt.la 	$(COVERAGE_LDFLAGS)
+
+noinst_PROGRAMS=info1
+
+info1_SOURCES=info1.c
+info1_LDFLAGS=
+info1_LDADD= $(LDADDS)
+

examples/dominfo/info1.c

@@ -0,0 +1,63 @@
+/**
+ * section: Informations
+ * synopsis: Extract information about Xen domain 0
+ * purpose: Demonstrate the basic use of the library to connect to the
+ *          hypervisor and extract domain information.
+ * usage: info1
+ * test: info1
+ * author: Daniel Veillard
+ * copy: see Copyright for the status of this software.
+ */
+
+#include <stdio.h>
+#include <libvirt/libvirt.h>
+
+/**
+ * getDomainInfo:
+ * @id: the id of the domain
+ *
+ * extract the domain 0 information
+ */
+static void
+getDomainInfo(int id) {
+    virConnectPtr conn = NULL; /* the hypervisor connection */
+    virDomainPtr dom = NULL;   /* the domain being checked */
+    virDomainInfo info;        /* the information being fetched */
+    int ret;
+
+    /* NULL means connect to local Xen hypervisor */
+    conn = virConnectOpenReadOnly(NULL);
+    if (conn == NULL) {
+        fprintf(stderr, "Failed to connect to hypervisor\n");
+        goto error;
+    }
+
+    /* Find the domain of the given id */
+    dom = virDomainLookupByID(conn, id);
+    if (dom == NULL) {
+        fprintf(stderr, "Failed to find Domain %d\n", id);
+        goto error;
+    }
+
+    /* Get the information */
+    ret = virDomainGetInfo(dom, &info);
+    if (ret < 0) {
+        fprintf(stderr, "Failed to get information for Domain %d\n", id);
+        goto error;
+    }
+
+    printf("Domains %d: %d CPUs\n", id, info.nrVirtCpu);
+
+error:
+    if (dom != NULL)
+        virDomainFree(dom);
+    if (conn != NULL)
+        virConnectClose(conn);
+}
+
+int main() {
+
+    getDomainInfo(0);
+
+    return(0);
+}

examples/domsuspend/.gitignore

@@ -0,0 +1,5 @@
+Makefile.in
+Makefile
+.deps
+.libs
+suspend

examples/domsuspend/Makefile.am

@@ -0,0 +1,10 @@
+
+INCLUDES = -I$(top_builddir)/include -I$(top_srcdir)/include -I@srcdir@/include
+LDADDS = @STATIC_BINARIES@ $(WARN_CFLAGS) $(top_builddir)/src/libvirt.la 	$(COVERAGE_LDFLAGS)
+
+noinst_PROGRAMS=suspend
+
+suspend_SOURCES=suspend.c
+suspend_LDFLAGS=
+suspend_LDADD= $(LDADDS)
+

examples/domsuspend/suspend.c

@@ -0,0 +1,134 @@
+/**
+ * section: Scheduling
+ * synopsis: Suspend a domain and then resume its execution
+ * purpose: Demonstrate the basic use of the library to suspend and
+ *          resume a domain. If no id is given on the command line
+ *          this script will suspend and resume the first domain found
+ *          which is not Domain 0.
+ * usage: suspend [id]
+ * test: suspend
+ * author: Daniel Veillard
+ * copy: see Copyright for the status of this software.
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <libvirt/libvirt.h>
+
+static virConnectPtr conn = NULL; /* the hypervisor connection */
+
+/**
+ * checkDomainState:
+ * @dom: the domain
+ *
+ * Return the current state of a domain or -1 if non-exsitant
+ */
+static int
+checkDomainState(virDomainPtr dom) {
+    virDomainInfo info;        /* the information being fetched */
+    int ret;
+
+    ret = virDomainGetInfo(dom, &info);
+    if (ret < 0) {
+        return(-1);
+    }
+    return(info.state);
+}
+
+/**
+ * SuspendAndResumeDomain:
+ * @id: the id of the domain
+ *
+ * extract the domain 0 information
+ */
+static void
+SuspendAndResumeDomain(int id) {
+    virDomainPtr dom = NULL;   /* the domain being checked */
+    int ret, state;
+
+    /* Find the domain of the given id */
+    dom = virDomainLookupByID(conn, id);
+    if (dom == NULL) {
+        fprintf(stderr, "Failed to find Domain %d\n", id);
+        goto error;
+    }
+
+    /* Check state */
+    state = checkDomainState(dom);
+    if ((state == VIR_DOMAIN_RUNNING) ||
+        (state == VIR_DOMAIN_NOSTATE) ||
+        (state == VIR_DOMAIN_BLOCKED)) {
+        printf("Suspending domain...\n");
+        ret = virDomainSuspend(dom);
+        if (ret < 0) {
+            fprintf(stderr, "Failed to suspend Domain %d\n", id);
+            goto error;
+        }
+        state = checkDomainState(dom);
+        if (state != VIR_DOMAIN_PAUSED) {
+            fprintf(stderr, "Domain %d state is not suspended\n", id);
+        } else {
+            printf("Domain suspended, resuming it...\n");
+        }
+        ret = virDomainResume(dom);
+        if (ret < 0) {
+            fprintf(stderr, "Failed to resume Domain %d\n", id);
+            goto error;
+        }
+        state = checkDomainState(dom);
+        if ((state == VIR_DOMAIN_RUNNING) ||
+            (state == VIR_DOMAIN_NOSTATE) ||
+            (state == VIR_DOMAIN_BLOCKED)) {
+            printf("Domain resumed\n");
+        } else {
+            fprintf(stderr, "Domain %d state indicate it is not resumed\n", id);
+        }
+    } else {
+        fprintf(stderr, "Domain %d is not in a state where it should be suspended\n", id);
+        goto error;
+    }
+
+error:
+    if (dom != NULL)
+        virDomainFree(dom);
+}
+
+int main(int argc, char **argv) {
+    int id = 0;
+
+    /* NULL means connect to local Xen hypervisor */
+    conn = virConnectOpenReadOnly(NULL);
+    if (conn == NULL) {
+        fprintf(stderr, "Failed to connect to hypervisor\n");
+        goto error;
+    }
+
+    if (argc > 1) {
+        id = atoi(argv[1]);
+    }
+    if (id == 0) {
+        int i, j, ids[10];
+        i = virConnectListDomains(conn, &ids[0], 10);
+        if (i < 0) {
+            fprintf(stderr, "Failed to list the domains\n");
+            goto error;
+        }
+        for (j = 0;j < i;j++) {
+            if (ids[j] != 0) {
+                id = ids[j];
+                break;
+            }
+        }
+    }
+    if (id == 0) {
+        fprintf(stderr, "Failed find a running guest domain\n");
+        goto error;
+    }
+
+    SuspendAndResumeDomain(id);
+
+error:
+    if (conn != NULL)
+        virConnectClose(conn);
+    return(0);
+}

examples/python/.gitignore

@@ -0,0 +1,2 @@
+Makefile
+Makefile.in

examples/python/Makefile.am

@@ -0,0 +1,3 @@
+EXTRA_DIST=						\
+	README						\
+	dominfo.py domrestore.py domsave.py domstart.py

examples/python/README

@@ -0,0 +1,14 @@
+Some simple examples on how to use the Python API for libvirt
+
+The examples are:
+
+dominfo.py  - print information about a running domU based on the results of
+              virDomainGetInfo and virDomainGetXMLDesc
+domstart.py - create a domU from an XML description if the domU isn't
+              running yet
+domsave.py  - save all running domU's into a directory
+domrestore.py - restore domU's from their saved files in a directory
+
+The XML files in this directory are examples of the XML format that libvirt
+expects, and will have to be adapted for your setup. They are only needed
+for domstart.py

examples/python/dominfo.py

@@ -0,0 +1,84 @@
+#! /usr/bin/python
+# dominfo - print some information about a domain
+
+import libvirt
+import sys
+import os
+import libxml2
+import pdb
+
+def usage():
+   print 'Usage: %s DOMAIN' % sys.argv[0]
+   print '       Print information about the domain DOMAIN'
+
+def print_section(title):
+    print "\n%s" % title
+    print "=" * 60
+
+def print_entry(key, value):
+    print "%-10s %-10s" % (key, value)
+
+def print_xml(key, ctx, path):
+    res = ctx.xpathEval(path)
+    if res is None or len(res) == 0:
+        value="Unknown"
+    else:
+        value = res[0].content
+    print_entry(key, value)
+    return value
+
+if not os.access("/proc/xen", os.R_OK):
+    print 'System is not running a Xen kernel'
+    sys.exit(1)
+
+if len(sys.argv) != 2:
+    usage()
+    sys.exit(2)
+
+name = sys.argv[1]
+
+# Connect to libvirt
+conn = libvirt.openReadOnly(None)
+if conn == None:
+    print 'Failed to open connection to the hypervisor'
+    sys.exit(1)
+
+try:
+    dom = conn.lookupByName(name)
+    # Annoyiingly, libvirt prints its own error message here
+except libvirt.libvirtError:
+    print "Domain %s is not runing" % name
+    sys.exit(0)
+
+info = dom.info()
+print_section("Domain info")
+print_entry("State:", info[0])
+print_entry("MaxMem:", info[1])
+print_entry("UsedMem:", info[2])
+print_entry("VCPUs:", info[3])
+
+# Read some info from the XML desc
+xmldesc = dom.XMLDesc(0)
+doc = libxml2.parseDoc(xmldesc)
+ctx = doc.xpathNewContext()
+print_section("Kernel")
+print_xml("Type:", ctx, "/domain/os/type")
+print_xml("Kernel:", ctx, "/domain/os/kernel")
+print_xml("initrd:", ctx, "/domain/os/initrd")
+print_xml("cmdline:", ctx, "/domain/os/cmdline")
+
+print_section("Devices")
+devs = ctx.xpathEval("/domain/devices/*")
+for d in devs:
+    ctx.setContextNode(d)
+    #pdb.set_trace()
+    type = print_xml("Type:", ctx, "@type")
+    if type == "file":
+        print_xml("Source:", ctx, "source/@file")
+        print_xml("Target:", ctx, "target/@dev")
+    elif type == "block":
+        print_xml("Source:", ctx, "source/@dev")
+        print_xml("Target:", ctx, "target/@dev")
+    elif type == "bridge":
+        print_xml("Source:", ctx, "source/@bridge")
+        print_xml("MAC Addr:", ctx, "mac/@address")

examples/python/domrestore.py

@@ -0,0 +1,36 @@
+#! /usr/bin/python
+# domstart - make sure a given domU is running, if not start it
+
+import libvirt
+import sys
+import os
+import libxml2
+import pdb
+
+def usage():
+   print 'Usage: %s DIR' % sys.argv[0]
+   print '       Restore all the domains contained in DIR'
+   print '       It is assumed that all files in DIR are'
+   print '       images of domU\'s previously created with save'
+
+if len(sys.argv) != 2:
+    usage()
+    sys.exit(2)
+
+dir = sys.argv[1]
+imgs = os.listdir(dir)
+
+conn = libvirt.open(None)
+if conn == None:
+    print 'Failed to open connection to the hypervisor'
+    sys.exit(1)
+
+for img in imgs:
+    file = os.path.join(dir, img)
+    print "Restoring %s ... " % img,
+    sys.stdout.flush()
+    ret = conn.restore(file)
+    if ret == 0:
+        print "done"
+    else:
+        print "error %d" % ret

examples/python/domsave.py

@@ -0,0 +1,40 @@
+#! /usr/bin/python
+# domstart - make sure a given domU is running, if not start it
+
+import libvirt
+import sys
+import os
+import libxml2
+import pdb
+
+def usage():
+   print 'Usage: %s DIR' % sys.argv[0]
+   print '       Save all currently running domU\'s into DIR'
+   print '       DIR must exist and be writable by this process'
+
+if len(sys.argv) != 2:
+    usage()
+    sys.exit(2)
+
+dir = sys.argv[1]
+
+conn = libvirt.open(None)
+if conn == None:
+    print 'Failed to open connection to the hypervisor'
+    sys.exit(1)
+
+doms = conn.listDomainsID()
+for id in doms:
+    if id == 0:
+        continue
+    dom = conn.lookupByID(id)
+    print "Saving %s[%d] ... " % (dom.name(), id),
+    sys.stdout.flush()
+    path = os.path.join(dir, dom.name())
+    ret = dom.save(path)
+    if ret == 0:
+        print "done"
+    else:
+        print "error %d" % ret
+
+#pdb.set_trace()

examples/python/domstart.py

@@ -0,0 +1,50 @@
+#! /usr/bin/python
+# domstart - make sure a given domU is running, if not start it
+
+import libvirt
+import sys
+import os
+import libxml2
+import pdb
+
+# Parse the XML description of domU from FNAME
+# and return a tuple (name, xmldesc) where NAME
+# is the name of the domain, and xmldesc is the contetn of FNAME
+def read_domain(fname):
+    fp = open(fname, "r")
+    xmldesc = fp.read()
+    fp.close()
+
+    doc = libxml2.parseDoc(xmldesc)
+    name = doc.xpathNewContext().xpathEval("/domain/name")[0].content
+    return (name, xmldesc)
+
+def usage():
+   print 'Usage: %s domain.xml' % sys.argv[0]
+   print '       Check that the domain described by DOMAIN.XML is running'
+   print '       If the domain is not running, create it'
+   print '       DOMAIN.XML must be a XML description of the domain'
+   print '       in libvirt\'s XML format'
+
+if len(sys.argv) != 2:
+    usage()
+    sys.exit(2)
+
+(name, xmldesc) = read_domain(sys.argv[1])
+
+conn = libvirt.open(None)
+if conn == None:
+    print 'Failed to open connection to the hypervisor'
+    sys.exit(1)
+
+try:
+    dom = conn.lookupByName(name)
+except libvirt.libvirtError:
+    print "Starting domain %s ... " % name,
+    sys.stdout.flush()
+    dom = conn.createLinux(xmldesc, 0)
+    if dom == None:
+        print "failed"
+        sys.exit(1)
+    else:
+        print "done"