<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=ISO-8859-1"/><linkrel="stylesheet"type="text/css"href="libvirt.css"/><linkrel="SHORTCUT ICON"href="/32favicon.png"/><title>Handling of errors</title></head><body><divid="container"><divid="intro"><divid="adjustments"></div><divid="pageHeader"></div><divid="content2"><h1class="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 <ahref="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
call it with the error informations</li>
<li>otherwise if there is a global callback set with <ahref="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
<li>conn: if available a pointer to the <ahref="html/libvirt-libvirt.html#virConnectPtr">virConnectPtr</a>
connection to the hypervisor where this happened</li>
<li>dom: if available a pointer to the <ahref="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 <ahref="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or
with <ahref="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 <ahref="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 <ahref="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <ahref="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><divclass="linkList2"><divclass="llinks2"><h3class="links2"><span>main menu</span></h3><ul><li><ahref="index.html">Home</a></li><li><ahref="news.html">Releases</a></li><li><ahref="intro.html">Introduction</a></li><li><ahref="architecture.html">libvirt architecture</a></li><li><ahref="downloads.html">Downloads</a></li><li><ahref="format.html">XML Format</a></li><li><ahref="python.html">Binding for Python</a></li><li><ahref="errors.html">Handling of errors</a></li><li><ahref="FAQ.html">FAQ</a></li><li><ahref="bugs.html">Reporting bugs and getting help</a></li><li><ahref="html/index.html">API Menu</a></li><li><ahref="examples/index.html">C code examples</a></li><li><ahref="ChangeLog.html">Recent Changes</a></li></ul></div><divclass="llinks2"><h3class="links2"><span>related links</span></h3><ul><li><ahref="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><ahref="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&component=libvirt&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr">Open bugs</a></li><li><ahref="http://hg.berrange.com/libraries/sys-virt">Perl bindings</a></li><li><ahref="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><formaction="search.php"enctype="application/x-www-form-urlencoded"method="get"><inputname="query"type="text"size="12"value="Search..."/><inputname="submit"type="submit"value="Go"/></form></li><li><ahref="http://xmlsoft.org/"><imgsrc="Libxml2-Logo-90x34.gif"alt="Made with Libxml2 Logo"/></a></li></ul><pclass="credits">Graphics and design by <ahref="mail:dfong@redhat.com">Diana Fong</a></p></div></div><divid="bottom"><pclass="p1"></p></div></div></body></html>
