External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-11-09 23:10:08 +00:00
Code Issues Packages Projects Releases Wiki Activity
3ad50bec71
libvirt/docs/errors.html

146 lines
8.9 KiB
HTML
Raw Normal View History

* docs/errors.html docs/libvir.html docs/*: added a page about error handling and regenerated the docs Daniel
2006-02-28 13:58:30 +00:00
<?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">
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
This file is autogenerated from errors.html.in
Do not edit this file. Changes will be lost.
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="SHORTCUT ICON" href="32favicon.png" />
<title>libvirt: Handling of errors</title>
<meta name="description" content="libvirt, virtualization, virtualization API" />
</head>
<body>
<div id="header">
<div id="headerLogo"></div>
<div id="headerSearch">
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get">
<input id="query" name="query" type="text" size="12" value="" />
<input id="submit" name="submit" type="submit" value="Search" />
</form>
</div>
</div>
<div id="body">
<div id="content">
<h1>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 information 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
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
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
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
the last logged error can be retrieved.</p>
<p>To avoid as much as possible troubles with a global variable in a
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
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
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
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
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
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>,
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
call it with the error information</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>
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
which is the default error function of the library issuing the error
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
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:
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
<ol><li>if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
which is the default error function of the library issuing the error
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
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 information is provided as a <a href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
read-only structure <a href="html/libvirt-virterror.html#virError">virError</a> containing the
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
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
targeted in the operation</li></ul>
<p>and then extra raw information about the error which may be initialized
to 0 or NULL if unused</p>
<ul><li>str1, str2, str3: string information, usually str1 is the error
message format</li><li>int1, int2: integer information</li></ul>
<p>So usually, setting up specific error handling with libvirt consist of
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
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>,
typos fixes * docs//* src/conf.c src/hash.c src/libvirt.c src/proxy_internal.c src/remote_internal.c src/virsh.c src/xen_internal.c src/xend_internal.c src/xml.c: applied patch from Atsushi SAKAI fixing a lot of typos Daniel
2008-04-04 07:58:29 +00:00
check the value of the code value, take appropriate action, if needed let
* docs/*.html: repair the damages made by Amaya on the content of documentation following feedback from Simon Hernandez Daniel
2007-03-22 15:17:31 +00:00
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>
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
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):
* docs/errors.html docs/libvir.html docs/*: added a page about error handling and regenerated the docs Daniel
2006-02-28 13:58:30 +00:00
global errno
#print "handler(%s, %s)" % (ctxt, err)
errno = err
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
libvirt.registerErrorHandler(handler, 'context') </pre>
<p>the second argument to the registerErrorHandler function is passed as the
* docs/architecture.html docs/errors.html docs/format.html docs/libvir.html: fixing typos spotted by Eduardo Pereira Daniel
2007-09-10 15:16:25 +00:00
first argument of the callback like in the C version. The error is a tuple
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
containing the same field as a virError in C, but cast to Python.</p>
</div>
<div id="menu">
<ul class="l0"><li>
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
</li><li>
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
</li><li>
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
</li><li>
<a title="Information for users, administrators and developers" class="inactive" href="docs.html">Documentation</a>
</li><li>
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
</li><li>
<a title="Frequently asked questions" class="inactive" href="FAQ.html">FAQ</a>
</li><li>
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
</li><li>
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
</li><li>
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
</li><li>
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
</li></ul>
</div>
</div>
<div id="footer">
<div id="projects">
<dl id="p1"><dt>
<a href="http://augeas.net/">Augeas</a>
</dt><dd>
<span>A configuration editing tool and API</span>
</dd><dt>
<a href="http://libvirt.org/">libvirt</a>
</dt><dd>
<span>The open source virtualization API</span>
</dd></dl>
<dl id="p2"><dt>
<a href="http://cobbler.et.redhat.com/">Cobbler</a>
</dt><dd>
<span>OS provisioning and profile management</span>
</dd><dt>
<a href="http://ovirt.org/">oVirt</a>
</dt><dd>
<span>Virtualization management across the data center</span>
</dd></dl>
<dl id="p3"><dt>
<a href="http://freeipa.org/">FreeIPA</a>
</dt><dd>
<span>Identity, policy and audit management</span>
</dd><dt>
<a href="http://virt-manager.org/">Virtual Machine Manager</a>
</dt><dd>
<span>Virtualization management from the desktop</span>
</dd></dl>
</div>
</div>
</body>
</html>
Reference in New Issue Copy Permalink