docs/errors.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1 >Handling of errors</h1>
   6     <p>The main goals of libvirt when it comes to error handling are:</p>
   7     <ul>
   8       <li>provide as much detail as possible</li>
   9       <li>provide the information as soon as possible</li>
  10       <li>dont force the library user into one style of error handling</li>
  11     </ul>
  12     <p>As result the library provide both synchronous, callback based and
  13 asynchronous error reporting. When an error happens in the library code the
  14 error is logged, allowing to retrieve it later and if the user registered an
  15 error callback it will be called synchronously. Once the call to libvirt ends
  16 the error can be detected by the return value and the full information for
  17 the last logged error can be retrieved.</p>
  18     <p>To avoid as much as possible troubles with a global variable in a
  19 multithreaded environment, libvirt will associate when possible the errors to
  20 the current connection they are related to, that way the error is stored in a
  21 dynamic structure which can be made thread specific. Error callback can be
  22 set specifically to a connection with</p>
  23     <p>So error handling in the code is the following:</p>
  24     <ol>
  25       <li>if the error can be associated to a connection for example when failing
  26     to look up a domain
  27     <ol><li>if there is a callback associated to the connection set with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
  28         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>,
  29         call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
  30         which is the default error function of the library issuing the error
  31         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>
  32       <li>otherwise like when failing to create a hypervisor connection:
  33     <ol><li>if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
  34         call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
  35         which is the default error function of the library issuing the error
  36         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>
  37     </ol>
  38     <p>In all cases the error information is provided as a <a href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to
  39 read-only structure <a href="html/libvirt-virterror.html#virError">virError</a> containing the
  40 following fields:</p>
  41     <ul>
  42       <li>code: an error number from the <a href="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a>
  43   enum</li>
  44       <li>domain: an enum indicating which part of libvirt raised the error see
  45     <a href="html/libvirt-virterror.html#virErrorDomain">virErrorDomain</a></li>
  46       <li>level: the error level, usually VIR_ERR_ERROR, though there is room for
  47     warnings like VIR_ERR_WARNING</li>
  48       <li>message: the full human-readable formatted string of the error</li>
  49       <li>conn: if available a pointer to the <a href="html/libvirt-libvirt-host.html#virConnectPtr">virConnectPtr</a>
  50     connection to the hypervisor where this happened</li>
  51       <li>dom: if available a pointer to the <a href="html/libvirt-libvirt-domain.html#virDomainPtr">virDomainPtr</a> domain
  52     targeted in the operation</li>
  53     </ul>
  54     <p>and then extra raw information about the error which may be initialized
  55 to 0 or NULL if unused</p>
  56     <ul>
  57       <li>str1, str2, str3: string information, usually str1 is the error
  58     message format</li>
  59       <li>int1, int2: integer information</li>
  60     </ul>
  61     <p>So usually, setting up specific error handling with libvirt consist of
  62 registering a handler with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or
  63 with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
  64 check the value of the code value, take appropriate action, if needed let
  65 libvirt print the error on stderr by calling <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>.
  66 For asynchronous error handing, set such a function doing nothing to avoid
  67 the error being reported on stderr, and call virConnGetLastError or
  68 virGetLastError when an API call returned an error value. It can be a good
  69 idea to use <a href="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <a href="html/libvirt-virterror.html#virConnResetLastError">virConnResetLastError</a>
  70 once an error has been processed fully.</p>
  71     <p>At the python level, there only a global reporting callback function at
  72 this point, see the error.py example about it:</p>
  73     <pre>def handler(ctxt, err):
  74     global errno
  75
  76     #print "handler(%s, %s)" % (ctxt, err)
  77     errno = err
  78
  79 libvirt.registerErrorHandler(handler, 'context') </pre>
  80     <p>the second argument to the registerErrorHandler function is passed as the
  81 first argument of the callback like in the C version. The error is a tuple
  82 containing the same field as a virError in C, but cast to Python.</p>
  83   </body>
  84 </html>