.. _crash:

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

Orthanc crashes very rarely. You are most likely looking for the FAQ
entry about :ref:`debugging Orthanc <debugging>`.


.. _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.


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 (generated thanks to the
`LSB - Linux Standard Base SDK
<https://en.wikipedia.org/wiki/Linux_Standard_Base>`__). 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://lsb.orthanc-server.com/orthanc/debug/1.5.8/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.8
  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!


Docker
------

To be written.