* docs/errors.html docs/libvir.html docs/*: added a page about

error handling and regenerated the docs Daniel

* docs/errors.html docs/libvir.html docs/*: added a page about
error handling and regenerated the docs Daniel
6c5a2257 · Daniel Veillard · 97e7e798 · 6c5a2257 · 6c5a2257 · 6c5a2257
13 changed file
--- a/ChangeLog
+++ b/ChangeLog
+Tue Feb 28 14:57:25 CET 2006 Daniel Veillard <veillard@redhat.com>
+
+	* docs/errors.html docs/libvir.html docs/*: added a page about
+	  error handling and regenerated the docs
+
 Tue Feb 28 13:12:50 CET 2006 Daniel Veillard <veillard@redhat.com>

 	* TODO: updated

--- a/docs/FAQ.html
+++ b/docs/FAQ.html
@@ -77,4 +77,4 @@
    via the pkg-config command line tool, like:</p>
    <p><code>pkg-config libvirt --libs</code></p>
  </li>
-</ol></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+</ol></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/architecture.html
+++ b/docs/architecture.html
@@ -24,4 +24,4 @@ connect to initialize the library. It will try to open the read-only socket
 <code>/var/run/xenstored/socket_ro</code> to connect to the Xen Store and
 also try to use the RPC to the Xen daemon. In this case use of hypervisor
 calls and write to the Xen Store will not be possible, restraining the amount
-of APIs available and slowing down information gathering about domains.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+of APIs available and slowing down information gathering about domains.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/bugs.html
+++ b/docs/bugs.html
@@ -7,4 +7,4 @@ page and follow the instructions. Patches with explanations and provided as
 attachments are really appreciated and will be discussed on the mailing list.
 If possible generate the patches by using cvs diff -u in a CVS checkout.</p><p>We expect to use <a href="https://bugzilla.redhat.com/">Red Hat
 Bugzilla</a> to track bugs for libvirt, though there isn't a libvirt software
-module defined yet, in the meantime use the mailing-list, thanks !.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+module defined yet, in the meantime use the mailing-list, thanks !.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/downloads.html
+++ b/docs/downloads.html
@@ -7,4 +7,4 @@ available, first register onto the server:</p><p><code>cvs -d :pserver:anoncvs@l
 checkout the development tree with:</p><p><code>cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co
 libvirt</code></p><p>Use ./autogen.sh to configure the local checkout, then <code>make</code>
 and <code>make install</code>, as usual. All normal cvs commands are now
-available except commiting to the base.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+available except commiting to the base.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/errors.html
+++ b/docs/errors.html
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvirt.css" /><link rel="SHORTCUT ICON" href="/32favicon.png" /><title>Handling of errors</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">Handling of errors</h1><p>The main goals of libvirt when it comes to error handling are:</p><ul><li>provide as much detail as possible</li>
+  <li>provide the informations as soon as possible</li>
+  <li>dont force the library user into one style of error handling</li>
+</ul><p>As result the library provide both synchronous, callback based and
+asynchronous error reporting. When an error happens in the library code the
+error is logged, allowing to retrieve it later and if the user registered an
+error callback it will be called synchronously. Once the call to libvirt ends
+the error can be detected by the return value and the full information for
+the last logged error can be retrieved.</p><p>To avoid as much as prossible troubles with a global variable in a
+multithreaded environment, libvirt will associate when possible the errors to
+the current connection they are related to, that way the error is stored in a
+dynamic structure which can be made thread specific. Error callback can be
+set specifically to a connection with</p><p>So error handling in the code is the following:</p><ol><li>if the error can be associated to a connection for example when failing
+    to look up a domain
+    <ol><li>if there is a callback associated to the connection set with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
+        call it with the error informations</li>
+      <li>otherwise if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
+        call it with the error information</li>
+      <li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
+        which is the default error function of the library issuing the error
+        on stderr</li>
+      <li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virConnGetLastError">virConnGetLastError</a></li>
+    </ol></li>
+  <li>otherwise like when failing to create an hypervisor connection:
+    <ol><li>if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
+        call it with the error information</li>
+      <li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
+        which is the default error function of the library issuing the error
+        on stderr</li>
+      <li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li>
+    </ol></li>
+</ol><p>In all cases the error informations are provided as a <a href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to
+read-only structure <a href="html/libvirt-virterror.html#virError">virError</a> containing the
+following fields: </p><ul><li>code: an error number from the <a href="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a>
+  enum</li>
+  <li>domain: an enum indicating which part of libvirt raised the error see
+    <a href="html/libvirt-virterror.html#virErrorDomain">virErrorDomain</a></li>
+  <li>level: the error level, usually VIR_ERR_ERROR, though there is room for
+    warnings like VIR_ERR_WARNING</li>
+  <li>message: the full human-readable formatted string of the error </li>
+  <li>conn: if available a pointer to the <a href="html/libvirt-libvirt.html#virConnectPtr">virConnectPtr</a>
+    connection to the hypervisor where this happened</li>
+  <li>dom: if available a pointer to the <a href="html/libvirt-libvirt.html#virDomainPtr">virDomainPtr</a> domain
+    targetted in the operation</li>
+</ul><p>and then extra raw informations about the error which may be initialized
+to 0 or NULL if unused</p><ul><li>str1, str2, str3: string informations, usually str1 is the error
+    message format</li>
+  <li>int1, int2: integer informations</li>
+</ul><p>So usually, setting up specific error handling with libvirt consist of
+registering an handler with with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or
+with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
+chech the value of the code value, take appropriate action, if needed let
+libvirt print the error on stderr by calling <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>.
+For asynchronous error handing, set such a function doing nothing to avoid
+the error being reported on stderr, and call virConnGetLastError or
+virGetLastError when an API call returned an error value. It can be a good
+idea to use <a href="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <a href="html/libvirt-virterror.html#virConnResetLastError">virConnResetLastError</a>
+once an error has been processed fully.</p><p>At the python level, there only a global reporting callback function at
+this point, see the error.py example about it:</p><pre>def handler(ctxt, err):
+    global errno
+
+    #print "handler(%s, %s)" % (ctxt, err)
+    errno = err
+
+libvirt.registerErrorHandler(handler, 'context') </pre><p>the second argument to the registerErrorHandler function is passed as the
+fist argument of the callback like in the C version. The error is a tuple
+containing the same field as a virError in C, but cast to Python.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/format.html
+++ b/docs/format.html
@@ -65,4 +65,4 @@ children in no specific order:</p><ul><li>source: indicating the bridge name</li
  <li>target: and optional target indicating the device name.</li>
 </ul><p>While the format may be extended in various ways as support for more
 hypervisor types and features are added, it is expected that this core subset
-will remain functional in spite of the evolution of the library.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+will remain functional in spite of the evolution of the library.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/index.html
+++ b/docs/index.html
@@ -15,8 +15,8 @@
        </div>
        <div id="content">
          <h3>what is <span class="style1">libvirt?</span></h3>
-          <p>Libvirt is a C toolkit to interract with the virtualization capabilities of
-recent versions of Linux (and other OSes). It is free software available
+          <p>Libvirt is a C toolkit to interract with the virtualization capabilities
+of recent versions of Linux (and other OSes). It is free software available
 under the <a href="http://www.opensource.org/licenses/lgpl-license.html">GNU
 Lesser General Public License</a>. Virtualization of the Linux Operating
 System means the ability to run multiple instances of Operating Systems
@@ -52,6 +52,9 @@ mechanisms if needed.</p>
            <li>
              <a href="python.html">Binding for Python</a>
            </li>
+            <li>
+              <a href="errors.html">Handling of errors</a>
+            </li>
            <li>
              <a href="FAQ.html">FAQ</a>
            </li>

--- a/docs/intro.html
+++ b/docs/intro.html
@@ -27,4 +27,4 @@ and for applications focusing on virtualization of a single node (the only
 exception being domain migration between node capabilities which may need to
 be added at the libvirt level). Where possible libvirt should be extendable
 to be able to provide the same API for remote nodes, however this is not the
-case at the moment, the code currently handle only local node accesses.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+case at the moment, the code currently handle only local node accesses.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/libvir.html
+++ b/docs/libvir.html
@@ -14,8 +14,8 @@ site</a></h1>

 <h3>what is <span class="style1">libvirt?</span></h3>

-<p>Libvirt is a C toolkit to interract with the virtualization capabilities of
-recent versions of Linux (and other OSes). It is free software available
+<p>Libvirt is a C toolkit to interract with the virtualization capabilities
+of recent versions of Linux (and other OSes). It is free software available
 under the <a href="http://www.opensource.org/licenses/lgpl-license.html">GNU
 Lesser General Public License</a>. Virtualization of the Linux Operating
 System means the ability to run multiple instances of Operating Systems
@@ -357,6 +357,123 @@ from the C API, the only points to notice are:</p>
    associated to the virDomain class.</li>
 </ul>

+<h2><a name="Errors" id="Errors">Handling of errors</a></h2>
+
+<p>The main goals of libvirt when it comes to error handling are:</p>
+<ul>
+  <li>provide as much detail as possible</li>
+  <li>provide the informations as soon as possible</li>
+  <li>dont force the library user into one style of error handling</li>
+</ul>
+
+<p>As result the library provide both synchronous, callback based and
+asynchronous error reporting. When an error happens in the library code the
+error is logged, allowing to retrieve it later and if the user registered an
+error callback it will be called synchronously. Once the call to libvirt ends
+the error can be detected by the return value and the full information for
+the last logged error can be retrieved.</p>
+
+<p>To avoid as much as prossible troubles with a global variable in a
+multithreaded environment, libvirt will associate when possible the errors to
+the current connection they are related to, that way the error is stored in a
+dynamic structure which can be made thread specific. Error callback can be
+set specifically to a connection with</p>
+
+<p>So error handling in the code is the following:</p>
+<ol>
+  <li>if the error can be associated to a connection for example when failing
+    to look up a domain
+    <ol>
+      <li>if there is a callback associated to the connection set with <a
+        href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
+        call it with the error informations</li>
+      <li>otherwise if there is a global callback set with <a
+        href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
+        call it with the error information</li>
+      <li>otherwise call <a
+        href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
+        which is the default error function of the library issuing the error
+        on stderr</li>
+      <li>save the error in the connection for later retrieval with <a
+        href="html/libvirt-virterror.html#virConnGetLastError">virConnGetLastError</a></li>
+    </ol>
+  </li>
+  <li>otherwise like when failing to create an hypervisor connection:
+    <ol>
+      <li>if there is a global callback set with <a
+        href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
+        call it with the error information</li>
+      <li>otherwise call <a
+        href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
+        which is the default error function of the library issuing the error
+        on stderr</li>
+      <li>save the error in the connection for later retrieval with <a
+        href="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li>
+    </ol>
+  </li>
+</ol>
+
+<p>In all cases the error informations are provided as a <a
+href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to
+read-only structure <a
+href="html/libvirt-virterror.html#virError">virError</a> containing the
+following fields: </p>
+<ul>
+  <li>code: an error number from the <a
+    href="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a>
+  enum</li>
+  <li>domain: an enum indicating which part of libvirt raised the error see
+    <a
+  href="html/libvirt-virterror.html#virErrorDomain">virErrorDomain</a></li>
+  <li>level: the error level, usually VIR_ERR_ERROR, though there is room for
+    warnings like VIR_ERR_WARNING</li>
+  <li>message: the full human-readable formatted string of the error </li>
+  <li>conn: if available a pointer to the <a
+    href="html/libvirt-libvirt.html#virConnectPtr">virConnectPtr</a>
+    connection to the hypervisor where this happened</li>
+  <li>dom: if available a pointer to the <a
+    href="html/libvirt-libvirt.html#virDomainPtr">virDomainPtr</a> domain
+    targetted in the operation</li>
+</ul>
+
+<p>and then extra raw informations about the error which may be initialized
+to 0 or NULL if unused</p>
+<ul>
+  <li>str1, str2, str3: string informations, usually str1 is the error
+    message format</li>
+  <li>int1, int2: integer informations</li>
+</ul>
+
+<p>So usually, setting up specific error handling with libvirt consist of
+registering an handler with with <a
+href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or
+with <a
+href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
+chech the value of the code value, take appropriate action, if needed let
+libvirt print the error on stderr by calling <a
+href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>.
+For asynchronous error handing, set such a function doing nothing to avoid
+the error being reported on stderr, and call virConnGetLastError or
+virGetLastError when an API call returned an error value. It can be a good
+idea to use <a
+href="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <a
+href="html/libvirt-virterror.html#virConnResetLastError">virConnResetLastError</a>
+once an error has been processed fully.</p>
+
+<p>At the python level, there only a global reporting callback function at
+this point, see the error.py example about it:</p>
+<pre>def handler(ctxt, err):
+    global errno
+
+    #print "handler(%s, %s)" % (ctxt, err)
+    errno = err
+
+libvirt.registerErrorHandler(handler, 'context') </pre>
+
+<p>the second argument to the registerErrorHandler function is passed as the
+fist argument of the callback like in the C version. The error is a tuple
+containing the same field as a virError in C, but cast to Python.</p>
+
 <h2><a name="FAQ" id="FAQ">FAQ</a></h2>

 <p>Table of Contents:</p>

--- a/docs/news.html
+++ b/docs/news.html
@@ -25,4 +25,4 @@ and check the <a href="ChangeLog.html">ChangeLog</a> to gauge progresses.</p><h3
 </ul><h3>0.0.1: Dec 19 2005</h3><ul><li>First release</li>
  <li>Basic management of existing Xen domains</li>
  <li>Minimal autogenerated Python bindings</li>
-</ul></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+</ul></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/python.html
+++ b/docs/python.html
@@ -47,4 +47,4 @@ from the C API, the only points to notice are:</p><ul><li>the import of the modu
  <li>extracting and printing some informations about the domain using
    various <span style="color: #E50073; background-color: #FFFFFF">methods</span>
    associated to the virDomain class.</li>
-</ul></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+</ul></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
--- a/docs/site.xsl
+++ b/docs/site.xsl
@@ -27,6 +27,9 @@
      <xsl:when test="$name = '#Help'">
        <xsl:text>help.html</xsl:text>
      </xsl:when>
+      <xsl:when test="$name = '#Errors'">
+        <xsl:text>errors.html</xsl:text>
+      </xsl:when>
      <xsl:when test="$name = '#Downloads'">
        <xsl:text>downloads.html</xsl:text>
      </xsl:when>