[PATCH 08/17] docs: Convert 'errors' page to rST
Peter Krempa
pkrempa at redhat.com
Mon Mar 7 15:59:28 UTC 2022
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/errors.html.in | 84 ----------------------------------
docs/errors.rst | 109 ++++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 110 insertions(+), 85 deletions(-)
delete mode 100644 docs/errors.html.in
create mode 100644 docs/errors.rst
diff --git a/docs/errors.html.in b/docs/errors.html.in
deleted file mode 100644
index ea4272822f..0000000000
--- a/docs/errors.html.in
+++ /dev/null
@@ -1,84 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <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
-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 possible 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 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>
- 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 a 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 information is 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-host.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-domain.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
-registering a handler with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or
-with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
-check 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
-first 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>
- </body>
-</html>
diff --git a/docs/errors.rst b/docs/errors.rst
new file mode 100644
index 0000000000..07c0fb1fc0
--- /dev/null
+++ b/docs/errors.rst
@@ -0,0 +1,109 @@
+==================
+Handling of errors
+==================
+
+The main goals of libvirt when it comes to error handling are:
+
+- provide as much detail as possible
+- provide the information as soon as possible
+- dont force the library user into one style of error handling
+
+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.
+
+To avoid as much as possible 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
+
+So error handling in the code is the following:
+
+#. if the error can be associated to a connection for example when failing to
+ look up a domain
+
+ #. if there is a callback associated to the connection set with
+ `virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__,
+ call it with the error information
+ #. otherwise if there is a global callback set with
+ `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it
+ with the error information
+ #. otherwise call
+ `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__
+ which is the default error function of the library issuing the error on
+ stderr
+ #. save the error in the connection for later retrieval with
+ `virConnGetLastError <html/libvirt-virterror.html#virConnGetLastError>`__
+
+#. otherwise like when failing to create a hypervisor connection:
+
+ #. if there is a global callback set with
+ `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it
+ with the error information
+ #. otherwise call
+ `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__
+ which is the default error function of the library issuing the error on
+ stderr
+ #. save the error in the connection for later retrieval with
+ `virGetLastError <html/libvirt-virterror.html#virGetLastError>`__
+
+In all cases the error information is provided as a
+`virErrorPtr <html/libvirt-virterror.html#virErrorPtr>`__ pointer to read-only
+structure `virError <html/libvirt-virterror.html#virError>`__ containing the
+following fields:
+
+- code: an error number from the
+ `virErrorNumber <html/libvirt-virterror.html#virErrorNumber>`__ enum
+- domain: an enum indicating which part of libvirt raised the error see
+ `virErrorDomain <html/libvirt-virterror.html#virErrorDomain>`__
+- level: the error level, usually VIR_ERR_ERROR, though there is room for
+ warnings like VIR_ERR_WARNING
+- message: the full human-readable formatted string of the error
+- conn: if available a pointer to the
+ `virConnectPtr <html/libvirt-libvirt-host.html#virConnectPtr>`__ connection
+ to the hypervisor where this happened
+- dom: if available a pointer to the
+ `virDomainPtr <html/libvirt-libvirt-domain.html#virDomainPtr>`__ domain
+ targeted in the operation
+
+and then extra raw information about the error which may be initialized to 0 or
+NULL if unused
+
+- str1, str2, str3: string information, usually str1 is the error message
+ format
+- int1, int2: integer information
+
+So usually, setting up specific error handling with libvirt consist of
+registering a handler with
+`virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__ or with
+`virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__, check
+the value of the code value, take appropriate action, if needed let libvirt
+print the error on stderr by calling
+`virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__. 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
+`virResetError <html/libvirt-virterror.html#virResetLastError>`__ or
+`virConnResetLastError <html/libvirt-virterror.html#virConnResetLastError>`__
+once an error has been processed fully.
+
+At the python level, there only a global reporting callback function at this
+point, see the error.py example about it:
+
+::
+
+ def handler(ctxt, err):
+ global errno
+
+ #print "handler(%s, %s)" % (ctxt, err)
+ errno = err
+
+ libvirt.registerErrorHandler(handler, 'context')
+
+the second argument to the registerErrorHandler function is passed as the first
+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.
diff --git a/docs/meson.build b/docs/meson.build
index e92ce6bd9e..d0c1217351 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -39,7 +39,6 @@ docs_html_in_files = [
'drvvirtuozzo',
'drvvmware',
'drvxen',
- 'errors',
'firewall',
'formatcaps',
'formatdomaincaps',
@@ -93,6 +92,7 @@ docs_rst_files = [
'developer-tooling',
'drvqemu',
'drvch',
+ 'errors',
'formatbackup',
'formatcheckpoint',
'formatdomain',
--
2.35.1
More information about the libvir-list
mailing list