.. _crash:

Crash analysis
==============

If you experience a crash within Orthanc (or one of its plugins), that
the troubleshooting sections (cf. :ref:`here <troubleshooting>` and
:ref:`here <dicom>`) do not help, and that you can't provide a robust
way to reproduce your issue by third-party developers, you'll have to
analyze the backtrace of Orthanc.


.. _segfault-plugin:

Generating a segmentation fault for test purpose
------------------------------------------------

.. highlight:: cpp

Here is the source code of a minimal C++ :ref:`plugin
<creating-plugins>` that can be used to simulate a segmentation fault
within Orthanc::

  #include <orthanc/OrthancCPlugin.h>
  
  extern "C"
  {
    int32_t OrthancPluginInitialize(OrthancPluginContext* context)
    {
      // Let's trigger a segmentation fault by writing to NULL
      intptr_t *p = NULL;
      *p = 42;
      return OrthancPluginErrorCode_Success;
    }

    void OrthancPluginFinalize()
    {
    }

    const char* OrthancPluginGetName()
    {
      return "crash";
    }

    const char* OrthancPluginGetVersion()
    {
      return "0.0";
    }
  }

As soon as Orthanc will try and load this plugin, it will crash. This
gives you the opportunity to learn how to debug Orthanc on your very
specific platform.


Any system
----------

First :ref:`compile Orthanc by yourself <compiling>`, in debug mode by
setting ``-DCMAKE_BUILD_TYPE=Debug`` when invoking CMake.

Then, learn how to use the debugger that is best suited to your
platform (e.g. Microsoft Visual Studio, gdb or Xcode).


GNU/Linux system using gdb
--------------------------

.. highlight:: bash

The Orthanc project provides precompiled debug binaries that can be
run on almost any recent GNU/Linux system. This allows to generate a
backtrace (the famous "core dumped" message) that can be analyzed by
any developer of Orthanc. Assuming that the :ref:`plugin above
<segfault-plugin>` is available as the ``crash.cpp`` file, here is a
sample debug session::

  $ wget http://orthanc.osimis.io/lsb/orthanc-debug/releases/1.5.6/Orthanc
  $ chmod +x ./Orthanc
  $ gcc -fPIC -shared ./crash.cpp -I ~/orthanc/Plugins/Include -o crash.so
  $ ulimit -c unlimited
  $ echo '{ "Plugins" : ["crash.so"] }' > Configuration.json
  $ rm -f core ; ./Orthanc Configuration.json
  W0427 15:43:24.215783 main.cpp:1436] Orthanc version: 1.5.6
  W0427 15:43:24.215910 main.cpp:1279] Performance warning: Non-release build, runtime debug assertions are turned on
  W0427 15:43:24.217585 OrthancConfiguration.cpp:61] Reading the configuration from: "Configuration.json"
  W0427 15:43:24.254733 main.cpp:700] Loading plugin(s) from: crash.so
  W0427 15:43:24.254866 PluginsManager.cpp:269] Registering plugin 'crash' (version 0.0)
  Segmentation fault (core dumped)


.. highlight:: text

This session creates a file called ``core`` in the current working
directory.  You can analyze it by running ``gdb`` as follows::

  $ gdb -c ./core ./Orthanc
  (gdb) bt
  #0  0x00007f7b1aa3d739 in OrthancPluginInitialize () from crash.so
  #1  0x00000000008632f0 in Orthanc::CallInitialize (plugin=..., context=...)
  at /home/jodogne/BuildBotWorker/Orthanc_1_5_6_-_LSB_Debug/build/Plugins/Engine/PluginsManager.cpp:98
  #2  0x0000000000864496 in Orthanc::PluginsManager::RegisterPlugin (this=0x4314f90, path="crash.so")
  at /home/jodogne/BuildBotWorker/Orthanc_1_5_6_-_LSB_Debug/build/Plugins/Engine/PluginsManager.cpp:272
  ...

If you are unable to analyze such a backtrace by yourself, feel free
to post your ``core`` file on the `Orthanc forum
<https://groups.google.com/forum/#!forum/orthanc-users>`__.

**Important:** The Orthanc developers will only be able to analyze the
``core`` files generated by our own precompiled binaries!

NB: In the future, debug binaries will be provided for the official
plugins (work in progress).


Docker
------

To be written.