.. _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 binaries with debug symbols
for the mainline that can 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 https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/Orthanc
  $ chmod +x ./Orthanc
  $ g++ -fPIC -shared ./crash.cpp -I ~/orthanc/OrthancServer/Plugins/Include -o crash.so
  $ ulimit -c unlimited
  $ echo '{ "Plugins" : ["./crash.so"] }' > Configuration.json
  $ rm -f core ; ./Orthanc Configuration.json
  W0103 18:05:01.661466             MAIN main.cpp:2041] Orthanc version: mainline (20240103T170440)
  W0103 18:05:01.661583             MAIN main.cpp:1775] Performance warning: Non-release build, runtime debug assertions are turned on
  W0103 18:05:01.661800             MAIN OrthancConfiguration.cpp:57] Reading the configuration from: "Configuration.json"
  W0103 18:05:01.864783             MAIN main.cpp:912] Loading plugin(s) from: ./crash.so
  W0103 18:05:01.864883             MAIN PluginsManager.cpp:261] Registering plugin 'crash' (version 0.0)
  Segmentation fault (core dumped)


.. highlight:: text

This session creates a file called ``core`` in the current working
directory. If you don't see this file, it probably means that your
GNU/Linux distribution customizes the name of core files (this is for
instance the case of Ubuntu 22.04 that sends core files to
``apport``). You can temporarily disable this behavior by typing::

  $ echo core | sudo tee /proc/sys/kernel/core_pattern


You can then analyze the ``core`` file by running ``gdb`` as follows::

  $ gdb -c ./core.424217 ./Orthanc
  (gdb) bt
  #0  0x00007f5943308111 in OrthancPluginInitialize () from ./crash.so
  #1  0x00000000005e1cbc in Orthanc::CallInitialize (plugin=..., context=...)
      at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Plugins/Engine/PluginsManager.cpp:87
  #2  0x00000000005e2f14 in Orthanc::PluginsManager::RegisterPlugin (this=0x2edc220, path="./crash.so")
      at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Plugins/Engine/PluginsManager.cpp:264

If you are unable to analyze such a backtrace by yourself, feel free
to post your ``core`` file on the `Orthanc Users discussion forum
<https://discourse.orthanc-server.org>`__. Do not forget to indicate
the content of
`<https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/revision.txt>`__
so that we can find the version of Orthanc that generated the core
file.


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