mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-02-19 18:11:31 +00:00
* docs/errors.html docs/libvir.html docs/*: added a page about
error handling and regenerated the docs Daniel
This commit is contained in:
parent
97e7e798b2
commit
6c5a225725
@ -1,3 +1,8 @@
|
||||
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
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
69
docs/errors.html
Normal file
69
docs/errors.html
Normal file
@ -0,0 +1,69 @@
|
||||
<?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>
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
121
docs/libvir.html
121
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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
Loading…
x
Reference in New Issue
Block a user